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).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.
Notes
This function should only be called once in each instance of the program that loads the libraries. And before the program ends, the DFinalize() function must be called.
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).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.
Notes
When defining load balancing, old sessions will be physically closed as soon as they are closed. New sessions will be created using the definitions in the new balancing list. If the list defined is exactly the same as the running list, the 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).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.
Type of pbData: AUTH_PWD_EX
Authentication by user and password with optional OTP/Certificate. All the fields in the structure must be filled in, only the Strong authentication fields are optional.
Type of pbData: AUTH_ATOKEN
Authentication by Access Tokens. All fields in the structure must be filled in. See the DManageAToken() API for information on managing session tokens(Access Tokens).
Type of pbData: AUTH_PWD_EX or AUTH_PWD
No authentication. Only the szAddr and nPort fields of the structure must be filled in. In the case of AUTH_PWD_EX fill in dwAuthType with SA_AUTH_NONE.
It displays a dialog for the user to enter their identifier (ID) and password or the path of the file containing their private key and digital certificate. Not yet supported.
0 (ZERO) if the function is successful.
See 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 it has been used. 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 closed 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.
When a user's password has expired, the function will return D_ERR_PWD_EXPIRED. In this case, a valid session handle will be returned, which can only be used to change the authenticated user's password. If the password change is successful, the session will have the other functions enabled. If the password change fails or if the session tries to perform any other operation, it will be disconnected by the server.
Observation
HSM sessions have session-thread affinity. This means that the same session cannot be used by several threads at the same time.
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.
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).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.
Forces the session to be physically closed. If the session is cached, it will be removed from the cache and physically closed.
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.
Notes
The session context, once released, becomes invalid for use in any other function. If the context is used again, the function will return the error code D_INVALID_CONTEXT.
