Detailed description

Symmetric and asymmetric cryptographic hash operations.

Functions
void	Encrypt (IntPtr hKey, bool Final, byte[] byData, ref int DataLen, int BufferLen)
	Encrypt blocks or files by passing the key reference. Uses the default mode/padding, i.e. MODE CBC and padding PKCS#5.

void	Encrypt (String strKeyId, byte[] byData)
	Encrypts a block in ECB mode without any padding. This function is useful for PIN BLOCK. The size of the data array must be compatible with the type of key.

byte[]	EncryptDefault (String strKeyId, byte[] byData)
	Encrypts a block using the standard HSM parameterization.

void	Encrypt (string strKeyId, IntPtr hHash, bool Final, byte[] iv, MODE_TYPE mode, PADDING_TYPE padding, byte[] byData, ref int DataLen, int BufferLen)
	Encrypts a hash, general data or a file.

void	Encrypt (IntPtr hKey, IntPtr hHash, bool Final, int dwFlags, byte[] iv, MODE_TYPE mode, PADDING_TYPE padding, byte[] byData, ref int DataLen, int BufferLen)
	Encrypts a hash, general data or a file.

void	EncryptDefault (IntPtr hKey, IntPtr hHash, bool Final, int dwFlags, byte[] iv, byte[] byData, ref int DataLen, int BufferLen)
	Encrypts using the standard HSM parameterization.

int	GetEncryptBuffLen (IntPtr hKey, IntPtr hHash, int DataLen)
	Returns the size of the encryption buffer.

byte[]	KEKEncode (String strKeyId, byte[] byKey)
	Encrypts a symmetric key that is outside the HSM using an RSA inside the HSM.

byte[]	KEKDecode (String strKeyId, byte[] byKey)
	Decrypts a symmetric key that is outside the HSM using an RSA inside the HSM.

void	Decrypt (string strKeyId, IntPtr hHash, bool Final, byte[] byData, ref int DataLen)
	Decrypts a hash, general data or a file.

void	Decrypt (IntPtr hKey, IntPtr hHash, bool Final, byte[] byData, ref int DataLen)
	Decrypts a hash, general data or a file.

void	Decrypt (string strKeyId, byte[] byData)
	Decrypts a block in ECB mode without any padding. This function is useful for PIN BLOCK. The size of the data array must be compatible with the type of key.

byte[]	DecryptDefault (string strKeyId, byte[] byData)
	Decrypts a block using the standard HSM parameterization.

void	Decrypt (string strKeyId, IntPtr hHash, bool Final, byte[] iv, MODE_TYPE mode, PADDING_TYPE padding, byte[] byData, ref int DataLen)
	Decrypts a hash, general data or a file.

void	Decrypt (IntPtr hKey, IntPtr hHash, bool Final, int dwFlags, byte[] iv, MODE_TYPE mode, PADDING_TYPE padding, byte[] byData, ref int DataLen)
	Decrypts a hash, general data or a file.

void	DecryptDefault (IntPtr hKey, IntPtr hHash, bool Final, int dwFlags, byte[] iv, byte[] byData, ref int DataLen)
	Decrypted using the standard HSM parameterization.

IntPtr	CreateHash (HASH_ALG AlgId)
	Creates a handle for a hash.

byte[]	generateHash (HASH_ALG AlgId, byte[] Data, int Flags)
	Generates a HASH in just one call.

byte[]	generateHash (HASH_ALG AlgId, byte[] Data)
	Generates a HASH in just one call.

byte[]	generateMAC (HASH_ALG AlgId, String KeyId, byte[] Data, int Flags)
	Generates a MAC in just one call.

byte[]	generateMAC (HASH_ALG AlgId, String KeyId, byte[] Data)
	Generates a MAC in just one call.

void	initMAC (HASH_ALG AlgId, String KeyId, int Flags)
	Initializes a MAC operation in parts. It must be finalized with endMAC.

void	initMAC (HASH_ALG AlgId, String KeyId)
	Initializes a MAC operation in parts. It must be finalized with endMAC.

void	updateMAC (byte[] Data)
	Updates a MAC operation with more data.

byte[]	endMAC ()
	Ends a MAC operation.

void	initHash (HASH_ALG AlgId, int Flags)
	Initializes a HASH operation in parts. It must be finalized with endHash.

void	initHash (HASH_ALG AlgId)
	Initializes a HASH operation in parts. It must be finalized with endHash.

void	updateHash (byte[] Data)
	Updates a HASH operation with more data.

byte[]	endHash ()
	Ends a HASH operation.

void	HashData (IntPtr hHash, byte[] byData)
	Finds the hash for a piece of data and associates it with the hash handle.

byte[]	Hash (HASH_ALG alg, byte[] data)
	Returns the hash of a piece of data.

void	DestroyHash (IntPtr hHash)
	Releases the handle of the hash resource.

void	BatchSign (string strKeyId, byte[] pbBlock, Int32 dwBlockCount, Int32 dwFlags)
	Sends a batch of blocks for signature in the HSM.

void	BatchSign (IntPtr hPrivateKey, byte[] pbBlock, Int32 dwBlockCount, Int32 dwFlags)
	Sends a batch of blocks for signature in the HSM.

byte[]	SignHash (String keyId, byte[] bHash, DinamoClient.HASH_ALG algHash)
	Sign a hash.

byte[]	SignHash (String keyId, byte[] bHash, DinamoClient.HASH_ALG algHash, Int32 dwFlags)
	Sign a hash.

byte[]	SignHash (String keyId, IntPtr pHash, DinamoClient.HASH_ALG algHash)

byte[]	SignHash (IntPtr hPrivateKey, IntPtr hHash)
	Sign a hash.

byte[]	SignHash (IntPtr hPrivateKey, IntPtr hHash, int dwFlags)
	Sign a hash.

bool	VerifySignature (IntPtr hHash, IntPtr hPublicKey, byte[] bySignature)
	Check a signature.

void	SetHashValue (IntPtr hHash, byte[] Value)
	Stores a hash.

byte[]	GetHashValue (IntPtr hHash)
	Returns the hash value.

byte[]	GetRandom (Int32 dwReturnLen)
	Returns a random number from the HSM generator.

DinamoApi.DN_M_OF_N_SPLIT_INFO	MofNSplit (byte bM, byte bN, byte[] pbSecret)
	Divides M from N in a secret. According to Shamir's secret sharing pattern.

byte[]	MofNRecover (DinamoApi.DN_M_OF_N_PART[] parts)
	Reconstructs the secret M of N from the parts of the custodians. According to Shamir's secret sharing pattern.

Functions

◆ Encrypt() [1/4]

void Encrypt	(	IntPtr	hKey,
		bool	Final,
		byte[]	byData,
		ref int	DataLen,
		int	BufferLen )

inline

Encrypt blocks or files by passing the key reference. Uses the default mode/padding, i.e. MODE CBC and padding PKCS#5.

Parameters

hKey	Key handle
Final	Indicates whether the block is the last
byData	Data to be encrypted. When the function returns, the original data is overwritten by the result of the encryption operation. The buffer size is specified by the dwBufLen parameter, the number of bytes to be processed is specified by the pdwDataLen parameter. The buffer size must be large enough to contain the encrypted data plus padding.
DataLen	Block size.When input parameter, contains the number of bytes that will be processed, when output parameter, contains the number of bytes of encrypted data.If the allocated buffer is not enough to receive all the encrypted data (lack of padding space, for example) the function will fail returning D_MORE_DATA.
BufferLen	Buffer size: For symmetric operations that require padding, the buffer must be at least the length of the data plus the size of the operation block of the algorithm to be used.

Exceptions

DinamoException Throws exception in case of error.

Examples: enc_dec.cs and rsa_enc_dec.cs.

◆ Encrypt() [2/4]

void Encrypt	(	String	strKeyId,
		byte[]	byData )

inline

Encrypts a block in ECB mode without any padding. This function is useful for PIN BLOCK. The size of the data array must be compatible with the type of key.

Parameters

strKeyId	Key reference
byData	Data to be encrypted. When the function returns, the original data is overwritten by the result of the encryption operation. The buffer size is specified by the dwBufLen parameter, the number of bytes to be processed is specified by the pdwDataLen parameter. The buffer size must be large enough to contain the encrypted data plus padding.

Exceptions

DinamoException Throws exception in case of error.

◆ EncryptDefault() [1/2]

byte[] EncryptDefault	(	String	strKeyId,
		byte[]	byData )

inline

Encrypts a block using the standard HSM parameterization.

For symmetric keys: MODE_CBC: Cipher Block Chain (CBC) PKCS5_PADDING: Padding is done following the pattern defined in PKCS#5. IV: Filled with zeros.

For RSA asymmetric keys: PKCS1_PADDING: PKCS#1 v1.5 padding is used.

Parameters

strKeyId	Key reference
byData	Data to be encrypted.

Return: Encrypted data.

Exceptions

DinamoException Throws exception in case of error.

◆ Encrypt() [3/4]

void Encrypt	(	string	strKeyId,
		IntPtr	hHash,
		bool	Final,
		byte[]	iv,
		MODE_TYPE	mode,
		PADDING_TYPE	padding,
		byte[]	byData,
		ref int	DataLen,
		int	BufferLen )

inline

Encrypts a hash, general data or a file.

Parameters

strKeyId Key reference

hHash Pointer to a hash

Final Indicates whether the block is the last

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

mode

Indicates the encryption operating mode of the block algorithm.

Value	Meaning
MODE_NONE	Does not define the operating mode. If the algorithm supports mode of operation, the MODE_CBC pattern will be used. For asymmetric keys, pass this flag.
MODE_ECB	Electronic Codebook (ECB)
MODE_CBC	Cipher Block Chain (CBC)
MODE_OFB	Output-Feedback. Not yet supported.

Only valid for symmetric keys and block algorithms.

padding

The library can work with 3 forms of symmetrical padding:

Value	Meaning
NO_PADDING	No padding is done, the data passed for encryption must already be a multiple of the size of the operation block.
PKCS5_PADDING	Padding is done following the standard defined in PKCS#5.
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 can create ambiguity in the decryption operation. If the data contains only ASCII text, for example, there is no problem.

The following values are accepted for asymmetric padding.

Value	Meaning
NO_RSA_PADDING	So as not to use padding.
PKCS1_PADDING	Uses PKCS#1 v1.5 type 2 padding.

byData Data to be encrypted. When the function returns, the original data is overwritten by the result of the encryption operation. The buffer size is specified by the dwBufLen parameter, the number of bytes to be processed is specified by the pdwDataLen parameter. The buffer size must be large enough to contain the encrypted data plus padding.

DataLen Block size.When input parameter, contains the number of bytes that will be processed, when output parameter, contains the number of bytes of encrypted data.If the allocated buffer is not enough to receive all the encrypted data (lack of padding space, for example) the function will fail returning D_MORE_DATA.

BufferLen Buffer size: For symmetric operations that require padding, the buffer must be at least the length of the data plus the size of the operation block of the algorithm to be used.

Exceptions

DinamoException Throws exception in case of error.

◆ Encrypt() [4/4]

void Encrypt	(	IntPtr	hKey,
		IntPtr	hHash,
		bool	Final,
		int	dwFlags,
		byte[]	iv,
		MODE_TYPE	mode,
		PADDING_TYPE	padding,
		byte[]	byData,
		ref int	DataLen,
		int	BufferLen )

inline

Encrypts a hash, general data or a file.

Parameters

hKey Key context

hHash Pointer to a hash

Final Indicates whether the block is the last

dwFlags Reserved for future use (must be 0).

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

mode

Indicates the encryption operating mode of the block algorithm.

Value	Meaning
MODE_NONE	Does not define the operating mode. If the algorithm supports mode of operation, the MODE_CBC pattern will be used. For asymmetric keys, pass this flag.
MODE_ECB	Electronic Codebook (ECB)
MODE_CBC	Cipher Block Chain (CBC)
MODE_OFB	Output-Feedback. Not yet supported.

Only valid for symmetric keys and block algorithms.

padding

The library can work with 3 forms of symmetrical padding:

Value	Meaning
NO_PADDING	No padding is done, the data passed for encryption must already be a multiple of the size of the operation block.
PKCS5_PADDING	Padding is done following the standard defined in PKCS#5.
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 can create ambiguity in the decryption operation. If the data contains only ASCII text, for example, there is no problem.

The following values are accepted for asymmetric padding.

Value	Meaning
NO_RSA_PADDING	So as not to use padding.
PKCS1_PADDING	Uses PKCS#1 v1.5 type 2 padding.

byData Data to be encrypted. When the function returns, the original data is overwritten by the result of the encryption operation. The buffer size is specified by the dwBufLen parameter, the number of bytes to be processed is specified by the pdwDataLen parameter. The buffer size must be large enough to contain the encrypted data plus padding.

DataLen Block size. When input parameter, contains the number of bytes that will be processed, when output parameter, contains the number of bytes of encrypted data.If the allocated buffer is not enough to receive all the encrypted data (lack of space for padding, for example) the function will fail returning D_MORE_DATA.

BufferLen Buffer size: For symmetric operations that require padding, the buffer must be at least the length of the data plus the size of the operation block of the algorithm to be used.

Exceptions

DinamoException Throws exception in case of error.

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

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

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

◆ EncryptDefault() [2/2]

void EncryptDefault	(	IntPtr	hKey,
		IntPtr	hHash,
		bool	Final,
		int	dwFlags,
		byte[]	iv,
		byte[]	byData,
		ref int	DataLen,
		int	BufferLen )

inline

Encrypts using the standard HSM parameterization.

For symmetric keys: MODE_CBC: Cipher Block Chain (CBC) PKCS5_PADDING: Padding is done following the pattern defined in PKCS#5.

For RSA asymmetric keys: PKCS1_PADDING: PKCS#1 v1.5 padding is used.

Parameters

hKey	Key context
hHash	Pointer to a hash
Final	Indicates whether the block is the last
dwFlags	Reserved for future use (must be 0).
iv	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. If null is passed, the zero-filled IV will be used.
byData	Data to be encrypted. When the function returns, the original data is overwritten by the result of the encryption operation. The buffer size is specified by the dwBufLen parameter, the number of bytes to be processed is specified by the pdwDataLen parameter. The buffer size must be large enough to contain the encrypted data plus padding.
DataLen	Block size. When input parameter, contains the number of bytes that will be processed, when output parameter, contains the number of bytes of encrypted data.If the allocated buffer is not enough to receive all the encrypted data (lack of space for padding, for example) the function will fail returning D_MORE_DATA.
BufferLen	Buffer size: For symmetric operations that require padding, the buffer must be at least the length of the data plus the size of the operation block of the algorithm to be used.

Exceptions

DinamoException Throws exception in case of error.

◆ GetEncryptBuffLen()

int GetEncryptBuffLen	(	IntPtr	hKey,
		IntPtr	hHash,
		int	DataLen )

inline

Returns the size of the encryption buffer.

Parameters

hKey	Key context
hHash	Pointer to a hash
DataLen	Size of the data to be encrypted

Return: Encryption buffer size

Exceptions

DinamoException Throws exception in case of error.

◆ KEKEncode()

byte[] KEKEncode	(	String	strKeyId,
		byte[]	byKey )

inline

Encrypts a symmetric key that is outside the HSM using an RSA inside the HSM.

Parameters

strKeyId	RSA Key Identification
byKey	Content of the symmetric key

Return: Encrypted symmetric key

Exceptions

DinamoException Throws exception in case of error.

◆ KEKDecode()

byte[] KEKDecode	(	String	strKeyId,
		byte[]	byKey )

inline

Decrypts a symmetric key that is outside the HSM using an RSA inside the HSM.

Parameters

strKeyId	RSA Key Identification
byKey	Content of the encrypted symmetric key

Exceptions

DinamoException Throws exception in case of error.

◆ Decrypt() [1/5]

void Decrypt	(	string	strKeyId,
		IntPtr	hHash,
		bool	Final,
		byte[]	byData,
		ref int	DataLen )

inline

Decrypts a hash, general data or a file.

Parameters

strKeyId	Key reference
hHash	Pointer to a hash
Final	Indicates whether the block is the last
byData	Buffer containing the data to be decrypted. When the function returns, the original data is overwritten by the result of the encryption operation. For block symmetric operations, the size of the data must always be a multiple of the block used by the algorithm in question.
DataLen	Returns the size of the data in byData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of data in clear text.

Exceptions

DinamoException Throws exception in case of error.

Examples: enc_dec.cs and rsa_enc_dec.cs.

◆ Decrypt() [2/5]

void Decrypt	(	IntPtr	hKey,
		IntPtr	hHash,
		bool	Final,
		byte[]	byData,
		ref int	DataLen )

inline

Decrypts a hash, general data or a file.

Parameters

hKey	Key context
hHash	Pointer to a hash
Final	Indicates whether the block is the last
byData	Buffer containing the data to be decrypted. When the function returns, the original data is overwritten by the result of the encryption operation. For block symmetric operations, the size of the data must always be a multiple of the block used by the algorithm in question.
DataLen	Returns the size of the data in byData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of data in clear text.

Exceptions

DinamoException Throws exception in case of error.

◆ Decrypt() [3/5]

void Decrypt	(	string	strKeyId,
		byte[]	byData )

inline

Decrypts a block in ECB mode without any padding. This function is useful for PIN BLOCK. The size of the data array must be compatible with the type of key.

Parameters

strKeyId	Key reference
byData	Data buffer

Exceptions

DinamoException Throws exception in case of error.

◆ DecryptDefault() [1/2]

byte[] DecryptDefault	(	string	strKeyId,
		byte[]	byData )

inline

Decrypts a block using the standard HSM parameterization.

For symmetric keys: MODE_CBC: Cipher Block Chain (CBC) PKCS5_PADDING: Padding is done following the pattern defined in PKCS#5. IV: Filled with zeros.

For RSA asymmetric keys: PKCS1_PADDING: PKCS#1 v1.5 padding is used.

Parameters

strKeyId	Key reference
byData	Data buffer

Return: The decrypted data.

Exceptions

DinamoException Throws exception in case of error.

◆ Decrypt() [4/5]

void Decrypt	(	string	strKeyId,
		IntPtr	hHash,
		bool	Final,
		byte[]	iv,
		MODE_TYPE	mode,
		PADDING_TYPE	padding,
		byte[]	byData,
		ref int	DataLen )

inline

Decrypts a hash, general data or a file.

Parameters

strKeyId Key reference

hHash Pointer to a hash

Final Indicates whether the block is the last

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

mode

Indicates the encryption operating mode of the block algorithm.

Value	Meaning
MODE_NONE	Does not define the operating mode. If the algorithm supports mode of operation, the MODE_CBC pattern will be used. For asymmetric keys, pass this flag.
MODE_ECB	Electronic Codebook (ECB)
MODE_CBC	Cipher Block Chain (CBC)
MODE_OFB	Output-Feedback. Not yet supported.

Only valid for symmetric keys and block algorithms.

padding

The library can work with 3 forms of symmetrical padding:

Value	Meaning
NO_PADDING	No padding is done, the data passed for encryption must already be a multiple of the size of the operation block.
PKCS5_PADDING	Padding is done following the standard defined in PKCS#5.
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 can create ambiguity in the decryption operation. If the data contains only ASCII text, for example, there is no problem.

The following values are accepted for asymmetric padding.

Value	Meaning
NO_RSA_PADDING	So as not to use padding.
PKCS1_PADDING	Uses PKCS#1 v1.5 type 2 padding.

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

DataLen Returns the size of the data in byData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of data in clear text.

Exceptions

DinamoException Throws exception in case of error.

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

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

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

◆ Decrypt() [5/5]

void Decrypt	(	IntPtr	hKey,
		IntPtr	hHash,
		bool	Final,
		int	dwFlags,
		byte[]	iv,
		MODE_TYPE	mode,
		PADDING_TYPE	padding,
		byte[]	byData,
		ref int	DataLen )

inline

Decrypts a hash, general data or a file.

Parameters

hKey Key connection

hHash Pointer to a hash

Final Indicates whether the block is the last

dwFlags Reserved for future use (must be 0).

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

mode

Indicates the encryption operating mode of the block algorithm.

Value	Meaning
MODE_NONE	Does not define the operating mode. If the algorithm supports mode of operation, the MODE_CBC pattern will be used. For asymmetric keys, pass this flag.
MODE_ECB	Electronic Codebook (ECB)
MODE_CBC	Cipher Block Chain (CBC)
MODE_OFB	Output-Feedback. Not yet supported.

Only valid for symmetric keys and block algorithms.

padding

The library can work with 3 forms of symmetrical padding:

Value	Meaning
NO_PADDING	No padding is done, the data passed for encryption must already be a multiple of the size of the operation block.
PKCS5_PADDING	Padding is done following the standard defined in PKCS#5.
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 can create ambiguity in the decryption operation. If the data contains only ASCII text, for example, there is no problem.

The following values are accepted for asymmetric padding.

Value	Meaning
NO_RSA_PADDING	So as not to use padding.
PKCS1_PADDING	Uses PKCS#1 v1.5 type 2 padding.

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

DataLen Returns the size of the data in byData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of data in clear text.

Exceptions

DinamoException Throws exception in case of error.

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

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

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

◆ DecryptDefault() [2/2]

void DecryptDefault	(	IntPtr	hKey,
		IntPtr	hHash,
		bool	Final,
		int	dwFlags,
		byte[]	iv,
		byte[]	byData,
		ref int	DataLen )

inline

Decrypted using the standard HSM parameterization.

For symmetric keys: MODE_CBC: Cipher Block Chain (CBC) PKCS5_PADDING: Padding is done following the pattern defined in PKCS#5.

For RSA asymmetric keys: PKCS1_PADDING: PKCS#1 v1.5 padding is used.

Parameters

hKey	Key connection
hHash	Pointer to a hash
Final	Indicates whether the block is the last
dwFlags	Reserved for future use (must be 0).
iv	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. If null is passed, the zero-filled IV will be used.
byData	Buffer containing the data to be decrypted. When the function returns, the original data is overwritten by the result of the encryption operation. For block symmetric operations, the size of the data must always be a multiple of the block used by the algorithm in question.
DataLen	Returns the size of the data in byData. When input parameter, contains the number of bytes to be processed, when output parameter, contains the number of bytes of data in clear text.

Exceptions

DinamoException Throws exception in case of error.

◆ CreateHash()

IntPtr CreateHash ( HASH_ALG AlgId )

inline

Creates a handle for a hash.

Parameters

AlgId Hash algorithm

Return: IntPtr Pointer to hash resource

Exceptions

DinamoException Throws exception in case of error.

◆ generateHash() [1/2]

byte[] generateHash	(	HASH_ALG	AlgId,
		byte[]	Data,
		int	Flags )

inline

Generates a HASH in just one call.

Parameters

AlgId	Hash algorithm
Data	Message
Flags	Zero must be passed

Return: HASH generated

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hash.cs.

◆ generateHash() [2/2]

byte[] generateHash	(	HASH_ALG	AlgId,
		byte[]	Data )

inline

Generates a HASH in just one call.

Parameters

AlgId	Hash algorithm
Data	Message

Return: HASH generated

Exceptions

DinamoException Throws exception in case of error.

◆ generateMAC() [1/2]

byte[] generateMAC	(	HASH_ALG	AlgId,
		String	KeyId,
		byte[]	Data,
		int	Flags )

inline

Generates a MAC in just one call.

Parameters

AlgId	Hash algorithm
KeyId	MAC key name
Data	Message
Flags	Zero should be passed

Return: MAC generated

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hmac.cs and generate_hmac_lau.cs.

◆ generateMAC() [2/2]

byte[] generateMAC	(	HASH_ALG	AlgId,
		String	KeyId,
		byte[]	Data )

inline

Generates a MAC in just one call.

Parameters

AlgId	Hash algorithm
KeyId	MAC key name
Data	Message

Return: MAC generated

Exceptions

DinamoException Throws exception in case of error.

◆ initMAC() [1/2]

void initMAC	(	HASH_ALG	AlgId,
		String	KeyId,
		int	Flags )

inline

Initializes a MAC operation in parts. It must be finalized with endMAC.

Parameters

AlgId	Hash algorithm
KeyId	MAC key name
Flags	Zero must be passed

Notes

The piecewise operation MUST be initialized with initMAC, the data passed with updateMAC and finalized with endMAC.
updateMAC can be called once or several times until the entire content of the message is sent and then endMAC to finish the operation and generate the MAC.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endMAC.

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hmac.cs.

◆ initMAC() [2/2]

void initMAC	(	HASH_ALG	AlgId,
		String	KeyId )

inline

Initializes a MAC operation in parts. It must be finalized with endMAC.

Parameters

AlgId	Hash algorithm
KeyId	MAC key name

Notes

The piecewise operation MUST be initialized with initMAC, the data passed with updateMAC and finalized with endMAC.
updateMAC can be called once or several times until the entire content of the message is sent and then endMAC to finish the operation and generate the MAC.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endMAC.

Exceptions

DinamoException Throws exception in case of error.

◆ updateMAC()

void updateMAC ( byte[] Data )

inline

Updates a MAC operation with more data.

Parameters

Data Message

Notes

The piecewise operation MUST be initialized with initMAC, the data passed with updateMAC and finalized with endMAC.
updateMAC can be called once or several times until the entire content of the message is sent and then endMAC to finish the operation and generate the MAC.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endMAC.

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hmac.cs.

◆ endMAC()

byte[] endMAC ( )

inline

Ends a MAC operation.

Return: MAC generated

Notes

The piecewise operation MUST be initialized with initMAC, the data passed with updateMAC and finalized with endMAC.
updateMAC can be called once or several times until the entire content of the message is sent and then endMAC to finish the operation and generate the MAC.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endMAC.

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hash.cs and generate_hmac.cs.

◆ initHash() [1/2]

void initHash	(	HASH_ALG	AlgId,
		int	Flags )

inline

Initializes a HASH operation in parts. It must be finalized with endHash.

Parameters

AlgId	Hash algorithm
Flags	Zero must be passed

Notes

The piecewise operation MUST be initialized with initHash, the data passed with updateHash and finalized with endHash.
updateHash can be called once or several times until the entire content of the message is sent and then endHash to finish the operation and generate the hash.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endHash.

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hash.cs.

◆ initHash() [2/2]

void initHash ( HASH_ALG AlgId )

inline

Initializes a HASH operation in parts. It must be finalized with endHash.

Parameters

AlgId Hash algorithm

Notes

The piecewise operation MUST be initialized with initHash, the data passed with updateHash and finalized with endHash.
updateHash can be called once or several times until the entire content of the message is sent and then endHash to finish the operation and generate the hash.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endHash.

Exceptions

DinamoException Throws exception in case of error.

◆ updateHash()

void updateHash ( byte[] Data )

inline

Updates a HASH operation with more data.

Parameters

Data Message

Notes

The piecewise operation MUST be initialized with initHash, the data passed with updateHash and finalized with endHash.
updateHash can be called once or several times until the entire content of the message is sent and then endHash to finish the operation and generate the hash.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endHash.

Exceptions

DinamoException Throws exception in case of error.

Examples: generate_hash.cs.

◆ endHash()

byte[] endHash ( )

inline

Ends a HASH operation.

Return: HASH generated

Notes

The piecewise operation MUST be initialized with initHash, the data passed with updateHash and finalized with endHash.
updateHash can be called once or several times until the entire content of the message is sent and then endHash to finish the operation and generate the hash.
A multi-part operation cannot be interleaved with other operations within the same session until it is terminated with endHash.

Exceptions

DinamoException Throws exception in case of error.

◆ HashData()

void HashData	(	IntPtr	hHash,
		byte[]	byData )

inline

Finds the hash for a piece of data and associates it with the hash handle.

Parameters

hHash	IntPtr Pointer to hash resource
byData	Data in bytes

Exceptions

DinamoException Throws exception in case of error.

◆ Hash()

byte[] Hash	(	HASH_ALG	alg,
		byte[]	data )

inline

Returns the hash of a piece of data.

Parameters

alg	Hash algorithm
data	Data in bytes

Return: Hash value in bytes

Exceptions

DinamoException Throws exception in case of error.

Examples: sign_hash.cs.

◆ DestroyHash()

void DestroyHash ( IntPtr hHash )

inline

Releases the handle of the hash resource.

Parameters

hHash IntPtr Pointer to hash resource

Exceptions

DinamoException Throws exception in case of error.

◆ BatchSign() [1/2]

void BatchSign	(	string	strKeyId,
		byte[]	pbBlock,
		Int32	dwBlockCount,
		Int32	dwFlags )

inline

Sends a batch of blocks for signature in the HSM.

Parameters

strKeyId	Key name.
pbBlock	Byte array containing the blocks that will be signed concatenated and with the appropriate paddings made. Add the zero padding of size DN_BATCH_SIGN_BLOCK_HEADER to the beginning of this array of blocks. The structure should be as follows. Zero padding of size DN_BATCH_SIGN_BLOCK_HEADER \| BLOCK 1 \| BLOCK 2 \| BLOCK 3 \| ... The signed blocks will be returned in the same positions as the input blocks.
dwBlockCount	Number of blocks contained in pbBlock.
dwFlags	Reserved for future use (must be 0).

Exceptions

DinamoException Throws exception in case of error.

Examples: batchsign.cs.

◆ BatchSign() [2/2]

void BatchSign	(	IntPtr	hPrivateKey,
		byte[]	pbBlock,
		Int32	dwBlockCount,
		Int32	dwFlags )

inline

Sends a batch of blocks for signature in the HSM.

Parameters

hPrivateKey	Key context.
pbBlock	Byte array containing the blocks that will be signed concatenated and with the appropriate paddings made. Add the zero padding of size DN_BATCH_SIGN_BLOCK_HEADER to the beginning of this array of blocks. The structure should be as follows. Zero padding of size DN_BATCH_SIGN_BLOCK_HEADER \| BLOCK 1 \| BLOCK 2 \| BLOCK 3 \| ... The signed blocks will be returned in the same positions as the input blocks.
dwBlockCount	Number of blocks contained in pbBlock.
dwFlags	Reserved for future use (must be 0).

Exceptions

DinamoException Throws exception in case of error.

◆ SignHash() [1/5]

byte[] SignHash	(	String	keyId,
		byte[]	bHash,
		DinamoClient.HASH_ALG	algHash )

inline

Sign a hash.

Parameters

keyId	Private key identifier
bHash	Array with hash
algHash	Hash algorithm used. See: HASH_ALG

Return: byte array

Exceptions

DinamoException Throws exception in case of error.

Examples: block_object.cs and sign_hash.cs.

◆ SignHash() [2/5]

byte[] SignHash	(	String	keyId,
		byte[]	bHash,
		DinamoClient.HASH_ALG	algHash,
		Int32	dwFlags )

inline

Sign a hash.

Parameters

keyId Private key identifier

bHash Array with hash

algHash Hash algorithm used. See: HASH_ALG

dwFlags

Subscription options, can be 0 or more of one of the values below:

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

Return: byte array

Exceptions

DinamoException Throws exception in case of error.

◆ SignHash() [3/5]

byte[] SignHash	(	String	keyId,
		IntPtr	pHash,
		DinamoClient.HASH_ALG	algHash )

inline

Obsolete: Use SignHash().

◆ SignHash() [4/5]

byte[] SignHash	(	IntPtr	hPrivateKey,
		IntPtr	hHash )

inline

Sign a hash.

Parameters

hHash	Pointer to the hash resource
hPrivateKey	Pointer to the private key

Return: Signature as an array of bytes.

Exceptions

DinamoException Throws exception in case of error.

◆ SignHash() [5/5]

byte[] SignHash	(	IntPtr	hPrivateKey,
		IntPtr	hHash,
		int	dwFlags )

inline

Sign a hash.

Parameters

hHash Pointer to the hash resource

hPrivateKey Pointer to the private key

dwFlags

Subscription options, can be 0 or more of one of the values below:

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

Return: Signature as an array of bytes.

Exceptions

DinamoException Throws exception in case of error.

◆ VerifySignature()

bool VerifySignature	(	IntPtr	hHash,
		IntPtr	hPublicKey,
		byte[]	bySignature )

inline

Check a signature.

Parameters

hHash	Pointer to the hash resource
hPublicKey	Pointer to the public key resource
bySignature	Signature array

Return: True in case of ok signature validation

Exceptions

DinamoException Throws exception in case of error.

◆ SetHashValue()

void SetHashValue	(	IntPtr	hHash,
		byte[]	Value )

inline

Stores a hash.

Parameters

hHash	Pointer to the hash resource
Value	Hash value

Exceptions

DinamoException Throws exception in case of error.

◆ GetHashValue()

byte[] GetHashValue ( IntPtr hHash )

inline

Returns the hash value.

Parameters

hHash Pointer to the hash resource

Return: Array with hash

Exceptions

DinamoException Throws exception in case of error.

◆ GetRandom()

byte[] GetRandom ( Int32 dwReturnLen )

inline

Returns a random number from the HSM generator.

Parameters

dwReturnLen Size in bytes of the random number

Return: Byte array of the random number found

Exceptions

DinamoException Throws exception in case of error.

◆ MofNSplit()

DinamoApi.DN_M_OF_N_SPLIT_INFO MofNSplit	(	byte	bM,
		byte	bN,
		byte[]	pbSecret )

inline

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

Parameters

bM	Minimum number of parts needed to rebuild the secret. Minimum of DinamoApi.DN_M_OF_N_S_MIN and maximum of DinamoApi.DN_M_OF_N_S_MAX.
bN	Total number of parts to be generated.
pbSecret	Secret to be shared. Must have size DinamoApi.DN_M_OF_N_S_LEN. Can be passed null so that a secret is randomly generated by the HSM.

Return: Information on the division of the secret.

Exceptions

DinamoException Throws exception in case of error.

Examples: m_of_n.cs.

◆ MofNRecover()

byte[] MofNRecover ( DinamoApi.DN_M_OF_N_PART[] parts )

inline

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

Parameters

parts Array of secret parts.

Return: Secret rebuilt.

Exceptions

DinamoException Throws exception in case of error.

Examples: m_of_n.cs.