Cryptographic hashing algorithms

Functions
UFR_STATUS DL_API	DLGetHashOutputByteLength (uint32_t hash_algo, VAR uint32_t *out_byte_len)
UFR_STATUS DL_API	DLGetHash (uint32_t hash_algo, IN const uint8_t *in, uint32_t in_len, OUT uint8_t *hash, uint32_t hash_alocated)
UFR_STATUS DL_API	DLGetHashToHeap (uint32_t hash_algo, IN const uint8_t *in, uint32_t in_len, VAR uint8_t **hash, VAR uint32_t *hash_len)
UFR_STATUS DL_API	DLHashInitChunked (uint32_t hash_algo)
UFR_STATUS DL_API	DLHashUpdateChunked (IN const uint8_t *in, uint32_t in_len)
UFR_STATUS DL_API	DLHashFinishChunked (OUT uint8_t *hash, uint32_t hash_alocated)
UFR_STATUS DL_API	DLHashFinishChunkedToHeap (OUT uint8_t **hash, VAR uint32_t *hash_alocated)
void DL_API	DLFree (void *ptr)

Detailed Description

Function Documentation

DLGetHashOutputByteLength()

UFR_STATUS DL_API DLGetHashOutputByteLength	(	uint32_t	hash_algo,
		VAR uint32_t *	out_byte_len )

This function is used to get hash output length in bytes for specified hash algorithms.

Parameters

hash_algo	Hash designator for which we want to get output length in bytes. Use values declared in E_HASH_ALGS enumeration.
out_byte_len	After successful function execution, the variable on which this pointer points to, will contain output hash length in bytes for specified hash algorithm.

Returns

Operation status

DLGetHash()

UFR_STATUS DL_API DLGetHash	(	uint32_t	hash_algo,
		IN const uint8_t *	in,
		uint32_t	in_len,
		OUT uint8_t *	hash,
		uint32_t	hash_alocated )

This function returns pointer to a null terminated string constant which contains the name of the hash algorithm designated by the input function parameter.

Parameters

hash_algo	Hash designator. Use values declared in E_HASH_ALGS enumeration
in	Input buffer of which hash is calculated.
in_len	Input buffer length in bytes. Maximum buffer length is 32 KB. If you have more data, use the chunked hashing method (see usage instructions of the DLHashInitChunked(), DLHashUpdateChunked() and DLHashFinishChunked() functions)
hash	After successful function execution, the variable on which this pointer points to, will contain output of the hashing sequence.
hash_alocated	This parameter should contain the number of bytes previously allocated in the hash buffer. This parameter have to be greater or equal to the output length of the hash algorithm which is specified by the hash_algo parameter passed in the previous call to the DLHashInitChunked(), in the beginning of the hashing sequence.

Returns

Operation status

DLGetHashToHeap()

UFR_STATUS DL_API DLGetHashToHeap	(	uint32_t	hash_algo,
		IN const uint8_t *	in,
		uint32_t	in_len,
		VAR uint8_t **	hash,
		VAR uint32_t *	hash_len )

This function calculates and returns the hash of the data in the buffer pointed by the “in” function parameter. Hash algorithm is specified by the hash_algo function parameter. If output bytes don't match with hash_alocated function parameter function returns CRYPTO_SUBSYS_WRONG_HASH_OUTPUT_LENGTH status. GetHashToHeap() automatically allocates memory, which *hash parameter will point to after successful execution. User is obligated to cleanup allocated memory space, occupied by the *hash, after use (e.g. by calling DLFree() or directly free() from the C/C++ code).

Parameters

hash_algo	Hash designator which specifies the hash algorithm used for calculation. Use values declared in E_HASH_ALGS enumeration.
in	Input buffer of which hash is calculated.
in_len	Input buffer length in bytes. Maximum buffer length is 32 KB. If you have more data, use the chunked hashing method (see usage instructions of the DLHashInitChunked(), DLHashUpdateChunked() and DLHashFinishChunked() functions).
hash	After successful function execution, the variable on which this pointer points to, will contain the pointer to the output hash.
hash_len	After successful function execution, the variable on which this pointer points to, will contain output hash length.

Returns

Operation status

DLHashInitChunked()

UFR_STATUS DL_API DLHashInitChunked

(

uint32_t

hash_algo

)

This function is used in conjunction with DLHashUpdateChunked() and DLHashFinishChunked() or DLHashFinishChunkedToHeap() functions. These functions have the same result as the single call to DLGetHash() or DLGetHashToHeap() functions but they are used for larger amounts of data to hash. These functions have to be called in the specific sequence. Disruption of the calling sequence leads to unpredictable results. In every hashing sequence, DLHashInitChunked() has to be called exactly once, in the beginning of the sequence. After successful hashing sequence initialization, there can be as many as needed DLHashUpdateChunked() calls. Chunk sizes may vary throughout the sequence. At the end of the sequence there can be exactly one call to either DLHashFinishChunked() or DLHashFinishChunkedToHeap() function. These two functions differ only in that the DLHashFinishChunkedToHeap() automatically allocates space for a resulting hash while the DLHashFinishChunked() expects to store the result in an already allocated memory on the heap. Calling one of DLHashFinishChunked() or DLHashFinishChunkedToHeap() functions finishes the current hashing sequence.

Parameters

hash_algo

Hash designator which specifies the hash algorithm used in the following hashing sequence. Use values declared in E_HASH_ALGS enumeration.

Returns

Operation status

DLHashUpdateChunked()

UFR_STATUS DL_API DLHashUpdateChunked	(	IN const uint8_t *	in,
		uint32_t	in_len )

This function is used in conjunction with DLHashInitChunked() and DLHashFinishChunked() or DLHashFinishChunkedToHeap() functions. These functions have the same result as the single call to DLGetHash() or DLGetHashToHeap() functions but they are used for larger amounts of data to hash. These functions have to be called in the specific sequence. Disruption of the calling sequence leads to unpredictable results. In every hashing sequence, DLHashInitChunked() have to be called exactly once, in the beginning of the sequence. After successful hashing sequence initialization, there can be as many as needed DLHashUpdateChunked() calls. Chunk sizes may vary throughout the sequence. At the end of the sequence there can be exactly one call to either DLHashFinishChunked() or DLHashFinishChunkedToHeap() function. These two functions differ only in that the DLHashFinishChunkedToHeap() automatically allocates space for a resulting hash while the DLHashFinishChunked() expects to store the result in an already allocated memory on the heap. Calling one of DLHashFinishChunked() or DLHashFinishChunkedToHeap() functions finishes current hashing sequence.

Parameters

in	One of the chunks of data of which hash is calculated.
in_len	Chunk length in bytes.

Returns

Operation status

DLHashFinishChunked()

UFR_STATUS DL_API DLHashFinishChunked	(	OUT uint8_t *	hash,
		uint32_t	hash_alocated )

This function is used in conjunction with DLHashInitChunked() and DLHashUpdateChunked() functions. These functions have the same result as the single call to DLGetHash() or DLGetHashToHeap() functions but they are used for larger amounts of data to hash. These functions have to be called in the specific sequence. Disruption of the calling sequence leads to unpredictable results. In every hashing sequence, DLHashInitChunked() have to be called exactly once, in the beginning of the sequence. After successful hashing sequence initialization, there can be as many as needed DLHashUpdateChunked() calls. Chunk sizes may vary throughout the sequence. At the end of the sequence there can be exactly one call to either DLHashFinishChunked() or DLHashFinishChunkedToHeap() function. These two functions differ only in that the DLHashFinishChunkedToHeap() automatically allocates space for a resulting hash while the DLHashFinishChunked() expects to store the result in an already allocated memory on the heap. Calling one of DLHashFinishChunked() or DLHashFinishChunkedToHeap() functions finishes the current hashing sequence.

Parameters

hash	After successful function execution, the variable on which this pointer points to, will contain output of the hashing sequence.
hash_alocated	This parameter should contain the number of bytes previously allocated in the hash buffer. This parameter have to be greater or equal to the output length of the hash algorithm which is specified by the hash_algo parameter passed in the previous call to the DLHashInitChunked(), in the beginning of the hashing sequence.

Returns

Operation status

DLHashFinishChunkedToHeap()

UFR_STATUS DL_API DLHashFinishChunkedToHeap	(	OUT uint8_t **	hash,
		VAR uint32_t *	hash_alocated )

This function is used in conjunction with DLHashInitChunked() and DLHashUpdateChunked() functions. These functions have the same result as the single call to DLGetHash() or DLGetHashToHeap() functions but they are used for larger amounts of data to hash. These functions have to be called in the specific sequence. Disruption of the calling sequence leads to unpredictable results. In every hashing sequence, DLHashInitChunked() have to be called exactly once, in the beginning of the sequence. After successful hashing sequence initialization, there can be as many as needed DLHashUpdateChunked() calls. Chunk sizes may vary throughout the sequence. At the end of the sequence there can be exactly one call to either DLHashFinishChunked() or DLHashFinishChunkedToHeap() function. These two functions differ only in that the DLHashFinishChunkedToHeap() automatically allocates space for a resulting hash while the DLHashFinishChunked() expects to store the result in an already allocated memory on the heap. Calling one of DLHashFinishChunked() or DLHashFinishChunkedToHeap() functions finishes the current hashing sequence. DLHashFinishChunkedToHeap() automatically allocates memory, which *hash parameter will point to, after successful execution. User is obligated to cleanup allocated memory space, occupied by the *hash, after use (e.g. by calling DLFree(cert) or directly free(cert) from the C/C++ code).

Parameters

hash	After successful function execution, the variable on which this pointer points to, will contain output of the hashing sequence.
hash_alocated	This parameter should contain the number of bytes previously allocated in the hash buffer. This parameter have to be greater or equal to the output length of the hash algorithm which is specified by the hash_algo parameter passed in the previous call to the DLHashInitChunked(), in the beginning of the hashing sequence.

Returns

Operation status

DLFree()

void DL_API DLFree

(

void *

ptr

)

Release the memory allocated from some of the library functions previously called making it available again for further allocations. Use to deallocate i.e. cleanup memory on the heap allocated. This function is a so-called helper for programming languages other than C/C++ where you can use a free(ptr) instead. Use only after calling the library functions for which it is explicitly indicated in this manual. Function returns nothing. After successful function execution ptr will point to NULL.

Parameters

ptr

Pointer to the memory allocated on the heap which you want to release. If ptr does not point to a block of memory allocated with the library functions, it causes undefined behavior. If ptr is NULL, the function does nothing. Digital signature verification Enumerations, types and structures for use with DigitalSignatureVerifyHash function enum E_ECC_CURVE_DEFINITION_TYPES { ECC_CURVE_INDEX, ECC_CURVE_NAME, ECC_CURVE_DOMAIN_PARAMETERS, ECC_CURVE_DEFINITION_TYPES_NUM };

Returns

Operation status