Hash operations

General Description

Macros
#define	CY_P64_PSA_HASH_OPERATION_INIT   {0}
	the initial value of the Hash operation context

Typedefs
typedef struct cy_p64_psa_hash_operation_s	cy_p64_psa_hash_operation_t
	The type of the state data structure for multipart hash operations. More...

Functions
cy_p64_psa_status_t	cy_p64_psa_sign_hash (cy_p64_psa_key_handle_t handle, cy_p64_psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_size, size_t *signature_length)
	Signs a hash or short message with a private key. More...
cy_p64_psa_status_t	cy_p64_psa_verify_hash (cy_p64_psa_key_handle_t handle, cy_p64_psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
	Verifies the signature of a hash or short message using a public key. More...
cy_p64_psa_status_t	cy_p64_psa_hash_setup (cy_p64_psa_hash_operation_t *operation, cy_p64_psa_algorithm_t alg)
	Sets up a multipart hash operation. More...
cy_p64_psa_status_t	cy_p64_psa_hash_update (cy_p64_psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
	Adds a message fragment to a multipart hash operation. More...
cy_p64_psa_status_t	cy_p64_psa_hash_finish (cy_p64_psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
	Finishes the calculation of the hash of a message. More...
static struct cy_p64_psa_hash_operation_s	cy_p64_psa_hash_operation_init (void)
	Initialize the Hash operation context.

Typedef Documentation

cy_p64_psa_hash_operation_t

typedef struct cy_p64_psa_hash_operation_s cy_p64_psa_hash_operation_t

The type of the state data structure for multipart hash operations.

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Function Documentation

cy_p64_psa_sign_hash()

cy_p64_psa_status_t cy_p64_psa_sign_hash	(	cy_p64_psa_key_handle_t	handle,
		cy_p64_psa_algorithm_t	alg,
		const uint8_t *	hash,
		size_t	hash_length,
		const uint8_t *	signature,
		size_t	signature_size,
		size_t *	signature_length
	)

Signs a hash or short message with a private key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling cy_p64_psa_hash_setup(), cy_p64_psa_hash_update() and cy_p64_psa_hash_finish(). Then pass the resulting hash as the hash parameter to this function. You can use CY_P64_PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

Parameters

	handle	Handle to the key to use for the operation. It must be an asymmetric key pair.
	alg	A signature algorithm that is compatible with the type of handle.
[in]	hash	The hash or message to sign.
	hash_length	Size of the hash buffer in bytes.
[out]	signature	Buffer where the signature is to be written.
	signature_size	Size of the signature buffer in bytes.
[out]	signature_length	On success, the number of bytes that make up the returned signature value.

Return values

CY_P64_PSA_SUCCESS
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_NOT_PERMITTED
CY_P64_PSA_ERROR_BUFFER_TOO_SMALL
CY_P64_PSA_ERROR_NOT_SUPPORTED
CY_P64_PSA_ERROR_INVALID_ARGUMENT
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_INSUFFICIENT_ENTROPY
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_verify_hash()

cy_p64_psa_status_t cy_p64_psa_verify_hash	(	cy_p64_psa_key_handle_t	handle,
		cy_p64_psa_algorithm_t	alg,
		const uint8_t *	hash,
		size_t	hash_length,
		const uint8_t *	signature,
		size_t	signature_length
	)

Verifies the signature of a hash or short message using a public key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling cy_p64_psa_hash_setup(), cy_p64_psa_hash_update() and cy_p64_psa_hash_finish(). Then pass the resulting hash as the hash parameter to this function. You can use CY_P64_PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

Parameters

	handle	Handle to the key to use for the operation. It must be a public key or an asymmetric key pair.
	alg	A signature algorithm compatible with the type of handle.
[in]	hash	The hash or message whose signature is to be verified.
	hash_length	The size of the hash buffer in bytes.
[in]	signature	The buffer containing the signature to verify.
	signature_length	The size of the signature buffer in bytes.

Return values

CY_P64_PSA_SUCCESS	The signature is valid.
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_NOT_PERMITTED
CY_P64_PSA_ERROR_INVALID_SIGNATURE	The calculation was perfomed successfully, but the passed signature is not a valid signature.
CY_P64_PSA_ERROR_NOT_SUPPORTED
CY_P64_PSA_ERROR_INVALID_ARGUMENT
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_hash_setup()

cy_p64_psa_status_t cy_p64_psa_hash_setup	(	cy_p64_psa_hash_operation_t *	operation,
		cy_p64_psa_algorithm_t	alg
	)

Sets up a multipart hash operation.

The sequence of operations to calculate a hash (message digest) is as follows:

1. Allocate an operation object to be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for cy_p64_psa_hash_operation_t, e.g. CY_P64_PSA_HASH_OPERATION_INIT.
3. Call cy_p64_psa_hash_setup() to specify the algorithm.
4. Call cy_p64_psa_hash_update() zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order.
5. To calculate the hash, call cy_p64_psa_hash_finish(). To compare the hash with an expected value, call cy_p64_psa_hash_verify().

If an error occurs at any step after a call to cy_p64_psa_hash_setup(), reset the operation by calling to cy_p64_psa_hash_abort(). The application may call cy_p64_psa_hash_abort() at any time after the operation has been initialized.

After a successful call to cy_p64_psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:

• A successful call to cy_p64_psa_hash_finish() or cy_p64_psa_hash_verify().
• A call to cy_p64_psa_hash_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for cy_p64_psa_hash_operation_t and not yet in use.
	alg	The hash algorithm to compute (CY_P64_PSA_ALG_XXX value such that CY_P64_PSA_ALG_IS_HASH(alg) is true).

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_NOT_SUPPORTED	alg is not a supported hash algorithm.
CY_P64_PSA_ERROR_INVALID_ARGUMENT	alg is not a hash algorithm.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be inactive).
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED

cy_p64_psa_hash_update()

cy_p64_psa_status_t cy_p64_psa_hash_update	(	cy_p64_psa_hash_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length
	)

Adds a message fragment to a multipart hash operation.

The application must call cy_p64_psa_hash_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling cy_p64_psa_hash_abort().

Parameters

[in,out]	operation	Active hash operation.
[in]	input	The buffer that contains the message fragment to hash.
	input_length	The size of the input buffer in bytes.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be active).
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED

cy_p64_psa_hash_finish()

cy_p64_psa_status_t cy_p64_psa_hash_finish	(	cy_p64_psa_hash_operation_t *	operation,
		uint8_t *	hash,
		size_t	hash_size,
		size_t *	hash_length
	)

Finishes the calculation of the hash of a message.

The application must call cy_p64_psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to cy_p64_psa_hash_update().

When this function returns success, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling cy_p64_psa_hash_abort().

Warning

Applications should not call this function if they expect a specific value for the hash. Call cy_p64_psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as memcmp is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.

Parameters

[in,out]	operation	Active hash operation.
[out]	hash	The buffer to write the hash in.
	hash_size	The size of the hash buffer in bytes.
[out]	hash_length	On success, the number of bytes that make up the hash value. This is always CY_P64_PSA_HASH_SIZE(alg) where alg is the hash algorithm that is calculated.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be active).
CY_P64_PSA_ERROR_BUFFER_TOO_SMALL	The size of the hash buffer is too small. You can determine a sufficient buffer size by calling CY_P64_PSA_HASH_SIZE(alg) where alg is the hash algorithm that is calculated.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED