Test OpenSSL Provider - Futurex Documentation

This section walks through creating a key pair in CryptoHub and running several OpenSSL commands that use it through the OpenSSL pkcs11 provider configured in the previous section. Run these commands with the provider configuration and cryptohub.json in the environment, matching the wiring from the previous section:

export OPENSSL_CONF=/etc/<product>/openssl-cryptohub.cnf
export CHLIBS_CONFIG=/etc/cryptohub.json

Confirm the CryptoHub token label

The token label your pkcs11: URIs reference is the cryptohubs[].label value defined in your cryptohub.json. Confirm it before building URIs:

openssl storeutl -text "pkcs11:"

The output lists the reachable tokens and objects. You can also use the bundled interactive pkcs11-manager. Pass the configuration path as its first argument, then use its initialization, login, and slot-listing menu actions:

pkcs11-manager /etc/cryptohub.json

Optionally, if OpenSC’s pkcs11-tool is installed (from the opensc package), list the token slots directly against the CryptoHub module:

pkcs11-tool --module /usr/local/lib/libcryptohub-pkcs11.so --list-token-slots

Create a key pair in CryptoHub

If you do not yet have a key in CryptoHub, use the key-generation action in the interactive pkcs11-manager menu. Give the key a label you will reference from OpenSSL, for example my_rsa2048_key.

pkcs11-manager /etc/cryptohub.json

The key is created in CryptoHub with the asymmetric usages pinned by this template’s config.json, which is what the OpenSSL examples below exercise. If your use case needs both Encrypt/Decrypt and Sign/Verify usages on the same key, first complete Enable the EDSV multi-usage combination for asymmetric keys. After generation, confirm the key is reachable by URI through the provider:

openssl storeutl -text "pkcs11:token=<label>;object=my_rsa2048_key;type=private"

Replace <label> with the token label confirmed above and my_rsa2048_key with your key’s label. Note: Keep provider URIs free of pin-value. The dedicated OpenSSL provider configuration supplies the module PIN from the protected pin file. With a 1.x provider, pin-source is an alternative to the configuration directive, not an additional PIN source.

OpenSSL example commands

The following commands use the key created in CryptoHub above. In each command that uses a CryptoHub key, the pkcs11 provider is specified with -provider pkcs11 -provider default, and the key is referenced by a pkcs11: URI. This section does not provide an exhaustive list of OpenSSL commands that you can run through the pkcs11 provider. It gives a few examples of use cases and confirms everything was configured correctly. Refer to the OpenSSL documentation (www.openssl.org/docs/) for the full list of compatible commands. Running one of these commands successfully forces a cryptographic operation against the key in CryptoHub: this is the proof that the provider reached CryptoHub, not merely that the configuration parses.

Example 1: Output the public key

openssl rsa -provider pkcs11 -provider default -in "pkcs11:token=<label>;object=my_rsa2048_key" -pubout -out my_rsa2048_pubkey.pem

If the command succeeds, the my_rsa2048_pubkey.pem file is generated and contains the public key.

Example 2: Encrypt and decrypt data

Generate a file, clear_data, containing sample ASCII data:

echo "This is a test file" > ./clear_data

Encrypt the clear_data file using the CryptoHub-backed public key and output the results to encrypted_data:

openssl pkeyutl -provider pkcs11 -provider default -encrypt -inkey "pkcs11:token=<label>;object=my_rsa2048_key" -pubin -in clear_data -out encrypted_data -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256

Decrypt the encrypted_data file using the CryptoHub-backed private key and output the results to decrypted_data:

openssl pkeyutl -provider pkcs11 -provider default -decrypt -inkey "pkcs11:token=<label>;object=my_rsa2048_key" -in encrypted_data -out decrypted_data -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256

Confirm that clear_data and decrypted_data are identical:

diff clear_data decrypted_data

If the command runs successfully and the files are identical, no output is displayed.

Example 3: Sign a file and verify the signature

Sign the clear_data file using the CryptoHub-backed private key and output the signature to clear_data.sig:

openssl dgst -sha256 -provider pkcs11 -provider default -sign "pkcs11:token=<label>;object=my_rsa2048_key" -out clear_data.sig clear_data

Verify the signature using the CryptoHub-backed public key:

openssl dgst -sha256 -verify "pkcs11:token=<label>;object=my_rsa2048_key;type=public" -signature clear_data.sig clear_data

If the signature was verified successfully, the message Verified OK displays on the screen.

Example 4: Create a self-signed Root CA

Generate a self-signed CA certificate using the CryptoHub-backed private key:

openssl req -new -x509 -provider pkcs11 -provider default -key "pkcs11:token=<label>;object=my_rsa2048_key" -out ssl-ca-cert.pem -days 365

When prompted, enter information about the self-signed CA certificate.

A successful command execution generates the ssl-ca-cert.pem file.

Example 5: Generate a CSR

Generate a CSR using the CryptoHub-backed private key:

openssl req -new -provider pkcs11 -provider default -key "pkcs11:token=<label>;object=my_rsa2048_key" -out ssl-client-cert-req.csr -days 365

When prompted, enter information about the certificate.

A successful command execution generates the ssl-client-cert-req.csr file.

Example 6: Sign a CSR

openssl x509 -req -provider pkcs11 -provider default -in ssl-client-cert-req.csr -CA ssl-ca-cert.pem -CAkey "pkcs11:token=<label>;object=my_rsa2048_key" -CAcreateserial -out signed-client-cert.pem -days 365

A successful command execution generates the signed-client-cert.pem file, containing the signed certificate. A serial number file, ssl-ca-cert.srl, is also created to track the certificate’s serial number for future CA operations.