aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: d846fe28c6e8c090ea659e32a382336389da26e6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

   

PKCS #11

Introduction

This is an implementation of the PKCS11 API for the Cryptech project. Like most PKCS #11 implementations, this one is incomplete and probably always will be: PKCS #11 is very open-ended, and the specification includes enough rope for an unwary developer to hang not only himself, but all of his friends, relations, and casual acquaintances.

Along with the PKCS #11 library itself, the package includes a companion Python interface ("cryptech.py11"), which uses the ctypes module from the Python standard library to talk to the PKCS #11 implementation. The Python implementation is intended primarily to simplify testing the C code, but can be used for other purposes; while it seems unlikely that anything could ever make PKCS #11 "fun", the cryptech.py11 library attempts to make it a bit less awful by providing both direct acess to the raw PKCS #11 API and a somewhat more "pythonic" API layered on top of the raw API.

Novel design features

PKCS11's data model involves an n-level-deep hierarchy of object classes, which is somewhat tedious to implement correctly in C, particularly if one wants the correspondence between specification and code to be at all obvious. In order to automate much of the drudge work involved, this implementation uses an external representation of the object class hierarchy, which is processed at compile time by a Python script to generate tables which drive the C code which performs the necessary type checking.

Current status

As of this writing, the implementation supports only the RSA, ECDSA, SHA-1, and SHA-2 algorithms, but the design is intended to be extensible.

The underlying cryptographic support comes from the Cryptech libhal package.

Testing to date has been done using the bin/pkcs11/ tools from the BIND9 distribution, the hsmcheck and ods-hsmutil tools from the OpenDNSSEC distribution, the hsmbully diagnostic tool, the Google pkcs11test test suite, and a somewhat ad hoc set of unit tests using Python's unittest library along with our own cryptech.py11 library.

The library is also known to work as an OpenSSL engine when used with the engine-pkcs11 package spun out of the OpenSC project. This has not been tested extensively, but key generation, signature, and verification all work (with RSA keys -- the engine appears not to understand ECDSA keys, we have not investigated into details here).

The PKCS11 header files are "derived from the RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki)". See the pkcs11*.h header files for details.

Code written for the Cryptech project is under the usual Cryptech BSD-style license.