Configuration

HSM 's PKCS#11 library Dinamo is one layer above the native API of Dinamo. You can consult the configuration options for the client library in the User Manual.

Configuration is done through environment variables (with prefix DFENCE_PKCS11_) which must be set in the scope of the system, user or process loading the library.

Info

Warning: Whenever you change the environment variables, you must restart the application.

User

DFENCE_PKCS11_USER

Id (name) of the user (userid) of the HSM that will be used by PKCS#11.

Variable must be set to the user id for the PKCS#11 library to work correctly.

Note: if you use the pPin parameter to enter the user id (see DFENCE_PKCS11_SPECIAL_PWD variable below) there is no need to set DFENCE_PKCS11_USER.

IP address

DFENCE_PKCS11_IP

IP address of the HSM.

Variable must be set to the IP address of the HSM for PKCS#11 to work correctly.

Note: if you use the pPin parameter to enter the HSM 's IP address (see DFENCE_PKCS11_SPECIAL_PWD variable below), the IP address defined here will be used in the unauthenticated PKCS#11 functions (e.g. C_GetTokenInfo, C_GetSlotInfo, etc.) and the IP address entered in pPin will be used in the authentication operation.

Special PIN

DFENCE_PKCS11_SPECIAL_PWD

Enables the user id, password and IP address of the HSM to be passed in the pPin parameter of the PKCS#11 C_Login function.

Variable not set or variable set to 0: the pPin parameter (in the PKCS#11 C_Login function) should only receive the HSM user'spassword:

password

Variable set to 1: the pPin parameter (in C_Login ) should receive the user id(userid), the password (password) and the IP address of the HSM(ip) in the format:

userid:password@ip

E.g.: master:12345678@10.0.62.10

If load balancing is enabled, the IP will be ignored internally.

For unauthenticated PKCS#11 functions, the IP address used will be the one entered in the DFENCE_PKCS11_IP variable.

Encrypted

DFENCE_PKCS11_ENCRYPTED

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

Variable not set or variable set to 1: the connection to the HSM will be encrypted.

Variable set to 0: the connection to the HSM will be in clear text.

It is recommended that you use an encrypted connection.

Auto Reconnect

DFENCE_PKCS11_AUTO_RECONNECT

Enables automatic reconnection of HSM sessions in case of failure.

Variable not set or set to 0: auto-reconnect is disabled.

Variable set to 1: auto-reconnect is enabled.

It is recommended to use auto-reconnect enabled.

Auto-reconnect is available in APIs that access the HSM and are not part of operations that require more than one step to complete.

Examples of APIs that do not have auto-reconnect: C_Encrypt, C_EncryptUpdate, C_Decrypt, C_DecryptUpdate etc. In the event of a network failure in these functions, you must close the failed session, open a new one and redo the operation.

Log Path

DFENCE_PKCS11_LOG_PATH

Path with the name of the file that will contain the logs generated by the library.

Variable not defined, the log is not generated.

Defined variable must contain path and filename.

Ex.: c:\tacndp11.log

Log Level

DFENCE_PKCS11_LOG_LEVEL

Sets the log level.

The log levels are:

0 : errors only; records only error situations (which normally prevent the requested service from being performed).
3 : debugging; records detailed operating information as well as error messages.
1000 : disabled; no event is logged.

Under normal operating conditions, it is recommended to keep the library log to a minimum. The debugging level can be used to diagnose operating problems.

Log Flush

DFENCE_PKCS11_LOG_FLUSH

Enables log messages to be written directly to the log file, without using a buffer.

Variable not set or set to 0: log messages are buffered and written to the log file at intervals.

Variable set to 1: log messages are written immediately to the file.

The library can keep a small buffer of log messages before making the physical recording in the file, which allows for performance gains. In error conditions or diagnostic situations, it is interesting that the log is written immediately after the occurrence.

Large Find List

DFENCE_PKCS11_LARGE_FIND_LIST

Enables the use of search for large numbers of objects.

Variable not set or set to 0: uses the standard search system with a reading limit of 512 objects per user. Objects above the 512 object limit are not listed in the search.

Allows other calls to be made using the same session during a search operation.

Example allowed:

C_FindObjectsInit(session1);
    . . .
    C_FindObjects(session1);
    . . .
    C_GetAttributeValue(session1);
    . . .
C_FindObjectsFinal(session1);

Variable set to 1: uses the search system for large quantities of objects per user.

Searches for quantities greater than 512 objects, but does not allow other calls to be made using the same session during a search operation.

Example allowed:

C_FindObjectsInit(session1);
    . . .
    C_FindObjects(session1);
    . . .
C_FindObjectsFinal(session1);
. . .
C_GetAttributeValue(session1);

Example not allowed:

C_FindObjectsInit(session1);
    . . .
    C_FindObjects(session1);
    . . .
    C_GetAttributeValue(session1);
    . . .
C_FindObjectsFinal(session1);

Non-Private Objects

HSM_PKCS11_NON_PRIVATE_OBJECTS_SUPPORT

Enables the creation of non-private objects ( CKA_PRIVATE attribute equal to 0).

The CKA_PRIVATE object attribute indicates whether an object is private or public in terms of its access requirements. In the context of PKCS#11, a public object can be accessed by an authenticated or unauthenticated session, while a private object can only be accessed using an authenticated session.

To allow the creation of public objects(CKA_PRIVATE equal to 0), this environment variable must be used.

Variable not set or set to 0: does not allow the generation of public objects(CKA_PRIVATE equal to 0).

Variable set to 1: allows the generation of public objects(CKA_PRIVATE equal to 0).

Conflicting Attributes

HSM_PKCS11_DISABLE_CONFLICTING_ATTR

Allows the use of conflicting attributes (e.g. CKA_SENSITIVE and CKA_EXTRACTABLE with CK_TRUE values).

To allow the creation of objects with conflicting attributes, this environment variable must be used. Currently, this option is valid for the CKA_SENSITIVE and CKA_EXTRACTABLE attributes.

Variable not set or set to 0: does not allow the generation of objects with conflicting attributes.

Variable set to 1: allows objects with conflicting attributes to be generated.