mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-03-03 01:13:37 +00:00
Fix errors in migration guide
Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
This commit is contained in:
Dave Rodgman
parent
1aea40427f
commit
759c0109f2
@ -10,6 +10,7 @@ Here's the list of breaking changes; each entry should help you answer these
|
||||
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 @@ used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same
|
||||
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 @@ also removed, as it was a work-around for a weakness in this particular
|
||||
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 @@ and still relied on `compat-1.3.h` in their code.
|
||||
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 @@ because the 3DES ciphersuites were disabled by that.
|
||||
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_starts(), mbedtls_ccm_set_lengths(),
|
||||
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 @@ 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.
|
||||
|
||||
Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options
|
||||
--
|
||||
|
||||
@ -309,6 +312,7 @@ code maintenance.
|
||||
|
||||
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 @@ This affects applications that call the `mbedtls_x509write_csr_set_extension`
|
||||
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 @@ TLS now favors faster curves over larger curves
|
||||
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 @@ The GCM multipart interface has changed as described in [“GCM multipart interf
|
||||
* 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 @@ Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `ps
|
||||
* 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 @@ handshake transcript hashes which can be obtained from the raw data
|
||||
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 @@ who were explicitly setting this option.
|
||||
|
||||
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 @@ outgoing record.
|
||||
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 @@ MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384.
|
||||
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 @@ The change affects users who use any of the following functions:
|
||||
|
||||
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 @@ The following functions now take an extra parameter indicating the size of the o
|
||||
* `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 @@ users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should
|
||||
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 @@ and if your peer doesn't support any, encourage them to upgrade their software.
|
||||
|
||||
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 @@ which can save memory by reducing the size of the TLS I/O buffers.
|
||||
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 @@ doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED`
|
||||
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 @@ This affects two classes of users:
|
||||
|
||||
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 @@ Migration paths:
|
||||
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 @@ equivalent to `mbedtls_x509_crt_parse_der()`, and/or
|
||||
`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 @@ disabling it can cause security issues and it is thus not recommended. If the
|
||||
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 @@ This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms.
|
||||
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 @@ users who didn't need that feature to avoid paying the cost in code size, by
|
||||
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 @@ Deprecated net.h file was removed
|
||||
|
||||
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 @@ Validation of enum-like values is somewhat useful, but not extremely important,
|
||||
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 @@ However, the same effect can be achieve by using link-time garbage collection.
|
||||
|
||||
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 @@ and include the `compat_2.x.h` header file which holds macros with proper
|
||||
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 @@ The signature functions in the PK module no longer accept 0 as the `hash_len` pa
|
||||
* `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 @@ To use PKCS#1 v1.5 padding, instead of
|
||||
```C
|
||||
mbedtls_rsa_init(ctx);
|
||||
```
|
||||
|
||||
Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C
|
||||
-----------------------------------------------------------------
|
||||
|
||||
@ -864,6 +889,7 @@ If you were using custom config file with MBEDTLS_SHA256_C enabled, then
|
||||
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 @@ Since the structure of `mbedtls_ssl_session` is no longer public from 3.0
|
||||
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 @@ Removal of some SSL error codes
|
||||
-----------------------------------------------------------------
|
||||
|
||||
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 @@ This affects users manually checking for the following error codes:
|
||||
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 @@ Migration path:
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user