Fix errors in migration guide
Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md
index f64b209..ef6df7a 100644
--- a/docs/3.0-migration-guide.md
+++ b/docs/3.0-migration-guide.md
@@ -10,6 +10,7 @@
two questions: (1) am I affected? (2) if yes, what's my migration path?
The changes are detailed below, and include:
+
- Removal of many insecure / obsolete features
- Tidying up of configuration options (including removing some less useful options)
- Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments.
@@ -36,7 +37,7 @@
value.
The only value supported by Mbed TLS 3.0.0 is `0x03000000`.
-Remove suport for TLS 1.0, 1.1 and DTLS 1.0
+Remove support for TLS 1.0, 1.1 and DTLS 1.0
-------------------------------------------
This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols.
@@ -53,7 +54,7 @@
version. There is no migration path since the feature is no longer relevant.
As a consequence of currently supporting only one version of (D)TLS (and in the
-future 1.3 which will have a different version negociation mechanism), support
+future 1.3 which will have a different version negotiation mechanism), support
for fallback SCSV (RFC 7507) was also removed. There is no migration path as
it's no longer useful with TLS 1.2 and later.
@@ -260,7 +261,6 @@
Please use the new names directly in your code; `scripts/rename.pl` (from any
of the 2.x releases - no longer included in 3.0) might help you do that.
-
Remove 3DES ciphersuites
--
@@ -270,7 +270,8 @@
3DES has weaknesses/limitations and there are better alternatives, and more and
more standard bodies are recommending against its use in TLS.
-The migration path here is to chose from the recomended in literature alternatives.
+The migration path here is to chose from the recommended in literature alternatives.
+
CCM interface changes: impact for alternative implementations
-------------------------------------------------------------
@@ -280,6 +281,7 @@
mbedtls_ccm_update_ad(), mbedtls_ccm_update() and mbedtls_ccm_finish().
Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to
implement those additional five API functions.
+
Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations
----------------------------------------------------------------------------
@@ -295,6 +297,7 @@
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.
+
Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options
--
@@ -309,6 +312,7 @@
The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used
for both DTLS-CID and TLS 1.3.
+
Change the API to allow adding critical extensions to CSRs
------------------------------------------------------------------
@@ -316,7 +320,7 @@
function.
The API is changed to include the parameter `critical` which allow to mark an
-extension included in a CSR as critical. To get the previous behaviour pass
+extension included in a CSR as critical. To get the previous behavior pass TODO
TLS now favors faster curves over larger curves
-----------------------------------------------
@@ -324,6 +328,7 @@
The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves.
If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection.
+
GCM interface changes: impact for alternative implementations
-------------------------------------------------------------
@@ -334,6 +339,7 @@
* 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.
+
GCM multipart interface: application changes
--------------------------------------------
@@ -346,6 +352,7 @@
* 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.
+
SSL key export interface change
-------------------------------
@@ -382,6 +389,7 @@
on the wire. Such users are also encouraged to reach out to the
Mbed TLS team on the mailing list, to let the team know about their
use case.
+
The RNG parameter is now mandatory for all functions that accept one
--------------------------------------------------------------------
@@ -422,6 +430,7 @@
This was a trade-off between code size and counter-measures; it is no longer
relevant as the counter-measure is now always on at no cost in code size.
+
Remove MaximumFragmentLength (MFL) query API
-----------------------------------------------------------------
@@ -433,7 +442,8 @@
Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()`
instead, which also provides such upper bounds but takes more factors
than just the MFL configuration into account.
-Change MBEDTLS_ECP_FIXED_POINT_OPTIM behaviour
+
+Change MBEDTLS_ECP_FIXED_POINT_OPTIM behavior
------------------------------------------------------
The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increase code size and it does
@@ -456,6 +466,7 @@
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.
+
Move part of timing module out of the library
--
@@ -465,6 +476,7 @@
If you were relying on these functions, you'll now need to change to using your
platform's corresponding functions directly.
+
Extra parameter for the output buffer size
------------------------------------------
@@ -474,6 +486,7 @@
* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()`
The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer.
+
Relaxed semantics for PSK configuration
-----------------------------------------------------------------
@@ -492,6 +505,7 @@
remove all but the last call, so that only one call to _either_
`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()`
remains.
+
Remove the configuration to enable weak ciphersuites in SSL / TLS
-----------------------------------------------------------------
@@ -504,6 +518,7 @@
If you were using a ciphersuite without encryption, you just have to
enable MBEDTLS_CIPHER_NULL_CIPHER now.
+
Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option
-------------------------------------------------------------
@@ -514,6 +529,7 @@
This option is replaced by the more fine-grained options
`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set
the maximum incoming and outgoing plaintext fragment lengths, respectively.
+
Remove the option to build the library without any entropy sources
------------------------------------------------------------------
@@ -525,6 +541,7 @@
and make sure your device is provisioned with a strong random seed.
Alternatively, for testing purposes only, you can create and register a fake
entropy function.
+
Remove the mode parameter from RSA functions
--------------------------------------------
@@ -561,7 +578,7 @@
Migration paths:
-1. Mbed TLS 3.0 does not offer a migration path for the usecase 1: Like many
+1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many
other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no
longer part of the public API in Mbed TLS 3.0, and direct structure field
access is no longer supported. Please see the corresponding migration guide.
@@ -569,10 +586,11 @@
2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by
calls to `mbedtls_ssl_get_session()` as demonstrated in the example
program `programs/ssl/ssl_client2.c`.
- Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION
+
+Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION
--------------------------------------------------------------------------
-This change does not affect users of the default configuration; it only affect
+This change does not affect users of the default configuration; it only affects
users who enable this option.
The X.509 standard says that implementations must reject critical extensions that
@@ -586,6 +604,7 @@
`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every
unsupported certificate extension and additionally the "certificate policies"
extension if it contains any unsupported certificate policies.
+
Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h`
-------------------------------------------------------------------
@@ -604,6 +623,7 @@
verification is for some reason undesirable, it can still be disabled by means
of the verification callback function passed to `mbedtls_x509_crt_verify()` (see
the documentation of this function for more information).
+
Remove MD2, MD4, RC4, Blowfish and XTEA algorithms
--
@@ -612,6 +632,7 @@
They are already niche or obsolete and most of them are weak or broken. For
those reasons possible users should consider switching to modern and safe
alternatives to be found in literature.
+
Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option
-------------------------------------------
@@ -623,6 +644,7 @@
disabling it.
This option is no longer present, but its functionality is now always enabled.
+
Deprecated functions were removed from AES
------------------------------------------
@@ -697,6 +719,7 @@
The file `include/mbedtls/net.h` was removed because its only function was to
include `mbedtls/net_sockets.h` which now should be included directly.
+
Remove MBEDTLS_CHECK_PARAMS option
----------------------------------
@@ -730,6 +753,7 @@
because the parameters concerned are usually constants in applications.
For more information see issue #4313.
+
Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default
--------------------------------------------------------------------------
@@ -743,6 +767,7 @@
Users who changed the default setting of the option need to change the config/
build system to remove that change.
+
Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option
--
@@ -798,8 +823,6 @@
renaming or to rename those function in their code according to the list from
mentioned header file.
-
-
Signature functions now require the hash length to match the expected value
---------------------------------------------------------------------------
@@ -824,6 +847,7 @@
* `mbedtls_pk_verify_ext`
The migration path is to pass the correct value to those functions.
+
Remove the padding parameters from mbedtls_rsa_init()
-----------------------------------------------------
@@ -853,6 +877,7 @@
```C
mbedtls_rsa_init(ctx);
```
+
Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C
-----------------------------------------------------------------
@@ -864,6 +889,7 @@
you will need to add `#define MBEDTLS_SHA224_C` option your config.
Current version of the library does not support enabling MBEDTLS_SHA256_C
without MBEDTLS_SHA224_C.
+
Session Cache API Change
-----------------------------------------------------------------
@@ -890,8 +916,9 @@
onwards, portable session cache implementations must not access fields of
`mbedtls_ssl_session`. See the corresponding migration guide. Users that
find themselves unable to migrate their session cache functionality without
-accessing fields of `mbedtls_ssl_session` should describe their usecase
+accessing fields of `mbedtls_ssl_session` should describe their use case
on the Mbed TLS mailing list.
+
SHA-512 and SHA-256 output type change
--------------------------
@@ -905,6 +932,7 @@
-----------------------------------------------------------------
This affects users manually checking for the following error codes:
+
- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED`
- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH`
- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE`
@@ -915,18 +943,24 @@
Migration paths:
- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH`
should never be returned from Mbed TLS, and there is no need to check for it.
+
Users should simply remove manual checks for those codes, and let the Mbed TLS
team know if -- contrary to the team's understanding -- there is in fact a situation
where one of them was ever returned.
+
- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and
`MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate
- is too large to fit into the output buffers. Users should check for
- `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their
- own certificate against the configured size of the output buffer to understand if
- the error is due to an overly large certificate.
--`MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN`, `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` and all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`.
+ is too large to fit into the output buffers.
+
+ Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially
+ compare the size of their own certificate against the configured size of the output buffer to
+ understand if the error is due to an overly large certificate.
+
+- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`
- Modified semantics of mbedtls_ssl_{get,set}_session()
+- all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives.
+
+Modified semantics of mbedtls_ssl_{get,set}_session()
-----------------------------------------------------------------
This affects users who call `mbedtls_ssl_get_session()` or
@@ -954,10 +988,10 @@
data instead.
- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x
is not useful since subsequent calls overwrite the effect of previous
- calls. Applications achieve equivalent functional behaviour by
+ calls. Applications achieve equivalent functional behavior by
issuing only the very last call to `mbedtls_ssl_set_session()`.
- Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option
+Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option
--
This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE
