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 RSAES-PKCS-v1_5.

Compatible key types

PSA_ALG_RSA_OAEP (macro)

The RSA OAEP asymmetric encryption algorithm.

#define PSA_ALG_RSA_OAEP(hash_alg) /* specification-defined value */

Parameters

hash_alg
A hash algorithm: a value of type psa_algorithm_t such that PSA_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 RSAES-OAEP, 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

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 that PSA_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, pass NULL to indicate that there is no salt.
salt_length
Size of the salt buffer in bytes. If salt is NULL, pass 0.
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:

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 of output 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() or PSA_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 with alg.
  • 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 with alg.
  • input_length or salt_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

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 that PSA_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, pass NULL to indicate that there is no salt.
salt_length
Size of the salt buffer in bytes. If salt is NULL, pass 0.
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:

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 of output 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() or PSA_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 with alg.
  • 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 with alg.
  • input_length or salt_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

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) /* specification-defined 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) \
    /* implementation-defined 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 that PSA_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 \
    /* implementation-defined 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) \
    /* implementation-defined 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 that PSA_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 \
    /* implementation-defined 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().