2 files changed, 57 insertions, 3 deletions
diff --git a/py11/__init__.py b/py11/__init__.py
index 86eb346..d800ab7 100644
--- a/py11/__init__.py
+++ b/py11/__init__.py
@@ -1,5 +1,10 @@
-# An attempt at a Python interface to PKCS 11 using the scary ctypes
-# module from the Python standard library.
+"""
+This is a Python interface to PKCS #11, using the ctypes module from
+the Python standard library.
+
+This is not (yet?) a complete implementation.  It's intended primarily
+to simplify testing of the underlying PKCS #11 shared library.
+"""
 
 from ctypes      import *
 from .exceptions import *
@@ -10,6 +15,34 @@ from .prototypes import *
 
 
 class PKCS11 (object):
+  """
+  PKCS #11 API object, encapsulating the PKCS #11 library itself.
+  Sample usage:
+
+    from py11 import *
+
+    p11 = PKCS11()
+    p11.C_Initialize()
+    session = p11.C_OpenSession()
+    p11.C_login(session, CK_USER, "secret")
+    p11.C_FindObjectsInit(session, {CKA_CLASS: CKO_PRIVATE_KEY, CKA_KEY_TYPE: CKK_EC, CKA_ID: foo})
+    keys = list(p11.C_FindObjects(session))
+    p11.C_FindObjectsFinal(session)
+    if len(keys) != 1:
+      raise RuntimeError
+    p11.C_SignInit(session, CK_ECDSA_SHA256, keys[0])
+    sig = p11.Sign(session, "Your mother was a hamster")
+    p11.C_CloseAllSessions(slot)
+    p11.C_Finalize()
+
+  The full raw PKCS #11 API is available via the .so attribute, but
+  using this can be tricky, both because it requires strict adherence
+  to the C API and because one needs to be careful not to run afoul of
+  the Python garbage collector.
+
+  The example above uses a set of interface routines built on top of the
+  raw PKCS #11 API, which map the API into something a bit more Pythonic.
+  """
 
   def __init__(self, so_name = "libpkcs11.so"):
     self.so_name = so_name
diff --git a/py11/mutex.py b/py11/mutex.py
index 1d99aa1..f71e006 100644
--- a/py11/mutex.py
+++ b/py11/mutex.py
@@ -1,4 +1,25 @@
-# Optional mutex implementation.
+"""
+Optional Python mutex implementation for py11 library, using the
+threading.Lock primitive to provide the mutex itself.
+
+Most of the code in this module has to do with mapping between the
+Python and PKCS #11 APIs.
+
+If you just want locking, it's probably simpler to let the C code
+handle it, by passing CKF_OS_LOCKING_OK to C_Initialize().
+
+The main reason for having a complete implementation in Python is to
+test the API.
+
+Sample usage:
+
+  from p11 import *
+  from py11.mutex import MutexDB
+
+  p11 = PKCS11()
+  mdb = MutexDB()
+  p11.C_Initialize(0, mdb.create, mdb.destroy, mdb.lock, mdb.unlock)
+"""
 
 from struct      import pack, unpack
 from .types      import *