Initializes the client libraries Dinamo and makes them ready for use. It must be called before any other function.
Parameters
[in]
dwReserved
Reserved for future use (must be 0).
Returns
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
Notes
This function must be called only once per program instance that loads the libraries. The DFinalize() function must be called before the program terminates.
Type of pvList: LOAD_BALANCE_LIST. Defines one or more balance lists. All the fields in the structure must be filled in. Pass the array of lists. The number of items must be entered in dwListCount up to a maximum of DN_MAX_LB_SETS. The number of HSM_ADDR structures defined per list must be a maximum of DN_MAX_LB_HSM_COUNT.
[in]
pvList
Pointer to the data or structures specified in dwParam.
[in]
dwListCount
Number of lists passed in pvList.
[in]
dwReserved
Reserved for future use (must be 0).
Returns
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
Notes
When load balancing is defined, existing sessions will be physically closed as they terminate. New sessions will be created using the definitions from the new load balancing list. If the defined list is exactly the same as the currently active list, the load balancing list will not be updated.
This function will enable load balancing even if the load balancing variable is not enabled.
Type of pvList: LOAD_BALANCE_LIST. Receives one or more balancing lists. The number of lists must be equal to or greater than the number of lists running. The number of items must be entered in dwListCount. The number of HSM_ADDR structures defined per list must be DN_MAX_LB_HSM_COUNT.
[in]
pvList
Pointer to the data or structures specified in dwParam. Can be NULL to retrieve the number of lists configured.
[in,out]
pdwListCount
The input should contain the number of lists passed into pvList. The output will contain the number of lists written to pvList. If pvList is NULL, this parameter will receive the number of lists expected.
[in]
dwReserved
Reserved for future use (must be 0).
Returns
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
pbData Type: AUTH_PWD_EX
User and password authentication with optional OTP/Certificate. All fields in the structure must be filled; only the strong authentication fields are optional.
pbData Type: AUTH_ATOKEN
Authentication using Access Tokens. All fields in the structure must be filled. See the DManageAToken() API for information on session token (Access Tokens) management.
pbData Type: AUTH_PWD_EX or AUTH_PWD
No authentication. Only the szAddr and nPort fields of the structure must be filled. In the case of AUTH_PWD_EX, fill dwAuthType with SA_AUTH_NONE.
Displays a dialog for the user to enter their identifier (ID) and password, or the path to the file containing their private key and digital certificate. Not yet supported.
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
Notes
The context returned by this function must be used in all subsequent calls to the HSM and released via the DCloseSession() function after use. A TCP connection is established in this call and terminated when the context is released.
The session is established in clear text (without encryption) if the ENCRYPTED_CONN flag is not specified; otherwise, a TLS v1.2 tunnel is established between the two ends of the channel.
Dinamo natively features a load balancing and session caching system. If load balancing is active and you need to ensure that a session is opened at a specific IP address, use the LB_BYPASS flag. With LB_BYPASS, the DOpenSession function will ignore the load balancing address list. It is not possible to disable or bypass the device's session cache using this or any other API function.
If a user's password has expired, the function will return D_ERR_PWD_EXPIRED. In this scenario, a valid session handle will be returned, which can only be used for changing the authenticated user's password. If the password change is successful, the session will have other functions enabled; if the password change fails or any other operation is attempted, the session will be disconnected by the server.
Note
HSM sessions exhibit session-thread affinity, meaning a single session cannot be concurrently utilized by multiple threads.
pbData type : DWORD Timeout in seconds for the session to remain in the cache. The default is DN_SESSION_CACHE_DEFAULT_TIMEOUT. It can also be configured globally via the HSM_SESSION_CACHE_TIMEOUT environment variable before calling DInitialize().
[in]
pbData
Pointer to the data or structures specified in dwParam.
[in]
dwDataLen
Size of the data or structure specified in dwParam.
[in]
dwFlags
Reserved for future use (must be 0).
Returns
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
Type of pbData: long *
HTTP response code of the last PIX HTTP request (POST, GET...) made in this session. This operation must be called immediately after calling the PIX request API. It must be called using the same session. Do not perform any other operations between these calls.
Type of pbData:PIX _HTTP_REQUEST_DETAILS *
Details of the last PIX HTTP request (POST, GET...) made in this session. This operation must be called immediately after calling the PIX request API. It must be called using the same session. Do not perform any other operations between these calls.
pbData type : DWORD Timeout in seconds for the session to remain in the cache. See DSetSessionParam() for details.
[out]
pbData
Pointer to the data or structures specified in dwParam. This parameter can be NULL to specify the amount of memory required.
[in,out]
pdwDataLen
Pointer to the buffer size, in bytes, specified in pbData. When the function returns, this parameter will contain the size of the data stored in pbData.
[in]
dwFlags
Reserved for future use (must be 0).
Returns
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
Forces the physical closure of the session. If the session is cached, it will be removed from the cache and physically closed.
Returns
0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.
Notes
Once released, the session context becomes invalid for use in any other function. If the context is reused, the function will return the D_INVALID_CONTEXT error code.
This function must be called only once during program termination. After its execution, any subsequent function calls will result in undefined behavior.
