Detailed description

Managing the life cycle of cryptographic keys in HSM.

Functions
IntPtr	GenerateKey (string KeyId, DinamoClient.KEY_ALG Alg, bool Exportable)
	Generates a permanent key in the HSM.

IntPtr	GenerateKey (string KeyId, DinamoClient.KEY_ALG Alg, bool Exportable, bool Temporary)
	Generates key.

IntPtr	GetUserKey (string KeyId)
	Returns the Handler of a key (DestroyUserKey must be called after allocation).

void	DestroyKey (IntPtr hKey)
	Release key handle.

int	GetKeyAlgId (string strKeyId)
	Returns the algorithm of a key.

int	GetKeyAlgId (IntPtr hKey)
	Returns the type of a key.

int	GetKeyPadding (IntPtr hKey)
	Returns the padding type of a key.

int	GetUserKeyLen (string KeyId)
	Returns the size of a key.

int	GetUserKeyLen (IntPtr hKey)
	Returns the size of a key.

bool	IsKeyExist (string KeyId)

bool	HasObject (string Id)
	Verifies the existence of an object.

void	GetMapInfo (string ObjectId, ref string Obj1Id, ref string Obj2Id)
	Retrieves map information (backward compatibility)

void	GetMapInfo (string ObjectId, ref string Obj1Id, ref int Obj1TypeId, ref string Obj2Id, ref int Obj2TypeId)
	Retrieves map information.

List< CertAssociation >	ListCertAssociations (bool onlyWithAssociation=false)
	Lists the certificates and their associated private keys.

bool	IsKeyReadLock (string KeyId)
	Test if the key is exportable.

bool	IsKeyReadLock (IntPtr hKey)
	Test if the key is exportable.

bool	IsKeyEncrypted (string KeyId)
	Test that the key is encrypted.

bool	IsKeyEncrypted (IntPtr hKey)
	Test that the key is encrypted.

void	BlockObject (string szObjectName, bool bBlock)
	Changes the lock status of an object.

bool	IsObjectBlocked (string szObjectName)
	Recovers the locked state of an object.

void	GenerateMap (string MapId, string Obj1Id, ALG Obj1Type, string Obj2Id, ALG Obj2Type)

void	RemoveObject (string ObjectId)
	Removes an object from the HSM.

void	RemoveObjectIfExists (string ObjectId)
	Removes an object from the HSM, if it exists.

string[]	ListObjects ()
	Lists the objects of the current HSM user.

Int32	ListCallback (string szName, ref DinamoApi.DBLOB pParam, Int32 bFinal)

string[]	ListObjects (ALG type)

byte[]	ReadFile (string FileId)

Int32	WriteLocalFileCallback (IntPtr pbData, Int32 cbData, ref DinamoApi.DBLOB_FILE pParam, Int32 bFinal)

void	WriteFile (string FileId, byte[] byFileData)
	Imports objects into the HSM. Certificates, PKCS#7, Keys.

Int32	ReadLocalFileCallback (IntPtr pbData, ref Int32 pcbData, IntPtr pParam, out Int32 pbFinal)

byte[]	ExportKey (IntPtr hKey, IntPtr hKeyEncryptionKey, BLOB_TYPE BlobType)

IntPtr	ImportKey (string KeyId, IntPtr hKeyEncryptionKey, byte[] byKeyBlob, BLOB_TYPE BlobType, KEY_ALG AlgId)

IntPtr	ImportKey (string KeyId, IntPtr hKeyEncryptionKey, byte[] byKeyBlob, BLOB_TYPE BlobType, KEY_ALG AlgId, bool Exportable, bool Temporary)

void	ImportPKCS12File (string FilePath, string Password, string KeyId, string CertId, bool Exportable)
	Imports a key/certificate from a file in PKCS#12 format into the HSM.

Int32	ImportPKCS12 (string FilePath, string Password, string KeyId, string CertId, bool Exportable)

void	ImportPKCS12 (byte[] Pkcs12, string Password, string KeyId, string CertId, bool Exportable)
	Imports a key/certificate from a buffer in PKCS#12 format into the HSM.

void	ImportPKCS12 (byte[] Pkcs12, string Password, string KeyId, Int32 KeyAttr, string CertId, string PubKeyId, Int32 Reserved)
	Imports a key/certificate from a buffer in PKCS#12 format into the HSM.

byte[]	PKCS8ExportKey (string szKeyId, string szSecret)

byte[]	SPBExportPKCS12 (string szISPB, string szSecret)

byte[]	ExportPKCS12 (string KeyId, string CertId, string Secret)
	Exports an HSM key and certificate in PKCS#12 format.

byte[]	ExportPKCS12 (string KeyId, string CertId, string Secret, Int32 Flags)
	Exports an HSM key and certificate in PKCS#12 format.

void	PKCS8ImportKey (string szKeyId, string szSecret, int dwKeyAlg, int dwAttrib, byte[] bKeyEnvelope)

void	SPBImportPKCS12 (string szKeyId, string szSecret, string szDomain, int dwKeyAlg, int dwAttrib, string file)

Functions

◆ GenerateKey() [1/2]

IntPtr GenerateKey	(	string	KeyId,
		DinamoClient.KEY_ALG	Alg,
		bool	Exportable )

inline

Generates a permanent key in the HSM.

Parameters

KeyId	Key identifier. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. An object identifier in HSM can have a maximum length, in characters, of DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.
Alg	Algorithm to be used. Dinamo.Hsm.DinamoClient.KEY_ALG
Exportable	Flag indicating the generation of an exportable key.

Return: Handle to the generated key object.

Exceptions

DinamoException Throws exception in case of error.

Examples: block_object.cs, dukpt.cs, generate_hmac.cs, oath.cs and rsa_enc_dec.cs.

◆ GenerateKey() [2/2]

IntPtr GenerateKey	(	string	KeyId,
		DinamoClient.KEY_ALG	Alg,
		bool	Exportable,
		bool	Temporary )

inline

Generates key.

Parameters

KeyId	Key identifier. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. An object identifier in HSM can have a maximum length, in characters, of DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.
Alg	Key algorithm. Dinamo.Hsm.DinamoClient.KEY_ALG
Exportable	Flag to generate the exportable key.
Temporary	Flag to generate a temporary key. This key has a life cycle for the duration of the session.

Return: Key handle.

Exceptions

DinamoException Throws exception in case of error.

◆ GetUserKey()

IntPtr GetUserKey ( string KeyId )

inline

Returns the Handler of a key (DestroyUserKey must be called after allocation).

Parameters

KeyId Key identifier

Return: User object handle

Exceptions

DinamoException Throws exception in case of error.

◆ DestroyKey()

void DestroyKey ( IntPtr hKey )

inline

Release key handle.

Parameters

hKey	Key handle.

Exceptions

DinamoException Throws exception in case of error.

Examples: block_object.cs, eft_gen_pin.cs, eft_gen_verify_cvv.cs, eft_verify_pinblock. cs and rsa_enc_dec.cs.

◆ GetKeyAlgId() [1/2]

int GetKeyAlgId ( string strKeyId )

inline

Returns the algorithm of a key.

Parameters

strKeyId User name

Return: Algorithm identifier.

Exceptions

DinamoException Throws exception in case of error.

◆ GetKeyAlgId() [2/2]

int GetKeyAlgId ( IntPtr hKey )

inline

Returns the type of a key.

Parameters

hKey	Key handle

Return: Key type

Exceptions

DinamoException Throws exception in case of error.

◆ GetKeyPadding()

int GetKeyPadding ( IntPtr hKey )

inline

Returns the padding type of a key.

Parameters

hKey	Key handle

Return: Key padding type

Exceptions

DinamoException Throws exception in case of error.

◆ GetUserKeyLen() [1/2]

int GetUserKeyLen ( string KeyId )

inline

Returns the size of a key.

Parameters

KeyId Key identification

Return: Key size in bits

Exceptions

DinamoException Throws exception in case of error.

◆ GetUserKeyLen() [2/2]

int GetUserKeyLen ( IntPtr hKey )

inline

Returns the size of a key.

Parameters

hKey	Key handle

Return: Key size in bits

Exceptions

DinamoException Throws exception in case of error.

◆ IsKeyExist()

bool IsKeyExist ( string KeyId )

inline

Obsolete: This API is discontinued. Please use hasObject().

Examples: oath.cs.

◆ HasObject()

bool HasObject ( string Id )

inline

Verifies the existence of an object.

Parameters

Id	Object identifier in the HSM.

Return: True if the object exists

Exceptions

DinamoException Throws exception in case of error.

◆ GetMapInfo() [1/2]

void GetMapInfo	(	string	ObjectId,
		ref string	Obj1Id,
		ref string	Obj2Id )

inline

Retrieves map information (backward compatibility)

Parameters

ObjectId	Map name
Obj1Id	Name of the object in the first slot
Obj2Id	Name of the object in the second slot

Exceptions

DinamoException Throws exception in case of error.

◆ GetMapInfo() [2/2]

void GetMapInfo	(	string	ObjectId,
		ref string	Obj1Id,
		ref int	Obj1TypeId,
		ref string	Obj2Id,
		ref int	Obj2TypeId )

inline

Retrieves map information.

Parameters

ObjectId	Map name
Obj1Id	Name of the object in the first slot
Obj1TypeId	Object type in the first slot
Obj2Id	Name of the object in the second slot
Obj2TypeId	Object type in the second slot

Exceptions

DinamoException Throws exception in case of error.

◆ ListCertAssociations()

List< CertAssociation > ListCertAssociations ( bool onlyWithAssociation = false )

inline

Lists the certificates and their associated private keys.

Parameters

onlyWithAssociation True if you only want certificates with associated keys

Return: Returns a list of certificate associations with their respective private keys.

Exceptions

DinamoException Throws exception in case of error.

Examples: list_association.cs.

◆ IsKeyReadLock() [1/2]

bool IsKeyReadLock ( string KeyId )

inline

Test if the key is exportable.

Parameters

KeyId Key name

Return: True if the key is exportable

Exceptions

DinamoException Throws exception in case of error.

◆ IsKeyReadLock() [2/2]

bool IsKeyReadLock ( IntPtr hKey )

inline

Test if the key is exportable.

Parameters

hKey	Key handle

Return: True if the key is exportable

Exceptions

DinamoException Throws exception in case of error.

◆ IsKeyEncrypted() [1/2]

bool IsKeyEncrypted ( string KeyId )

inline

Test that the key is encrypted.

Parameters

KeyId Key name

Return: True if the key is encrypted

Exceptions

DinamoException Throws exception in case of error.

◆ IsKeyEncrypted() [2/2]

bool IsKeyEncrypted ( IntPtr hKey )

inline

Test that the key is encrypted.

Parameters

hKey	Key handle

Return: True if the key is encrypted

Exceptions

DinamoException Throws exception in case of error.

◆ BlockObject()

void BlockObject	(	string	szObjectName,
		bool	bBlock )

inline

Changes the lock status of an object.

Parameters

szObjectName	Object name
bBlock	true for locked and false for unlocked

Exceptions

DinamoException Throws exception in case of error.

Examples: block_object.cs.

◆ IsObjectBlocked()

bool IsObjectBlocked ( string szObjectName )

inline

Recovers the locked state of an object.

Parameters

szObjectName Object name

Return: true if locked and false if unlocked.

Exceptions

DinamoException Throws exception in case of error.

Examples: block_object.cs.

◆ GenerateMap()

void GenerateMap	(	string	MapId,
		string	Obj1Id,
		ALG	Obj1Type,
		string	Obj2Id,
		ALG	Obj2Type )

inline

◆ RemoveObject()

void RemoveObject ( string ObjectId )

inline

Removes an object from the HSM.

Parameters

ObjectId Object name

Exceptions

DinamoException Throws exception in case of error.

Examples: block_object.cs, dukpt.cs, eft_gen_pin.cs, eft_gen_verify_cvv.cs, eft_verify_pinblock.cs, generate_hmac.cs, generate_hmac_lau.cs and rsa_enc_dec.cs.

◆ RemoveObjectIfExists()

void RemoveObjectIfExists ( string ObjectId )

inline

Removes an object from the HSM, if it exists.

Parameters

ObjectId Object name

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_ckd.cs, bchain_eddsa_sign.cs, bchain_get_address.cs, bchain_get_pub. cs and bchain_sign_hash.cs.

◆ ListObjects() [1/2]

string[] ListObjects ( )

inline

Lists the objects of the current HSM user.

Return: Array containing the names of objects.

Exceptions

DinamoException Throws exception in case of error.

◆ ListCallback()

Int32 ListCallback	(	string	szName,
		ref DinamoApi.DBLOB	pParam,
		Int32	bFinal )

inline

◆ ListObjects() [2/2]

string[] ListObjects ( ALG type )

inline

◆ ReadFile()

byte[] ReadFile ( string FileId )

inline

Examples: read_file.cs.

◆ WriteLocalFileCallback()

Int32 WriteLocalFileCallback	(	IntPtr	pbData,
		Int32	cbData,
		ref DinamoApi.DBLOB_FILE	pParam,
		Int32	bFinal )

inline

◆ WriteFile()

void WriteFile	(	string	FileId,
		byte[]	byFileData )

inline

Imports objects into the HSM. Certificates, PKCS#7, Keys.

Parameters

FileId Key identifier. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. An object identifier in HSM can have a maximum length, in characters, of DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.

byFileData object in the

Exceptions

DinamoException Throws exception in case of error.

◆ ReadLocalFileCallback()

Int32 ReadLocalFileCallback	(	IntPtr	pbData,
		ref Int32	pcbData,
		IntPtr	pParam,
		out Int32	pbFinal )

inline

◆ ExportKey()

byte[] ExportKey	(	IntPtr	hKey,
		IntPtr	hKeyEncryptionKey,
		BLOB_TYPE	BlobType )

inline

Examples: rsa_enc_dec.cs.

◆ ImportKey() [1/2]

IntPtr ImportKey	(	string	KeyId,
		IntPtr	hKeyEncryptionKey,
		byte[]	byKeyBlob,
		BLOB_TYPE	BlobType,
		KEY_ALG	AlgId )

inline

Examples: eft_gen_pin.cs, eft_gen_verify_cvv.cs, eft_verify_pinblock.cs, generate_hmac_lau. cs and rsa_enc_dec.cs.

◆ ImportKey() [2/2]

IntPtr ImportKey	(	string	KeyId,
		IntPtr	hKeyEncryptionKey,
		byte[]	byKeyBlob,
		BLOB_TYPE	BlobType,
		KEY_ALG	AlgId,
		bool	Exportable,
		bool	Temporary )

inline

◆ ImportPKCS12File()

void ImportPKCS12File	(	string	FilePath,
		string	Password,
		string	KeyId,
		string	CertId,
		bool	Exportable )

inline

Imports a key/certificate from a file in PKCS#12 format into the HSM.

Parameters

FilePath	Location of the physical PFX file to be imported.
Password	Password to open PFX file.
KeyId	Name that the imported key will have 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 DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.
CertId	Name that the imported certificate will have 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 DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.
Exportable	Import the key in exportable form.

Exceptions

DinamoException Throws exception in case of error.

◆ ImportPKCS12() [1/3]

Int32 ImportPKCS12	(	string	FilePath,
		string	Password,
		string	KeyId,
		string	CertId,
		bool	Exportable )

inline

Obsolete: This API is discontinued. Please use ImportPKCS12File().

Examples: import_export_pkcs12.cs.

◆ ImportPKCS12() [2/3]

void ImportPKCS12	(	byte[]	Pkcs12,
		string	Password,
		string	KeyId,
		string	CertId,
		bool	Exportable )

inline

Imports a key/certificate from a buffer in PKCS#12 format into the HSM.

Parameters

Pkcs12	PKCS#12.
Password	Password for PKCS#12.
KeyId	Name that the imported key will have 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 DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.
CertId	Name that the imported certificate will have 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 DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.
Exportable	Import the key in exportable form.

Exceptions

DinamoException Throws exception in case of error.

◆ ImportPKCS12() [3/3]

void ImportPKCS12	(	byte[]	Pkcs12,
		string	Password,
		string	KeyId,
		Int32	KeyAttr,
		string	CertId,
		string	PubKeyId,
		Int32	Reserved )

inline

Imports a key/certificate from a buffer in PKCS#12 format into the HSM.

Parameters

Pkcs12 PKCS#12.

Password Password for PKCS#12.

KeyId Name that the imported key will have 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 DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.

KeyAttr

Attributes of the key to be imported into the HSM. Additional parameters of the key.

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

CertId Name that the imported certificate will have 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 DinamoApi.MAX_OBJ_NAME_LEN. 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 DinamoApi.MAX_OBJ_ID_FQN_LEN-1.

PubKeyId Name that the imported public key will have inside the HSM. Can be null to not import the public key object.

Reserved Reserved for future use. Must be 0.

Exceptions

DinamoException

◆ PKCS8ExportKey()

byte[] PKCS8ExportKey	(	string	szKeyId,
		string	szSecret )

inline

◆ SPBExportPKCS12()

byte[] SPBExportPKCS12	(	string	szISPB,
		string	szSecret )

inline

◆ ExportPKCS12() [1/2]

byte[] ExportPKCS12	(	string	KeyId,
		string	CertId,
		string	Secret )

inline

Exports an HSM key and certificate in PKCS#12 format.

Parameters

KeyId	Name of the key to be exported.
CertId	Name of the certificate to be exported.
Secret	Password protection for PKCS#12.

Exceptions

DinamoException Throws exception in case of error.

Examples: import_export_pkcs12.cs.

◆ ExportPKCS12() [2/2]

byte[] ExportPKCS12	(	string	KeyId,
		string	CertId,
		string	Secret,
		Int32	Flags )

inline

Exports an HSM key and certificate in PKCS#12 format.

Parameters

KeyId Name of the key to be exported.

CertId Name of the certificate to be exported.

Secret Password protection for PKCS#12.

Flags

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.

Exceptions

DinamoException Throws exception in case of error.

◆ PKCS8ImportKey()

void PKCS8ImportKey	(	string	szKeyId,
		string	szSecret,
		int	dwKeyAlg,
		int	dwAttrib,
		byte[]	bKeyEnvelope )

inline

◆ SPBImportPKCS12()

void SPBImportPKCS12	(	string	szKeyId,
		string	szSecret,
		string	szDomain,
		int	dwKeyAlg,
		int	dwAttrib,
		string	file )

inline