1Crypto11
2========
3
4[](https://godoc.org/github.com/ThalesIgnite/crypto11)
5[](https://travis-ci.com/ThalesIgnite/crypto11)
6
7This is an implementation of the standard Golang crypto interfaces that
8uses [PKCS#11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/pkcs11-base-v2.40-errata01-os-complete.html) as a backend. The supported features are:
9
10* Generation and retrieval of RSA, DSA and ECDSA keys.
11* Importing and retrieval of x509 certificates
12* PKCS#1 v1.5 signing.
13* PKCS#1 PSS signing.
14* PKCS#1 v1.5 decryption
15* PKCS#1 OAEP decryption
16* ECDSA signing.
17* DSA signing.
18* Random number generation.
19* AES and DES3 encryption and decryption.
20* HMAC support.
21
22Signing is done through the
23[crypto.Signer](https://golang.org/pkg/crypto/#Signer) interface and
24decryption through
25[crypto.Decrypter](https://golang.org/pkg/crypto/#Decrypter).
26
27To verify signatures or encrypt messages, retrieve the public key and do it in software.
28
29See [the documentation](https://godoc.org/github.com/ThalesIgnite/crypto11) for details of various limitations,
30especially regarding symmetric crypto.
31
32
33Installation
34============
35
36Since v1.0.0, crypto11 requires Go v1.11+. Install the library by running:
37
38```bash
39go get github.com/ThalesIgnite/crypto11
40```
41
42The crypto11 library needs to be configured with information about your PKCS#11 installation. This is either done programmatically
43(see the `Config` struct in [the documentation](https://godoc.org/github.com/ThalesIgnite/crypto11)) or via a configuration
44file. The configuration file is a JSON representation of the `Config` struct.
45
46A minimal configuration file looks like this:
47
48```json
49{
50 "Path" : "/usr/lib/softhsm/libsofthsm2.so",
51 "TokenLabel": "token1",
52 "Pin" : "password"
53}
54```
55
56- `Path` points to the library from your PKCS#11 vendor.
57- `TokenLabel` is the `CKA_LABEL` of the token you wish to use.
58- `Pin` is the password for the `CKU_USER` user.
59
60Testing Guidance
61================
62
63Disabling tests
64---------------
65
66To disable specific tests, set the environment variable `CRYPTO11_SKIP=<flags>` where `<flags>` is a comma-separated
67list of the following options:
68
69* `CERTS` - disables certificate-related tests. Needed for AWS CloudHSM, which doesn't support certificates.
70* `OAEP_LABEL` - disables RSA OAEP encryption tests that use source data encoding parameter (also known as a 'label'
71in some crypto libraries). Needed for AWS CloudHSM.
72* `DSA` - disables DSA tests. Needed for AWS CloudHSM (and any other tokens not supporting DSA).
73
74Testing with Thales Luna HSM
75----------------------------
76
77
78
79
80Testing with AWS CloudHSM
81-------------------------
82
83A minimal configuration file for CloudHSM will look like this:
84
85```json
86{
87 "Path" : "/opt/cloudhsm/lib/libcloudhsm_pkcs11_standard.so",
88 "TokenLabel": "cavium",
89 "Pin" : "username:password",
90 "UseGCMIVFromHSM" : true,
91}
92```
93
94To run the test suite you must skip unsupported tests:
95
96```
97CRYPTO11_SKIP=CERTS,OAEP_LABEL,DSA go test -v
98```
99
100Be sure to take note of the supported mechanisms, key types and other idiosyncrasies described at
101https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library.html. Here's a collection of things we
102noticed when testing with the v2.0.4 PKCS#11 library:
103
104- 1024-bit RSA keys don't appear to be supported, despite what `C_GetMechanismInfo` tells you.
105- The `CKM_RSA_PKCS_OAEP` mechanism doesn't support source data. I.e. when constructing a `CK_RSA_PKCS_OAEP_PARAMS`,
106one must set `pSourceData` to `NULL` and `ulSourceDataLen` to zero.
107- CloudHSM will generate it's own IV for GCM mode. This is described in their documentation, see footnote 4 on
108https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-mechanisms.html.
109- It appears that `CKA_ID` values must be unique, otherwise you get a `CKR_ATTRIBUTE_VALUE_INVALID` error.
110- Very rapid session opening can trigger the following error:
111 ```
112 C_OpenSession failed with error CKR_ARGUMENTS_BAD : 0x00000007
113 HSM error 8c: HSM Error: Already maximum number of sessions are issued
114 ```
115
116Testing with SoftHSM2
117---------------------
118
119To set up a slot:
120
121 $ cat softhsm2.conf
122 directories.tokendir = /home/rjk/go/src/github.com/ThalesIgnite/crypto11/tokens
123 objectstore.backend = file
124 log.level = INFO
125 $ mkdir tokens
126 $ export SOFTHSM2_CONF=`pwd`/softhsm2.conf
127 $ softhsm2-util --init-token --slot 0 --label test
128 === SO PIN (4-255 characters) ===
129 Please enter SO PIN: ********
130 Please reenter SO PIN: ********
131 === User PIN (4-255 characters) ===
132 Please enter user PIN: ********
133 Please reenter user PIN: ********
134 The token has been initialized.
135
136The configuration looks like this:
137
138 $ cat config
139 {
140 "Path" : "/usr/lib/softhsm/libsofthsm2.so",
141 "TokenLabel": "test",
142 "Pin" : "password"
143 }
144
145(At time of writing) OAEP is only partial and HMAC is unsupported, so expect test skips.
146
147Testing with nCipher nShield
148--------------------
149
150In all cases, it's worth enabling nShield PKCS#11 log output:
151
152 export CKNFAST_DEBUG=2
153
154To protect keys with a 1/N operator cardset:
155
156 $ cat config
157 {
158 "Path" : "/opt/nfast/toolkits/pkcs11/libcknfast.so",
159 "TokenLabel": "rjk",
160 "Pin" : "password"
161 }
162
163You can also identify the token by serial number, which in this case
164means the first 16 hex digits of the operator cardset's token hash:
165
166 $ cat config
167 {
168 "Path" : "/opt/nfast/toolkits/pkcs11/libcknfast.so",
169 "TokenSerial": "1d42780caa22efd5",
170 "Pin" : "password"
171 }
172
173A card from the cardset must be in the slot when you run `go test`.
174
175To protect keys with the module only, use the 'accelerator' token:
176
177 $ cat config
178 {
179 "Path" : "/opt/nfast/toolkits/pkcs11/libcknfast.so",
180 "TokenLabel": "accelerator",
181 "Pin" : "password"
182 }
183
184(At time of writing) GCM is not implemented, so expect test skips.
185
186Limitations
187===========
188
189 * The [PKCS1v15DecryptOptions SessionKeyLen](https://golang.org/pkg/crypto/rsa/#PKCS1v15DecryptOptions) field
190is not implemented and an error is returned if it is nonzero.
191The reason for this is that it is not possible for crypto11 to guarantee the constant-time behavior in the specification.
192See [issue #5](https://github.com/ThalesIgnite/crypto11/issues/5) for further discussion.
193 * Symmetric crypto support via [cipher.Block](https://golang.org/pkg/crypto/cipher/#Block) is very slow.
194You can use the `BlockModeCloser` API
195(over 400 times as fast on my computer)
196but you must call the Close()
197interface (not found in [cipher.BlockMode](https://golang.org/pkg/crypto/cipher/#BlockMode)).
198See [issue #6](https://github.com/ThalesIgnite/crypto11/issues/6) for further discussion.
199
200Contributions
201========
202
203Contributions are gratefully received. Before beginning work on sizeable changes, please open an issue first to
204discuss.
205
206Here are some topics we'd like to cover:
207
208* Full test instructions for additional PKCS#11 implementations.
View as plain text