Detailed description

HSM Management.

HSM Management. More...

Settings and Macros
#define	DN_NT_MAX_TARGET_LEN (255)

#define	DN_NTOOL_PING (1)

#define	DN_NTOOL_TRACERT (2)

#define	DN_NTOOL_CROSS_CHECK (100)

#define	DN_WRITE_FILE_OPT_CERT_CHAIN (1)

#define	DN_WRITE_FILE_OPT_NO_CONVERSION (2)

#define	DN_ATOKEN_CACHE_GET_COUNT (0)

#define	DN_ATOKEN_CACHE_GC (1)

#define	DN_SC_SHADOW_LEN (24)

#define	DN_SC_MAX_PIN_LEN (8)

#define	DN_S_NSAUTH_ASSOC (1)

#define	DN_S_NSAUTH_RESET (2)

#define	DN_S_NSAUTH_AUTH (3)

#define	DN_S_NSAUTH_eAUTH (4)

#define	DN_S_NSAUTH_CHECK (5)

Type Definitions
typedef int(AAP_API *	funcListKeyCallback) (char szKeyName, void pParam, BOOL bFinal)

typedef int(AAP_API *	funcLogEventCallback) (char szEvent, void pParam, BOOL bFinal)

typedef int(AAP_API *	funcReadLocalFileCallback)(BYTE pbData, DWORD pdwDataLen, void pParam, BOOL pbFinal)

typedef int(AAP_API *	funcWriteLocalFileCallback)(BYTE pbData, DWORD dwDataLen, void pParam, BOOL bFinal)

typedef int(AAP_API *	funcListAKeysCallback) (void pvToken, void pParam, BOOL bFinal)

Enumerations
enum	RetCodeMsgType { CODE_MSG = 1 , DESC_MSG }

Functions
int AAP_API	DListObjs (HSESSIONCTX hSession, funcListKeyCallback fncallback, void *pParam)

int AAP_API	DListBlobs (HSESSIONCTX hSession, funcListKeyCallback fncallback, void *pParam)

int AAP_API	DBackupData (HSESSIONCTX hSession, char szBackupFile, char szPin, int nDirection)

int AAP_API	DBackupObject (HSESSIONCTX hSession, DWORD dwOP, char szObjectId, char szPin, BYTE pbData, DWORD pdwDataLen, DWORD dwReserved)

int AAP_API	DGetLogEvents (HSESSIONCTX hSession, funcLogEventCallback fncallback, void *pParam)

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

int AAP_API	DGetHSMTLSCert (char szAddress, int nPort, DWORD dwOutFormat, BYTE ppbOutCert, DWORD pdwOutCertLen, DWORD dwFlags)

int AAP_API	DHSMTool (HSESSIONCTX hSession, DWORD dwOption, const char szTarget, void pvResult, DWORD pdwResultLen, DWORD dwFlags)

int AAP_API	DWriteFileBuffer (HSESSIONCTX hSession, const char szFileId, BYTE pbFile, DWORD dwFileSize, DWORD dwOptions)

int AAP_API	DWriteFile (HSESSIONCTX hSession, char szFileId, DWORD dwFileSize, funcReadLocalFileCallback fncallback, void pParam)

int AAP_API	DReadFile (HSESSIONCTX hSession, char szFileId, funcWriteLocalFileCallback fncallback, void pParam)

int AAP_API	DReadFileBuffer (HSESSIONCTX hSession, const char szFileId, BYTE ppbData, DWORD pdwDataLen, DWORD dwReserved)

int AAP_API	DRemoveObj (HSESSIONCTX hSession, char *szObjId)

int AAP_API	DGetStatLog (HSESSIONCTX hSession, DWORD dwStart, DWORD dwOffset, DWORD pdwLogSize, BYTE *ppbLog)

int AAP_API	DTruncateLog (HSESSIONCTX hSession)

int AAP_API	DFindHSM (DWORD dwServiceType, DWORD dwFilter, void *ppvOutputData, DWORD pdwOutputDataLen, DWORD dwFlags)

int AAP_API	DManageAToken (HSESSIONCTX hSession, BYTE bOP, DN_A_TOKEN_FULL pstATokenFull, funcListAKeysCallback fnCallBack, void pvCallbackParam, DWORD dwParam)

int AAP_API	DManageATokenCache (HSESSIONCTX hSession, DWORD dwOP, void *pOutData, DWORD dwParam)

int AAP_API	DDSBindHSM (HSESSIONCTX hSession, const char *szBindKey, DWORD dwReserved)

int AAP_API	DDSUnbindHSM (HSESSIONCTX hSession, DWORD dwReserved)

int AAP_API	DSCGetShadow (const char szPin, DN_M_OF_N_PART pstPart, DWORD dwReserved)

int AAP_API	DNSAuthSetState (HSESSIONCTX hSession, DWORD dwAcl, BYTE bState, DN_M_OF_N_PART *pstParts, DWORD dwPartsCount, DWORD dwReserved)

int AAP_API	DGetErrorString (int nErrorValue, char szErrorCode, char szErrorDesc)

const char *AAP_API	DGetReturnCodeString (int nErrorValue, RetCodeMsgType eErrorType)

Definitions and macros

◆ DN_NT_MAX_TARGET_LEN

#define DN_NT_MAX_TARGET_LEN (255)

#include <dinamo.h>

◆ DN_NTOOL_PING

#define DN_NTOOL_PING (1)

#include <dinamo.h>

◆ DN_NTOOL_TRACERT

#define DN_NTOOL_TRACERT (2)

#include <dinamo.h>

◆ DN_NTOOL_CROSS_CHECK

#define DN_NTOOL_CROSS_CHECK (100)

#include <dinamo.h>

◆ DN_WRITE_FILE_OPT_CERT_CHAIN

#define DN_WRITE_FILE_OPT_CERT_CHAIN (1)

#include <dinamo.h>

◆ DN_WRITE_FILE_OPT_NO_CONVERSION

#define DN_WRITE_FILE_OPT_NO_CONVERSION (2)

#include <dinamo.h>

◆ DN_ATOKEN_CACHE_GET_COUNT

#define DN_ATOKEN_CACHE_GET_COUNT (0)

#include <dinamo.h>

◆ DN_ATOKEN_CACHE_GC

#define DN_ATOKEN_CACHE_GC (1)

#include <dinamo.h>

◆ DN_SC_SHADOW_LEN

#define DN_SC_SHADOW_LEN (24)

#include <dinamo.h>

Shadow size of a smart card M of N Dinamo.

◆ DN_SC_MAX_PIN_LEN

#define DN_SC_MAX_PIN_LEN (8)

#include <dinamo.h>

Maximum PIN size for a smart card M of N Dinamo.

◆ DN_S_NSAUTH_ASSOC

#define DN_S_NSAUTH_ASSOC (1)

#include <dinamo.h>

Set the associated state.

◆ DN_S_NSAUTH_RESET

#define DN_S_NSAUTH_RESET (2)

#include <dinamo.h>

Reset NSAuth state. Not associated and not authorized.

◆ DN_S_NSAUTH_AUTH

#define DN_S_NSAUTH_AUTH (3)

#include <dinamo.h>

Set the authorized state. Not available yet.

◆ DN_S_NSAUTH_eAUTH

#define DN_S_NSAUTH_eAUTH (4)

#include <dinamo.h>

Set the session's state to authorized. The ACL must be set with DN_S_NSAUTH_ASSOC first.

◆ DN_S_NSAUTH_CHECK

#define DN_S_NSAUTH_CHECK (5)

#include <dinamo.h>

Check the shadow share set. This flag doesn't change the NSAuth state.

Type definitions

◆ funcListKeyCallback

typedef int(AAP_API * funcListKeyCallback) (char *szKeyName, void *pParam, BOOL bFinal)

#include <dinamo.h>

Pointer to callback function for listing objects.

Parameters

[in]	szKeyName	Object name.
[in]	pParam	Pointer to a parameter passed to the DListObjs() function.
[in]	bFinal	Flag indicating the last record.

Return: 0

◆ funcLogEventCallback

typedef int(AAP_API * funcLogEventCallback) (char *szEvent, void *pParam, BOOL bFinal)

#include <dinamo.h>

Pointer to a callback function to record the events generated by the server.

Parameters

[in]	szEvent	Log event.
[in]	pParam	Pointer to a parameter passed to the DgetLogEvents function.
[in]	bFinal	Indicates the end of event sending.

Return: 0

◆ funcReadLocalFileCallback

typedef int(AAP_API * funcReadLocalFileCallback)(BYTE *pbData, DWORD *pdwDataLen, void *pParam, BOOL *pbFinal)

#include <dinamo.h>

Pointer to callback function to read the file to be uploaded to the HSM.

Parameters

[in]	pbData	Buffer containing the read data.
[in]	pdwDataLen	Pointer to a DWORD containing the number of bytes read from the file
[in]	pParam	Pointer to a parameter passed to the DWriteFile() function.
[in]	pbFinal	Flag indicating the end of the file.

Return: 0

◆ funcWriteLocalFileCallback

typedef int(AAP_API * funcWriteLocalFileCallback)(BYTE *pbData, DWORD dwDataLen, void *pParam, BOOL bFinal)

#include <dinamo.h>

Pointer to callback function to locally save the file retrieved from the HSM.

Parameters

[in]	pbData	Buffer with the data that will be written to the file.
[in]	dwDataLen	Number of bytes to be recorded.
[in]	pParam	Pointer to a parameter passed to the DWriteFile() function.
[in]	bFinal	Flag indicating the end of the file.

Return: 0

◆ funcListAKeysCallback

typedef int(AAP_API * funcListAKeysCallback) (void *pvToken, void *pParam, BOOL bFinal)

#include <dinamo.h>

Pointer to callback function for listing session tokens in DManageAToken().

Parameters

[in]	pvToken	Pointer that will receive a DN_A_TOKEN_FULL structure containing the session token data.
[in]	pParam	Pointer to a parameter passed to the DManageAToken() function.
[in]	bFinal	Flag indicating the last record.

Return: 0

Enumerations

◆ RetCodeMsgType

enum RetCodeMsgType

#include <dinamo.h>

Enumeration of return code message types.

Enumerators
CODE_MSG	Returns the text of the return code.
DESC_MSG	Returns the description of the return code.

Functions

◆ DListObjs()

int AAP_API DListObjs	(	HSESSIONCTX	hSession,
		funcListKeyCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Lists the objects stored on Dinamo, including keys and files.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	fncallback	Pointer to a callback function used to list the names (identifiers) of objects.
[in]	pParam	Pointer to any parameter that will be passed to the callback function

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: API functions Dinamo must not be called from within the callback function (parameter fncallback) using the same context (parameter hSession) passed to the DListObjs() function. When necessary, use a different session context.

Examples: list_keys.c.

◆ DListBlobs()

int AAP_API DListBlobs	(	HSESSIONCTX	hSession,
		funcListKeyCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Lists the blobs stored on Dinamo.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	fncallback	Pointer to a callback function used to list the names (identifiers) of the blobs.
[in]	pParam	Pointer to any parameter that will be passed to the callback function

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: API functions Dinamo must not be called from within the callback function (parameter fncallback) using the same context (parameter hSession) passed to the DListBlobs() function. When necessary, use a different session context.

◆ DBackupData()

int AAP_API DBackupData	(	HSESSIONCTX	hSession,
		char *	szBackupFile,
		char *	szPin,
		int	nDirection )

#include <dinamo.h>

Creates or restores the backup of objects (keys, certificates, etc.) stored internally on Dinamo.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] szBackupFile Path of the backup file.

[in] szPin Password for protecting the backup file. Must be ASCII characters. The length must be between MIN_BACKUP_PIN_LEN and MAX_BACKUP_PIN_LEN.

[in]

nDirection

[in] Specifies the action to be performed.

Value	Meaning
MAKE_BACKUP	The backup file will be created, if it exists, it will be overwritten.
MAKE_RESTORE_WITHOUT_NET_CONFIG	The existing backup data, not including network parameters, in the file indicated by szBackupFile will be restored.
MAKE_RESTORE_WITH_NET_CONFIG	The existing backup data, including network parameters, in the file indicated by szBackupFile will be restored.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: This function creates or recovers a backup copy of the objects stored on the system to or from an encrypted file. The encryption and decryption key is derived from the password entered by the user. This encryption/decryption operation is independent of how the object is stored on Dinamo (encrypted or unencrypted). The backup copy is always encrypted. The password used to generate the backup must be used when restoring. You can indicate whether or not the network parameters (IP address, mask and gateway) should be restored. To restore large files, over 2147483647 bytes, the HSM server must be at least version 3.9.0.2 or higher.

Observation: Objects marked as non-exportable on Dinamo will also be included in the backup copy. This operation is not selective, i.e. all objects in the Dinamo storage area will be copied.

◆ DBackupObject()

int AAP_API DBackupObject	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		char *	szObjectId,
		char *	szPin,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Creates or restores the backup of a specific object in the HSM.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwOP

Specifies the action to be performed.

Value Meaning

D_BACKUP_OBJ Backs up the object specified in szObjectId and writes the content to pbData. pdwDataLen should contain the size of the buffer pointed to by pbData and at the end of the call you will receive the total bytes copied to pbData. Case pbData is NULL, pdwDataLen will receive the buffer size pbData needed to accommodate the backup. You can use a buffer greater than or equal to D_MAX_BACKUP_OBJ_LEN to avoid an extra call to this function, just to retrieve the required backup buffer size.

D_RESTORE_OBJ Restores the object's backup. szObjectId should contain the name that the restored object will have within the HSM. pbData should contain the buffer of the backup that will be restored and pdwDataLen the size of pbData.

[in] szObjectId Name of the object within the HSM.

[in] szPin Password for protecting the backup file. Must be ASCII characters. The length must be between MIN_BACKUP_PIN_LEN and MAX_BACKUP_PIN_LEN.

[in,out] pbData Buffer containing the object's backup. See options in dwOP for more details.

[in,out] pdwDataLen Backup size. See options in dwOP for more details.

[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 creates or recovers a backup copy of a specific object (a key, for example) to or from an encrypted file. The backup is always encrypted with two layers: first with the HSM's Server Master Key (SVMK) and second with the encryption key derived from the password entered by the user. The password used to generate the backup must be used when restoring.

As the object was encrypted by the SVMK, it can only be restored on HSMs Dinamo initialized with the same SVMK. From a security point of view, the object contained in the backup is still protected by the HSM's cryptographic boundary.

Different lines of HSM models Dinamo may have different methods for deriving SVMK from the seed. The backups generated in XP and ST models are interoperable with each other, but not with model backups Pocket.

Observation: The backup can be performed with exportable or non-exportable objects and this state is preserved in the restore. Only the object specified in szObjectId will be included in the backup.

◆ DGetLogEvents()

int AAP_API DGetLogEvents	(	HSESSIONCTX	hSession,
		funcLogEventCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Retrieves the log events generated by the server.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	fncallback	Pointer to a callback function used to record events generated by the server.
[in]	pParam	Pointer to any parameter that will be passed to the callback function.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: This option allows a program to receive log messages generated internally on Dinamo; the program then receives a copy of all log messages. There is a limit of 03 (three) receivers simultaneously receiving event notifications, to avoid degrading the HSM's performance. The messages sent continue to be recorded in the server's internal file. The first hexadecimal value shown in the log line is a timestamp and the second is an ID used internally.

Examples: get_rt_logs.c.

◆ DAdmOperation()

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

#include <dinamo.h>

Performs administrative operations on the server.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwParam

Specifies the operation that will be performed and consequently the structure or data passed in the parameter pbData.

Value	Meaning
AO_SHUTDOWN	Type of `pbData:` NULL Turn off the HSM. At this point you will need to intervene manually to make the server available again, i.e. you will need to turn on the equipment and insert the operation card. Not yet supported
AO_RESTART	Type of `pbData:` NULL Restart the HSM. At this point you will need to intervene manually to make the server available again, i.e. insert the operation card. Not yet supported.
AO_KEEPALIVE	Type of `pbData:` NULL It performs a simple exchange of messages between the client and the server in order to maintain the established connection.
TO_SET_DATE_TIME	Type of `pbData:` struct tm (time.h) Set the date and time of the HSM. The default GMT (Greenwich Mean Time) time (no time zone) must be entered.
AO_SET_PWD_SEC_POLICY	Type of `pbData:` PWD_SEC_POLICY Defines the parameters of the HSM's security policy.
AO_GET_PWD_SEC_POLICY	Type of `pbData:` PWD_SEC_POLICY Retrieves the parameters of the HSM security policy.
AO_SET_TLS_BUNDLE	Type of `pbData:` TLS_BUNDLE_INFO Defines the key and certificate that will be used by the HSM's TLS.
TO_EFTD_ACTIVATE	Type of `pbData:` NULL Activates the EFTd module. Currently only user DN_EFTD_DEFAULT_USER is allowed for this operation.
TO_EFTD_DEACTIVATE	Type of `pbData:` NULL Deactivates the EFTd module. Currently only the DN_EFTD_DEFAULT_USER is allowed for this operation.
TO_EFTD_RESET_CONF	Type of `pbData:` NULL Returns the EFTd module settings to the factory settings. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation.
TO_EFTD_GET_CONF	Type of `pbData:` *DN_EFTD_CONF Retrieves settings from the EFTd module. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation.
TO_EFTD_SET_MSG_HEADER_LEN	Type of `pbData:` *BYTE Defines the header size of EFTd module messages. Accepts values between DN_EFTD_MIN_MSG_HEADER_LEN e DN_EFTD_MAX_MSG_HEADER_LEN. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation.
TO_EFTD_SET_PIN_LEN	Type of `pbData:` *BYTE Sets the pin size of the EFTd module. Accepts values between DN_EFTD_MIN_PIN_LEN e DN_EFTD_MAX_PIN_LEN. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation.
AO_GET_GLOBAL_OBJ_STATS	Type of `pbData:` *DN_GLOBAL_OBJ_STATS Retrieves global object statistics. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation.
AO_GET_SEC_POLICY_GFLAGS	Type of `pbData:` *DWORD Retrieves the HSM security flags. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation.
AO_SET_SEC_POLICY_GFLAGS	Type of `pbData:` DWORD Sets the HSM security flags. Only users with ACL_USR_REMOTE_INFO or ACL_SYS_OPERATOR are authorized for this operation. See supported values in the comments.

[in] pbData Pointer to the data or structures specified in dwParam.

[in] dwDataLen Size of data or structure specified in dwParam.

[in]

dwFlags

It must be 0 or one of the values below.

Value	Meaning
TO_KEEPALIVE_FLAG_NOISELESS	Type of `dwParam:` AO_KEEPALIVE Causes the keep alive operation not to generate logs in the HSM.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: The AO_KEEPALIVE option runs a heartbeat test on the Dinamo service. A positive result shows that the HSM is processing client requests correctly and that its internal state is consistent and intact. It can be used, for example, by monitoring and support teams to indicate the OK status of Dinamo.

The AO_GET_SEC_POLICY_GFLAGS and AO_SET_SEC_POLICY_GFLAGS options support the following values:

Value	Meaning
DN_SEPOL_GF_ENABLE_HTTP_X509_SA	Enables authentication of HTTP clients by X.509 certificates.
DN_SEPOL_GF_ENABLE_NSA_API_AUTH	Enables M of N partition authentication via API.

Examples: connect_hsm.c.

◆ DGetHSMTLSCert()

int AAP_API DGetHSMTLSCert	(	char *	szAddress,
		int	nPort,
		DWORD	dwOutFormat,
		BYTE **	ppbOutCert,
		DWORD *	pdwOutCertLen,
		DWORD	dwFlags )

#include <dinamo.h>

Retrieves the HSM certificate used in TLS.

Parameters

[in] szAddress HSM address.

[in] nPort HSM access port. The default port is DEFAULT_PORT.

[in]

dwOutFormat

Certificate output format.

Value	Meaning
CERT_OUT_DER	Exports the server's certificate in X.509 DER format.
CERT_OUT_DER	Exports the server's certificate in X.509 PEM format.

[in] ppbOutCert Pointer with the certificate in the format specified in dwOutFormat. This pointer must be released with DFree.

[in] pdwOutCertLen Certificate size indicated in ppbOutCert.

[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.

◆ DHSMTool()

int AAP_API DHSMTool	(	HSESSIONCTX	hSession,
		DWORD	dwOption,
		const char *	szTarget,
		void **	pvResult,
		DWORD *	pdwResultLen,
		DWORD	dwFlags )

#include <dinamo.h>

Run test tools from the HSM.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwOption

Operating option.

Value	Meaning
DN_NTOOL_PING	Performs a PING operation from the HSM. `pvResult` will contain a string.
DN_NTOOL_TRACERT	Performs a TRACERT operation from the HSM. `pvResult` will contain a string.
DN_NTOOL_CROSS_CHECK	Performs a cross-check operation from the HSM. `pvResult` will contain a vector of structures CROSS_CHECK_NODE.

[in] szTarget Target address of the operation to be executed. Maximum size of DN_NT_MAX_TARGET_LEN.

[out] pvResult Pointer that will contain the result of the command executed. This pointer must be freed with DFree.

[out] pdwResultLen Size of the buffer returned in pvResult.

[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.

◆ DWriteFileBuffer()

int AAP_API DWriteFileBuffer	(	HSESSIONCTX	hSession,
		const char *	szFileId,
		BYTE *	pbFile,
		DWORD	dwFileSize,
		DWORD	dwOptions )

#include <dinamo.h>

Import a file into HSM.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] szFileId Identifier of the new file within the HSM.

[in] pbFile Buffer containing the file to be imported.

[in]

dwFileSize

Size of the file to be uploaded.

[in] dwOptions Value

Meaning

DN_WRITE_FILE_OPT_CERT_CHAIN

The file provided is a certificate chain. Do not use this option with other file types.

DN_WRITE_FILE_OPT_NO_CONVERSION

The file will be imported without format conversion.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The recorded file is opaque to the HSM, is protected by SVMK (Server Master Key) and will always be an exportable object.
The maximum file size accepted by HSM is 64 Kb.
The files sent to the HSM, described in the table below, will have their types detected automatically.

Type	Format
X.509 certificates	DER or PEM
CRL (Certificate Revocation List) or LCR (List of Revoked Certificates)	DER or PEM
PKCS#7 certificate chains	DER or PEM (PEM detection requires the use of the DN_WRITE_FILE_OPT_CERT_CHAIN flag)

Examples: pkcs7_sign.c, sign_check_pix_jws.c, sign_verify_dict.c, sign_verify_pix.c and sign_verify_xml.c.

◆ DWriteFile()

int AAP_API DWriteFile	(	HSESSIONCTX	hSession,
		char *	szFileId,
		DWORD	dwFileSize,
		funcReadLocalFileCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Import a file into HSM.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szFileId	Identifier of the new file within the HSM.
[in]	dwFileSize	Size of the file to be uploaded.
[in]	fncallback	Pointer to a callback function used to read the file to be loaded.
[in]	pParam	Pointer to any parameter that will be passed to the callback function.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The recorded file is opaque to the HSM and will not be encrypted internally and will always be an exportable object.
The maximum file size accepted by HSM is 512kb.
The files sent to the HSM, described in the table below, will have their types detected automatically.

Type	Format
X.509 certificates	DER
CRL (Certificate Revocation List) or LCR (List of Revoked Certificates)	DER
PKCS#7 certificate chains	DER

◆ DReadFile()

int AAP_API DReadFile	(	HSESSIONCTX	hSession,
		char *	szFileId,
		funcWriteLocalFileCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Export an HSM file.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szFileId	File identifier within the HSM.
[in]	fncallback	Pointer to a callback function used to write the retrieved file.
[in]	pParam	Pointer to any parameter that will be passed to the callback function.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: This API should not be used to export keys.

◆ DReadFileBuffer()

int AAP_API DReadFileBuffer	(	HSESSIONCTX	hSession,
		const char *	szFileId,
		BYTE **	ppbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Exports an HSM file to a buffer.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szFileId	File identifier within the HSM.
[out]	ppbData	Pointer that will receive the data from the read file. Memory is allocated internally. The memory must be freed with DFree().
[out]	pdwDataLen	Receives the size of the buffer allocated in `ppbData`.
[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 API should not be used to export keys.

◆ DRemoveObj()

int AAP_API DRemoveObj	(	HSESSIONCTX	hSession,
		char *	szObjId )

#include <dinamo.h>

Removes an object stored on Dinamo, whether it's a key or a file.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szObjId	Identifier of the object within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: ckd_bchain.c, gen_ecdh.c, gen_xecdh.c, get_key_info_bchain.c, get_pub_key_bchain.c, import_export_bchain. c and sign_verify_bchain.c.

◆ DGetStatLog()

int AAP_API DGetStatLog	(	HSESSIONCTX	hSession,
		DWORD	dwStart,
		DWORD	dwOffset,
		DWORD *	pdwLogSize,
		BYTE **	ppbLog )

#include <dinamo.h>

Retrieves the contents of the server log.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	dwStart	Starting position, in bytes, of the log to be retrieved. To receive the entire contents of the log, enter GET_LOG_START_FULL.
[in]	dwOffset	Amount, in bytes, to be retrieved from the starting position indicated by `dwStart`. To receive the entire contents of the log, indicate GET_LOG_END_FULL .
[out]	pdwLogSize	Pointer to DWORD that will contain the amount, in bytes, of the retrieved log.
[out]	ppbLog	Pointer to the pointer that will contain the log retrieved from the server. Memory allocation is done internally by the library. The calling application is responsible for freeing the allocated memory. See the DFree() function.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

See also: DGetStatLogSize(), DTruncateLog()

Examples: download_log.c.

◆ DTruncateLog()

int AAP_API DTruncateLog ( HSESSIONCTX hSession )

#include <dinamo.h>

Allows you to delete the contents of the server log.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

See also: DGetStatLogSize(), DGetStatLog()

◆ DFindHSM()

int AAP_API DFindHSM	(	DWORD	dwServiceType,
		DWORD	dwFilter,
		void **	ppvOutputData,
		DWORD *	pdwOutputDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Searches for available HSMs on the network using the SLP protocol via multicast.

Parameters

[in]

dwServiceType

Defines the type of HSM service that will be searched for.

Value	Meaning
DN_FIND_SRVC_TYPE_IP	Lists all IP-type services found. Lists all available IP interfaces. The same HSM can be listed more than once with different IPs. The value of `dwFilter` should be DN_FIND_FILTER_TYPE_ALL.
DN_FIND_SRVC_TYPE_AAP	Lists all AAP-type services found. Lists all HSMs that have the service running.
DN_FIND_SRVC_TYPE_ALL	Lists all types of service.

[in]

dwFilter

Defines the type of filter to be used in the search.

Value	Meaning
DN_FIND_FILTER_TYPE_POCKET	Lists all the HSMs Pocket found.
DN_FIND_FILTER_TYPE_HSM	Lists all HSM DINAMO ST or XP found.
DN_FIND_FILTER_TYPE_ALL	Lists all HSM DINAMO ST, XP or Pocket found.

[out] ppvOutputData Pointer, of type SLP_SRVR_INFO, which will contain the list of HSMs found. Memory allocation is done internally by the library. The calling application is responsible for freeing the allocated memory. See the DFree() function.

[out] pdwOutputDataLen Pointer to DWORD that will contain the number of structures (described in dwOutputType) returned in ppvOutputData.

[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.

Notes: The search is carried out using SLP (Service Location Protocol) via multicast. All HSMs that are accessible and running the service will appear in this list.

◆ DManageAToken()

int AAP_API DManageAToken	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		DN_A_TOKEN_FULL *	pstATokenFull,
		funcListAKeysCallback	fnCallBack,
		void *	pvCallbackParam,
		DWORD	dwParam )

#include <dinamo.h>

Manages the user's ownaccess tokens.

Observation: When designing the application, take into account the fact that Access Tokens are volatile, as detailed below.

For authentication using session tokens, see the DOpenSession() function with the SS_ATOKEN option.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

bOP

Specifies the operation to be performed.

Value	Meaning
DN_A_TOKEN_OP_ISSUE	Issues a session token. Fill in the parameter `qwExpiration` entry into `pstATokenFull`, which on return from the API will receive the issued token. Pass NULL in `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_REVOKE	Revoke a session token if it exists. Fill in the parameter `Key` entry into `pstATokenFull`. Pass NULL in `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_L_ISSUE	Issues a session token. Only to the connected HSM, does not replicate the session token. Fill in the parameter `qwExpiration` entry into `pstATokenFull`, which on return from the API will receive the issued token. Pass NULL in `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_L_REVOKE	Revokes a session token if it exists. Only for the connected HSM, does not replicate the session token. Fill in the `Key` entry into `pstATokenFull`. Pass NULL in `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_LIST	Lists all active tokens for this user. The callback function must be passed in `fnCallBack`. Pass NULL in `pstATokenFull`;

[in,out] pstATokenFull Pointer to a structure of type DN_A_TOKEN_FULL. See option bOP for instructions on how to fill in the structure.

[in] fnCallBack Pointer to callback function of type funcListAKeysCallback. Can be NULL. See option bOP for instructions on how to fill in the structure.

[in] pvCallbackParam Pointer to any parameter that will be passed to the callback function. Can be NULL.

[in] dwParam Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

Access Tokens are kept in volatile memory, so they are erased when the HSM is restarted. Despite being volatile, Access Tokens are replicated between HSMs.

The cleaning of expired Access Tokens takes place in 2 stages:

when a user who has expired Access Tok ens makes a login attempt using Access Tokens. Clears only the Access Tokens themselves.
using the DManageATokenCache() function. Clears all expired Access Tokens from the HSM.

The maximum limit of Access Tokens issued per HSM can be seen in the table below.

Model	Maximum limit
Pocket	1024
XP	1 Million
ST	1 Million

This operation is available from version 3.17 of the HSM firmware. The implementation of Access Tokens prior to firmware version 3.17 is legacy.

Applications that use this functionality must update the HSM client to version 3.2.18 or higher, along with the HSM firmware to version 3.17 or higher.

There is no compatibility between new and old versions of the HSM client and firmware.

◆ DManageATokenCache()

int AAP_API DManageATokenCache	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		void *	pOutData,
		DWORD	dwParam )

#include <dinamo.h>

Manages the cache of session tokens(Access Tokens) for the entire HSM. This functionality is suitable for granular control of application authentication, where the issuing of tokens is managed by the security officer.

For authentication using session tokens, see the DOpenSession() function with the SS_ATOKEN option. Access tokens are issued using the DManageAToken() function.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwOP

Specifies the operation to be performed.

Value	Meaning
DN_ATOKEN_CACHE_GET_COUNT	Retrieves the number of session tokens from the entire HSM. Pass in `pOutData` a DWORD that will receive the total number of HSM session tokens.
DN_ATOKEN_CACHE_GC	Runs the Garbage Collector for HSM session tokens. This option cleans up all HSM Access Tokens that are no longer valid. Pass NULL in `pOutData`.

[out] pOutData Output data. See usage options in dwOP.

[in] dwParam 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 operation is available from version 3.17 of the HSM firmware and from version 3.2.18 of the HSM client.
The DN_ATOKEN_CACHE_GC option must be called periodically by the application to keep the Access Token cache levels under control. The GC execution schedule must be programmed taking into account the times when HSM workloads are highest.

◆ DDSBindHSM()

int AAP_API DDSBindHSM	(	HSESSIONCTX	hSession,
		const char *	szBindKey,
		DWORD	dwReserved )

#include <dinamo.h>

Link an HSM to a Dinamo Services account.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szBindKey	Link key. Generated on the Dinamo Services website.
[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.

◆ DDSUnbindHSM()

int AAP_API DDSUnbindHSM	(	HSESSIONCTX	hSession,
		DWORD	dwReserved )

#include <dinamo.h>

Disassociates an HSM from a Dinamo Services account.

Parameters

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

◆ DSCGetShadow()

int AAP_API DSCGetShadow	(	const char *	szPin,
		DN_M_OF_N_PART *	pstPart,
		DWORD	dwReserved )

#include <dinamo.h>

Reads the shadow of a smart card M from N Dinamo.

Parameters

[in]	szPin	Card PIN. It must be an ASCII numeric string with a maximum length of DN_SC_MAX_PIN_LEN.
[out]	pstPart	Data from the shadow read. The details can be seen with the DN_M_OF_N_PART_DETAILS structure.
[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.

◆ DNSAuthSetState()

int AAP_API DNSAuthSetState	(	HSESSIONCTX	hSession,
		DWORD	dwAcl,
		BYTE	bState,
		DN_M_OF_N_PART *	pstParts,
		DWORD	dwPartsCount,
		DWORD	dwReserved )

#include <dinamo.h>

Sets the authorization status of the M of N partition.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwAcl

User ACL.

Value	Meaning
NSAUTH_ACL_NOP	Without permission.
NSAUTH_ACL_OBJ_OPEN	Permission to open/use objects. Set by default.
NSAUTH_ACL_OBJ_EXPORT	Permission to export objects.
NSAUTH_ACL_OBJ_DEL	Permission to delete objects.
NSAUTH_ACL_OBJ_BLOCK	Permission to lock objects.
NSAUTH_ACL_NS_DEL	Permission to delete the namespace. The user must be in the associated state in order to be removed.

[in]

bState

State to be defined.

Value	Meaning
DN_S_NSAUTH_ASSOC	Define the associated state. Enter the user's ACL.
DN_S_NSAUTH_RESET	Reset NSAuth status. Not associated and not authorized. Pass NSAUTH_ACL_NOP in `dwAcl`.
DN_S_NSAUTH_AUTH	Sets the authorized status. Not yet available.
DN_S_NSAUTH_eAUTH	Sets the session state to authorized. The ACL must be set to DN_S_NSAUTH_ASSOC first. Pass NSAUTH_ACL_NOP in `dwAcl`.
DN_S_NSAUTH_CHECK	Checks the set of shadows. This flag does not change the NSAuth state. Pass NSAUTH_ACL_NOP in `dwAcl`.

[in] pstParts Data from the M-partition of N.

[in] dwPartsCount Number of parts.

[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.

◆ DGetErrorString()

int AAP_API DGetErrorString	(	int	nErrorValue,
		char *	szErrorCode,
		char *	szErrorDesc )

#include <dinamo.h>

Obsolete: This API is discontinued, use DGetReturnCodeString().

◆ DGetReturnCodeString()

const char *AAP_API DGetReturnCodeString	(	int	nErrorValue,
		RetCodeMsgType	eErrorType )

#include <dinamo.h>

Retrieves the description of a return code from the APIs DINAMO.

Parameters

[in] nErrorValue Return code.

[in]

eErrorType

Return string type.

Value	Meaning
CODE_MSG	Returns the text of the return code.
DESC_MSG	Returns the description of the return code.

Return: Returns the string as defined in eErrorType.

Detailed description

Settings and Macros

Type Definitions

Enumerations

Functions

Definitions and macros

◆ DN_NT_MAX_TARGET_LEN

◆ DN_NTOOL_PING

◆ DN_NTOOL_TRACERT

◆ DN_NTOOL_CROSS_CHECK

◆ DN_WRITE_FILE_OPT_CERT_CHAIN

◆ DN_WRITE_FILE_OPT_NO_CONVERSION

◆ DN_ATOKEN_CACHE_GET_COUNT

◆ DN_ATOKEN_CACHE_GC

◆ DN_SC_SHADOW_LEN

◆ DN_SC_MAX_PIN_LEN

◆ DN_S_NSAUTH_ASSOC

◆ DN_S_NSAUTH_RESET

◆ DN_S_NSAUTH_AUTH

◆ DN_S_NSAUTH_eAUTH

◆ DN_S_NSAUTH_CHECK

Type definitions

◆ funcListKeyCallback

◆ funcLogEventCallback

◆ funcReadLocalFileCallback

◆ funcWriteLocalFileCallback

◆ funcListAKeysCallback

Enumerations

◆ RetCodeMsgType

Functions

◆ DListObjs()

◆ DListBlobs()

◆ DBackupData()

◆ DBackupObject()

◆ DGetLogEvents()

◆ DAdmOperation()

◆ DGetHSMTLSCert()

◆ DHSMTool()

◆ DWriteFileBuffer()

◆ DWriteFile()

◆ DReadFile()

◆ DReadFileBuffer()

◆ DRemoveObj()

◆ DGetStatLog()

◆ DTruncateLog()

◆ DFindHSM()

◆ DManageAToken()

◆ DManageATokenCache()

◆ DDSBindHSM()

◆ DDSUnbindHSM()

◆ DSCGetShadow()

◆ DNSAuthSetState()

◆ DGetErrorString()

◆ DGetReturnCodeString()