aboutsummaryrefslogtreecommitdiff
path: root/py11
diff options
context:
space:
mode:
authorRob Austein <sra@hactrn.net>2015-09-20 17:51:01 -0400
committerRob Austein <sra@hactrn.net>2015-09-20 17:51:01 -0400
commit48f0c98b02ef77fa63d31a58341b07d07b6c47f6 (patch)
tree8affb1df901607dd2b48fe1d93876905cb168be3 /py11
parent91b051e349e3644b4a2114ec0366f8bd7d794f56 (diff)
Minimal documentation for py11.
Diffstat (limited to 'py11')
-rw-r--r--py11/__init__.py37
-rw-r--r--py11/mutex.py23
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 *