API C/C++
HSM Dinamo
Loading...
Looking for...
No entries found
Settings and Macros | Functions
Session

Detailed description

Client session management with HSM.

See the HSM technical documentation.

Settings and Macros

#define DN_INIT_PARAM_CONF_FAST_FAIL (128)
 

Functions

int AAP_API DInitialize(DWORD dwReserved)
 
int AAP_API DSetLBList(DWORD dwParam, void *pvList, DWORD dwListCount, DWORD dwReserved)
 
int AAP_API DGetLBList(DWORD dwParam, void *pvList, DWORD *pdwListCount, DWORD dwReserved)
 
int AAP_API DOpenSession(HSESSIONCTX *phSession, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)
 
int AAP_API DSetSessionParam(HSESSIONCTX hSession, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)
 
int AAP_API DGetSessionParam(HSESSIONCTX hSession, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwFlags)
 
int AAP_API DCloseSession(HSESSIONCTX *phSession, DWORD dwFlags)
 
int AAP_API DFinalize ()
 

Definitions and macros

◆ DN_INIT_PARAM_CONF_FAST_FAIL

#define DN_INIT_PARAM_CONF_FAST_FAIL   (128)

#include <dinamo.h>

Configuration for fast failure.

Functions

◆ DInitialize()

int AAP_API DInitialize ( DWORD dwReserved)

#include <dinamo.h>

Initializes the client libraries Dinamo and makes them ready for use. It must be called before any other function.

Parameters
[in]dwReservedReserved 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.
Examples
ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenization.c, user_add_remove.c, user_otp.c and verify_pin_block.c.

◆ DSetLBList()

int AAP_API DSetLBList ( DWORD dwParam,
void * pvList,
DWORD dwListCount,
DWORD dwReserved )

#include <dinamo.h>

Defines the load balancing list. This configuration is done in real time.

Parameters
[in]dwParamSpecifies how load balancing will be defined and consequently the data structure passed in the parameter pvList.
Value Meaning
DN_LB_LIST Type of pvList: LOAD_BALANCE_LIST. Define one or more balancing 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 structures HSM_ADDR defined per list should be a maximum of DN_MAX_LB_HSM_COUNT.
[in]pvListPointer to the data or structures specified in dwParam.
[in]dwListCountNumber of lists passed in pvList.
[in]dwReservedReserved 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.

◆ DGetLBList()

int AAP_API DGetLBList ( DWORD dwParam,
void * pvList,
DWORD * pdwListCount,
DWORD dwReserved )

#include <dinamo.h>

Retrieves the list of running load balancers.

Parameters
[in]dwParamSpecifies how the load balancing recovery will be done and consequently the data structure passed in the parameter pvList.
Value Meaning
DN_LB_LIST Type of pvList: LOAD_BALANCE_LIST. It 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 structures HSM_ADDR defined by list should be DN_MAX_LB_HSM_COUNT.
[in]pvListPointer to the data or structures specified in dwParam. Can be NULL to retrieve the number of lists configured.
[in,out]pdwListCountThe input must contain the number of lists passed in pvList. The output will contain the number of lists written in pvList. Case pvList is NULL this parameter will receive the number of lists expected.
[in]dwReservedReserved for future use (must be 0).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.

◆ DOpenSession()

int AAP_API DOpenSession ( HSESSIONCTX * phSession,
DWORD dwParam,
BYTE * pbData,
DWORD dwDataLen,
DWORD dwFlags )

#include <dinamo.h>

It establishes a session with Dinamo and returns a context to be used by all other functions.

Parameters
[out]phSessionPointer to the session context. After use, it must be released with the DCloseSession() function.
[in]dwParamSpecifies how the session will be authenticated and consequently the data structure passed in the parameter pbData.
Value Meaning
SS_USER_PWD Type of pbData: AUTH_PWD Authentication by user and password. All fields in the structure must be filled in.
SS_USR_PWD_EX 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.
SS_ATOKEN 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).
SS_ANONYMOUS 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.
SS_HTTP Type of pbData: AUTH_HTTP
Authentication via HTTP at Dinamo Services. All fields in the structure must be filled in.
Not implemented.
SS_WIN_CREDENTIAL Type of pbData: AUTH_WIN_CREDENTIAL. All fields in the structure must be filled in.
[in]pbDataPointer to the data or structures specified in dwParam.
[in]dwDataLenSize of data or structure specified in dwParam.
[in]dwFlagsChanges certain behaviors of the function, can be zero.
Value Meaning
ENCRYPTED_CONN Establishes an encrypted session (TLS v1.2). Data will travel in clear text if this flag is not specified.
USER_INTERACTIVE 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.
LB_BYPASS Ignores load balancing configurations. Logging on to the HSM address indicated via pbData.
CACHE_BYPASS Ignores the session cache settings and opens this session without going through the session cache.
DS_BYPASS Ignores session settings Dinamo Services.
Return
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.
Examples
ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenization.c, user_add_remove.c, user_otp.c and verify_pin_block.c.

◆ DSetSessionParam()

int AAP_API DSetSessionParam ( HSESSIONCTX hSession,
DWORD dwParam,
BYTE * pbData,
DWORD dwDataLen,
DWORD dwFlags )

#include <dinamo.h>

Changes the session parameters.

Parameters
[in]hSessionContext acquired through the DOpenSession() function.
[in]dwParamSpecifies the session parameter to be configured and consequently the data structure passed in the parameter pbData.
Value Meaning
SP_SESSION_TIMEOUT Type of pbData: DWORD
Global session timeout in milliseconds. This timeout value only applies to the client. .
Not yet supported.
SP_SEND_TIMEOUT Type of pbData: DWORD
Timeout in milliseconds for the send function of the network subsystem.
SP_RECV_TIMEOUT Type of pbData: DWORD
Timeout in milliseconds for the recv function of the network subsystem.
[in]pbDataPointer to the data or structures specified in dwParam.
[in]dwDataLenSize of data or structure specified in dwParam.
[in]dwFlagsReserved for future use (must be 0).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.

◆ DGetSessionParam()

int AAP_API DGetSessionParam ( HSESSIONCTX hSession,
DWORD dwParam,
BYTE * pbData,
DWORD * pdwDataLen,
DWORD dwFlags )

#include <dinamo.h>

Retrieves session parameters.

Parameters
[in]hSessionContext acquired through the DOpenSession() function.
[in]dwParamConsult dwParam in DSetSessionParam(). Other dwParamDGetSessionParam:
Value Meaning
SP_SESSION_ID Type of pbData: DWORD
Session identifier on the server.
Not yet supported.
SP_SESSION_CIPHER Type of pbData: char *
Algorithms negotiated in the TLS session. Maximum size MAX_CHANNEL_CIPHER_NAME_LEN
SP_SESSION_PIX_HTTP_RET 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.
SP_SESSION_PIX_HTTP_REQ_DETAILS 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.
SP_HSM_OP_MODE Type of pbData: DWORD *
HSM operating mode. Can have the values DN_HSM_OP_NRM, DN_HSM_OP_RM1, DN_HSM_OP_RM2 etc.
[out]pbDataPointer to the data or structures specified in dwParam. This parameter can be NULL to specify the amount of memory required.
[in,out]pdwDataLenPointer 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]dwFlagsReserved for future use (must be 0).
Return
0 (ZERO) if the function is successful.
See the Return Codes section for other values.

◆ DCloseSession()

int AAP_API DCloseSession ( HSESSIONCTX * phSession,
DWORD dwFlags )

#include <dinamo.h>

Ends a session with Dinamo and releases its context.

Parameters
[in,out]phSessionPointer to the session context. When the function returns this parameter, it will be equal to NULL.
[in]dwFlagsChanges certain behaviors of the function, can be zero.
Value Meaning
CLOSE_PHYSICALLY 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.
Examples
ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenization.c, user_add_remove.c, user_otp.c and verify_pin_block.c.

◆ DFinalize()

int AAP_API DFinalize ( )

#include <dinamo.h>

Finalizes the client libraries Dinamo.

Return
0 (ZERO)
Notes
This function should only be called once at the end of the program. After its execution, any other function called will have undefined behavior.
Examples
ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenization.c, user_add_remove.c, user_otp.c and verify_pin_block.c.
Generated by Doxygen / Doxygen Awesome