| Gilles Peskine | 7f312c8 | 2021-05-20 11:51:46 +0200 | [diff] [blame^] | 1 | GCM multipart interface: application changes |
| 2 | -------------------------------------------- |
| 3 | |
| 4 | The GCM module now supports arbitrary chunked input in the multipart interface. |
| 5 | |
| 6 | For applications using GCM for multipart operations, this means the following changes: |
| 7 | |
| 8 | * `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. |
| 9 | * 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. |
| 10 | * `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: |
| 11 | * As long as the input remains block-aligned, the output length is exactly the input length, as before. |
| 12 | * 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()`. |
| 13 | * `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. |
| 14 | |
| 15 | Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. |