OpenSSL

The UKCClosedUnbound Key Control - The name of Unbound's key management product. integration with the OpenSSL infrastructure includes two steps: importing the UKCClosedUnbound Key Control - The name of Unbound's key management product. openssl engine and configuring the OpenSSL to use the engine.

OpenSSL Prerequisites

  • OpenSSL version: 1.0.2<x>.
    • Windows:
    • Use the OpenSSL libraries (libeay32.dll and ssleay32.dll) provided with the Unbound Client distribution and located in the Windows OpenSSL DLLs folder.

Unbound OpenSSL Engine

By default, OpenSSL:

  • Assumes that the key material is stored in the file system.
  • Provides an in-memory implementation of cryptography operations.

To mitigate these limitations, OpenSSL provides an extension by means of the OpenSSL Engine plug-in mechanism.

Unbound Tech provides an OpenSSL engine that allows the storage and processing of crypto material within the UKCClosedUnbound Key Control - The name of Unbound's key management product. servers. The engine is included in the UKCClosedUnbound Key Control - The name of Unbound's key management product. client distribution and is installed in the OpenSSL Engine, Files, and Libraries folder.

To allow transparent use of file-oriented openssl commands:

Note
The Unbound OpenSSL engine is implemented in a way that it doesn't interfere with the OpenSSL using its native PEMClosedPrivacy-enhanced Electronic Mail - Base64 encoded DER certificate, enclosed between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" files with the complete private key material.

OpenSSL Engine Configuration on Linux

If you are using Linux with standard OpenSSL and the key material is stored in the first registered partition, then proceed with the following quick steps:

  1. Add the Unbound OpenSSL engine (dyadicsec) to the openssl engines by running this script:
  2. /etc/ekm/dy_openssl

    This script adds settings of the Unbound OpenSSL engine to the openssl.cnf.

    Important for RHClosedRed Hat Linux-8
    After running the dy_openssl script on the Linux RHClosedRed Hat Linux-8 machine, open the updated openssl.cnf file and add the engines = engine_section directive to the [ default_modules ] section.
    After the change, you should see the following in the [ default_modules ] section:

    [ default_modules ]
    ssl_conf = ssl_module
    engines = engine_section

  3. Check that the Unbound OpenSSL engine (dyadicsec) is listed among the OpenSSL engines:
  4. openssl engine

    // --- truncated ---
    (dyadicsec) Dyadic Security engine support

    Troubleshooting

    If dyadicsec is missing from the openssl engine list, proceed as follows:
    1. Run which openssl and notice its path.
    2. Run sudo find / -name openssl.cnf and notice the location of the most probable candidate to be used by the current openssl.
    3. Edit the /etc/ekm/dy_openssl script and update the path to the openssl.cnf.
    4. Rerun the script and check the openssl engine output.
    5. As needed, repeat steps 2-4 with the path to the next openssl.conf.

  5. Create environmental variable OPENSSL_CONF for the duration of your session:
  6. export OPENSSL_CONF="path to the <openssl.cnf>"

    Example (RHEL):

    export OPENSSL_CONF="/etc/pki/tls/openssl.cnf"

    Note
    To create a persistent environmental variable, add the above line to your shell startup file. For example, if you are using the Bash shell, add the above line to the .bashrc file.

  7. To confirm the successful integration, run the openssl genrsa -out key.pem 2048 command
    and make sure that a new RSA key appears in the partition. Alternatively, display the content of the PEMClosedPrivacy-enhanced Electronic Mail - Base64 encoded DER certificate, enclosed between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" file to observe the filler pattern in it.
  8. Note
    UKCClosedUnbound Key Control - The name of Unbound's key management product. supports only three RSA key sizes - 2048, 3072, and 4096.
    The absence of the response to the openssl genrsa [size] command indicates that the provided key size is not supported. In particular, it is true for the OpenSSL 1.0.1 and earlier versions that, by default, generate a 1024 bit RSA key.

Modify the Unbound Section in Openssl.cnf

By default, Unbound OpenSSL engine uses the following UKCClosedUnbound Key Control - The name of Unbound's key management product. parameters:

  • Partition - the first partition (" slot 0") in the list of the registered partitions.
  • User credentials - the default USER with the default password.

To modify these parameters:

  1. Edit the updated openssl.cnf file.
  2. Navigate to the [dyadicsec_section].
  3. As needed, uncomment and update the set_partition setting. Refer to The set_partition Setting.
  4. As needed, uncomment and update the login setting. Refer to The login Setting.

# --------------------------
[dyadicsec_section]
# dyadicsec ENGINE specific commands
engine_id = dyadicsec
dynamic_path = OpenSSL Engine, Files, and Libraries
default_algorithms = RSA, ECDH, ECDSA
init = 1
#set_partition = partition_name
#login = '{"username":"user_name","password":"pwd"}'
# ---------------------------
# dyadicsec specific ctrl.
set_gen_mode = 1
#BUFFER_SIZE = 2
#VERBOSE = EMPTY
#QUIET = EMPTY
# ---------------------------

For the description of the other settings, refer to OpenSSL CONF library. In particular,

  • dynamic_path points at the implementation of the engine.
  • init = 1 indicates that the engine is initialized before executing the subsequent commands in this section.
  • Important
    Do not change the position of this statement in the file and do not remove it.

The set_partition Setting

By default, the Unbound OpenSSL engine uses the first partition in the ucl partition list. For example:

ucl partition list

Partition 0: Encrypt1
Partition 1: CodeSign1

By default, the openssl tool shall address its request to partition Encrypt1.

To address the requests to partition CodeSign1, use the set_partition=<partition name> statement:

set_partition = CodeSign1

The login Setting

You must specify user credentials if one of the following applies:

  • The default USER of the partition has a non-empty password.
  • The procedure is performed by a non-default USER of the partition.

In such a case, uncomment the login statement and specify the credentials.

login=<{"username":"user_name","password":"pwd"}>

The credentials are specified using JSON format enclosed into curly braces {} that may interfere with your shell.

For username Signer100 with a password Signer100!, use one of the following options to escape the braces from being processed by your shell:

  • with backslashes:
  • login=\{\"username\"\:\"Signer100\" , \"password\":\"Signer100!\"\}

  • with backtick:
  • login='{"username":"Signer100","password":"Signer100!"}'

Control Key Generation

By default, key generation in UKCClosedUnbound Key Control - The name of Unbound's key management product. through OpenSSL is enabled. To turn it off, use the set_gen_mode setting:

  • To disable: set_gen_mode = 0
  • To enable: set_gen_mode = 1

OpenSSL Engine Configuration on Windows

As needed, either add the openssl.cnf file or update it.

To customize the default Unbound OpenSSL engine settings, refer to Modify the Unbound Section in Openssl.cnf.

Create OpenSSL Configuration

If the openssl.cnf is missing, proceed as follows:

  1. Create the openssl.cnf file with the following content.
  2. Set the OPENSSL_CONF environmental variable to point at the created file.

# ---------------------------
[openssl_init]
engines = engine_section
# --------------------------
[engine_section]
# Configure ENGINE named "dyadicsec"
dyadicsec = dyadicsec_section
# --------------------------
[dyadicsec_section]
# dyadicsec ENGINE specific commands
engine_id = dyadicsec
dynamic_path = C:\Program Files\Dyadic\ekm-client\bin\dyadicsec.dll
default_algorithms = RSA, ECDH, ECDSA
init = 1
#set_partition = partition_name
#login = '{"username":"user_name","password":"pwd"}'
# ---------------------------
# dyadicsec specific ctrl.
set_gen_mode = 1
#BUFFER_SIZE = 2
#VERBOSE = EMPTY
#QUIET = EMPTY
# ---------------------------

Update OpenSSL Configuration

If your machine already has openssl.cnf, proceed as follows:

  1. As needed, set the OPENSSL_CONF environmental variable to point at the file.
  2. Update the openssl.cnf file as follows:
    • Prepend the following to the beginning of the file:
    • # ---------------------------
      [openssl_init]
      engines = engine_section
      # --------------------------

    • Append the following to the end of the file:
    • # --------------------------
      [engine_section]
      # Configure ENGINE named "dyadicsec"
      dyadicsec = dyadicsec_section
      # --------------------------
      [dyadicsec_section]
      # dyadicsec ENGINE specific commands
      engine_id = dyadicsec
      dynamic_path = C:\Program Files\Dyadic\ekm-client\bin\dyadicsec.dll
      default_algorithms = RSA, ECDH, ECDSA
      init = 1
      #set_partition = partition_name
      #login = '{"username":"user_name","password":"pwd"}'
      # ---------------------------
      # dyadicsec specific ctrl.
      set_gen_mode = 1
      #BUFFER_SIZE = 2
      #VERBOSE = EMPTY
      #QUIET = EMPTY
      # ---------------------------