From 48f0c98b02ef77fa63d31a58341b07d07b6c47f6 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sun, 20 Sep 2015 17:51:01 -0400 Subject: Minimal documentation for py11. --- py11/__init__.py | 37 +++++++++++++++++++++++++++++++++++-- py11/mutex.py | 23 ++++++++++++++++++++++- 2 files changed, 57 insertions(+), 3 deletions(-) (limited to 'py11') 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 * -- cgit v1.2.3