10.8. Asymmetric encryption
Asymmetric encryption is provided through the functions psa_asymmetric_encrypt()
and psa_asymmetric_decrypt()
.
10.8.1. Asymmetric encryption algorithms
PSA_ALG_RSA_PKCS1V15_CRYPT
(macro)
The RSA PKCS#1 v1.5 asymmetric encryption algorithm.
#define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t)0x07000200)
This encryption scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §7.2 under the name RSAESPKCSv1_5.
Compatible key types
PSA_KEY_TYPE_RSA_PUBLIC_KEY
(asymmetric encryption only)PSA_ALG_RSA_OAEP
(macro)
The RSA OAEP asymmetric encryption algorithm.
#define PSA_ALG_RSA_OAEP(hash_alg) /* specificationdefined value */
Parameters

hash_alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. The hash algorithm is used for MGF1.
Returns
The corresponding RSA OAEP encryption algorithm.
Unspecified if hash_alg
is not a supported hash algorithm.
Description
This encryption scheme is defined by [RFC8017] §7.1 under the name RSAESOAEP, with the following options:
 The mask generation function MGF1 defined in [RFC8017] Appendix B.2.1.
 The specified hash algorithm is used to hash the label, and for the mask generation function.
Compatible key types
PSA_KEY_TYPE_RSA_PUBLIC_KEY
(asymmetric encryption only)10.8.2. Asymmetric encryption functions
psa_asymmetric_encrypt
(function)
Encrypt a short message with 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);
Parameters

key
 Identifer 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
 The asymmetric encryption algorithm to compute: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_ASYMMETRIC_ENCRYPTION
(
alg
)
is true. 
input
 The message to encrypt.

input_length
 Size of the
input
buffer in bytes. 
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, passNULL
to indicate that there is no salt. 
salt_length
 Size of the
salt
buffer in bytes. Ifsalt
isNULL
, pass0
. 
output
 Buffer where the encrypted message is to be written.

output_size
Size of the
output
buffer in bytes. This must be appropriate for the selected algorithm and key: The required output size is
PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE
(
key_type
,
key_bits
,
alg
)
wherekey_type
andkey_bits
are the type and bitsize respectively ofkey
. PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE
evaluates to the maximum output size of any supported asymmetric encryption.
 The required output size is

output_length
 On success, the number of bytes that make up the returned output.
Returns: psa_status_t

PSA_SUCCESS
 Success.
The first
(*output_length)
bytes ofoutput
contain the encrypted output. 
PSA_ERROR_BAD_STATE
 The library requires initializing by a call to
psa_crypto_init()
. 
PSA_ERROR_INVALID_HANDLE
key
is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
 The key does not have the
PSA_KEY_USAGE_ENCRYPT
flag, or it does not permit the requested algorithm. 
PSA_ERROR_BUFFER_TOO_SMALL
 The size of the
output
buffer is too small.PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE()
orPSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE
can be used to determine a sufficient buffer size. 
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
alg
is not an asymmetric encryption algorithm.key
is not a public key or an asymmetric key pair, that is compatible withalg
.input_length
is not valid for the algorithm and key type.salt_length
is not valid for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
alg
is not supported or is not an asymmetric encryption algorithm.key
is not supported for use withalg
.input_length
orsalt_length
are too large for the implementation.

PSA_ERROR_INSUFFICIENT_ENTROPY

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID
Description
 For
PSA_ALG_RSA_PKCS1V15_CRYPT
, no salt is supported.
psa_asymmetric_decrypt
(function)
Decrypt a short message with a private 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);
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
 The asymmetric encryption algorithm to compute: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_ASYMMETRIC_ENCRYPTION
(
alg
)
is true. 
input
 The message to decrypt.

input_length
 Size of the
input
buffer in bytes. 
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, passNULL
to indicate that there is no salt. 
salt_length
 Size of the
salt
buffer in bytes. Ifsalt
isNULL
, pass0
. 
output
 Buffer where the decrypted message is to be written.

output_size
Size of the
output
buffer in bytes. This must be appropriate for the selected algorithm and key: The required output size is
PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE
(
key_type
,
key_bits
,
alg
)
wherekey_type
andkey_bits
are the type and bitsize respectively ofkey
. PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE
evaluates to the maximum output size of any supported asymmetric decryption.
 The required output size is

output_length
 On success, the number of bytes that make up the returned output.
Returns: psa_status_t

PSA_SUCCESS
 Success.
The first
(*output_length)
bytes ofoutput
contain the decrypted output. 
PSA_ERROR_BAD_STATE
 The library requires initializing by a call to
psa_crypto_init()
. 
PSA_ERROR_INVALID_HANDLE
key
is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
 The key does not have the
PSA_KEY_USAGE_DECRYPT
flag, or it does not permit the requested algorithm. 
PSA_ERROR_BUFFER_TOO_SMALL
 The size of the
output
buffer is too small.PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE()
orPSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE
can be used to determine a sufficient buffer size. 
PSA_ERROR_INVALID_PADDING
 The algorithm uses padding, and the input does not contain valid padding.

PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
alg
is not an asymmetric encryption algorithm.key
is not an asymmetric key pair, that is compatible withalg
.input_length
is not valid for the algorithm and key type.salt_length
is not valid for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
alg
is not supported or is not an asymmetric encryption algorithm.key
is not supported for use withalg
.input_length
orsalt_length
are too large for the implementation.

PSA_ERROR_INSUFFICIENT_ENTROPY

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID
Description
 For
PSA_ALG_RSA_PKCS1V15_CRYPT
, no salt is supported.
10.8.3. Support macros
PSA_ALG_IS_RSA_OAEP
(macro)
Whether the specified algorithm is an RSA OAEP encryption algorithm.
#define PSA_ALG_IS_RSA_OAEP(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is an RSA OAEP algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE
(macro)
Sufficient output buffer size for psa_asymmetric_encrypt()
.
#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \ /* implementationdefined value */
Parameters

key_type
 An asymmetric key type, either a key pair or a public key.

key_bits
 The size of the key in bits.

alg
 An asymmetric encryption algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_ASYMMETRIC_ENCRYPTION
(
alg
)
is true.
Returns
A sufficient output buffer size for the specified asymmetric encryption algorithm and key parameters. An implementation can return either 0
or a correct size for an asymmetric encryption algorithm and key parameters that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_asymmetric_encrypt()
will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.
See also PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE
.
PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE
(macro)
A sufficient output buffer size for psa_asymmetric_encrypt()
, for any of the supported key types and asymmetric encryption algorithms.
#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE \ /* implementationdefined value */
If the size of the output buffer is at least this large, it is guaranteed that psa_asymmetric_encrypt()
will not fail due to an insufficient buffer size.
See also PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE()
.
PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE
(macro)
Sufficient output buffer size for psa_asymmetric_decrypt()
.
#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \ /* implementationdefined value */
Parameters

key_type
 An asymmetric key type, either a key pair or a public key.

key_bits
 The size of the key in bits.

alg
 An asymmetric encryption algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_ASYMMETRIC_ENCRYPTION
(
alg
)
is true.
Returns
A sufficient output buffer size for the specified asymmetric encryption algorithm and key parameters. An implementation can return either 0
or a correct size for an asymmetric encryption algorithm and key parameters that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_asymmetric_decrypt()
will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.
See also PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE
.
PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE
(macro)
A sufficient output buffer size for psa_asymmetric_decrypt()
, for any of the supported key types and asymmetric encryption algorithms.
#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \ /* implementationdefined value */
If the size of the output buffer is at least this large, it is guaranteed that psa_asymmetric_decrypt()
will not fail due to an insufficient buffer size.
See also PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE()
.