Start documenting PKCS11 more explicitly, plus related tweaks. Re #827final-827-int

5 files changed, 43 insertions, 9 deletions

diff --git a/paramiko/client.py b/paramiko/client.py
index e18bc9fa..0b25cc76 100644
--- a/paramiko/client.py
+++ b/paramiko/client.py
@@ -294,11 +294,10 @@ class SSHClient(ClosingContextManager):
             The targets name in the kerberos database. default: hostname
         :param float banner_timeout: an optional timeout (in seconds) to wait
             for the SSH banner to be presented.
-        :param str pkcs11session: The pkcs11 session obtained by calling
-            pkcs11_open_session. If using PKCS11 in a multithreaded application
-            you can share the session between threads. You can make multiple
-            calls to connect using the same pkcs11 session. You must call
-            pkcs11_close_session to cleanly close the session.
+        :param str pkcs11_session: The PKCS#11 session obtained by calling
+            `pkcs11.open_session`. Note that the caller is responsible for
+            calling `pkcs11.close_session` with that object at shutdown, as it
+            may be reused between multiple clients.
         :param float auth_timeout: an optional timeout (in seconds) to wait for
             an authentication response.
 
diff --git a/paramiko/pkcs11.py b/paramiko/pkcs11.py
index 3a2c6f8c..fc626488 100644
--- a/paramiko/pkcs11.py
+++ b/paramiko/pkcs11.py
@@ -1,5 +1,35 @@
-from ctypes import (c_void_p, c_ulong, c_int, c_char_p, cast, addressof,
-                    sizeof, byref, cdll, Structure)
+"""
+Support for PKCS#11-hosted private RSA keys & operations using them.
+
+Smart devices (such as smartcards and YubiKeys) can hold private key data & its
+corresponding public key data (in the form of a certificate) as well as perform
+signature operations using the private key - all without actually exposing the
+private key to the user, and typically protected by a secret PIN as well.
+
+Traditionally, Paramiko expects access to private key material, so the PKCS#11
+style of approach requires extra code - in this case, using the `ctypes` stdlib
+module to access a PKCS#11 "provider", a ``.so`` or ``.dll`` file such as those
+distributed by `OpenSC <https://github.com/OpenSC/OpenSC/wiki>`_.
+
+The typical case involves generating a PKCS "session" (via `.open_session`,
+giving it the provider file path and the PIN) and handing the result to
+`.Client.connect` as its ``pkcs11_session`` argument. The same session may be
+used across multiple clients and/or threads; in any case, it must be explicitly
+closed via `.close_session`.
+
+.. note::
+    This module is based on the following reference material:
+
+    - `OpenSSH's own PKCS#11 support
+      <https://github.com/openssh/openssh-portable/blob/master/ssh-pkcs11.c>`_
+    - `The official PKCS#11 specification
+      <http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html>`_
+"""
+
+from ctypes import (
+    c_void_p, c_ulong, c_int, c_char_p, cast, addressof, sizeof, byref, cdll,
+    Structure,
+)
 import subprocess
 import os
 import errno
diff --git a/sites/docs/api/pkcs11.rst b/sites/docs/api/pkcs11.rst
new file mode 100644
index 00000000..5848646a
--- /dev/null
+++ b/sites/docs/api/pkcs11.rst
@@ -0,0 +1,4 @@
+PKCS#11 support
+===============
+
+.. automodule:: paramiko.pkcs11
diff --git a/sites/docs/index.rst b/sites/docs/index.rst
index 87265d95..8b7c7415 100644
--- a/sites/docs/index.rst
+++ b/sites/docs/index.rst
@@ -52,6 +52,7 @@ Authentication & keys
     api/keys
     api/ssh_gss
     api/kex_gss
+    api/pkcs11
 
 
 Other primary functions
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst
index d71b5c7b..63bb80bd 100644
--- a/sites/www/changelog.rst
+++ b/sites/www/changelog.rst
@@ -12,8 +12,8 @@ Changelog
   ``SSHException``, so your ``except`` statements will all still work!) Also
   migrated ``InvalidHostKey`` to ``ssh_exception.py`` (though it is of course
   still importable from its previous home, ``hostkeys.py``.)
-* :feature:`827` Add support for PKCS #11 which enables the use of smartcards
-  and other cryptographic tokens.
+* :feature:`827` Add support for PKCS #11 (via `paramiko.pkcs11`) which enables
+  the use of smartcards and other cryptographic tokens, such as YubiKeys.
 * :support:`979` Update how we use `Cryptography <https://cryptography.io>`_'s
   signature/verification methods so we aren't relying on a deprecated API.
   Thanks to Paul Kehrer for the patch.