Detailed description

Symmetric and asymmetric cryptographic hash operations.

Functions
int AAP_API	DEncrypt (HKEYCTX hKey, HHASHCTX hHash, BOOL bFinal, DWORD dwFlags, BYTE pbData, DWORD pdwDataLen, DWORD dwBufLen)

int AAP_API	DDecrypt (HKEYCTX hKey, HHASHCTX hHash, BOOL bFinal, DWORD dwFlags, BYTE pbData, DWORD pdwDataLen)

int AAP_API	DCreateHash (HSESSIONCTX hSession, int nAlgId, HKEYCTX hKey, DWORD dwFlags, HHASHCTX * hHash)

int AAP_API	DHashData (HHASHCTX hHash, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DSetHashParam (HHASHCTX hHash, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DGetHashParam (HHASHCTX hHash, DWORD dwParam, BYTE pbData, DWORD pdwDataLen, DWORD dwFlags)

int AAP_API	DSignHash (HHASHCTX hHash, HKEYCTX hKey, DWORD dwFlags, BYTE pbSignature, DWORD pdwSigLen)

int AAP_API	DDestroyHash (HHASHCTX *phHash)

int AAP_API	DVerifySignature (HHASHCTX hHash, BYTE *pbSignature, DWORD dwSigLen, HKEYCTX hPubKey, DWORD dwFlags)

int AAP_API	DDuplicateHash (HHASHCTX hHash, DWORD dwFlag, HHASHCTX *phHash)

int AAP_API	DGetRandom (HSESSIONCTX hSession, BYTE *pbData, DWORD dwDataLen)

int AAP_API	DGenEcdhKey (HSESSIONCTX hSession, DWORD dwOP, char szPriKey, void pvInData, DWORD dwInDataLen, BYTE pbOutData, DWORD pdwOutDataLen, DWORD dwFlags)

int AAP_API	DCRLCertCheck (HSESSIONCTX hSession, char szCRL, char szCertId, char *szVerifyInfo)

int AAP_API	DMofNSplit (HSESSIONCTX hSession, BYTE bM, BYTE bN, BYTE pbSecret, DWORD dwSecretLen, DN_M_OF_N_SPLIT_INFO pstSplitInfo, DWORD dwReserved)

int AAP_API	DMofNRecover (HSESSIONCTX hSession, DN_M_OF_N_PART pstParts, DWORD dwPartsCount, BYTE pbSecret, DWORD dwReserved)

Functions

◆ DEncrypt()

int AAP_API DEncrypt	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		BOOL	bFinal,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwBufLen )

#include <dinamo.h>

Data encryption. The algorithm used depends on the key entered in the hKey parameter.

Parameters

[in] hKey Key context.

[in] hHash Hash context if the data is hashed before being encrypted. After the operation is complete, the hash value can be obtained using the DGetHashParam() function.

[in] bFinal Indicates the last block of a series that has been encrypted. TRUE for last block or FALSE otherwise.

[in]

dwFlags

The values in the table below are acceptable for specific cases.

Value	Meaning
D_NO_RSA_PADDING	No padding for RSA keys. Use only for RSA keys. Can be used together with the D_FORCE_ACTUAL_RSA flag.
D_FORCE_ACTUAL_RSA	Uses the RSA key directly. Encryption with private key in DEncrypt and decryption with DDecrypt. Can be used in conjunction with the D_NO_RSA_PADDING flag.

[in,out] pbData Pointer to a buffer containing the data to be encrypted. When the function returns, the original data is overwritten by the result of the encryption operation.
The buffer size is specified by the dwBufLen parameter, the number of bytes to be processed is specified by the pdwDataLen parameter. The buffer size must be large enough to contain the encrypted data plus padding.

[in,out] pdwDataLen Pointer to a DWORD that contains the size of the data in pbData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of encrypted data.
If the allocated buffer is not enough to receive all the ciphered data (for example, there is no space for padding) the function will fail and return D_MORE_DATA.

[in] dwBufLen Buffer size passed in pbData. For symmetric operations that require padding, the buffer must be at least the length of the data plus the size of the operation block of the algorithm to be used.

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

Notes: If a large amount of data is to be encrypted, it can be done in part, with subsequent DEncrypt calls. In the last call, the bFinal parameter must be passed with a true value.

: Only the last block is padded (when applicable), so the remaining blocks must be of a size consistent with the algorithm used. The buffer where the data is passed must be large enough to accommodate the padding as well.

: This API supports RSA operations performed directly on this function. The data to be operated on must have a length equal to or less than the size of the key minus 11 bytes. When using the public key for encryption, the padding used is PKCS#1 type 2 and in the decryption process, the padding is checked and removed. For operations with the private key, PKCS#1 type 1 padding is used. The HSM will check the formatting of the padding even when the operation has no padding defined, as in D_NO_RSA_PADDING. RSA encryption and decryption operations are only enabled in non-restricted mode (NRM).

See also: DGenerateKey().

Examples: crypt_sym.c.

◆ DDecrypt()

int AAP_API DDecrypt	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		BOOL	bFinal,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD *	pdwDataLen )

#include <dinamo.h>

Decrypts data, often encrypted by the DEncrypt function. The algorithm used depends on the key entered in the hKey parameter.

Parameters

[in] hKey Key context.

[in] hHash Hash context if the data is subjected to the hash operation after being decrypted. After the operation is complete, the hash value can be obtained using the DGetHashParam() function.

[in] bFinal Indicates the last block of a series that has been encrypted. TRUE for last block or FALSE otherwise.

[in]

dwFlags

The values in the table below are acceptable for specific cases.

Value	Meaning
D_NO_RSA_PADDING	No padding for RSA keys. Use only for RSA keys. Can be used together with the D_FORCE_ACTUAL_RSA flag.
D_FORCE_ACTUAL_RSA	Uses the RSA key directly. Encryption with private key in DEncrypt and decryption with DDecrypt. Can be used in conjunction with the D_NO_RSA_PADDING flag.

[in,out] pbData Pointer to a buffer containing the data to be decrypted. When the function returns, the original data is overwritten by the result of the encryption operation.
For block symmetric operations, the size of the data must always be a multiple of the block used by the algorithm in question.

[in,out] pdwDataLen Pointer to a DWORD that contains the size of the data in pbData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of data in clear text.

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

Notes: If a large amount of data is to be decrypted, it can be done in part, with subsequent DDecrypt calls. In the last call, the bFinal parameter must be passed with a true value.

: Only in the last block is padding undone (when applicable), so the remaining blocks must be of a size consistent with the algorithm used, and if the CBC symmetric encryption mode of operation is being used, the initialization vector will be reset to zero.

: This API supports RSA operations performed directly on this function. The data to be operated on must have a length equal to the size of the key. When using the public key for encryption, the padding used is PKCS#1 type 2 and in the decryption process, the padding is checked and removed. For operations with the private key, PKCS#1 type 1 padding is used. The HSM will check the formatting of the padding even when the operation has no padding defined, as in D_NO_RSA_PADDING. RSA encryption and decryption operations are only enabled in non-restricted mode (NRM).

Examples: crypt_sym.c.

◆ DCreateHash()

int AAP_API DCreateHash	(	HSESSIONCTX	hSession,
		int	nAlgId,
		HKEYCTX	hKey,
		DWORD	dwFlags,
		HHASHCTX *	hHash )

#include <dinamo.h>

Initializes a hash context to be used with a data stream. This context is used for subsequent DHashData(), DHashSessionKey() calls, among others.

Parameters

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

[in]

nAlgId

Defines the algorithm associated with the hash context.

Value	Meaning
ALG_MD5	MD5 hash algorithm. hKey must be NULL.
ALG_SHA1	SHA1 hash algorithm. hKey must be NULL.
ALG_SSL_SHA1_MD5	Hash for SSLv3 client authentication. hKey must be NULL.
ALG_SHA2_224	SHA2 hash algorithm - 224. hKey must be NULL.
ALG_SHA2_256	SHA2 hash algorithm - 256. hKey must be NULL.
ALG_SHA2_384	SHA2 hash algorithm - 384. hKey must be NULL.
ALG_SHA2_512	SHA2 hash algorithm - 512. hKey must be NULL.
ALG_SHA3_224	SHA3 hash algorithm - 224. hKey must be NULL.
ALG_SHA3_256	SHA3 hash algorithm - 256. hKey must be NULL.
ALG_SHA3_384	SHA3 hash algorithm - 384. hKey must be NULL.
ALG_SHA3_512	SHA3 hash algorithm - 512. hKey must be NULL.
ALG_HMAC_MD5	HMAC MD5 algorithm. hKey must be the context for the key used in HMAC.
ALG_HMAC_SHA1	HMAC SHA1 algorithm. hKey must be the context for the key used in HMAC.
ALG_HMAC_SHA2_256	HMAC SHA2 algorithm - 256. hKey must be the context for the key used in HMAC.
ALG_HMAC_SHA2_384	HMAC SHA2 algorithm - 384. hKey must be the context for the key used in HMAC.
ALG_HMAC_SHA2_512	HMAC SHA2 algorithm - 512. hKey must be the context for the key used in HMAC.
ALG_CMAC_DES	CMAC 3DES algorithm. hKey must be the context for the 3DES key used in CMAC.
ALG_CMAC_AES	CMAC AES algorithm. hKey must be the context for the AES key used in CMAC.
ALG_IDENTITY_FUNC	Identity function. The input data is the same as the output data. hKey NULL.

[in] hKey Must be passed according to the type of algorithm passed in nAlgId.

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

[out] hHash Pointer to the context of the generated hash. After use, it must be released with the DDestroyHash() function.

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

Examples: create_hash.c, sign_verify.c and sign_verify_eddsa.c.

◆ DHashData()

int AAP_API DHashData	(	HHASHCTX	hHash,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Adds data to a given hash context. This function can be called several times to add discontinuous data.

Parameters

[in]	hHash	Hash context generated by the DCreateHash() function.
[in]	pbData	Buffer containing the data that will be added to the hash context.
[in]	dwDataLen	Number of bytes to be added.
[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.

Examples: create_hash.c, sign_verify.c and sign_verify_eddsa.c.

◆ DSetHashParam()

int AAP_API DSetHashParam	(	HHASHCTX	hHash,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Changes a hash context created by DCreateHash().

Parameters

[in] hHash Hash context generated by the DCreateHash() function.

[in]

dwParam

Defines the hash context parameter to be modified.

Value	Meaning
DHP_HASH_VALUE	Type of `pbData:` BYTE * pbData should be a pointer to a buffer containing the hash value to be associated with the context. Once a value has been assigned to this parameter, the hash value can no longer be changed and future DHashData or DHashSessionKey calls will fail returning the error code D_INVALID_HASH_STATE.
DHP_RESET	Type of `pbData:` NULL Resets the hash context to the initial state. The hash value is deleted.

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

◆ DGetHashParam()

int AAP_API DGetHashParam	(	HHASHCTX	hHash,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Returns attributes associated with a given hash context. The hash value can be retrieved using this function.

Parameters

[in] hHash Hash context generated by the DCreateHash() function.

[in]

dwParam

Defines the hash context parameter to be retrieved.

Value	Meaning
DHP_ALGID	Type of `pbData:` DWORD Retrieves the algorithm associated with that context when it was created.
DHP_HASH_SIZE	Type of `pbData:` DWORD Retrieves the length of the hash value.
DHP_HASH_VALUE	Type of `pbData:` BYTE * `pbData` will be a pointer to a buffer containing the hash value associated with the context. Once this attribute is returned, the hash value can no longer be changed and future DHashData or DHashSessionKey calls will fail returning the error code D_INVALID_HASH_STATE.

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

Examples: create_hash.c.

◆ DSignHash()

int AAP_API DSignHash	(	HHASHCTX	hHash,
		HKEYCTX	hKey,
		DWORD	dwFlags,
		BYTE *	pbSignature,
		DWORD *	pdwSigLen )

#include <dinamo.h>

Signs a piece of data from its hash context created with the DCreateHash() function.

Parameters

[in] hHash Hash context generated by the DCreateHash() function.

[in] hKey Context of the private key to be used in the signature.

[in]

dwFlags

You must pass 0 or some modifier defined in the list below.

Value	Meaning
DN_SIGN_NO_HASH_OID	When this flag is specified, the object identifier (OID) is not placed in front of the hash value, as provided in PKCS#7, DigestInfo attribute. By default, this value is always added to the signature. Only for RSA signatures.
DN_SIGN_DISABLE_LEGACY_OPERATION	When this flag is specified, the client API uses the newest versions of the HSM signature implementation. Use with HSMs version 4.0 or higher. By default, this flag is disabled for compatibility reasons. Newer signing algorithms will automatically use the newer implementation and may not be supported by older HSMs.
DN_SIGN_ECC_P11_FMT	Uses the ECC signature format PKCS#11 v2.40 section 2.3.1.

[out] pbSignature Buffer that will receive the signature. This parameter can be NULL to specify the amount of memory required.

[in,out] pdwSigLen Pointer to the size of the signature, in bytes. When the function returns, this parameter will contain the size of the data stored in pbSignature.

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

Notes: The standard signature format generated by the DSignHash() complies with the specifications of PKCS#1 v.1.5, using padding type 1 when an RSA key is used, with the use of ECDSA keys the signature will be in the DER ANSI X9.62/ standard.RFC 3278 section-8.2.
DER ECDSA standard:

ECDSA-Sig-Value ::= SEQUENCE {

r INTEGER,

s INTEGER

}

Signatures generated with EdDSA keys are made using the PureEdDSA signature algorithm as described in RFC 8032. Therefore, the ALG_IDENTITY_FUNC algorithm must be used in the hash APIs to use the identity function. The maximum data size accepted for signing is DN_SIG_EDDSA_MAX_DATA_LEN bytes.

Examples: sign_verify.c and sign_verify_eddsa.c.

◆ DDestroyHash()

int AAP_API DDestroyHash ( HHASHCTX * phHash )

#include <dinamo.h>

Releases the context of a hash after it has been used. Once this context has been released, it can no longer be used by any function and becomes invalid.

Parameters

[in] phHash Hash context generated by the DCreateHash() function.

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

Examples: create_hash.c, sign_verify.c and sign_verify_eddsa.c.

◆ DVerifySignature()

int AAP_API DVerifySignature	(	HHASHCTX	hHash,
		BYTE *	pbSignature,
		DWORD	dwSigLen,
		HKEYCTX	hPubKey,
		DWORD	dwFlags )

#include <dinamo.h>

Checks the signature of the hash associated with a context.

Parameters

[in] hHash Hash context generated by the DCreateHash() function.

[in] pbSignature Buffer containing the signature to be verified.

[in] dwSigLen Number of bytes in the signature.

[in] hPubKey Context for the public key used to verify the signature.

[in]

dwFlags

Function behavior modifiers.

Value	Meaning
DN_VERIFY_NO_HASH_OID	When this flag is specified, the object identifier (OID) is not checked, as provided for in PKCS#7, DigestInfo attribute. By default, this value is always checked. Only in RSA operations.
DN_VERIFY_ECC_P11_FMT	Uses the ECC signature format PKCS#11 v2.40 section 2.3.1.

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

Notes: More details on the signature formats accepted by this API can be seen in the DSignHash() API comments.

Examples: sign_verify.c and sign_verify_eddsa.c.

◆ DDuplicateHash()

int AAP_API DDuplicateHash	(	HHASHCTX	hHash,
		DWORD	dwFlag,
		HHASHCTX *	phHash )

#include <dinamo.h>

Duplicates the context of a hash, including its internal state.

Parameters

[in]	hHash	Hash context generated by the DCreateHash() function.
[in]	dwFlag	Reserved for future use (must be 0).
[in]	phHash	Pointer to the context of the generated hash. After use, it must be released with the DDestroyHash() function.

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

Notes: The hash contexts are independent, so when you release the original context, the new context is still valid.

◆ DGetRandom()

int AAP_API DGetRandom	(	HSESSIONCTX	hSession,
		BYTE *	pbData,
		DWORD	dwDataLen )

#include <dinamo.h>

Retrieves a certain number of pseudo-random bytes for cryptographic use.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[out]	pbData	Buffer that will be filled with the pseudo-random bytes.
[in]	dwDataLen	Size in bytes of `pbData`.

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

◆ DGenEcdhKey()

int AAP_API DGenEcdhKey	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		char *	szPriKey,
		void *	pvInData,
		DWORD	dwInDataLen,
		BYTE *	pbOutData,
		DWORD *	pdwOutDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

It generates ashared secret/key using the ECDH (Elliptc Curve Diffie-Hellman)key-agreement protocol.

Parameters

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

[in]

dwOP

Function behavior modifiers.

Value	Meaning
DN_GEN_KEY_KDF_RAW_SECRET	Returns in `pbOutData` the ECDH secret key without derivation. We recommend deriving a key from this to communicate with the peer. The parameter passed in `pvInData` must be a pointer to a buffer containing the pair's public key in DER format.
DN_GEN_KEY_X9_63_SHA256	Derives an ECDH secret key in the ANSI X9.63 standard using SHA256. Must be passed `pvInData` the structure GEN_ECDH_X9_63. See documentation for GEN_ECDH_X9_63 for filling details. Optionally returns in `pbOutData` the generated secret key, see GEN_ECDH_X9_63 for more details.

[in] szPriKey Identifier of the private key within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are differentiated ( case sensitive)

[in] pvInData Pointer to the function's input data. Must be filled in as described in the options for dwOP

[in] dwInDataLen Size in bytes of pvInData.

[out] pbOutData Buffer that will receive the output key/secret. This parameter can be NULL to return the amount of memory needed in pdwOutDataLen. This parameter will be ignored when the operation is to write the key to the HSM.

[in,out] pdwOutDataLen Pointer to buffer size pbOutDatain bytes, which will contain the output key/secret. When the function returns, this parameter will contain the size of the data actually stored in pbOutData. This parameter will be ignored when the operation is to write the key to the HSM.

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

Examples: gen_ecdh.c and gen_xecdh.c.

◆ DCRLCertCheck()

int AAP_API DCRLCertCheck	(	HSESSIONCTX	hSession,
		char *	szCRL,
		char *	szCertId,
		char *	szVerifyInfo )

#include <dinamo.h>

Validates an X.509 certificate in the HSM using an LCR (List of Revoked Certificates) and a certificate chain.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szCRL	Name of the LCR (List of Revoked Certificates).
[in]	szCertId	Name of the certificate to be validated.
[in]	szVerifyInfo	Name of the certificate chain/certificate for validating the certificate specified in szCertId. Can be passed NULL to avoid checking the certificate chain.

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

◆ DMofNSplit()

int AAP_API DMofNSplit	(	HSESSIONCTX	hSession,
		BYTE	bM,
		BYTE	bN,
		BYTE *	pbSecret,
		DWORD	dwSecretLen,
		DN_M_OF_N_SPLIT_INFO *	pstSplitInfo,
		DWORD	dwReserved )

#include <dinamo.h>

Divides M from N in a secret. According to Shamir's secret sharing pattern.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bM	Minimum number of parts needed to rebuild the secret. Minimum DN_M_OF_N_S_MIN and maximum DN_M_OF_N_S_MAX.
[in]	bN	Total number of parts generated. Minimum DN_M_OF_N_S_MIN and maximum DN_M_OF_N_S_MAX.
[in]	pbSecret	A secret that will be shared in several parts. It should be DN_M_OF_N_S_LEN. NULL can be passed so that a secret is randomly generated by the HSM, in which case the value will be returned in `pstSplitInfo`.
[in]	dwSecretLen	Size of data entered in `pbSecret`. Case `pbSecret` is NULL pass 0 in this parameter.
[out]	pstSplitInfo	Output data.
[in]	dwReserved	Reserved for future use (must be 0).

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

Notes: The session used in this operation can be authenticated or anonymous.

Examples: m_of_n.c.

◆ DMofNRecover()

int AAP_API DMofNRecover	(	HSESSIONCTX	hSession,
		DN_M_OF_N_PART *	pstParts,
		DWORD	dwPartsCount,
		BYTE *	pbSecret,
		DWORD	dwReserved )

#include <dinamo.h>

Reconstructs the secret M of N from the parts of the custodians. According to Shamir's secret sharing pattern.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	pstParts	Array of custodian parts.
[in]	dwPartsCount	Number of parts passed in `pstParts`.
[in]	pbSecret	Reconstructed secret. Must have size DN_M_OF_N_S_LEN.
[in]	dwReserved	Reserved for future use (must be 0).

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

Notes: The session used in this operation can be authenticated or anonymous.

Examples: m_of_n.c.