OpenSSL with NFKM engine
Quick usage
Assuming you have a key named sslkey protected by OCS sslOCS and the current working directory contains your index.html file.
Ensure that the environment variable OPENSSL_ENGINES is defined as $NFAST_HOME/openssl/lib/engines-3/0 on Linux or %NFAST_HOME%\openssl\lib\engines-3\0 on Windows before running the following.
The command assumes that you already have a certificate.
If you don’t have one, see the command in Testing with a self-signed certificate.
The command has been wrapped for readability but should be written on one line.
preload -c sslOCS openssl s_server -engine nfkm -keyform engine
-key simple_sslkey -port 4433 -cert <path-to-certificate> -HTTPYou can verify that this works with cURL command in a different terminal window:
curl https://www.example.com:4433/index.htmlThe output should print the contents of your index.html file.
You can see the server using the HSM to make signatures by running openssl with NFLOG_SEVERITY=debug1 set.
Testing with a self-signed certificate
The following assumes there is an existing OCS called exampleocs present in the Security World and that the environment variable OPENSSL_ENGINES is defined as $NFAST_HOME/openssl/lib/engines-3/0 on Linux or %NFAST_HOME%\openssl\lib\engines-3\0 on Windows.
The commands have been wrapped for readability but should each be written on one line.
Verify that the NFKM engine works with openssl.
-
Create a key using the
generatekeyutility.generatekey simple protect=token recovery=yes ident=ssltest plainname=ssltest type=RSA size=2048 pubexp='' nvram=no -
Create a self-signed certificate for the key using
openssl req.preload -c exampleocs openssl req -x509 -engine nfkm -keyform engine -subj /CN=www.example.com -addext subjectAltName=DNS:www.example.com -key simple_ssltest -new > ssltest.pem -
openssl s_serverincludes an example web server, which can be told to use the NFKM engine with the newly created key and certificate.-
Make a new directory in your current directory with a new file called
index.htmlcontaining the text<h1>Sample page</h1>. -
From the new directory, run the following command.
preload -c exampleocs openssl s_server -engine nfkm -keyform engine -key simple_ssltest -port 4433 -cert ../ssltest.pem -HTTP
-
You can now request the page using cURL in a different terminal window.
curl --insecure https://www.example.com:4433/index.htmlThis should print <h1>Sample page</h1>.
You can see the server using the HSM to make signatures by running openssl with NFLOG_SEVERITY=debug1 set.
Private key operations
NFKM engine implements select private key operations outlined in Key type and mechanism support. The public and symmetric key operations are left to the OpenSSL software implementation.
The commands used for signing, verifying, encryption and decryption with NFKM engine are outlined below.
Signing/verifying (DSA/ECDSA/RSA)
# Sign
openssl dgst -engine nfkm -keyform engine -out <sigfile> <shaflag> \
-sigopt rsa_padding_mode:<padding mode> -sign <keyname> <infile>
# Export public key
openssl pkey -engine nfkm -inform engine -pubout -in <keyname> -out <pubkeyfile>
# Verify
openssl dgst -verify <pubkeyfile> <shaflag> -sigopt -signature <sigfile> \
rsa_padding_mode:<padding mode>| keyname |
Key to use, in the format |
| infile |
Input file to sign. |
| sigfile |
Signed file. |
| shaflag |
Hash mechanism flag. |
| padding mode |
Padding mode for RSA only (omit |
| pubkeyfile |
Exported public key data. |
Encryption/decryption (RSA)
# Encrypt
openssl pkeyutl -encrypt -engine nfkm -keyform engine -inkey <keyname> \
-in <infile> -out <encfile> -pkeyopt rsa_padding_mode:<padding mode>
# Decrypt
openssl pkeyutl -decrypt -engine nfkm -keyform engine -inkey <keyname> \
-in <encfile> -pkeyopt rsa_padding_mode:<padding mode>| keyname |
Key to use, in the format |
| infile |
Plaintext file to encrypt. |
| encfile |
Encrypted file. |
| padding mode |
Padding mode. |
Key type and mechanism support
The following table lays out the key types and mechanisms which are supported by the NFKM engine. Details about the key size and curve restrictions in FIPS 140 Level 3 mode can be found in the nShield Support for Cryptographic Algorithms application note.
| Feature | Unrestricted | FIPS 140 Level 3 | Common Criteria CMTS | |
|---|---|---|---|---|
DSA signature |
with SHA-1 |
✓ |
✗ |
✓ |
with SHA-224 |
✓ |
Restricted |
✓ |
|
with SHA-256 |
✓ |
Restricted |
✓ |
|
with SHA-384 |
✓ |
Restricted |
✓ |
|
with SHA-512 |
✓ |
Restricted |
✓ |
|
ECDSA signature[1] |
with SHA-1 |
✓ |
✗ |
✓ |
with SHA-224 |
✓ |
Restricted |
✓ |
|
with SHA-256 |
✓ |
Restricted |
✓ |
|
with SHA-384 |
✓ |
Restricted |
✓ |
|
with SHA-512 |
✓ |
Restricted |
✓ |
|
RSA signature[2] |
with SHA-1 |
✓ |
✗ |
✓ |
with SHA-224 |
✓ |
Restricted |
✓ |
|
with SHA-256 |
✓ |
Restricted |
✓ |
|
with SHA-384 |
✓ |
Restricted |
✓ |
|
with SHA-512 |
✓ |
Restricted |
✓ |
|
RSA signature padding mode[2] |
PKCS#1v1.5 padding |
✓ |
Restricted |
✓ |
PSS padding |
✓ |
Restricted |
✓ |
|
ANSI X9.31 padding |
✓ |
Restricted |
✓ |
|
RSA decryption padding mode[2] |
PKCS#1v1.5 padding |
✓ |
✗ |
✓ |
OAEP padding |
✓ |
Restricted |
✓ |
|