Go to content

Configuration

The OpenSSL Engine Dinamo is a layer above the native API of Dinamo. See Client software for client library configuration options.

Environmental variables

The OpenSSL Engine is configured using environment variables (prefixed by HSM_OSSL_ENGINE_) that must be configured in the operating system or in the process that loads the Engine library.1

Attention

Whenever the environment variables are changed, the application must be restarted.

User

HSM_OSSL_ENGINE_USER

Name of the HSM user that will be used by the OpenSSL Engine.

Variable must be set to the user's name for the OpenSSL Engine to work.

IP

HSM_OSSL_ENGINE_IP

Address of the HSM that will be used by the OpenSSL Engine.

Variable must be set to the IP address of the HSM for the OpenSSL Engine to work.

Encrypted

HSM_OSSL_ENGINE_ENCRYPTED

Defines whether the connection made to the HSM should be encrypted (TLS) or open (clear text).

Variable not defined encrypted connection. Variable set to use 0 for open connection and 1 for encrypted connection.

It is recommended that you use an encrypted connection.

Command Control

The OpenSSL Engine at Dinamo accepts the settings per control command described in the following table. These settings take precedence over settings made via environment variables. The settings made by control command can be made before or immediately after initializing the Engine (ENGINE_init()).

USR

Defines the HSM user that will be used to connect to the HSM.

Value must be a string containing the user's name.

USR_PWD

Sets the password of the user used to connect to the HSM.

Value must be a string containing the user's password.

IP

Defines the IP that will be used to connect to the HSM.

Value must be a string containing the IP address.

NO_TLS

Disables the use of TLS when connecting to the HSM. If this control is not set, the HSM will operate by default with TLS enabled.

Value must be a number, where 1 to disable the TLS connection and 0 to enable the TLS connection.

Some functions related to the use of commands:

int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));

int ENGINE_cmd_is_executable(ENGINE *e, int cmd);

int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,long i, void *p, void (*f)(void), int cmd_optional);

int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, int cmd_optional);

See specific OpenSSL documentation for usage and other/current functions.

[ 1] OpenSSL Engine Manual version 1.0.2

Below is a practical example using the openssl command line program with the OpenSSL Engine from Dinamo passing the settings via OpenSSL control commands (see table above).

The command req expects an RSA key already created within the HSM. Some parameters (path library, user id, IP address and key id) must match the environment.

>openssl
OpenSSL> version
OpenSSL 1.0.2p 14 Aug 2018
OpenSSL> engine -t dynamic -pre SO_PATH:D:\dinamo.dll -pre ID:dinamo -pre LIST_ADD:1 -pre LOAD -pre USR:user -pre IP:10.10.10.10 -pre USR_PWD:12345678
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:D:\dinamo.dll
[Success]: ID:dinamo
[Success]: LIST_ADD:1
[Success]: LOAD
[Success]: USR:user
[Success]: IP:10.10.10.10
[Success]: USR_PWD:12345678
Loaded: (dinamo) Dinamo engine support
     [ available ]
OpenSSL> req -engine dinamo -new -key rsa -keyform engine -out req_rsa.pem -text -x509 -subj "/CN=John RSA Doe"
engine "dinamo" set.
OpenSSL>

  1. The prefix of the environment variables has been updated since version 3.2.26 of the HSM client. As of this version, the prefix is HSM_in previous versions the prefix is DFENCE_.

    Example:

    Old version: DFENCE_OSSL_ENGINE_ENCRYPTED.

    New version: HSM_OSSL_ENGINE_ENCRYPTED. ↩