diff --git a/ChangeLog.d/cipher-delayed-output.txt b/ChangeLog.d/cipher-delayed-output.txt new file mode 100644 index 0000000000..0c8f7db990 --- /dev/null +++ b/ChangeLog.d/cipher-delayed-output.txt @@ -0,0 +1,6 @@ +API changes + * For multi-part AEAD operations with the Cipher module, calling + mbedtls_cipher_finish() is now mandatory. Previously the documentation + was unclear on this point, and this function happened to never do + anything with the currently implemented AEADs, so in practice is was + possible to skip calling it, which is no longer supported. diff --git a/docs/3.0-migration-guide.d/cipher-delayed-output.md b/docs/3.0-migration-guide.d/cipher-delayed-output.md new file mode 100644 index 0000000000..e376880b85 --- /dev/null +++ b/docs/3.0-migration-guide.d/cipher-delayed-output.md @@ -0,0 +1,15 @@ +Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations +---------------------------------------------------------------------------- + +This only affect people who use the Cipher module to perform AEAD operations +using the multi-part API. + +Previously, the documentation didn't state explicitly if it was OK to call +`mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after +the last call to `mbedtls_cipher_update()` - that is, without calling +`mbedtls_cipher_finish()` in-between. If you code was missing that call, +please add it and be prepared to get as much as 15 bytes of output. + +Currently the output is always 0 bytes, but it may be more when alternative +implementations of the underlying primitives are in use, or with future +versions of the library.