Asymmetric cryptography#

Functions#

psa_sign_message(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Sign a message with a private key.

psa_status_t

psa_verify_message(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

psa_status_t

psa_sign_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Sign a hash or short message with a private key.

psa_status_t

psa_verify_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)

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

psa_status_t

psa_asymmetric_encrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)

Encrypt a short message with a public key.

psa_status_t

psa_asymmetric_decrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)

Decrypt a short message with a private key.

Function Documentation#

psa_sign_message#

psa_status_t psa_sign_message (psa_key_id_t key, psa_algorithm_t alg, const uint8_t * input, size_t input_length, uint8_t * signature, size_t signature_size, size_t * signature_length)

Sign a message with a private key.

Parameters

Type	Direction	Argument Name	Description
psa_key_id_t	[in]	key	Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
psa_algorithm_t	[in]	alg	An asymmetric signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_MESSAGE(`alg`) is true), that is compatible with the type of `key`.
const uint8_t *	[in]	input	The input message to sign.
size_t	[in]	input_length	Size of the `input` buffer in bytes.
uint8_t *	[out]	signature	Buffer where the signature is to be written.
size_t	[in]	signature_size	Size of the `signature` buffer in bytes. This must be appropriate for the selected algorithm and key: The required signature size is #PSA_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of key. #PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.
size_t *	[out]	signature_length	On success, the number of bytes that make up the returned signature value.

For hash-and-sign algorithms, this includes the hashing step.

Note

To perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and then pass the resulting hash to psa_sign_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

psa_verify_message#

psa_status_t psa_verify_message (psa_key_id_t key, psa_algorithm_t alg, const uint8_t * input, size_t input_length, const uint8_t * signature, size_t signature_length)

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

Parameters

Type	Direction	Argument Name	Description
psa_key_id_t	[in]	key	Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
psa_algorithm_t	[in]	alg	An asymmetric signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_MESSAGE(`alg`) is true), that is compatible with the type of `key`.
const uint8_t *	[in]	input	The message whose signature is to be verified.
size_t	[in]	input_length	Size of the `input` buffer in bytes.
const uint8_t *	[out]	signature	Buffer containing the signature to verify.
size_t	[in]	signature_length	Size of the `signature` buffer in bytes.

Note

To perform a multi-part hash-and-sign signature verification algorithm, first use a multi-part hash operation to hash the message and then pass the resulting hash to psa_verify_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

psa_sign_hash#

psa_status_t psa_sign_hash (psa_key_id_t key, psa_algorithm_t alg, const uint8_t * hash, size_t hash_length, uint8_t * signature, size_t signature_size, size_t * signature_length)

Sign a hash or short message with a private key.

Parameters

Type	Direction	Argument Name	Description
psa_key_id_t	N/A	key	Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_HASH.
psa_algorithm_t	N/A	alg	A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.
const uint8_t *	[in]	hash	The hash or message to sign.
size_t	N/A	hash_length	Size of the `hash` buffer in bytes.
uint8_t *	[out]	signature	Buffer where the signature is to be written.
size_t	N/A	signature_size	Size of the `signature` buffer in bytes.
size_t *	[out]	signature_length	On success, the number of bytes that make up the returned signature value.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the hash parameter to this function. You can use PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

psa_verify_hash#

psa_status_t psa_verify_hash (psa_key_id_t key, psa_algorithm_t alg, const uint8_t * hash, size_t hash_length, const uint8_t * signature, size_t signature_length)

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

Parameters

Type	Direction	Argument Name	Description
psa_key_id_t	N/A	key	Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
psa_algorithm_t	N/A	alg	A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.
const uint8_t *	[in]	hash	The hash or message whose signature is to be verified.
size_t	N/A	hash_length	Size of the `hash` buffer in bytes.
const uint8_t *	[in]	signature	Buffer containing the signature to verify.
size_t	N/A	signature_length	Size of the `signature` buffer in bytes.

psa_asymmetric_encrypt#

psa_status_t psa_asymmetric_encrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t * input, size_t input_length, const uint8_t * salt, size_t salt_length, uint8_t * output, size_t output_size, size_t * output_length)

Encrypt a short message with a public key.

Parameters

Type	Direction	Argument Name	Description
psa_key_id_t	N/A	key	Size of the `salt` buffer in bytes. If `salt` is `NULL`, pass 0.
psa_algorithm_t	[out]	alg	Buffer where the encrypted message is to be written.
const uint8_t *	N/A	input	Size of the `output` buffer in bytes.
size_t	[out]	input_length	On success, the number of bytes that make up the returned output.
const uint8_t *	[in]	salt	A salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass `NULL`. If the algorithm supports an optional salt and you do not want to pass a salt, pass `NULL`.
size_t	N/A	salt_length
uint8_t *	N/A	output
size_t	N/A	output_size
size_t *	N/A	output_length

For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

psa_asymmetric_decrypt#

psa_status_t psa_asymmetric_decrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t * input, size_t input_length, const uint8_t * salt, size_t salt_length, uint8_t * output, size_t output_size, size_t * output_length)

Decrypt a short message with a private key.

Parameters

Type	Direction	Argument Name	Description
psa_key_id_t	N/A	key	Size of the `salt` buffer in bytes. If `salt` is `NULL`, pass 0.
psa_algorithm_t	[out]	alg	Buffer where the decrypted message is to be written.
const uint8_t *	N/A	input	Size of the `output` buffer in bytes.
size_t	[out]	input_length	On success, the number of bytes that make up the returned output.
const uint8_t *	[in]	salt	A salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass `NULL`. If the algorithm supports an optional salt and you do not want to pass a salt, pass `NULL`.
size_t	N/A	salt_length
uint8_t *	N/A	output
size_t	N/A	output_size
size_t *	N/A	output_length

For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.