github.com/ezekielnewren/crypto11
Package crypto11 enables access to cryptographic keys from PKCS#11 using Go crypto API. PKCS#11 tokens are accessed via Context objects. Each Context connects to one token. Context objects are created by calling Configure or ConfigureFromFile. In the latter case, the file should contain a JSON representation of a Config. There is support for generating DSA, RSA and ECDSA keys. These keys can be found later using FindKeyPair. All three key types implement the crypto.Signer interface and the RSA keys also implement crypto.Decrypter. RSA keys obtained through FindKeyPair will need a type assertion to be used for decryption. Assert either crypto.Decrypter or SignerDecrypter, as you prefer. Symmetric keys can also be generated. These are found later using FindKey. See the documentation for SecretKey for further information. Note that PKCS#11 session handles must not be used concurrently from multiple threads. Consumers of the Signer interface know nothing of this and expect to be able to sign from multiple threads without constraint. We address this as follows. 1. When a Context is created, a session is created and the user is logged in. This session remains open until the Context is closed, to ensure all object handles remain valid and to avoid repeatedly calling C_Login. 2. The Context also maintains a pool of read-write sessions. The pool expands dynamically as needed, but never beyond the maximum number of r/w sessions supported by the token (as reported by C_GetInfo). If other applications are using the token, a lower limit should be set in the Config. 3. Each operation transiently takes a session from the pool. They have exclusive use of the session, meeting PKCS#11's concurrency requirements. Sessions are returned to the pool afterwards and may be re-used. Behaviour of the pool can be tweaked via Config fields: - PoolWaitTimeout controls how long an operation can block waiting on a session from the pool. A zero value means there is no limit. Timeouts occur if the pool is fully used and additional operations are requested. - MaxSessions sets an upper bound on the number of sessions. If this value is zero, a default maximum is used (see DefaultMaxSessions). In every case the maximum supported sessions as reported by the token is obeyed. The PKCS1v15DecryptOptions SessionKeyLen field is not implemented and an error is returned if it is nonzero. The reason for this is that it is not possible for crypto11 to guarantee the constant-time behavior in the specification. See https://github.com/thalesignite/crypto11/issues/5 for further discussion. Symmetric crypto support via cipher.Block is very slow. You can use the BlockModeCloser API but you must call the Close() interface (not found in cipher.BlockMode). See https://github.com/ThalesIgnite/crypto11/issues/6 for further discussion.
Readme
This is an implementation of the standard Golang crypto interfaces that uses PKCS#11 as a backend. The supported features are:
Signing is done through the crypto.Signer interface and decryption through crypto.Decrypter.
To verify signatures or encrypt messages, retrieve the public key and do it in software.
See the documentation for details of various limitations, especially regarding symmetric crypto.
Since v1.0.0, crypto11 requires Go v1.11+. Install the library by running:
go get github.com/ThalesIgnite/crypto11
The crypto11 library needs to be configured with information about your PKCS#11 installation. This is either done programmatically
(see the Config struct in the documentation) or via a configuration
file. The configuration file is a JSON representation of the Config struct.
A minimal configuration file looks like this:
{
"Path" : "/usr/lib/softhsm/libsofthsm2.so",
"TokenLabel": "token1",
"Pin" : "password"
}
Path points to the library from your PKCS#11 vendor.TokenLabel is the CKA_LABEL of the token you wish to use.Pin is the password for the CKU_USER user.To disable specific tests, set the environment variable CRYPTO11_SKIP=<flags> where <flags> is a comma-separated
list of the following options:
CERTS - disables certificate-related tests. Needed for AWS CloudHSM, which doesn't support certificates.OAEP_LABEL - disables RSA OAEP encryption tests that use source data encoding parameter (also known as a 'label'
in some crypto libraries). Needed for AWS CloudHSM.DSA - disables DSA tests. Needed for AWS CloudHSM (and any other tokens not supporting DSA).A minimal configuration file for CloudHSM will look like this:
{
"Path" : "/opt/cloudhsm/lib/libcloudhsm_pkcs11_standard.so",
"TokenLabel": "cavium",
"Pin" : "username:password",
"UseGCMIVFromHSM" : true,
}
To run the test suite you must skip unsupported tests:
CRYPTO11_SKIP=CERTS,OAEP_LABEL,DSA go test -v
Be sure to take note of the supported mechanisms, key types and other idiosyncrasies described at https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library.html. Here's a collection of things we noticed when testing with the v2.0.4 PKCS#11 library:
C_GetMechanismInfo tells you.CKM_RSA_PKCS_OAEP mechanism doesn't support source data. I.e. when constructing a CK_RSA_PKCS_OAEP_PARAMS,
one must set pSourceData to NULL and ulSourceDataLen to zero.CKA_ID values must be unique, otherwise you get a CKR_ATTRIBUTE_VALUE_INVALID error.C_OpenSession failed with error CKR_ARGUMENTS_BAD : 0x00000007
HSM error 8c: HSM Error: Already maximum number of sessions are issued
To set up a slot:
$ cat softhsm2.conf
directories.tokendir = /home/rjk/go/src/github.com/ThalesIgnite/crypto11/tokens
objectstore.backend = file
log.level = INFO
$ mkdir tokens
$ export SOFTHSM2_CONF=`pwd`/softhsm2.conf
$ softhsm2-util --init-token --slot 0 --label test
=== SO PIN (4-255 characters) ===
Please enter SO PIN: ********
Please reenter SO PIN: ********
=== User PIN (4-255 characters) ===
Please enter user PIN: ********
Please reenter user PIN: ********
The token has been initialized.
The configuration looks like this:
$ cat config
{
"Path" : "/usr/lib/softhsm/libsofthsm2.so",
"TokenLabel": "test",
"Pin" : "password"
}
(At time of writing) OAEP is only partial and HMAC is unsupported, so expect test skips.
In all cases, it's worth enabling nShield PKCS#11 log output:
export CKNFAST_DEBUG=2
To protect keys with a 1/N operator cardset:
$ cat config
{
"Path" : "/opt/nfast/toolkits/pkcs11/libcknfast.so",
"TokenLabel": "rjk",
"Pin" : "password"
}
You can also identify the token by serial number, which in this case means the first 16 hex digits of the operator cardset's token hash:
$ cat config
{
"Path" : "/opt/nfast/toolkits/pkcs11/libcknfast.so",
"TokenSerial": "1d42780caa22efd5",
"Pin" : "password"
}
A card from the cardset must be in the slot when you run go test.
To protect keys with the module only, use the 'accelerator' token:
$ cat config
{
"Path" : "/opt/nfast/toolkits/pkcs11/libcknfast.so",
"TokenLabel": "accelerator",
"Pin" : "password"
}
(At time of writing) GCM is not implemented, so expect test skips.
BlockModeCloser API
(over 400 times as fast on my computer)
but you must call the Close()
interface (not found in cipher.BlockMode).
See issue #6 for further discussion.Contributions are gratefully received. Before beginning work on sizeable changes, please open an issue first to discuss.
Here are some topics we'd like to cover:
FAQs
Package crypto11 enables access to cryptographic keys from PKCS#11 using Go crypto API. PKCS#11 tokens are accessed via Context objects. Each Context connects to one token. Context objects are created by calling Configure or ConfigureFromFile. In the latter case, the file should contain a JSON representation of a Config. There is support for generating DSA, RSA and ECDSA keys. These keys can be found later using FindKeyPair. All three key types implement the crypto.Signer interface and the RSA keys also implement crypto.Decrypter. RSA keys obtained through FindKeyPair will need a type assertion to be used for decryption. Assert either crypto.Decrypter or SignerDecrypter, as you prefer. Symmetric keys can also be generated. These are found later using FindKey. See the documentation for SecretKey for further information. Note that PKCS#11 session handles must not be used concurrently from multiple threads. Consumers of the Signer interface know nothing of this and expect to be able to sign from multiple threads without constraint. We address this as follows. 1. When a Context is created, a session is created and the user is logged in. This session remains open until the Context is closed, to ensure all object handles remain valid and to avoid repeatedly calling C_Login. 2. The Context also maintains a pool of read-write sessions. The pool expands dynamically as needed, but never beyond the maximum number of r/w sessions supported by the token (as reported by C_GetInfo). If other applications are using the token, a lower limit should be set in the Config. 3. Each operation transiently takes a session from the pool. They have exclusive use of the session, meeting PKCS#11's concurrency requirements. Sessions are returned to the pool afterwards and may be re-used. Behaviour of the pool can be tweaked via Config fields: - PoolWaitTimeout controls how long an operation can block waiting on a session from the pool. A zero value means there is no limit. Timeouts occur if the pool is fully used and additional operations are requested. - MaxSessions sets an upper bound on the number of sessions. If this value is zero, a default maximum is used (see DefaultMaxSessions). In every case the maximum supported sessions as reported by the token is obeyed. The PKCS1v15DecryptOptions SessionKeyLen field is not implemented and an error is returned if it is nonzero. The reason for this is that it is not possible for crypto11 to guarantee the constant-time behavior in the specification. See https://github.com/thalesignite/crypto11/issues/5 for further discussion. Symmetric crypto support via cipher.Block is very slow. You can use the BlockModeCloser API but you must call the Close() interface (not found in cipher.BlockMode). See https://github.com/ThalesIgnite/crypto11/issues/6 for further discussion.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.