Minimal documentation for py11.

1 files changed, 35 insertions, 2 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