Detailed description

Managing the life cycle of cryptographic keys in HSM.

Managing the life cycle of cryptographic keys in HSM. More...

Data Structures
struct	DN_EXPORT_BYOK_AZURE

Settings 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 except ECX). */

#define	D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFDF) /* Import a key in P8 format */

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

#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) /* Import an RSA private key. */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ECC

#define D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Imports an ECC private key (Elliptic Curves except ECX). */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_P8

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

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ECX

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

#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>

Export 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 parameters entered, within the HSM.

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. An object identifier in the HSM can have a maximum length, in characters, of MAX_OBJ_ID (including the terminator character). When creating keys in another user's partition (permission 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 terminator character).

[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	168-bit 3DES-EDE(Encrypt-Decrypt-Encrypt) with odd parity.
ALG_DESX	DESX of 192 bits. The effective size is 118 bits.
ALG_ARC4	ARC4 with 128 bits.
ALG_ARC5	ARC5 with 128 bits, 8-byte block and using 16 rounds.
ALG_AES_128	128-bit AES.
ALG_AES_192	AES with 192 bits.
ALG_AES_256	256-bit AES.

RSA Asymmetric Keys

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

ECC Asymmetric Keys

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

ECX Asymmetric Keys

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

HMAC Keys

Value	Meaning
ALG_HMAC_MD5	HMAC MD5 key with a size of 16 bytes.
ALG_HMAC_SHA1	HMAC SHA1 key with a size of 20 bytes.
ALG_HMAC_SHA2_256	HMAC SHA2 256 key with a size of 32 bytes.
ALG_HMAC_SHA2_384	HMAC SHA2 384 key with a size of 48 bytes.
ALG_HMAC_SHA2_512	HMAC SHA2 512 key with a size of 64 bytes.

[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, must be NULL.

In addition to the values in the previous table, you can add a key usage profile definition.
You can define the key usage profile (Attribute Usage-profile), using only one of the values below. If none of the values below are specified, the switch profile is set to free for any use. It is mandatory to define the usage profile 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	VSC generation/verification
AUP_EFT_VISA_PVK	PVP 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 derivation MK, IDN
AUP_EMV_IMKDAC	ICC DAC shunt
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	signature/envelope TR34
AUP_SPB_PK	SPB signature generation/verification and key wrapping

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

Return: 0 (ZERO) if the function is successful.
See 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 symmetric key contexts are assigned the following default values, where applicable:

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

The operation block size of the algorithms 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 216 + 1 = 65537). Optionally, an exponent of value 3 can be used for reasons of compatibility with older systems, but this is not recommended.
ECC keys are defined according to 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

Examples: crypt_sym.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, key_add_remove.c, key_attribute.c, pin_block_translate.c, sign_verify.c, sign_verify_eddsa.c and tokenization.c.

◆ DGenerateKeyMaterial()

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

#include <dinamo.h>

It generates a cryptographic key and returns its contents. This operation generates a key using the HSM and returns the contents of the key without persisting the key in the HSM.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	nAlgId	Defines the algorithm of the cryptographic key to be generated. This operation only supports symmetric key algorithms. See list of algorithms in DGenerateKey().
[in]	pbData	Buffer that will contain the generated key. NULL can be passed 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 size entered is not sufficient to complete the operation, pdwDataLen will contain the expected size of pbData.
[in]	dwReserved	Reserved for future use.

Return: 0 (ZERO) if the function is successful.
See 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, as long as 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	It will generate a key handle based on specific parameters and will not go to the HSM to check the parameters entered. To use this flag, a duly completed GET_USR_KEY_OFFLINE structure must be passed in szKeyId. Note that no correlation checks are made on the data entered. 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 used only in specific cases of use of M of N of partition in the state of `associate, authorized`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.

Return: 0 (ZERO) if the function is successful.
See 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>

Import a cryptographic key into the HSM. Keys can be permanent or temporary. Keys exported with the DExportKey() function can be imported without changing their format.

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 Context of the key with which the blob of the key to be imported is encrypted - KEK (key encryption key)

[in]

dwBlobType

Key buffer format in parameter pbData.

Value	Meaning
PRIVATEKEY_BLOB_STRICT	An RSA or EC 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.
PRIVATEKEY_BLOB	Same behavior as PRIVATEKEY_BLOB_STRICT but older versions of HSM can return RSA keys as a concatenation of private key and public key in the formats defined in PKCS#1 v1.5, in sections 7.1 and 7.2. This option is retained 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 the PrivateKeyInfo 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 public keys (ECC and ECX) the standard is the SubjectPublicKeyInfo DER format.
SIMPLE_BLOB	A symmetric key will be imported in the format SIMPLE_BLOB.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 to encrypt the key must be 2, as defined in PKCS#1 v1.5 section 8.1.
PLAINTEXTKEY_BLOB	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	It defines a symmetric key encrypted by a KEK (Key Encryption Key) that 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 into the HSM base directly, without any specific formatting.
HOTP_BLOB	Defines the import of an HTOP object into the user partition.
PUBLICKEY_BLOB_HSM	A public key from an RSA/ECC key pair in DER format will be imported into the HSM. hKEKey must be equal to NULL.
PUBLICKEY_RSA_PARTS_HSM	A public key will be imported into the HSM from the module and the public exponent. hKEKey must be equal to NULL. The completed RSA_PUB_KEY_PARTS structure must be passed in pbData.
WRAPPED_KEY_BLOB	Import 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 into the HSM database directly, without any specific formatting.
WRAPPED_KEY_BLOB_P8	Import 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 into the HSM database directly, without any specific formatting. In the key export operation, the format of the private key will be PKCS#8.

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

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

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

[in] dwDataLen Size of the data block with 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.

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

Notes: For session keys and public keys, it is recommended that the TEMPORARY_KEY flag is used, to avoid temporary keys taking up unnecessary space in the HSM.

SIMPLE_BLOB format:

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

PRIVATEKEY_BLOB DER structures:

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
}

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: DGenerateKey() observations.

Examples: eft_validate_cvv.c, import_export.c, pin_block_translate.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 parameter `pbData`. See parameter `dwBlobType` in DImportKey() for the 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 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`.

Return: 0 (ZERO) if the function is successful.
See 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_ecdh.c, gen_xecdh.c and import_export.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 asymmetric RSA private key enveloped according to the PKCS#8 standard into the HSM. The RSA private key can be imported in clear text or protected by a digital envelope. For details on the standards, see the RSA Labs Public-Key Cryptography Standards (PKCS) documents. In the restricted operating modes (RM1 and RM2), RSA keys can only be imported via the PKCS#8 standard using a digital envelope, deriving an AES 256 key from a password of at least 01 character and no more than 16, and the derivation is done according to the PKCS#5 version 2.0 standard.
The envelope used can come from any system that adheres to the standards described.

Parameters

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

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

[in] szSecret Password used to derive the AES 256 key. Can be passed NULL for no password (import in clear text) or a password of no ND_MAX_P8_PWD_LEN characters plus null terminator.

[in]

dwKeyAlg

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

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

[in]

dwAttrib

Additional key parameters.

Value	Meaning
EXPORTABLE_KEY	The key can be exported in HSM clear.

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

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

Return: 0 (ZERO) if the function is successful.
See 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 asymmetric RSA private key stored in the HSM according to the PKCS#8 standard. The RSA private key can be exported in clear text or protected by a digital envelope. For details on the standards, see the RSA Labs Public-Key Cryptography Standards (PKCS) documents. In restricted operating modes (RM1 and RM2), exportable RSA keys can only be exported via the PKCS#8 standard using a digital envelope, deriving an AES 256 key from a password between ND_MIN_P8_PWD_LEN and ND_MAX_P8_PWD_LEN characters in length, and the derivation is done according to the PKCS#5 version 2.0 standard. The output envelope can be imported into any system that adheres to the standards described.

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 plus null terminator, used to derive the AES 256 key. NULL can be passed to export in clear text, without a password.
[out]	ppbKeyEnvelope	Pointer that will contain the outgoing PKCS#8 envelope. Memory allocation is done internally by the library. The calling application is responsible for freeing the allocated memory. The DFree() function must be used to free this buffer.
[out]	pdwKeyEnvelopeLen	Pointer to DWORD that will contain the size in bytes of the outgoing PKCS#8 envelope.

Return: 0 (ZERO) if the function is successful.
See 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>

Changes the parameters of key contexts which, in general, will influence their manipulation.

Parameters

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

[in]

dwParam

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

Value	meaning
DKP_IV	Type of `pbData:` BYTE * Initialization vector used with blockchain 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 operation block. More details in the Remarks section. Only valid for symmetric keys.
DKP_PADDING	Type of `pbData:` DWORD The library can work with the following symmetrical paddings: D_NO_PADDING: No padding is done, the data passed for encryption must already be a multiple of the operation block size. D_PKCS5_PADDING: Padding is done following the standard defined in PKCS#5. This is the default padding if none is defined. D_ZERO_PADDINGIf 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 zero bytes, as it can create 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: Padding is done following the standard defined in PKCS#1 v1.5. It is the standard 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 same hash as used in the message hash, using the salt with the maximum size available in the block. Option not available for legacy subscriptions. D_PSS_SALT_LEN_MD_PADDING: Padding is done following the PSS standard defined in PKCS#1 EMSA-PSS-ENCODE with the same hash as 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 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, data passed for encryption must already be the length of the operation block for RSA keys. For RSA only available in legacy operations. For elliptic curve keys, no padding and available in non-legacy operations. Default option for elliptic curve keys.
DKP_MODE	Type of `pbData:` DWORD Indicates the encryption operating 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). MODE_KW: AESWRAP according to the standard RFC-3394. Used in the encryption and decryption operations of other keys. 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 standard RFC-5649. Used in the encryption and decryption operations of other keys. 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 Mark the key as non-exportable. Not yet supported.

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

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

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

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

◆ 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 Context of the key to be exported

[in]

dwParam

Defines the operation that will be performed 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 is stored encrypted inside the HSM; if false, the key is stored in the clear.
DKP_KEY_INFO	Type of `pbData:` GET_USR_KEY_OFFLINE Returns the key's basic information.
DKP_BLOCK_SIZE	Type of `pbData:` DWORD Retrieves the size of the key block 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 statistical 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).

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

See also: DGenerateKey().

Examples: 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 hash entered. 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 that will be generated. See list of algorithms in DGenerateKey().
[in]	dwFlags	Additional key parameters. See 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.

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

◆ DDuplicateKey()

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

#include <dinamo.h>

Duplicates the context of a key, 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.

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

Notes: The contexts of the keys are independent, so when you release the original context, the new context is still 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 the execution of a hash. The hash context must have a clean context in order to be used in this function, i.e. 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).

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

Notes: The key must be marked as exportable for this operation to take place.

◆ DDestroyKey()

int AAP_API DDestroyKey	(	HKEYCTX *	phKey,
		DWORD	dwFlags )

#include <dinamo.h>

Releases the context of a key 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] 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 out by `phKey`physically removes the key from the base of the HSM. This parameter should only be used when it is certain that the key will no longer be needed.

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

Examples: crypt_sym.c, eft_validate_cvv.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, import_export.c, key_add_remove.c, key_attribute.c, pin_block_translate.c, sign_verify.c, sign_verify_eddsa.c and verify_pin_block.c.

◆ 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 HSM's PKCS#10 CSR generation API.

Parameters

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

[in] szPrivateKeyName Private key identifier.

[in]

bVersion

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

Value	Meaning
CORE_P10_CSR_VERSION1	PKCS#10 CSR version 1.

[in] szDN DN (Dinstinguished Name), for generating the CSR, with a maximum size 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 that will receive the CSR.
The size of the allocated buffer will be available via pdwCSRLen.
Memory allocation is done 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 standard HSM hash in the CSR signature.
CORE_P10_HASH_SHA1	It uses SHA-1 in the CSR signature.
CORE_P10_HASH_SHA224	It uses SHA-224 in the CSR signature.
CORE_P10_HASH_SHA256	It uses SHA-256 in the CSR signature.
CORE_P10_HASH_SHA384	It uses SHA-384 in the CSR signature.
CORE_P10_HASH_SHA512	It uses SHA-512 in the CSR signature.

Notes: DN field examples.
/CN=test

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

Return: 0 (ZERO) if the function is successful.
See 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>

It associates a private key with a certificate and optionally a public key following the PKCS#11 Base v2.40 section 4.6.3 specifications and the one 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. You can pass NULL to avoid generating the associated public key. 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.

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

Notes

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

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

In the case of EC keys, the 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 a private key and an RSA certificate in PKCS#12 format.

Parameters

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

[in] szPkcs12Pwd Password for PKCS#12 file. Pass NULL to generate PKCS#12 without 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 allocated internally 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 in the table below.

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

Return: 0 (ZERO) if the function is successful.
See 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 that will be imported.
[in]	dwPkcs12Len	Size of the buffer containing PKCS#12 in `pbPkcs12`.
[in]	szPkcs12Pwd	Password for PKCS#12. Pass NULL in case 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 to 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 you don't want the public key to be imported.
[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.

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 file in PKCS#12 format.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function. .
[in]	szPkcs12File	Name of the PKCS#12 file to be imported.
[in]	szPkcs12Pwd	Password for PKCS#12. Pass NULL in case 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 to 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.

Return: 0 (ZERO) if the function is successful.
See 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>

Decrypts the information in an RSA public key. Accepts public keys in PKCS#1 RSAPublicKey or X.509 SubjectPublicKeyInfo format.

Parameters

[in] pbKey Public key.

[in] dwKeyLen Buffer size pbKey.

[in]

dwInForm

Key entry 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).

Return: 0 (ZERO) if the function is successful.
See 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>

Decrypts the information in an RSA private key. Accepts private keys in PKCS#1 RSAPrivateKey or PKCS#8 PrivateKeyInfo format without encryption.

Parameters

[in] pbRsa Private key.

[in] dwRsaLen Buffer size pbRsa.

[in]

dwInForm

Key entry 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).

Return: 0 (ZERO) if the function is successful.
See 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>

Export 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 that will be exported.

[in]

dwType

Type of export. The table below is accepted.

Attribute	Value
DN_BYOK_TYPE_AZURE	Export BYOK key to Azure. Pass the structure DN_EXPORT_BYOK_AZURE 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 allocated internally and must be freed using DFree().

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

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

Detailed description

Data Structures

Settings 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

◆ 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()