10.8. Asymmetric encryption

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.

`PSA_ALG_RSA_OAEP` (macro)

The RSA OAEP asymmetric encryption algorithm.

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

Parameters

hash_alg: The hash algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(hash_alg) is true) to use 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 mask generation function MGF1 defined in [RFC8017] Appendix B.

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

An asymmetric encryption algorithm that is compatible with the type of key.

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:

The required output size is 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_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported asymmetric encryption.

output_length

On success, the number of bytes that make up the returned output.

Returns: psa_status_t

PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
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 the required buffer size.
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.

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

An asymmetric encryption algorithm that is compatible with the type of key.

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:

The required output size is 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_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported asymmetric decryption.

output_length

On success, the number of bytes that make up the returned output.

Returns: psa_status_t

PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
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 the required buffer size.
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_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.

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) /* specification-defined value */

Parameters

alg: An algorithm identifier (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: The asymmetric encryption algorithm.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_asymmetric_encrypt() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

Description

This macro returns a sufficient buffer size for a ciphertext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the ciphertext might be smaller, depending on the algorithm.

Warning

This function might evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.

`PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE` (macro)

A sufficient output buffer size for psa_asymmetric_encrypt(), for any supported asymmetric encryption.

#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE \
    /* implementation-defined value */

`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: The asymmetric encryption algorithm.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_asymmetric_decrypt() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

Description

This macro returns a sufficient buffer size for a plaintext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the plaintext might be smaller, depending on the algorithm.

Warning

This function might evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.

`PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE` (macro)

A sufficient output buffer size for psa_asymmetric_decrypt(), for any supported asymmetric decryption.

#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \
    /* implementation-defined value */

10.8. Asymmetric encryption

10.8.1. Asymmetric encryption algorithms

PSA_ALG_RSA_PKCS1V15_CRYPT (macro)

PSA_ALG_RSA_OAEP (macro)

10.8.2. Asymmetric encryption functions

psa_asymmetric_encrypt (function)

psa_asymmetric_decrypt (function)

10.8.3. Support macros

PSA_ALG_IS_RSA_OAEP (macro)

PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE (macro)

PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE (macro)

PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE (macro)

PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE (macro)

`PSA_ALG_RSA_PKCS1V15_CRYPT` (macro)

`PSA_ALG_RSA_OAEP` (macro)

`psa_asymmetric_encrypt` (function)

`psa_asymmetric_decrypt` (function)

`PSA_ALG_IS_RSA_OAEP` (macro)

`PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE` (macro)

`PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE` (macro)

`PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE` (macro)

`PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE` (macro)