From 68547187f6513efbc57b3b280e921696b7bb5ec6 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:53:09 +0100 Subject: [PATCH] Move subsections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 44 ++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 09e5bd870d..8a121feb48 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -238,6 +238,28 @@ If you were using a config file with MBEDTLS_SHA512_C and without MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add `#define MBEDTLS_SHA384_C` to your config file. +### GCM multipart interface: application changes + +The GCM module now supports arbitrary chunked input in the multipart interface. +This changes the interface for applications using the GCM module directly for multipart operations. +Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any 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. +* `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. + +### 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. + ### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed This doesn't affect users of the default configuration; it only affects people @@ -283,28 +305,6 @@ 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. -### GCM multipart interface: application changes - -The GCM module now supports arbitrary chunked input in the multipart interface. -This changes the interface for applications using the GCM module directly for multipart operations. -Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any 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. -* `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. - -### 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. - ### Remove the mode parameter from RSA functions This affects all users who use the RSA encryption, decryption, sign and