Asymmetric cryptography

Functions
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. More...
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. More...
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. More...
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. For hash-and-sign algorithms, this includes the hashing step. More...
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. More...
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. More...

Detailed Description

Function Documentation

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

	key	Identifier of the key to use for the operation. It must be an asymmetric key pair. It must allow the usage #PSA_KEY_USAGE_DECRYPT.
	alg	An asymmetric encryption algorithm that is compatible with the type of key.
[in]	input	The message to decrypt.
	input_length	Size of the input buffer in bytes.
[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.

• For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

  Parameters

  	salt_length	Size of the salt buffer in bytes. If salt is NULL, pass 0.
  [out]	output	Buffer where the decrypted message is to be written.
  	output_size	Size of the output buffer in bytes.
  [out]	output_length	On success, the number of bytes that make up the returned output.

  Return values

  #PSA_SUCCESS
  #PSA_ERROR_INVALID_HANDLE
  #PSA_ERROR_NOT_PERMITTED
  #PSA_ERROR_BUFFER_TOO_SMALL	The size of the output buffer is too small. You can determine a sufficient buffer size by calling #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
  #PSA_ERROR_NOT_SUPPORTED
  #PSA_ERROR_INVALID_ARGUMENT
  #PSA_ERROR_INSUFFICIENT_MEMORY
  #PSA_ERROR_COMMUNICATION_FAILURE
  #PSA_ERROR_HARDWARE_FAILURE
  #PSA_ERROR_CORRUPTION_DETECTED
  #PSA_ERROR_STORAGE_FAILURE
  #PSA_ERROR_INSUFFICIENT_ENTROPY
  #PSA_ERROR_INVALID_PADDING
  #PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

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

	key	Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. It must allow the usage #PSA_KEY_USAGE_ENCRYPT.
	alg	An asymmetric encryption algorithm that is compatible with the type of key.
[in]	input	The message to encrypt.
	input_length	Size of the input buffer in bytes.
[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.

• For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

  Parameters

  	salt_length	Size of the salt buffer in bytes. If salt is NULL, pass 0.
  [out]	output	Buffer where the encrypted message is to be written.
  	output_size	Size of the output buffer in bytes.
  [out]	output_length	On success, the number of bytes that make up the returned output.

  Return values

  #PSA_SUCCESS
  #PSA_ERROR_INVALID_HANDLE
  #PSA_ERROR_NOT_PERMITTED
  #PSA_ERROR_BUFFER_TOO_SMALL	The size of the output buffer is too small. You can determine a sufficient buffer size by calling #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
  #PSA_ERROR_NOT_SUPPORTED
  #PSA_ERROR_INVALID_ARGUMENT
  #PSA_ERROR_INSUFFICIENT_MEMORY
  #PSA_ERROR_COMMUNICATION_FAILURE
  #PSA_ERROR_HARDWARE_FAILURE
  #PSA_ERROR_CORRUPTION_DETECTED
  #PSA_ERROR_STORAGE_FAILURE
  #PSA_ERROR_INSUFFICIENT_ENTROPY
  #PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

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.

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.

Parameters

	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.
	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. For ECDSA, the digest length must match or exceed the curve length in security strength. This means the lengths will be the same in all cases except for SHA-512 with a 521-bit curve.
[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

#PSA_SUCCESS
#PSA_ERROR_INVALID_HANDLE
#PSA_ERROR_NOT_PERMITTED
#PSA_ERROR_BUFFER_TOO_SMALL	The size of the signature buffer is too small. You can determine a sufficient buffer size by calling #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_ERROR_NOT_SUPPORTED
#PSA_ERROR_INVALID_ARGUMENT
#PSA_ERROR_INSUFFICIENT_MEMORY
#PSA_ERROR_COMMUNICATION_FAILURE
#PSA_ERROR_HARDWARE_FAILURE
#PSA_ERROR_CORRUPTION_DETECTED
#PSA_ERROR_STORAGE_FAILURE
#PSA_ERROR_INSUFFICIENT_ENTROPY
#PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

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

Parameters

[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.
[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. For ECDSA, the digest length must match or exceed the curve length in security strength, per FIPS 186-4 guidelines. This means the lengths will be the same in all cases except for SHA-512 with a 521-bit curve.
[in]	input	The input message to sign.
[in]	input_length	Size of the input buffer in bytes.
[out]	signature	Buffer where the signature is to be written.
[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.
[out]	signature_length	On success, the number of bytes that make up the returned signature value.

Return values

#PSA_SUCCESS
#PSA_ERROR_INVALID_HANDLE
#PSA_ERROR_NOT_PERMITTED	The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
#PSA_ERROR_BUFFER_TOO_SMALL	The size of the signature buffer is too small. You can determine a sufficient buffer size by calling #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_ERROR_NOT_SUPPORTED
#PSA_ERROR_INVALID_ARGUMENT
#PSA_ERROR_INSUFFICIENT_MEMORY
#PSA_ERROR_COMMUNICATION_FAILURE
#PSA_ERROR_HARDWARE_FAILURE
#PSA_ERROR_CORRUPTION_DETECTED
#PSA_ERROR_STORAGE_FAILURE
#PSA_ERROR_DATA_CORRUPT
#PSA_ERROR_DATA_INVALID
#PSA_ERROR_INSUFFICIENT_ENTROPY
#PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

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.

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.

Parameters

	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.
	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. For ECDSA, the digest length must match the curve length in security strength. This means the lengths will be the same in all cases except for SHA-512 with a 521-bit curve.
[in]	hash	The hash or message whose signature is to be verified.
	hash_length	Size of the hash buffer in bytes.
[in]	signature	Buffer containing the signature to verify.
	signature_length	Size of the signature buffer in bytes.

Return values

#PSA_SUCCESS	The signature is valid.
#PSA_ERROR_INVALID_HANDLE
#PSA_ERROR_NOT_PERMITTED
#PSA_ERROR_INVALID_SIGNATURE	The calculation was performed successfully, but the passed signature is not a valid signature.
#PSA_ERROR_NOT_SUPPORTED
#PSA_ERROR_INVALID_ARGUMENT
#PSA_ERROR_INSUFFICIENT_MEMORY
#PSA_ERROR_COMMUNICATION_FAILURE
#PSA_ERROR_HARDWARE_FAILURE
#PSA_ERROR_CORRUPTION_DETECTED
#PSA_ERROR_STORAGE_FAILURE
#PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

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.

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.

Parameters

[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.
[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. For ECDSA, the digest length must match or exceed the curve length in security strength. This means the lengths will be the same in all cases except for SHA-512 with a 521-bit curve.
[in]	input	The message whose signature is to be verified.
[in]	input_length	Size of the input buffer in bytes.
[out]	signature	Buffer containing the signature to verify.
[in]	signature_length	Size of the signature buffer in bytes.

Return values

#PSA_SUCCESS
#PSA_ERROR_INVALID_HANDLE
#PSA_ERROR_NOT_PERMITTED	The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
#PSA_ERROR_INVALID_SIGNATURE	The calculation was performed successfully, but the passed signature is not a valid signature.
#PSA_ERROR_NOT_SUPPORTED
#PSA_ERROR_INVALID_ARGUMENT
#PSA_ERROR_INSUFFICIENT_MEMORY
#PSA_ERROR_COMMUNICATION_FAILURE
#PSA_ERROR_HARDWARE_FAILURE
#PSA_ERROR_CORRUPTION_DETECTED
#PSA_ERROR_STORAGE_FAILURE
#PSA_ERROR_DATA_CORRUPT
#PSA_ERROR_DATA_INVALID
#PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.