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_XXXvalue such thatPSA_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
inputbuffer 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, passNULLto indicate that there is no salt. -
salt_length - Size of the
saltbuffer in bytes. IfsaltisNULL, pass0. -
output - Buffer where the encrypted message is to be written.
-
output_size Size of the
outputbuffer 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_typeandkey_bitsare the type and bit-size respectively ofkey. PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZEevaluates 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 -
PSA_ERROR_INVALID_HANDLE -
PSA_ERROR_NOT_PERMITTED - The key does not have the
PSA_KEY_USAGE_ENCRYPTflag, or it does not permit the requested algorithm. -
PSA_ERROR_BUFFER_TOO_SMALL - The size of the
outputbuffer is too small.PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE()orPSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZEcan 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
inputbuffer 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, passNULLto indicate that there is no salt. -
salt_length - Size of the
saltbuffer in bytes. IfsaltisNULL, pass0. -
output - Buffer where the decrypted message is to be written.
-
output_size Size of the
outputbuffer 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_typeandkey_bitsare the type and bit-size respectively ofkey. PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZEevaluates 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 -
PSA_ERROR_INVALID_HANDLE -
PSA_ERROR_NOT_PERMITTED - The key does not have the
PSA_KEY_USAGE_DECRYPTflag, or it does not permit the requested algorithm. -
PSA_ERROR_BUFFER_TOO_SMALL - The size of the
outputbuffer is too small.PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE()orPSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZEcan 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.
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 supported asymmetric encryption.
#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE \ /* implementation-defined value */
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 - 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.
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 supported asymmetric decryption.
#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \ /* implementation-defined value */
See also PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE().