Home

Awesome

Crypto11

GoDoc Build Status

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.

Installation

Since v1.0.0, crypto11 requires Go v1.11+. Install the library by running:

go get github.com/ThalesGroup/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"
}

Build

This package is using CGo for cryptographic packages.
Enable CGo before building Crypto11 :

go env -w CGO_ENABLED=1
go build

Testing Guidance

Disabling tests

To disable specific tests, set the environment variable CRYPTO11_SKIP=<flags> where <flags> is a comma-separated list of the following options:

Unit test on one file

export DEPENDENCIES="rand.go attributes.go hmac.go block.go crypto11.go common.go keys.go blockmode_cmd.go rsa.go certificates.go ecdsa.go blockmode.go sessions.go aead.go dsa.go symmetric.go common_test.go"
go test block_test.go $DEPENDENCIES

Remote debug :

dlv test --headless --listen=:2345 --api-version=2 --accept-multiclient block_test.go $DEPENDENCIES

Testing with AWS CloudHSM

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:

Testing with SoftHSM2

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.

Testing with nCipher nShield

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.

Testing with a TPM and PKCS11

You must know that tpm2-pkcs11 is much more limited than other libraries like softhsm2 for cryptographic operations.
The absence of the C_GenerateKey function in the tpm2-pkcs11 library is one example of the limitations.
However, some of the tests have been modified to support the tpm2-pkcs11 library's specificities.

To test with a TPM, you need to :

Configure :

{
  "Path": "/usr/lib/x86_64-linux-gnu/libtpm2_pkcs11.so.1",
  "TokenLabel": "mylabel",
  "Pin": "mypin"
}

Fine tune the unit tests to use the keys you created in the previous step.
Beware that a lot of unit tests may fail otherwise. You must fine-tune your usecase for a TPM usage.

Limitations

Contributions

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:

Vulnerability check

$ govulncheck ./...                                                                                                                       ─╯
Scanning your code and 112 packages across 5 dependent modules for known vulnerabilities...

No vulnerabilities found.