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_KEY_TYPE_RSA_KEY_PAIR
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) /* 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

PSA_KEY_TYPE_RSA_KEY_PAIR
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 permit 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 permit 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().