Keys

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