mbedtls_psa_aead_encrypt() function

The attributes of the key to use for the operation.

The buffer containing the key context.

Size of the \p key_buffer buffer in bytes.

The AEAD algorithm to compute.

Nonce or IV to use.

Size of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of key.

Additional data that will be authenticated but not encrypted.

Size of additional_data in bytes.

Data that will be authenticated and encrypted.

Size of plaintext in bytes.

Output buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.

Size of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key: - A sufficient output size is PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) where key_type is the type of key. - PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE( plaintext_length) evaluates to the maximum ciphertext size of any supported AEAD encryption.

On success, the size of the output in the ciphertext buffer.

Retrieve the lifetime from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Retrieve the key type from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Retrieve the key size from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare the type of a key. This function overwrites any key type previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Declare the size of a key. This function overwrites any key size previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Reset a key attribute structure to a freshly initialized state. You must initialize the attribute structure as described in the documentation of the type #psa_key_attributes_t before calling this function. Once the structure has been initialized, you may call this function at any time. This function frees any auxiliary resources that the structure may contain.

Import a key in binary format. This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types. The key data determines the key size. The attributes may optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0 in \p attributes indicates that the key size is solely determined by the key data. Implementations must reject an attempt to import a key of size 0. This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.

Prepare a key slot to receive key material. This function allocates a key slot and sets its metadata. If this function fails, call psa_fail_key_creation(). This function is intended to be used as follows: -# Call psa_start_key_creation() to allocate a key slot, prepare it with the specified attributes, and in case of a volatile key assign it a volatile key identifier. -# Populate the slot with the key material. -# Call psa_finish_key_creation() to finalize the creation of the slot. In case of failure at any step, stop the sequence and call psa_fail_key_creation(). On success, the key slot's state is PSA_SLOT_FILLING. It is the responsibility of the caller to change the slot's state to PSA_SLOT_EMPTY/FULL once key creation has finished.

Get the key buffer size required to store the key material of a key associated with an opaque driver.

Retrieve the key identifier from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare usage flags for a key. Usage flags are part of a key's usage policy. They encode what kind of operations are permitted on the key. For more details, refer to the documentation of the type #psa_key_usage_t. This function overwrites any usage flags previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Declare the permitted algorithm policy for a key. The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. The following algorithm policies are supported: - 0 does not allow any cryptographic operation with the key. The key may be used for non-cryptographic actions such as exporting (if permitted by the usage flags). - An algorithm value permits this particular algorithm. - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified signature scheme with any hash algorithm. - An algorithm built from #PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows any MAC algorithm from the same base class (e.g. CMAC) which generates/verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. - An algorithm built from #PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG allows any AEAD algorithm from the same base class (e.g. CCM) which generates/verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. This function overwrites any algorithm policy previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Derive a key from an ongoing key derivation operation with custom production parameters. See the description of psa_key_derivation_out_key() for the operation of this function with the default production parameters. Mbed TLS currently does not currently support any non-default production parameters.

Generate a key or key pair using custom production parameters. See the description of psa_generate_key() for the operation of this function with the default production parameters. In addition, this function supports the following production customizations, described in more detail in the documentation of ::psa_custom_key_parameters_t: - RSA keys: generation with a custom public exponent.

Set the key for a multipart symmetric encryption operation.

Set the key for a multipart symmetric decryption operation.

Retrieve the algorithm policy from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Retrieve all the publicly-accessible attributes of a key.

Export a key in binary format

Import a key in binary format.

Export a public key or the public part of a key pair in binary format.

Validate optional attributes during key creation. Some key attributes are optional during key creation. If they are specified in the attributes structure, check that they are consistent with the data in the slot. This function should be called near the end of key creation, after the slot in memory is fully populated but before saving persistent data.

Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

Sign an already-calculated hash with a private key.

Verify the signature a hash or short message using a public key.

Start signing a hash or short message with a private key, in an interruptible manner.

Start reading and verifying a hash or short message, in an interruptible manner.

Perform a key agreement and return the raw shared secret, using built-in raw key agreement functions.

Generate a key.

Process an authenticated decryption operation.

Set up a multipart MAC calculation operation using Mbed TLS.

Set up a multipart MAC verification operation using Mbed TLS.

Set the key for a multipart authenticated encryption operation. If an error occurs at any step after a call to mbedtls_psa_aead_encrypt_setup(), the operation is reset by the PSA core by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.

Set the key for a multipart authenticated decryption operation. If an error occurs at any step after a call to mbedtls_psa_aead_decrypt_setup(), the PSA core resets the operation by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.

Calculate the MAC (message authentication code) of a message using Mbed TLS.

Import an RSA key in binary format.

Decrypt a short message with a private key. - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

Export a public RSA key or the public part of an RSA key pair in binary format.

Generate an RSA key.

Sign an already-calculated hash with an RSA private key.

Verify the signature a hash or short message using a public RSA key.

Encrypt a short message with a public key. - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

Import an ECP key in binary format.

Export an ECP public key or the public part of an ECP key pair in binary format.

Generate an ECP key.

Sign an already-calculated hash with ECDSA.

Verify an ECDSA hash or short message signature.

Perform a key agreement and return the raw ECDH shared secret.

Perform a key agreement and return the FFDH shared secret.

Export a public key or the public part of a DH key pair in binary format.

Generate DH key.

Import DH key.

Format key data and metadata and save to a location for given key slot. This function formats the key data and metadata and saves it to a persistent storage backend. The storage location corresponding to the key slot must be empty, otherwise this function will fail. This function should be called after loading the key into an internal slot to ensure the persistent key is not saved into a storage location corresponding to an already occupied non-persistent key, as well as ensuring the key data is validated. Note: This function will only succeed for key buffers which are not empty. If passed a NULL pointer or zero-length, the function will fail with #PSA_ERROR_INVALID_ARGUMENT.

Parses key data and metadata and load persistent key for given key slot number. This function reads from a storage backend, parses the key data and metadata and writes them to the appropriate output parameters. Note: This function allocates a buffer and returns a pointer to it through the data parameter. On successful return, the pointer is guaranteed to be valid and the buffer contains at least one byte of data. psa_free_persistent_key_data() must be called on the data buffer afterwards to zeroize and free this buffer.

Formats key data and metadata for persistent storage

Parses persistent storage data into key data and metadata

Encrypt a message using a symmetric cipher.

Decrypt a message using a symmetric cipher.

Declare a key as persistent and set its key identifier. If the attribute structure currently declares the key as volatile (which is the default content of an attribute structure), this function sets the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT. This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_generate_key_custom(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() or psa_copy_key(). This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Set the location of a persistent key. To make a key persistent, you must give it a persistent key identifier with psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile. This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_generate_key_custom(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() or psa_copy_key(). This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Retrieve the usage flags from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare the enrollment algorithm for a key. An operation on a key may indifferently use the algorithm set with psa_set_key_algorithm() or with this function. \warning Setting an enrollment algorithm is not recommended, because using the same key with different algorithms can allow some attacks based on arithmetic relations between different computations made with the same key, or can escalate harmless side channels into exploitable ones. Use this function only if it is necessary to support a protocol for which it has been verified that the usage of the key with multiple algorithms is safe.

Derive a key from an ongoing key derivation operation. This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key's location, usage policy, type and size are taken from \p attributes. If you view the key derivation's output as a stream of bytes, this function destructively reads as many bytes as required from the stream. The operation's capacity decreases by the number of bytes read. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort(). How much output is produced and consumed from the operation, and how the key is derived, depends on the key type and on the key size (denoted \c bits below): - For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling #psa_key_derivation_output_bytes and passing the resulting output to #psa_import_key. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (\c bits / 8) bytes from the operation. The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_AES; - #PSA_KEY_TYPE_ARIA; - #PSA_KEY_TYPE_CAMELLIA; - #PSA_KEY_TYPE_DERIVE; - #PSA_KEY_TYPE_HMAC; - #PSA_KEY_TYPE_PASSWORD_HASH. - For ECC keys on a Montgomery elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Montgomery curve), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is: - Curve25519 (#PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte string and process it as specified in RFC 7748 §5. - Curve448 (#PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte string and process it as specified in RFC 7748 §5. - For key types for which the key is represented by a single sequence of \c bits bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length (\c bits / 8) bytes rounded up to the nearest whole number of bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by psa_export_key(). The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_DES. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively (for example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys). - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group) where \c group designates any Diffie-Hellman group) and ECC keys on a Weierstrass elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Weierstrass curve). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, *N* - 2] where *N* is the boundary of the private key domain (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, or the order of the curve's base point for ECC). Add 1 to the resulting integer and use this as the private key *x*. This method allows compliance to NIST standards, specifically the methods titled "key-pair generation by testing candidates" in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman, in FIPS 186-4 §B.1.2 for DSA, and in NIST SP 800-56A §5.6.1.2.2 or FIPS 186-4 §B.4.2 for elliptic curve keys. - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR, the way in which the operation output is consumed is implementation-defined. In all cases, the data that is read is discarded from the operation. The operation's capacity is decreased by the number of bytes read. For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification may include additional restrictions on the derived key based on the attributes and strength of the secret key.

Derive a key from an ongoing key derivation operation with custom production parameters.

Generate a key or key pair. The key is generated randomly. Its location, usage policy, type and size are taken from \p attributes. Implementations must reject an attempt to generate a key of size 0. The following type-specific considerations apply: - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.

Generate a key or key pair using custom production parameters.

Make a copy of a key. Copy key material from one location to another. This function is primarily useful to copy a key from one location to another, since it populates a key using the material from another key which may have a different lifetime. This function may be used to share a key with a different party, subject to implementation-defined restrictions on key sharing. The policy on the source key must have the usage flag #PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element. The resulting key may only be used in a way that conforms to both the policy of the original key and the policy specified in the \p attributes parameter: - The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in \p attributes. - If both allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy. - If either of the policies allows an algorithm and the other policy allows a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm. - If the policies do not allow any algorithm in common, this function fails with the status #PSA_ERROR_INVALID_ARGUMENT. The effect of this function on implementation-defined attributes is implementation-defined.

Determine valid PSA attributes that can be used to import a key into PSA. The attributes determined by this function are suitable for calling mbedtls_pk_import_into_psa() to create a PSA key with the same key material. The typical flow of operations involving this function is ``` psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; int ret = mbedtls_pk_get_psa_attributes(pk, &attributes); if (ret != 0) ...; // error handling omitted // Tweak attributes if desired psa_key_id_t key_id = 0; ret = mbedtls_pk_import_into_psa(pk, &attributes, &key_id); if (ret != 0) ...; // error handling omitted ```

Import a key into the PSA key store. This function is equivalent to calling psa_import_key() with the key material from \p pk. The typical way to use this function is: -# Call mbedtls_pk_get_psa_attributes() to obtain attributes for the given key. -# If desired, modify the attributes, for example: - To create a persistent key, call psa_set_key_identifier() and optionally psa_set_key_lifetime(). - To import only the public part of a key pair: psa_set_key_type(&attributes, PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR( psa_get_key_type(&attributes))); - Restrict the key usage if desired. -# Call mbedtls_pk_import_into_psa().

Calculate the key buffer size required to store the key material of a key associated with an opaque driver from input key data.

Validate the internal consistency of key attributes. This function only rejects invalid attribute values. If does not validate the consistency of the attributes with any key data that may be involved in the creation of the key. Call this function early in the key creation process.

Retrieve the enrollment algorithm policy from key attributes.

Find a free slot for a key that is to be created. This function calls the relevant method in the driver to find a suitable slot for a key with the given attributes.

Sign an already-calculated hash with a private key using p256-m's ECDSA implementation

Verify the signature of a hash using a SECP256R1 public key using p256-m's ECDSA implementation.

Import SECP256R1 key.

Export SECP256R1 public key, from the private key.

Generate SECP256R1 ECC Key Pair. Interface function which calls the p256-m key generation function and places it in the key buffer provided by the caller (Mbed TLS) in the correct format. For a SECP256R1 curve this is the 32 bit private key.

Perform raw key agreement using p256-m's ECDH implementation