From 7f312c811b6a3f3889c0c24cf8edf46e27318f36 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 20 May 2021 11:51:46 +0200 Subject: [PATCH] Add migration guides for GCM Signed-off-by: Gilles Peskine --- docs/3.0-migration-guide.d/gcm-alt.md | 10 ++++++++++ docs/3.0-migration-guide.d/gcm-multipart.md | 15 +++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 docs/3.0-migration-guide.d/gcm-alt.md create mode 100644 docs/3.0-migration-guide.d/gcm-multipart.md diff --git a/docs/3.0-migration-guide.d/gcm-alt.md b/docs/3.0-migration-guide.d/gcm-alt.md new file mode 100644 index 0000000000..388e2bedd5 --- /dev/null +++ b/docs/3.0-migration-guide.d/gcm-alt.md @@ -0,0 +1,10 @@ +GCM interface changes: impact for alternative implementations +------------------------------------------------------------- + +The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. +* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: + * Always return the partial output immediately, even if it does not consist of a whole number of blocks. + * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. diff --git a/docs/3.0-migration-guide.d/gcm-multipart.md b/docs/3.0-migration-guide.d/gcm-multipart.md new file mode 100644 index 0000000000..f37f7e8e01 --- /dev/null +++ b/docs/3.0-migration-guide.d/gcm-multipart.md @@ -0,0 +1,15 @@ +GCM multipart interface: application changes +-------------------------------------------- + +The GCM module now supports arbitrary chunked input in the multipart interface. + +For applications using GCM for multipart operations, this means the following changes: + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. +* The current implementation has a limitation that `mbedtls_gcm_update_ad()` may only be called once. This limitation will be lifted shortly; watch https://github.com/ARMmbed/mbedtls/issues/4351 for updates. +* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: + * As long as the input remains block-aligned, the output length is exactly the input length, as before. + * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. + +Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes.