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> -HTTP

You can verify that this works with cURL command in a different terminal window:

curl https://www.example.com:4433/index.html

The 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.

  1. Create a key using the generatekey utility.

    generatekey simple protect=token recovery=yes ident=ssltest
    plainname=ssltest type=RSA size=2048 pubexp='' nvram=no

  2. 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

  3. openssl s_server includes an example web server, which can be told to use the NFKM engine with the newly created key and certificate.

    1. Make a new directory in your current directory with a new file called index.html containing the text <h1>Sample page</h1>.

    2. 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.html

This 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.

Common problems

invalid engine "nfkm"

Ensure 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.

unable to load server certificate private key file

Ensure that preload is used when using operations with an OCS-protected or softcard-protected key:

  • preload -c ocsname openssl […​]

  • preload -s softcardname openssl […​]