Detailed description

Lifecycle management of cryptographic keys in the HSM.

Data Structures
struct	DN_EXPORT_BYOK_AZURE

Definitions and Macros
#define	D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1) /* Imports an RSA private key. */

#define	D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Imports an ECC private key (Elliptic Curves with the exception of ECX). */

#define	D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFFFDF) /* Imports a key in P8 format */

#define	D_IMPORT_ALG_PRIV_KEY_ECX (0xFFFFDE) /* Import an ECX private key */

#define	D_IMPORT_ALG_PRIV_KEY_DSA (0xFFFFFFDD) /* Import a DSA private key */

#define	D_IMPORT_ALG_PRIV_KEY_DH (0xFFFFDC) /* Import a DH private key */

#define	D_IMPORT_ALG_PRIV_KEY_ML_DSA (0xFFFFDA) /* Import a ML-DSA private key */

#define	D_IMPORT_ALG_PRIV_KEY_ML_KEM (0xFFFFFFD9) /* Import an ML-KEM private key */

#define	D_IMPORT_ALG_PRIV_KEY_SLH_DSA (0xFFFFFFD8) /* Import a private key SLH-DSA */

#define	DN_FORM_DER (1)

#define	DN_BYOK_TYPE_AZURE (1)

#define	DN_BYOK_TYPE_AWS (2)

Functions
int AAP_API	DGenerateKey (HSESSIONCTX hSession, char szKeyId, int nAlgId, DWORD dwFlags, HKEYCTX phKey)

int AAP_API	DGenerateKeyMaterial (HSESSIONCTX hSession, int nAlgId, BYTE pbData, DWORD pdwDataLen, DWORD dwReserved)

int AAP_API	DGetUserKey (HSESSIONCTX hSession, char szKeyId, DWORD dwFlags, HKEYCTX phKey)

int AAP_API	DImportKey (HSESSIONCTX hSession, char szKeyId, HKEYCTX hKEKey, DWORD dwBlobType, int nAlgId, DWORD dwFlags, BYTE pbData, DWORD dwDataLen, HKEYCTX *phKey)

int AAP_API	DExportKey (HKEYCTX hKey, HKEYCTX hKEKey, DWORD dwBlobType, DWORD dwFlags, BYTE pbData, DWORD pdwDataLen)

int AAP_API	DPKCS8ImportKey (HSESSIONCTX hSession, char szKeyId, char szSecret, DWORD dwKeyAlg, DWORD dwAttrib, BYTE *pbKeyEnvelope, DWORD dwKeyEnvelopeLen)

int AAP_API	DPKCS8ExportKey (HSESSIONCTX hSession, char szKeyId, char szSecret, BYTE *ppbKeyEnvelope, DWORD pdwKeyEnvelopeLen)

int AAP_API	DSetKeyParam (HKEYCTX hKey, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DGetKeyParam (HKEYCTX hKey, DWORD dwParam, BYTE pbData, DWORD pdwDataLen, DWORD dwFlags)

int AAP_API	DDeriveKey (HHASHCTX hHash, char szKeyId, int nAlgId, DWORD dwFlags, HKEYCTX phKey)

int AAP_API	DDuplicateKey (HKEYCTX hKey, DWORD dwFlags, HKEYCTX *phKey)

int AAP_API	DHashSessionKey (HKEYCTX hKey, HHASHCTX hHash, DWORD dwFlags)

int AAP_API	DDestroyKey (HKEYCTX *phKey, DWORD dwFlags)

int AAP_API	DGeneratePKCS10CSR (HSESSIONCTX hSession, char szPrivateKeyName, BYTE bVersion, char szDN, DWORD dwOutType, DWORD pdwCSRLen, BYTE *ppbCSR, DWORD dwParam)

int AAP_API	DAssociatePKCS11Key (HSESSIONCTX hSession, char szPriKey, char szPubKey, char szCert, void pvReserved, DWORD dwReserved)

int AAP_API	DExportPKCS12 (const HSESSIONCTX hSession, const char szPkcs12Pwd, const char szKeyId, const char szCertId, const char szReserved, BYTE *ppbPkcs12, DWORD pdwPkcs12Len, DWORD dwFlags)

int AAP_API	DImportPKCS12Buffer (const HSESSIONCTX hSession, BYTE pbPkcs12, DWORD dwPkcs12Len, const char szPkcs12Pwd, const char szKeyId, DWORD dwKeyAttr, const char szCertId, const char *szPubKeyId, DWORD dwFlags)

int AAP_API	DImportPKCS12 (const HSESSIONCTX hSession, const char szPkcs12File, const char szPkcs12Pwd, const char szKeyId, const DWORD dwKeyAttr, const char szCertId)

int AAP_API	DRSAPublicKey2Info (BYTE pbKey, DWORD dwKeyLen, DWORD dwInForm, void pvPubKeyInfo, DWORD dwReserved)

int AAP_API	DRSAPrivateKey2Info (const BYTE pbRsa, DWORD dwRsaLen, DWORD dwInForm, DN_RSA_PRIVATE_KEY_INFO stRsaInfo, DWORD dwReserved)

int AAP_API	DByokExport (HSESSIONCTX hSession, const char cszKeyId, const char cszKekId, DWORD dwType, const void pvData, BYTE ppbOutData, DWORD pdwOutDataLen, DWORD dwReserved)

Definitions and macros

◆ D_IMPORT_ALG_PRIV_KEY_RSA

#define D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1) /* Importa uma chave privada RSA. */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ECC

#define D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Importa uma chave privada ECC(Curvas Elípticas com exceção de ECX). */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_P8

#define D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFFFDF) /* Importa uma chave no formato P8 */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ECX

#define D_IMPORT_ALG_PRIV_KEY_ECX (0xFFFFFFDE) /* Importa uma chave privada ECX */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_DSA

#define D_IMPORT_ALG_PRIV_KEY_DSA (0xFFFFFFDD) /* Importa uma chave privada DSA */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_DH

#define D_IMPORT_ALG_PRIV_KEY_DH (0xFFFFFFDC) /* Importa uma chave privada DH */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ML_DSA

#define D_IMPORT_ALG_PRIV_KEY_ML_DSA (0xFFFFFFDA) /* Importa uma chave privada ML-DSA */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ML_KEM

#define D_IMPORT_ALG_PRIV_KEY_ML_KEM (0xFFFFFFD9) /* Importa uma chave privada ML-KEM */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_SLH_DSA

#define D_IMPORT_ALG_PRIV_KEY_SLH_DSA (0xFFFFFFD8) /* Importa uma chave privada SLH-DSA */

#include <dinamo.h>

◆ DN_FORM_DER

#define DN_FORM_DER (1)

#include <dinamo.h>

DER format.

◆ DN_BYOK_TYPE_AZURE

#define DN_BYOK_TYPE_AZURE (1)

#include <dinamo.h>

Exports BYOK key to Azure.

◆ DN_BYOK_TYPE_AWS

#define DN_BYOK_TYPE_AWS (2)

#include <dinamo.h>

Export BYOK key to AWS.

Functions

◆ DGenerateKey()

int AAP_API DGenerateKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		int	nAlgId,
		DWORD	dwFlags,
		HKEYCTX *	phKey )

#include <dinamo.h>

Creates and stores a cryptographic key associated with an algorithm according to the specified parameters, within the HSM.

Parameters

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

[in] szKeyId The key identifier within the HSM. This identifier must not contain spaces or special characters. It is case-sensitive. An object identifier in the HSM can have a maximum length of MAX_OBJ_ID characters (including the null terminator). When creating keys in another user's partition (permission is required), the name must be fully qualified with an FQN (Full Qualified Name: partition_id/obj_id). The maximum length for an FQN is MAX_OBJ_ID_FQN_LEN (including the null terminator).

[in]

nAlgId

Defines the algorithm associated with the cryptographic key to be generated.

Symmetric Keys

Value	Meaning
ALG_DES	56-bit DES with odd parity.
ALG_3DES_112	112-bit 3DES-EDE (Encrypt-Decrypt-Encrypt) with odd parity.
ALG_3DES_168	3DES-EDE (Encrypt-Decrypt-Encrypt) with 168 bits and odd parity.
ALG_DESX	192-bit DESX. The effective size is 118 bits.
ALG_ARC4	128-bit ARC4.
ALG_ARC5	128-bit ARC5, 8-byte block, using 16 rounds.
ALG_AES_128	128-bit AES.
ALG_AES_192	192-bit AES.
ALG_AES_256	256-bit AES.

RSA Asymmetric Keys

Value	Meaning
ALG_RSA_512	RSA key pair with a 512-bit modulus.
ALG_RSA_1024	RSA key pair with a 1024-bit modulus.
ALG_RSA_2048	RSA key pair with a 2048-bit modulus.
ALG_RSA_4096	RSA key pair with a 4096-bit modulus.
ALG_RSA_1152	RSA key pair with a 1152-bit modulus.
ALG_RSA_1408	RSA key pair with a 1408-bit modulus.
ALG_RSA_1536	RSA key pair with a 1536-bit modulus.
ALG_RSA_1976	RSA key pair with a 1976-bit modulus.
ALG_RSA_1984	RSA key pair with a 1984-bit modulus.
ALG_RSA_8192	RSA key pair with an 8192-bit modulus.
ALG_RSA_2304	RSA key pair with a 2304-bit modulus.
ALG_RSA_2560	RSA key pair with a 2560-bit modulus.
ALG_RSA_2816	RSA key pair with a 2816-bit modulus.
ALG_RSA_3072	RSA key pair with a 3072-bit modulus.

ECC Asymmetric Keys

Value	Meaning
ALG_ECC_SECP112R1	SECG/WTLS curve over a 112-bit prime finite field (verifiably random elliptic curve domain parameters).
ALG_ECC_SECP112R2	SECG curve over a 112-bit prime finite field (verifiably random elliptic curve domain parameters 2).
ALG_ECC_SECP128R1	SECG curve over a 128-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP128R2	SECG curve over a 128-bit prime finite field (verifiably random elliptic curve domain parameters 2).
ALG_ECC_SECP160K1	SECG curve over a 160-bit prime finite field (koblitz domain parameters ).
ALG_ECC_SECP160R1	SECG curve over a 160-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP160R2	SECG/WTLS curve over a 160-bit prime finite field (verifiably random elliptic curve domain parameters 2).
ALG_ECC_SECP192K1	SECG curve over a 192-bit prime finite field (koblitz domain parameters ).
ALG_ECC_SECP192R1	SECG/X9.62/NIST curve over a 192-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP224K1	SECG curve over a 224-bit prime finite field (koblitz domain parameters ).
ALG_ECC_SECP224R1	SECG/NIST curve over a 224-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP256K1	SECG curve over a 256-bit prime finite field (koblitz domain parameters ).
ALG_ECC_SECP256R1	SECG/X9.62 curve over a 256-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP384R1	SECG/NIST curve over a 384-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP521R1	SECG/NIST curve over a 521-bit prime finite field (verifiably random elliptic curve domain parameters 1).
ALG_ECC_X9_62_PRIME192V1	X9.62 curve over a 192-bit prime finite field (version 1 domain parameters).
ALG_ECC_X9_62_PRIME192V2	X9.62 curve over a 192-bit prime finite field (version 2 domain parameters).
ALG_ECC_X9_62_PRIME192V3	X9.62 curve over a 192-bit prime finite field (version 3 domain parameters).
ALG_ECC_X9_62_PRIME239V1	X9.62 curve over a 239-bit prime finite field (version 1 domain parameters).
ALG_ECC_X9_62_PRIME239V2	X9.62 curve over a 239-bit prime finite field (version 2 domain parameters).
ALG_ECC_X9_62_PRIME239V3	X9.62 curve over a 239-bit prime finite field (version 3 domain parameters).
ALG_ECC_X9_62_PRIME256V1	X9.62 curve over a 256-bit prime finite field (version 1 domain parameters).
ALG_ECC_BRAINPOOL_P160R1	Brainpool RFC 5639 curve over a 160-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P160T1	Brainpool RFC 5639 curve over a 160-bit prime finite field (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P192R1	Brainpool RFC 5639 curve over a 192-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P192T1	Brainpool RFC 5639 curve over a 192-bit prime finite field (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P224R1	Brainpool RFC 5639 curve over a 224-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P224T1	Brainpool RFC 5639 curve over a 224-bit prime finite field (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P256R1	Brainpool RFC 5639 curve over a 256-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P256T1	Brainpool RFC 5639 curve over a 256-bit prime finite field (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P320R1	Brainpool RFC 5639 curve over a 320-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P320T1	Brainpool RFC 5639 curve over a 320-bit prime finite field (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P384R1	Brainpool RFC 5639 curve over a 384-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P384T1	Brainpool RFC 5639 curve over a 384-bit prime finite field (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P512R1	Brainpool RFC 5639 curve over a 512-bit prime finite field (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P512T1	Brainpool RFC 5639 curve over a 512-bit prime finite field (twisted domain parameters 1)

ECX Asymmetric Keys

Value	Meaning
ALG_ECX_ED25519	RFC 8032 curve (signature only) over a ~256-bit prime finite field.
ALG_ECX_ED448	RFC 8032 curve (signature only) over a ~448-bit prime finite field.
ALG_ECX_X25519	RFC 7748 curve (key-agreement only) over a ~256-bit prime finite field.
ALG_ECX_X448	RFC 7748 curve (key-agreement only) over a ~448-bit prime finite field.

PQC Asymmetric Keys

Value	Meaning
ALG_ML_DSA_44	ML-DSA-44 key pair, FIPS 204 standard.
ALG_ML_DSA_65	ML-DSA-65 key pair, FIPS 204 standard.
ALG_ML_DSA_87	ML-DSA-87 key pair, FIPS 204 standard.
ALG_ML_KEM_512	ML-KEM-512 key pair, FIPS 203 standard.
ALG_ML_KEM_768	ML-KEM-768 key pair, FIPS 203 standard.
ALG_ML_KEM_1024	ML-KEM-1024 key pair, FIPS 203 standard.
ALG_SLH_DSA_SHA2_128S	SLH-DSA-SHA2-128S key pair, FIPS 205 standard.
ALG_SLH_DSA_SHAKE_128S	SLH-DSA-SHAKE-128S key pair FIPS 205 standard.
ALG_SLH_DSA_SHA2_128F	SLH-DSA-SHA2-128F key pair, FIPS 205 standard.
ALG_SLH_DSA_SHAKE_128F	SLH-DSA-SHAKE-128F key pair, FIPS 205 standard.
ALG_SLH_DSA_SHA2_192S	SLH-DSA-SHA2-192S key pair, FIPS 205 standard.
ALG_SLH_DSA_SHAKE_192S	SLH-DSA-SHAKE-192S key pair, FIPS 205 standard.
ALG_SLH_DSA_SHA2_192F	SLH-DSA-SHA2-192F key pair, FIPS 205 standard.
ALG_SLH_DSA_SHAKE_192F	SLH-DSA-SHAKE-192F key pair, FIPS 205 standard.
ALG_SLH_DSA_SHA2_256S	SLH-DSA-SHA2-256S key pair, FIPS 205 standard.
ALG_SLH_DSA_SHAKE_256S	SLH-DSA-SHAKE-256S key pair FIPS 205 standard.
ALG_SLH_DSA_SHA2_256F	SLH-DSA-SHA2-256F key pair, FIPS 205 standard.
ALG_SLH_DSA_SHAKE_256F	SLH-DSA-SHAKE-256F key pair, FIPS 205 standard.

HMAC Keys

Value	Meaning
ALG_HMAC_MD5	16-byte HMAC MD5 key.
ALG_HMAC_SHA1	20-byte HMAC SHA1 key.
ALG_HMAC_SHA2_256	32-byte HMAC SHA2 256 key.
ALG_HMAC_SHA2_384	48-byte HMAC SHA2 384 key.
ALG_HMAC_SHA2_512	64-byte HMAC SHA2 512 key.

[in]

dwFlags

Additional key parameters.

Value	Meaning
EXPORTABLE_KEY	The key can be exported from the HSM.
TEMPORARY_KEY	The key will only exist while the session is active. It will be destroyed when the session is closed. The `szKeyId` parameter, the key identifier, can be NULL. In this case, the HSM will generate a unique identifier for the key. You can retrieve the key identifier with the DGetKeyParam() function. Temporary keys cannot be locked or renamed; they are also not replicated.

In addition to the values in the previous table, a key usage profile definition can be added.
It is possible to define the key usage profile (Attribute Usage-profile), using only one of the values below. If none of the values below are specified, the key profile is set to be free for any use. Defining the usage profile is mandatory when the HSM is in RM3.

Value	Meaning
AUP_DIG_SIG	signature generation/verification
AUP_DATA_CRYPTO	data encryption/decryption
AUP_KeK	key wrapping/unwrapping
AUP_MAC	MAC generation/verification
AUP_KDF	key derivation function
AUP_CRYPTOGRAM	cryptogram generation/verification
AUP_KEY_TRANSLATE	key translation
AUP_EFT_CVK	CVV generation/verification
AUP_EFT_VISA_PVK	PVV generation
AUP_EFT_IBM_3624	PIN generation/validation
AUP_EFT_PEK	PIN encryption/decryption
AUP_EFT_BDK	DUKPT
AUP_EFT_IPEK	DUKPT IPEK
AUP_EMV_IMK	ICC MK, IDN derivation
AUP_EMV_IMKDAC	ICC DAC derivation
AUP_EMV_IMKENC	ICC data encryption - PinBlock
AUP_EMV_IMKMAC	ICC data cryptogram - EmvMac
AUP_EMV_KeK	ICC MK wrapping
AUP_EMV_IMKKDF	EMV key derivation
AUP_EMV_IMKACRYPTO	ARPC calculation
AUP_EFT_KeK	EFT key wrapping/unwrapping
AUP_EMV_DIG_SIG	EMV signature generation/verification
AUP_EFT_TR31_KBPK	TR31 key-block protection key
AUP_EFT_TR34_PK	TR34 signature/envelope
AUP_SPB_PK	SPB signature generation/verification and wrapping
AUP_EFT_X9_24_PART	ANS1 X9.24 (20044) Annex C

[in] phKey Pointer to the generated key context. After use, it must be released with the DDestroyKey() function. NULL can be passed to prevent returning the key context.

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

Attention: At Dinamo all keys are stored encrypted, regardless of the operating mode (NRM, RM1 or RM2).

Notes

The following default values are assigned to symmetric key contexts, where applicable:

Parameter	Value
Initialization Vector	It will be a vector with all bytes equal to zero and with the same block size as the key algorithm's operation.
Symmetric Encryption Operation Mode	The CBC (Cipher Block Chaining) mode will be used.
Padding	The format defined in the PKCS#5 standard will be used as padding.

The block size for algorithm operations follows the table below:

Value	Block size
ALG_DES	8 bytes
ALG_3DES_112	8 bytes
ALG_3DES_168	8 bytes
ALG_AES_128	16 bytes
ALG_AES_192	16 bytes
ALG_AES_256	16 bytes
ALG_ARC5	8 bytes

RSA keys in HSM are preferably created with a fixed and defined public exponent (three bytes in the sequence 01 00 01, decimal value of 2¹⁶ + 1 = 65537. Optionally, an exponent of value 3 can be used for compatibility with older systems, but this is not recommended.
ECC keys are defined according to the following standards:

Standards for Efficient Cryptography Group (SECG)
Wireless Transport Layer Security (WTLS)
ANSI X9.62:2005 - Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA)
NIST FIPS PUB 186-4 - Digital Signature Standard (DSS)

RFC 5639 - Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation
The standard values for PQC keys are:

Type	Value
Deterministic	ML-DSA enabled; SLH-DSA disabled.
Pre-hash	Disabled. Only used when a specific hash is defined.
Context	Disabled. Only used when a specific context is defined.

◆ DGenerateKeyMaterial()

int AAP_API DGenerateKeyMaterial	(	HSESSIONCTX	hSession,
		int	nAlgId,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Generates a cryptographic key and returns its material. This operation generates a key using the HSM and returns the key's content without persisting it in the HSM.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	nAlgId	Defines the algorithm for the cryptographic key to be generated. This operation only supports symmetric key algorithms. See the list of algorithms in DGenerateKey().
[in]	pbData	Buffer that will contain the generated key. Can be passed as NULL to receive the expected size of pbData in pdwDataLen.
[in,out]	pdwDataLen	Pointer containing the size of the pbData buffer. This variable will contain the exact size of the data copied into pbData. If pbData is NULL or the specified size is insufficient to complete the operation, pdwDataLen will contain the expected size of pbData.
[in]	dwReserved	Reserved for future use.

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

◆ DGetUserKey()

int AAP_API DGetUserKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		DWORD	dwFlags,
		HKEYCTX *	phKey )

#include <dinamo.h>

Retrieves the context of a key, provided the current user has access, stored within the HSM. This function does not create a new key.

Parameters

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

[in] szKeyId Identifier of the key within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. See szKeyId in DGenerateKey() for details on maximum identifier sizes.

[in]

dwFlags

Pass zero. Otherwise, the following table is accepted.

Value	Meaning
D_GET_USR_KEY_OFFLINE	Generates a key handle based on specific parameters and will not access the HSM to verify the provided parameters. To use this flag, a properly filled GET_USR_KEY_OFFLINE structure must be passed in szKeyId. Note that no correlation checks are performed on the provided data. Passing invalid data will generate an invalid handle, even if this function returns success.
D_GET_USR_KEY_NO_PUB	If it retrieves a public key, it will not try to export its contents to retrieve more details. The key information will be partial. This option is only used in specific cases of using M of N partition in the `associated, authorized` state, where exporting the public key is not allowed.

[out] phKey Pointer to the context of the generated key. After use, it must be released with the DDestroyKey() function.

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

See also: DGenerateKey().

Examples: key_attribute.c.

◆ DImportKey()

int AAP_API DImportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		HKEYCTX	hKEKey,
		DWORD	dwBlobType,
		int	nAlgId,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD	dwDataLen,
		HKEYCTX *	phKey )

#include <dinamo.h>

Imports a cryptographic key into the HSM. Keys can be permanent or temporary. Keys exported using the DExportKey() function can be imported without format alteration.

Parameters

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

[in] szKeyId Identifier of the key within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. See szKeyId in DGenerateKey() for details on maximum identifier sizes.

[in] hKEKey Key context with which the key blob to be imported is encrypted - KEK (key encryption key)

[in]

dwBlobType

Format of the key buffer in the parameter pbData.

Value	Meaning
PRIVATEKEY_BLOB_STRICT	An RSA, EC or PQC key pair will be imported in PRIVATEKEY_BLOB format. hKEKey must be the context of a symmetric key, a public key (internal to the HSM see PUBLICKEY_BLOB_HSM) or NULL. The following formats are accepted. For RSA: Private key (containing modulus information and public exponent), defined in PKCS#1 v1.5 section 7.2. For ECC keys must have the ECPrivateKey format described in RFC 5915. For ECX keys (EdDSA and XECDH) the format is that described in RFC 8410. For PQC keys, the standard is PrivateKeyInfo in DER format.
PRIVATEKEY_BLOB	Same behavior as PRIVATEKEY_BLOB_STRICT, but in older HSM versions, it may return RSA keys as a concatenation of private and public keys in the formats defined in PKCS#1 v1.5, sections 7.1 and 7.2. This option is maintained for compatibility. Use PRIVATEKEY_BLOB_STRICT.
PRIVATEKEY_BLOB_P8	An RSA key pair will be imported in PRIVATEKEY_BLOB_P8 format. hKEKey must be the context of a symmetric key. The key blob format is PrivateKeyInfo as defined in PKCS#8.
PUBLICKEY_BLOB	A public key will be imported from an RSA or EC key pair in the format PUBLICKEY_BLOB.hKEKey must be equal to NULL. The context returned by the public key import should only be used in digital envelope operations, as the HSM does not persistently create RSA objects with only the public part of the key following the PKCS#1 v2.2 DER format standard. For EC (ECC and ECX) and PQC public keys, the standard is SubjectPublicKeyInfo DER format.
PUBLICKEY_BLOB_X509	Imports/exports a public key in X.509 format. The public key format is SubjectPublicKeyInfo as defined in RFC 5280. The hKEKey parameter must be equal to NULL.
SIMPLE_BLOB	A symmetric key will be imported in SIMPLE_BLOB format. hKEKey must be the context of a private key associated with the public key used to encrypt the blob to be imported. The padding type used for key encryption must be 2, as defined in PKCS#1 v1.5 section 8.1.
PLAINTEXTKEY_BLOB	A symmetric key or HMAC key will be imported in plaintext. For HMAC keys, the length can range from DN_HMAC_IMPORT_MIN_KEY_LEN to DN_HMAC_IMPORT_MAX_KEY_LEN bytes. This flag is not yet supported for RSA keys.
SIMPLE_BLOB_OAEP	Defines import via digital envelope using the PKCS#1 version 2.1 standard, with RSAES-OAEP encryption scheme with SHA-1 hash. The KEK must be a private key in the HSM, whose corresponding public key was used to create the envelope. The context for this KEK can be obtained via a call to DGetUserKey, where the id of the HSM's RSA key used to open the envelope will be entered. This import method can be used in restricted operating modes.
SYM_WRAPPED_KEY_BLOB	Defines a symmetric key encrypted by a KEK (Key Encryption Key) which is also symmetric. The hKEKey parameter must contain the context of a symmetric key with the appropriate usage parameters already defined, such as mode and padding. The key will be decrypted and imported directly into the HSM's database, without specific formatting.
HOTP_BLOB	Defines the import of an HTOP type object to the user partition.
PUBLICKEY_BLOB_HSM	A public key from an RSA/ECC key pair in DER format will be imported into the HSM. PQC must be SPKI format SubjectPublickeyInfo fno DER format. hKEKey must be equal to NULL.
PUBLICKEY_RSA_PARTS_HSM	A public key, derived from the modulus and public exponent, will be imported into the HSM. hKEKey must be NULL. The RSA_PUB_KEY_PARTS structure must be passed in pbData, duly filled.
WRAPPED_KEY_BLOB	Imports a key encrypted by a KEK (Key Encryption Key). The hKEKey parameter must contain the context of a symmetric key with the appropriate usage parameters already defined, such as mode (according to the algorithm) and padding. The key will be decrypted and imported directly into the HSM's base, without specific formatting.
WRAPPED_KEY_BLOB_P8	Imports a key encrypted by a KEK (Key Encryption Key). The hKEKey parameter must contain the context of a symmetric key with the appropriate usage parameters already defined, such as mode (according to the algorithm) and padding. The key will be decrypted and imported directly into the HSM's base, without specific formatting. In the key export operation, the private key format will be PKCS#8.
WRAPPED_KEY_KMIP	Export/import the private key as a KMIP Key Value containing a key in Transparent RSA Private Key format.
PUBLICKEY_BLOB_KMIP	Exports the public key as a KMIP Key Value containing a key in Transparent RSA Public Key format.

[in] nAlgId Indicates the algorithm associated with the cryptographic key to be generated. See the list of algorithms in DGenerateKey(). Use D_IMPORT_ALG_PRIV_KEY_RSA when the imported private key is RSA and encrypted by a KEK; the specific algorithm will be automatically detected by the HSM after opening the encrypted BLOB.

[in] dwFlags Additional key parameters. See options in the DGenerateKey() function.

[in] pbData Buffer containing the key to be imported.

[in] dwDataLen Size of the data block containing the key to be imported.

[out] phKey Pointer to the context of the generated key. After use, it must be released with the DDestroyKey function.

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

Notes: For session keys and public keys, it is recommended to use the TEMPORARY_KEY flag, preventing temporary-use keys from occupying unnecessary space in the HSM.

Format of the SIMPLE_BLOB:

EB = 00 || BT || PS || 00 || D

DER structures for PRIVATEKEY_BLOB:

RSAPrivateKey ::= SEQUENCE {
    version Version,
    modulus INTEGER, -- n
    publicExponent INTEGER, -- e
    privateExponent INTEGER, -- d
    prime1 INTEGER, -- p
    prime2 INTEGER, -- q
    exponent1 INTEGER, -- d mod (p-1)
    exponent2 INTEGER, -- d mod (q-1)
    coefficient INTEGER -- (inverse of q) mod p
}

  ECPrivateKey ::= SEQUENCE {
  version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
  privateKey     OCTET STRING,
  parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
  publicKey  [1] BIT STRING OPTIONAL
}

PrivateKeyInfo ::= SEQUENCE {
       version                   Version,
       privateKeyAlgorithm       PrivateKeyAlgorithmIdentifier,
       privateKey                PrivateKey,
       attributes           [0]  IMPLICIT Attributes OPTIONAL }

DER structure of PUBLICKEY_BLOB:

RSAPublicKey ::= SEQUENCE {
    modulus INTEGER, -- n
    publicExponent INTEGER -- e
}

DER structure of PUBLICKEY_BLOB_X509:

SubjectPublicKeyInfo ::= SEQUENCE {
                     algorithm AlgorithmIdentifier,
                     publicKey BIT STRING }

See also: Remarks on DGenerateKey().

Examples: eft_calc_arpc.c, eft_merge_lmk_encrypt.c, eft_validate_cvv.c, import_export.c, ocra_gen.c, pin_block_translate.c, sign_verify_pqc_ml_dsa.c, sign_verify_pqc_slh_dsa.c, and verify_pin_block.c.

◆ DExportKey()

int AAP_API DExportKey	(	HKEYCTX	hKey,
		HKEYCTX	hKEKey,
		DWORD	dwBlobType,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD *	pdwDataLen )

#include <dinamo.h>

Exports a key stored in the HSM so that it can be transported. The key can then be imported back into Dinamo with the DImportKey() function.

Parameters

[in]	hKey	Context of the key to be exported.
[in]	hKEKey	Context of the key with which the key block will be encrypted - KEK (key encryption key).
[in]	dwBlobType	Key buffer format in the `pbData` parameter. See parameter `dwBlobType` in DImportKey() for list of types.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	pbData	Buffer containing the key data according to the dwBlobType parameter. This parameter can be NULL to specify the required amount of memory.
[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`.

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

Notes: Only keys created as exportable can be extracted with this function; otherwise, the error code D_INVALID_KEY_STATE will be returned.

Examples: gen_dh.c, gen_ecdh.c, gen_xecdh.c, import_export.c, pqc_kem_encaps_decaps.c, pqc_kem_encaps_decaps_persistent.c, sign_verify_pqc_ml_dsa.c, and sign_verify_pqc_slh_dsa.c.

◆ DPKCS8ImportKey()

int AAP_API DPKCS8ImportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szSecret,
		DWORD	dwKeyAlg,
		DWORD	dwAttrib,
		BYTE *	pbKeyEnvelope,
		DWORD	dwKeyEnvelopeLen )

#include <dinamo.h>

Imports an RSA private asymmetric key, enveloped according to the PKCS#8 standard, into the HSM. The RSA private key can be imported in plaintext or protected by a digital envelope. For details on the standards, refer to the Public-Key Cryptography Standards (PKCS) documents from RSA Labs. In restricted operating modes (RM1 and RM2), RSA keys can only be imported via the PKCS#8 standard using a digital envelope. This involves deriving an AES 256 key from a password of at least 1 character and at most 16 characters, with the derivation performed according to the PKCS#5 version 2.0 standard.
The envelope used may originate from any system compliant with the described standards.

Parameters

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

[in] szKeyId Identifier for the RSA key that will be created on the basis of the HSM. See szKeyId in DGenerateKey() for details on maximum identifier sizes.

[in] szSecret Password used to derive the AES 256 key. NULL can be passed to indicate no password (plaintext import), or a password of up to ND_MAX_P8_PWD_LEN characters plus a null terminator.

[in]

dwKeyAlg

Indicates the algorithm associated with the cryptographic key to be generated.

Value	Meaning
ALG_RSA_512	RSA key pair with a 512-bit modulus.
ALG_RSA_1024	RSA key pair with a 1024-bit modulus.
ALG_RSA_2048	RSA key pair with a 2048-bit modulus.
ALG_RSA_4096	RSA key pair with a 4096-bit modulus.
ALG_RSA_1152	RSA key pair with a 1152-bit modulus.
ALG_RSA_1408	RSA key pair with a 1408-bit modulus.
ALG_RSA_1536	RSA key pair with a 1536-bit modulus.
ALG_RSA_1976	RSA key pair with a 1976-bit modulus.
ALG_RSA_1984	RSA key pair with a 1984-bit modulus.
ALG_RSA_8192	RSA key pair with an 8192-bit modulus.
ALG_RSA_2304	RSA key pair with a 2304-bit modulus.
ALG_RSA_2560	RSA key pair with a 2560-bit modulus.
ALG_RSA_2816	RSA key pair with a 2816-bit modulus.
ALG_RSA_3072	RSA key pair with a 3072-bit modulus.

[in]

dwAttrib

Additional key parameters.

Value	Meaning
EXPORTABLE_KEY	The key can be exported from the HSM in plaintext.

[in] pbKeyEnvelope Buffer containing the input PKCS#8 envelope.

[in] dwKeyEnvelopeLen Size in bytes of the input PKCS#8 envelope.

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

◆ DPKCS8ExportKey()

int AAP_API DPKCS8ExportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szSecret,
		BYTE **	ppbKeyEnvelope,
		DWORD *	pdwKeyEnvelopeLen )

#include <dinamo.h>

Exports an RSA private asymmetric key stored in the HSM, enveloped according to the PKCS#8 standard. The RSA private key can be exported in plaintext or protected by a digital envelope. For details on the standards, refer to the Public-Key Cryptography Standards (PKCS) documents from RSA Labs. In restricted operating modes (RM1 and RM2), exportable RSA keys can only be exported via the PKCS#8 standard using a digital envelope. This involves deriving an AES 256 key from a password with a length between ND_MIN_P8_PWD_LEN and ND_MAX_P8_PWD_LEN characters, with the derivation performed according to the PKCS#5 version 2.0 standard. The output envelope can be imported into any system compliant with the described standards.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Identifier of the RSA key to be exported. See `szKeyId` in DGenerateKey() for details on maximum identifier sizes.
[in]	szSecret	Password with a length between ND_MIN_P8_PWD_LEN and ND_MAX_P8_PWD_LEN characters plus a null terminator, used to derive the AES 256 key. NULL can be passed to export in plaintext, without a password.
[out]	ppbKeyEnvelope	A pointer to a pointer that will hold the output PKCS#8 envelope. Memory allocation is handled internally by the library. The calling application is responsible for freeing the allocated memory. The DFree() function must be used to release this buffer.
[out]	pdwKeyEnvelopeLen	A pointer to a DWORD that will contain the size, in bytes, of the output PKCS#8 envelope.

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

◆ DSetKeyParam()

int AAP_API DSetKeyParam	(	HKEYCTX	hKey,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Modifies parameters of key contexts, which generally influence their manipulation.

Parameters

[in] hKey Context of the key to be exported.

[in]

dwParam

Defines the operation to be executed and, consequently, the structure or data passed in the parameter pbData.

Value	meaning
DKP_IV	Type of `pbData:` BYTE * Initialization vector used with block algorithms according to their symmetric encryption mode of operation. The size of the initialization vector depends on the symmetric algorithm used, since it has the same length as the block operation. More details in the Remarks section. Only valid for symmetric keys. To define an IV DKP_IV_AUTO_GEN must be FALSE.
DKP_IV_AUTO_GEN	Type of `pbData:` BYTE * Initialization vector generated automatically in the HSM for the symmetric key. As of version 6.2 of the HSM firmware, IV generation is optimized in just 1 step (IV generation and encryption). In previous versions, the generation of the IV is done in 2 separate steps, done in the HSM and transparent to the caller. Set TRUE for automatic IV generation. If this option is not set, the default value will be FALSE, meaning that the IV must be set by the user using the DKP_IV option. It must be used in RM2 and RM3 modes. The IV value generated must be retrieved with the DGetKeyParam() function using the DKP_IV parameter. The new IV will be available after the first call to DEncrypt. This option should only be enabled for encryption.
DKP_PADDING	Type of `pbData:` DWORD The library can work with the following symmetric paddings: D_NO_PADDING: No padding is done, the data passed for encryption must already be a multiple length of the operation block size. D_PKCS5_PADDING: Padding is done following the pattern defined in PKCS#5. This is the default padding if none is defined. D_ZERO_PADDING: If the length of the data is not a multiple of the size of the operation block, it is completed with leading zeros until it reaches a size supported by the algorithm. This type of padding should not be used with data where there may be bytes with a value of zero, as it could lead to ambiguity in the decryption operation. If the data contains only ASCII text, for example, there is no problem. Only valid for symmetric keys. The library can work with the following asymmetric paddings: D_PKCS1_PADDING: The padding is done following the pattern defined in PKCS#1 v1.5. It is the default padding for RSA keys, if none is defined. D_PSS_PADDING: Padding is done following the PSS standard defined in PKCS#1 EMSA-PSS-ENCODE with the hash equal to that used in the message hash, using the salt with the maximum size available in the block. Option not available for legacy signatures. D_PSS_SALT_LEN_MD_PADDING: Padding is done following the PSS standard defined in PKCS#1 EMSA-PSS-ENCODE with the hash equal to that used in the message hash, using the salt with the same size as the hash output used in the operation. Option not available for legacy signatures. D_OAEP_SHA1_PADDING: Padding is done following the PKCS#1 version 2.1 standard, with the RSAES-OAEP encryption scheme with SHA-1 hash. Option not available for legacy signatures. D_OAEP_SHA2_256_PADDING: Padding is done following the PKCS#1 version 2.1 standard, with RSAES-OAEP encryption scheme with SHA2-256 hash. Option not available for legacy signatures. D_X931_PADDING: Padding is done following the ANSI X9.31 standard. Option not available for legacy signatures. D_NO_PADDING: No padding is done, the data passed for encryption must already be the length of the operation block size for RSA keys. For RSA only available in legacy operations. For elliptic curve keys there is no padding and it is available in non-legacy operations. Default option for elliptic curve keys.
DKP_MODE	Type of `pbData:` DWORD Indicates the encryption operation mode of the block algorithm. MODE_ECB: Electronic Codebook (ECB) MODE_CBC: Cipher Block Chain (CBC) MODE_GCM: Galois/Counter Mode. The authentication tag is located right after the encrypted/decrypted data with the size of (returned size - message size in clear text). Pass in DEncrypt() DN_GCM_MODE_TAG_LEN extra bytes in the buffer of the last block to accommodate the TAG. MODE_KW: AESWRAP according to the RFC-3394 standard. Used in the encryption and decryption operations of other keys, see DExportKey() and DImportKey() APIs. The padding used is the one defined in the standard, any other value will be ignored. Use the default IV with value 0xA6A6A6A6A6A6A60000000000000000. MODE_KWP: AESWRAP with padding according to the RFC-5649 standard. Used in the encryption and decryption operations of other keys, see DExportKey() and DImportKey() APIs. The padding used is the one defined in the standard, any other value will be ignored. Use the default IV with value 0xA65959A6000000000000000000000000. MODE_OFB: Output-Feedback. Not yet supported. Only valid for symmetric keys and block algorithms.
DKP_OWNER	Type of `pbData:` char * Assigns a user the privilege of owning the key. `pbData` is a pointer to a string with the identifier of an HSM user. Not yet supported.
DKP_USER	Type of `pbData:` char * Assigns a user the key's user privilege. `pbData` is a pointer to a string with the identifier of an HSM user. Not yet supported.
DKP_READ_LOCK	Type of `pbData:` NULL Marks the key as non-exportable. Not yet supported.
DKP_PQC_SIG_DET	Type of `pbData:` BYTE * Defines whether the ML-DSA signature will be deterministic or non-deterministic (hedged). Set TRUE for deterministic and FALSE for hedged. FALSE will be the default value if this property is not set.
DKP_PQC_SIG_PH	Type of `pbData:` BYTE * Defines whether the ML-DSA signature will be with or without pre-hash (pre-calculated hash). Set TRUE to pre-hash, in which case the hash context must be passed with hash algorithms other than ALG_IDENTITY_FUNC, where M' will be calculated internally. Set FALSE for the hash to be calculated in the operation, use the ALG_IDENTITY_FUNC hash algorithm, passing the message. FALSE will be the default value if this property is not set.
DKP_PQC_CTX	Type of `pbData:` BYTE * Defines the signature context string for the PQC ML-DSA and SLH-DSA keys. The buffer size must be a maximum of DN_MAX_PQC_DSA_CTX_LEN. If this option is not set, the default value will be NULL.

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

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

[in] dwFlags REMOVE_ATTRIBUTE can be used to revoke a user's privilege over a key. This flag should only be used in conjunction with DKP_OWNER or DKP_USER.

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

Examples: crypt_sym_gcm.c, crypt_sym_gcm_iv_auto.c, sign_verify_pqc_ml_dsa.c and sign_verify_pqc_slh_dsa.c.

◆ DGetKeyParam()

int AAP_API DGetKeyParam	(	HKEYCTX	hKey,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Retrieves parameters from key contexts.

Parameters

[in] hKey Key context to be exported

[in]

dwParam

Defines the operation to be executed and, consequently, the structure or data passed in the parameter pbData. All values described in DSetKeyParam() and more:

Value	meaning
DKP_ALGID	Type of `pbData:` DWORD Retrieves the cryptographic algorithm associated with the key. The list of possible values is the same as that defined for the nAlgId parameter in the DGenerateKey function (see page 36). If the object is not a cryptographic key, the value returned is ALG_OBJ.
DKP_KEYLEN	Type of `pbData:` DWORD Retrieves the size of the key in bytes.
DKP_ENCRYPTED	Type of `pbData:` BOOL Returns the state of the key inside the HSM. If true the key will be stored encrypted inside the HSM, if false the key will be stored in the clear.
DKP_KEY_INFO	Type of `pbData:` GET_USR_KEY_OFFLINE Returns the basic key information.
DKP_BLOCK_SIZE	Type of `pbData:` DWORD Retrieves the key's block size in bytes.
DKP_OBJ_ATTRIBUTES	Type of `pbData:` DWORD Retrieves the attributes of the key.
DKP_OBJ_STATS	Type of `pbData:` DN_OBJ_STATS Retrieves the object's statistics information.

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

[in] pdwDataLen Size of data or structure specified in dwParam

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

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

See also: DGenerateKey().

Examples: crypt_sym_gcm_iv_auto.c and key_attribute.c.

◆ DDeriveKey()

int AAP_API DDeriveKey	(	HHASHCTX	hHash,
		char *	szKeyId,
		int	nAlgId,
		DWORD	dwFlags,
		HKEYCTX *	phKey )

#include <dinamo.h>

Derives a key from the provided hash. If the hash is not yet complete, it will be finalized and its value used as a symmetric key.

Parameters

[in]	hHash	Hash context created with DCreateHash.
[in]	szKeyId	Identifier of the key within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. See `szKeyId` in DGenerateKey() for details on maximum identifier sizes.
[in]	nAlgId	Indicates the algorithm associated with the cryptographic key to be generated. See the list of algorithms in DGenerateKey().
[in]	dwFlags	Additional key parameters. See the list of additional key parameters in DGenerateKey().
[in]	phKey	Pointer to the context of the generated key. After use, it must be released with the DDestroyKey() function.

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

◆ DDuplicateKey()

int AAP_API DDuplicateKey	(	HKEYCTX	hKey,
		DWORD	dwFlags,
		HKEYCTX *	phKey )

#include <dinamo.h>

Duplicates a key context, including its internal state.

Parameters

[in]	hKey	Key context.
[in]	dwFlags	Reserved for future use (must be 0).
[out]	phKey	Pointer to the context of the generated key. After use, it must be released with the DDestroyKey() function.

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

Notes: Key contexts are independent; thus, when the original context is released, the new context remains valid.

◆ DHashSessionKey()

int AAP_API DHashSessionKey	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		DWORD	dwFlags )

#include <dinamo.h>

Uses the value of a symmetric key as input data for a hash operation. The hash context must be clean to be used with this function; that is, it cannot have been used with the DHashData() function.

Parameters

[in]	hKey	Key context.
[in]	hHash	Hash context created with DCreateHash().
[in]	dwFlags	Reserved for future use (must be 0).

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

Notes: For this operation to be performed, the key must be marked as exportable.

◆ DDestroyKey()

int AAP_API DDestroyKey	(	HKEYCTX *	phKey,
		DWORD	dwFlags )

#include <dinamo.h>

Releases a key context after use. Once released, this context can no longer be used by any function and becomes invalid.

Parameters

[in] phKey Pointer to a key context that will be released.

[in]

dwFlags

Operation modifiers.

Value	Meaning
REMOVE_FROM_HSM	In addition to releasing the context pointed to by `phKey`, it physically removes the key from the HSM base. This parameter should only be used when it is certain that the key will no longer be needed.

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

◆ DGeneratePKCS10CSR()

int AAP_API DGeneratePKCS10CSR	(	HSESSIONCTX	hSession,
		char *	szPrivateKeyName,
		BYTE	bVersion,
		char *	szDN,
		DWORD	dwOutType,
		DWORD *	pdwCSRLen,
		BYTE **	ppbCSR,
		DWORD	dwParam )

#include <dinamo.h>

Generates a CSR (Certificate Signing Request). This is a specialized function of the HSM's PKCS#10 CSR generation API.

Parameters

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

[in] szPrivateKeyName Private key identifier.

[in]

bVersion

PKCS#10 CSR version. The following table is supported.

Value	Meaning
CORE_P10_CSR_VERSION1	PKCS#10 CSR version 1.

[in] szDN DN (Distinguished Name), for CSR generation, with a maximum length of CORE_P10_CSR_DN_MAX_LEN. DN fields must be separated by '/'.

[in]

dwOutType

CSR output type. The following table is supported.

Value	Meaning
P10_CSR_DER	Exports the CSR in DER format.
P10_CSR_PEM	Exports the CSR in PEM format.

[out] pdwCSRLen Pointer to the size of the buffer allocated in ppbCSR.

[out] ppbCSR Pointer to a pointer that will receive the CSR.
The size of the allocated buffer will be available via pdwCSRLen.
Memory allocation is handled internally.
The calling application is responsible for freeing the allocated memory using the DFree() API.

[in]

dwParam

Additional parameters. The following table is supported.

Value	Meaning
0	Uses the HSM's default hash for CSR signing.
CORE_P10_HASH_SHA1	Uses SHA-1 for CSR signing.
CORE_P10_HASH_SHA224	Uses SHA-224 for CSR signing.
CORE_P10_HASH_SHA256	Uses SHA-256 for the CSR signature.
CORE_P10_HASH_SHA384	Uses SHA-384 for the CSR signature.
CORE_P10_HASH_SHA512	Uses SHA-512 for the CSR signature.
CORE_P10_HASH_SHA3_224	It uses SHA3-224 to sign the CSR.
CORE_P10_HASH_SHA3_256	It uses SHA3-256 to sign the CSR.
CORE_P10_HASH_SHA3_384	It uses SHA3-384 to sign the CSR.
CORE_P10_HASH_SHA3_512	Use SHA3-512 to sign the CSR.

Notes: Examples of DN field.
/CN=teste

/CN=www.teste.com/O=teste/OU=engenharia

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

Examples: gen_csr.c.

◆ DAssociatePKCS11Key()

int AAP_API DAssociatePKCS11Key	(	HSESSIONCTX	hSession,
		char *	szPriKey,
		char *	szPubKey,
		char *	szCert,
		void *	pvReserved,
		DWORD	dwReserved )

#include <dinamo.h>

Associates a private key with a certificate and optionally a public key, following the PKCS#11 Base v2.40 specifications, section 4.6.3, and as used by Firefox.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function. .
[in]	szPriKey	Name of the private key to be associated.
[in]	szPubKey	Name of the public key to be associated. NULL can be passed to avoid generating the associated public key. It must be related to the private key.
[in]	szCert	Name of the certificate to be exported. It must be related to the private key.
[in]	pvReserved	Reserved for future use. Must be NULL.
[in]	dwReserved	Reserved for future use. Must be 0.

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

Notes

The default association is based on the one used by Firefox, which modifies object metadata according to the table below.

Attribute	Value
CKA_ID	SHA1 of the public key module. Defined for Private key, public key, and certificate.
CKA_LABEL	Certificate ID. Defined for private key and certificate.
CKA_SUBJECT	Subject retrieved from the certificate. Defined for private key and certificate.

For EC keys, CKA_ID will be the SHA1 hash of the CKA_PUBLIC_KEY_INFO value.

See also: DImportPKCS12().

◆ DExportPKCS12()

int AAP_API DExportPKCS12	(	const HSESSIONCTX	hSession,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szReserved,
		BYTE **	ppbPkcs12,
		DWORD *	pdwPkcs12Len,
		DWORD	dwFlags )

#include <dinamo.h>

Exports an RSA private key and certificate in PKCS#12 format.

Parameters

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

[in] szPkcs12Pwd Password for the PKCS#12 file. Pass NULL to generate a PKCS#12 without a password.

[in] szKeyId Name of the private key to be exported. See szKeyId in DGenerateKey() for details on maximum identifier sizes.

[in] szCertId Name of the certificate to be exported. It must be related to the private key.

[in] szReserved Reserved for future use. Must be NULL.

[out] ppbPkcs12 Pointer to a pointer that will contain the generated PKCS#12. This data area will be internally allocated and must be freed using DFree().

[out] pdwPkcs12Len Pointer to the size of the data written in ppbPkcs12.

[in]

dwFlags

Pass 0 or one of the options from the table below.

Attribute	Value
DN_EXPORT_P12_LEGACY	Exports the key and certificate and generates the PKCS#12 file in software.

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

Notes: The PKCS#12 export with the DN_EXPORT_P12_LEGACY flag uses RC2 for certificate encryption, TripleDES(CBC) for key encryption, and SHA1 as the default hash.

See also: DImportPKCS12Buffer() DImportPKCS12().

◆ DImportPKCS12Buffer()

int AAP_API DImportPKCS12Buffer	(	const HSESSIONCTX	hSession,
		BYTE *	pbPkcs12,
		DWORD	dwPkcs12Len,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		DWORD	dwKeyAttr,
		const char *	szCertId,
		const char *	szPubKeyId,
		DWORD	dwFlags )

#include <dinamo.h>

Imports a private/public key and a certificate from a buffer in PKCS#12 format.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function. .
[in]	pbPkcs12	PKCS#12 to be imported.
[in]	dwPkcs12Len	Size of the buffer containing PKCS#12 in `pbPkcs12`.
[in]	szPkcs12Pwd	PKCS#12 password. Pass NULL if there is no password.
[in]	szKeyId	Name of the private key to be imported. See `szKeyId` in DGenerateKey() for details on maximum identifier sizes.
[in]	dwKeyAttr	Attributes of the private key that will be imported See `dwFlags` in DGenerateKey() for details on the key attributes.
[in]	szCertId	Name of the certificate to be imported. It must be related to the private key.
[in]	szPubKeyId	Name of the public key that can be imported. Can be NULL if the public key is not to be imported.
[in]	dwFlags	Reserved for future use. Must be 0.

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

See also: DExportPKCS12(), DImportPKCS12().

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

◆ DImportPKCS12()

int AAP_API DImportPKCS12	(	const HSESSIONCTX	hSession,
		const char *	szPkcs12File,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		const DWORD	dwKeyAttr,
		const char *	szCertId )

#include <dinamo.h>

Imports a private/public key and a certificate from a PKCS#12 formatted file.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function. .
[in]	szPkcs12File	Name of the PKCS#12 file to be imported.
[in]	szPkcs12Pwd	PKCS#12 password. Pass NULL if there is no password.
[in]	szKeyId	Name of the private key to be imported. See `szKeyId` in DGenerateKey() for details on maximum identifier sizes.
[in]	dwKeyAttr	Attributes of the private key that will be imported See `dwFlags` in DGenerateKey() for details on the key attributes.
[in]	szCertId	Name of the certificate to be imported. It must be related to the private key.

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

See also: DExportPKCS12(), DImportPKCS12Buffer().

◆ DRSAPublicKey2Info()

int AAP_API DRSAPublicKey2Info	(	BYTE *	pbKey,
		DWORD	dwKeyLen,
		DWORD	dwInForm,
		void *	pvPubKeyInfo,
		DWORD	dwReserved )

#include <dinamo.h>

Decodes the information of an RSA public key. It accepts public keys in PKCS#1 RSAPublicKey or X.509 SubjectPublicKeyInfo format.

Parameters

[in] pbKey Public key.

[in] dwKeyLen Size of the pbKey buffer.

[in]

dwInForm

Key input format in pbKey. The table below is accepted.

Attribute	Value
DN_FORM_DER	Key in DER format.

[out] pvPubKeyInfo Pointer to a DN_RSA_PUB_KEY_INFO structure.

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

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

◆ DRSAPrivateKey2Info()

int AAP_API DRSAPrivateKey2Info	(	const BYTE *	pbRsa,
		DWORD	dwRsaLen,
		DWORD	dwInForm,
		DN_RSA_PRIVATE_KEY_INFO *	stRsaInfo,
		DWORD	dwReserved )

#include <dinamo.h>

Decodes the information of an RSA private key. It accepts private keys in PKCS#1 RSAPrivateKey or unencrypted PKCS#8 PrivateKeyInfo format.

Parameters

[in] pbRsa Private key.

[in] dwRsaLen Size of the pbRsa buffer.

[in]

dwInForm

Key input format in pbRsa. The table below is accepted.

Attribute	Value
DN_FORM_DER	Key in DER format.

[out] stRsaInfo Pointer to a DN_RSA_PRIVATE_KEY_INFO structure.

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

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

◆ DByokExport()

int AAP_API DByokExport	(	HSESSIONCTX	hSession,
		const char *	cszKeyId,
		const char *	cszKekId,
		DWORD	dwType,
		const void *	pvData,
		BYTE **	ppbOutData,
		DWORD *	pdwOutDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Exports a key in BYOK (Bring Your Own Key) format to a cloud provider.

Parameters

[in] hSession Session context.

[in] cszKeyId Identifier of the key to be exported. See szKeyId in DGenerateKey() for details on maximum identifier sizes.

[in] cszKekId Identifier of the KEK key that will be used to encrypt the key to be exported.

[in]

dwType

Export type. The table below is supported.

Attribute	Value
DN_BYOK_TYPE_AZURE	Export BYOK key to Azure. Pass the DN_EXPORT_BYOK_AZURE structure in `pvData`.
DN_BYOK_TYPE_AWS	Export BYOK key to AWS. Pass D_OAEP_SHA1_PADDING or D_OAEP_SHA2_256_PADDING. DWORD type in `pvData`.

[in] pvData Pointer to a specific data structure for each type of export. See dwType for details.

[out] ppbOutData Pointer to a pointer that will contain the output data. This data area will be internally allocated and must be freed using DFree().

[out] pdwOutDataLen Pointer to the size of the data written to ppbOutData.

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

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

Detailed description

Data Structures

Definitions and Macros

Functions

Definitions and macros

◆ D_IMPORT_ALG_PRIV_KEY_RSA

◆ D_IMPORT_ALG_PRIV_KEY_ECC

◆ D_IMPORT_ALG_PRIV_KEY_P8

◆ D_IMPORT_ALG_PRIV_KEY_ECX

◆ D_IMPORT_ALG_PRIV_KEY_DSA

◆ D_IMPORT_ALG_PRIV_KEY_DH

◆ D_IMPORT_ALG_PRIV_KEY_ML_DSA

◆ D_IMPORT_ALG_PRIV_KEY_ML_KEM

◆ D_IMPORT_ALG_PRIV_KEY_SLH_DSA

◆ DN_FORM_DER

◆ DN_BYOK_TYPE_AZURE

◆ DN_BYOK_TYPE_AWS

Functions

◆ DGenerateKey()

◆ DGenerateKeyMaterial()

◆ DGetUserKey()

◆ DImportKey()

◆ DExportKey()

◆ DPKCS8ImportKey()

◆ DPKCS8ExportKey()

◆ DSetKeyParam()

◆ DGetKeyParam()

◆ DDeriveKey()

◆ DDuplicateKey()

◆ DHashSessionKey()

◆ DDestroyKey()

◆ DGeneratePKCS10CSR()

◆ DAssociatePKCS11Key()

◆ DExportPKCS12()

◆ DImportPKCS12Buffer()

◆ DImportPKCS12()

◆ DRSAPublicKey2Info()

◆ DRSAPrivateKey2Info()

◆ DByokExport()