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 (prefixed with DFENCE_PKCS11_) that must be set in the scope of the system, the user or the process that loads 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 to enter the user id (see variable DFENCE_PKCS11_SPECIAL_PWD below) there is no need to define 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 to enter the IP address of HSM (see variable DFENCE_PKCS11_SPECIAL_PWD below) the IP address defined here will be used in unauthenticated PKCS#11 functions (e.g: C_GetTokenInfo, C_GetSlotInfoetc ) and the IP address entered in pPin will be used in the authentication operation.

Special PIN

DFENCE_PKCS11_SPECIAL_PWD

Enables the passing of the user id, password and IP address of the HSM in the pPin of the PKCS#11 function C_Login.

Variable not defined or variable defined for 0parameter pPin (in function PKCS#11 C_Login) should only receive the password (password) of the HSM:

password

Variable set to 1parameter pPin (in C_Login ) should be given the user's id (userid), the password (password) the IP address of 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.

Encrypted

DFENCE_PKCS11_ENCRYPTED

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

Variable not defined or variable defined for 1the connection to the HSM will be encrypted.

Variable set to 0the connection to the HSM will be in plain 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 defined or defined in 0: auto-reconnect is disabled.

Variable defined in 1auto-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 no feature 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 1log messages are written directly to the file.

The library can keep a small buffer of log messages before physically writing to the file. This allows for performance gains. In error conditions or diagnostic situations, it is interesting that the log is written immediately after it occurs.

Large Find List

DFENCE_PKCS11_LARGE_FIND_LIST

Enables the use of search for large numbers of objects.

Variable not defined or defined for 0search: 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 1search system: uses the search system for large numbers 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 (attribute CKA_PRIVATE equal to 0).

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

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

Variable not defined or defined for 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 e 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 attributes CKA_SENSITIVE e CKA_EXTRACTABLE.

Variable not defined or defined for 0: does not allow the generation of objects with conflicting attributes.

Variable set to 1: allows the generation of objects with conflicting attributes.