mbedtls_chachapoly_starts() function

The ChaCha20-Poly1305 context. This must be initialized and bound to a key.

The nonce/IV to use for the message. This must be a readable buffer of length \c 12 Bytes.

The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).

This function initializes the specified ChaCha20-Poly1305 context. It must be the first API called before using the context. It must be followed by a call to \c mbedtls_chachapoly_setkey() before any operation can be done, and to \c mbedtls_chachapoly_free() once all operations with that context have been finished. In order to encrypt or decrypt full messages at once, for each message you should make a single call to \c mbedtls_chachapoly_crypt_and_tag() or \c mbedtls_chachapoly_auth_decrypt(). In order to encrypt messages piecewise, for each message you should make a call to \c mbedtls_chachapoly_starts(), then 0 or more calls to \c mbedtls_chachapoly_update_aad(), then 0 or more calls to \c mbedtls_chachapoly_update(), then one call to \c mbedtls_chachapoly_finish(). \warning Decryption with the piecewise API is discouraged! Always use \c mbedtls_chachapoly_auth_decrypt() when possible! If however this is not possible because the data is too large to fit in memory, you need to: - call \c mbedtls_chachapoly_starts() and (if needed) \c mbedtls_chachapoly_update_aad() as above, - call \c mbedtls_chachapoly_update() multiple times and ensure its output (the plaintext) is NOT used in any other way than placing it in temporary storage at this point, - call \c mbedtls_chachapoly_finish() to compute the authentication tag and compared it in constant time to the tag received with the ciphertext. If the tags are not equal, you must immediately discard all previous outputs of \c mbedtls_chachapoly_update(), otherwise you can now safely use the plaintext.

This function releases and clears the specified ChaCha20-Poly1305 context.

This function sets the ChaCha20-Poly1305 symmetric encryption key.

This function feeds additional data to be authenticated into an ongoing ChaCha20-Poly1305 operation. The Additional Authenticated Data (AAD), also called Associated Data (AD) is only authenticated but not encrypted nor included in the encrypted output. It is usually transmitted separately from the ciphertext or computed locally by each party. You may call this function multiple times to process an arbitrary amount of AAD. It is permitted to call this function 0 times, if no AAD is used. This function cannot be called any more if data has been processed by \c mbedtls_chachapoly_update(), or if the context has been finished. \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().

Thus function feeds data to be encrypted or decrypted into an on-going ChaCha20-Poly1305 operation. The direction (encryption or decryption) depends on the mode that was given when calling \c mbedtls_chachapoly_starts(). You may call this function multiple times to process an arbitrary amount of data. It is permitted to call this function 0 times, if no data is to be encrypted or decrypted. \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().

This function finished the ChaCha20-Poly1305 operation and generates the MAC (authentication tag). \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().

This function performs a complete ChaCha20-Poly1305 authenticated encryption with the previously-set key. \warning You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key.

This function performs a complete ChaCha20-Poly1305 authenticated decryption with the previously-set key.