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]

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.

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, sc_change_pin.c, sc_copy_set.c, sc_create_svmk. c, sc_erase . c, sc_get_set_label . c, sc_inspect. 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]	dwParam	Specifies 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]	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.

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]	dwParam	Specifies 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]	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 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]	dwReserved	Reserved 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]	phSession	Pointer to the session context. After use, it must be released with the DCloseSession() function.
[in]	dwParam	Specifies 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]	pbData	Pointer to the data or structures specified in dwParam.
[in]	dwDataLen	Size of data or structure specified in dwParam.
[in]	dwFlags	Changes 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, sc_copy_set .c, sc_create_svmk.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]	hSession	Context acquired through the DOpenSession() function.
[in]	dwParam	Specifies 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]	pbData	Pointer to the data or structures specified in dwParam.
[in]	dwDataLen	Size of data or structure specified in dwParam.
[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.

DGetSessionParam()

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

#include <dinamo.h>

Retrieves session parameters.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	dwParam	Consult 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]	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).

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]	phSession	Pointer to the session context. When the function returns this parameter, it will be equal to NULL.
[in]	dwFlags	Changes 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, sc_copy_set .c, sc_create_svmk.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, sc_change_pin.c, sc_copy_set.c, sc_create_svmk. c, sc_erase . c, sc_get_set_label . c, sc_inspect. 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.