Merge pull request #4402 from mpg/migration-guide-3.0
Migration guide for 3.0
This commit is contained in:
Gilles Peskine
GitHub
commit
275b9b2ef4
4 changed files with 257 additions and 10 deletions
13
ChangeLog
13
ChangeLog
|
|
@ -49,16 +49,9 @@ Removals
|
|||
* Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
|
||||
compile-time option, which was off by default. Users should not trust
|
||||
certificates signed with SHA-1 due to the known attacks against SHA-1.
|
||||
If needed, SHA-1 cerificate can still be used by providing custom
|
||||
verification profile to mbedtls_x509_crt_verify_with_profile function
|
||||
in x509_crt.h, or mbedtls_ssl_conf_cert_profile function in ssl.h.
|
||||
Example of custom verification profile, supporting SHA-1:
|
||||
const mbedtls_x509_crt_profile mbedtls_x509_crt_custom = {
|
||||
MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA1 ),
|
||||
0xFFFFFFF, /* Any PK alg */
|
||||
0xFFFFFFF, /* Any curve */
|
||||
2048
|
||||
};
|
||||
If needed, SHA-1 certificates can still be verified by using a custom
|
||||
verification profile.
|
||||
|
||||
* Removed deprecated things in psa/crypto_compat.h. Fixes #4284
|
||||
* Removed deprecated functions from hashing modules. Fixes #4280.
|
||||
* Remove PKCS#11 library wrapper. PKCS#11 has limited functionality,
|
||||
|
|
|
|||
5
ChangeLog.d/rm-ticket-lifetime-option
Normal file
5
ChangeLog.d/rm-ticket-lifetime-option
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
Removals
|
||||
* Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
|
||||
compile-time option. This option has been inactive for a long time.
|
||||
Please use the `lifetime` parameter of `mbedtls_ssl_ticket_setup()`
|
||||
instead.
|
||||
27
docs/3.0-migration-guide.d/00README
Normal file
27
docs/3.0-migration-guide.d/00README
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
Please add your migration guide entries here. Until 3.0 is released, each PR
|
||||
that makes backwards-incompatible changes should add a file here, with the
|
||||
extension .md, a descriptive name and the following format:
|
||||
|
||||
---%<------%<------%<------%<------%<------%<------%<------%<---
|
||||
|
||||
The change that was made
|
||||
------------------------
|
||||
|
||||
Who exactly is affected: does this affect users of the default config, of a
|
||||
particular feature? Remember to contextualise.
|
||||
|
||||
If I'm affected, what's my migration path? How should I change my code if this
|
||||
is an API change; if a feature was removed what are my alternatives?
|
||||
|
||||
---%<------%<------%<------%<------%<------%<------%<------%<---
|
||||
|
||||
PRs that make multiple independent changes should include one entry for each
|
||||
changes or logical groups of changes. You can either add multiple files or put
|
||||
multiple entries in the same file.
|
||||
|
||||
For examples, have a look a docs/3.0-migration-guide.md (which includes the
|
||||
top-level header and an intro before the list of entries).
|
||||
|
||||
As part of release preparation, the entries in this directory will be appended
|
||||
to docs/3.0-migration-guide.md and then re-ordered and reviewed one last time.
|
||||
The file is then going to be moved to the version-independent docs repo.
|
||||
222
docs/3.0-migration-guide.md
Normal file
222
docs/3.0-migration-guide.md
Normal file
|
|
@ -0,0 +1,222 @@
|
|||
Migrating from Mbed TLS 2.x to Mbed TLS 3.0
|
||||
===========================================
|
||||
|
||||
This guide details the steps required to migrate from Mbed TLS version 2.x to
|
||||
Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks
|
||||
compatibility with previous versions, so users (and alt implementors) might
|
||||
need to change their own code in order to make it work with Mbed TLS 3.0.
|
||||
|
||||
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?
|
||||
|
||||
Some function parameters were made const
|
||||
----------------------------------------
|
||||
|
||||
Various functions in the PK and ASN.1 modules had a `const` qualifier added to
|
||||
some of their parameters.
|
||||
|
||||
This normally doesn't affect your code, unless you use pointers to reference
|
||||
those functions. In this case, you'll need to update the type of your pointers
|
||||
in order to match the new signature.
|
||||
|
||||
Deprecated functions were removed from hashing modules
|
||||
------------------------------------------------------
|
||||
|
||||
Modules: MD2, MD4, MD5, SHA1, SHA256, SHA512, MD.
|
||||
|
||||
- The functions `mbedtls_xxx_starts()`, `mbedtls_xxx_update()`,
|
||||
`mbedtls_xxx_finish()` and `mbedtls_xxx()` were removed. Please use the
|
||||
function with the same name with `_ret` appended and check the return value.
|
||||
- The function `mbedtls_md_init_ctx()` was removed; please use
|
||||
`mbedtls_md_setup()` instead.
|
||||
- The functions `mbedtls_xxx_process()` were removed. You normally don't need
|
||||
to call that from application code. However if you do (or if you want to
|
||||
provide your own version of that function), please use
|
||||
`mbedtls_internal_xxx_process()` instead, and check the return value.
|
||||
|
||||
Deprecated error codes for hardware failures were removed
|
||||
---------------------------------------------------------
|
||||
|
||||
- The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules
|
||||
were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used
|
||||
instead.
|
||||
- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules
|
||||
were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead.
|
||||
|
||||
Deprecated names for PSA constants and types were removed
|
||||
---------------------------------------------------------
|
||||
|
||||
Some constants and types that were present in beta versions of the PSA Crypto
|
||||
API were removed from version 1.0 of specification. Please switch to the new
|
||||
names provided by the 1.0 specification instead.
|
||||
|
||||
Internal / alt-focused headers were moved to a private location
|
||||
----------------------------------------------------------------
|
||||
|
||||
This shouldn't affect users who took care not to include headers that
|
||||
were documented as internal, despite being in the public include directory.
|
||||
|
||||
If you're providing alt implementations of ECP or RSA, you'll need to add our
|
||||
`library` directory to your include path when building your alt
|
||||
implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been
|
||||
renamed to `ecp_alt.h` and `rsa_alt_helpers.h` respectively.
|
||||
|
||||
If you're a library user and used to rely on having access to a structure or
|
||||
function that's now in a private header, please reach out on the mailing list
|
||||
and explain your need; we'll consider adding a new API in a future version.
|
||||
|
||||
Remove the option to allow SHA-1 by default in certificates
|
||||
-----------------------------------------------------------
|
||||
|
||||
This does not affect users who use the default `config.h`, as this option was
|
||||
already off by default.
|
||||
|
||||
If you used to enable `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` in your
|
||||
`config.h`, first please take a moment to consider whether you really still
|
||||
want to accept certificates signed with SHA-1 as those are considered insecure
|
||||
and no CA has issued them for a while. If you really need to allow SHA-1 in
|
||||
certificates, please set up a custom profile as follows:
|
||||
|
||||
```
|
||||
const mbedtls_x509_crt_profile mbedtls_x509_crt_custom = {
|
||||
MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA1 ) |
|
||||
MBEDTLS_X509_ID_FLAG( /* other hash */ ) /* | etc */,
|
||||
0xFFFFFFF, /* Or specific PK algs */
|
||||
0xFFFFFFF, /* Or specific curves */
|
||||
2048 /* Or another RSA min bitlen */
|
||||
};
|
||||
```
|
||||
Then pass it to `mbedtls_x509_crt_verify_with_profile()` if you're verifying
|
||||
a certificate chain directly, or to `mbedtls_ssl_conf_cert_profile()` if the
|
||||
verification happens during a TLS handshake.
|
||||
|
||||
Remove the certs module from the library
|
||||
----------------------------------------
|
||||
|
||||
This should not affect production use of the library, as the certificates and
|
||||
keys included there were never suitable for production use.
|
||||
|
||||
However it might affect you if you relied on them for testing purposes. In
|
||||
that case, please embed your own test certificates in your test code; now that
|
||||
`certs.c` is out of the library there is no longer any stability guaranteed
|
||||
and it may change in incompatible ways at any time.
|
||||
|
||||
Remove the HAVEGE module
|
||||
------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
This only affects users who called the HAVEGE modules directly (not
|
||||
recommended), or users who used it through the entropy module but had it as the
|
||||
only source of entropy. If you're in that case, please declare OS or hardware
|
||||
RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed
|
||||
file created securely during device provisioning. See
|
||||
<https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool> for more
|
||||
information.
|
||||
|
||||
Remove support for parsing SSLv2 ClientHello
|
||||
--------------------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
This only affects TLS servers that have clients who send an SSLv2 ClientHello.
|
||||
These days clients are very unlikely to do that. If you have a client that
|
||||
does, please try contacting them and encouraging them to upgrade their
|
||||
software.
|
||||
|
||||
Remove support for SSL 3.0
|
||||
--------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3`
|
||||
and relied on that version in order to communicate with peers that are not up
|
||||
to date. If one of your peers is in that case, please try contacting them and
|
||||
encouraging them to upgrade their software.
|
||||
|
||||
Remove support for compatibility with old Mbed TLS's truncated HMAC
|
||||
-------------------------------------------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
This only affects TLS users who enabled `MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT` and
|
||||
used the Truncated HMAC extension to communicate with peers using old version
|
||||
of Mbed TLS. Please consider using a CCM-8 ciphersuite instead of the
|
||||
Truncated HMAC extension, or convincing your peer to upgrade their version of
|
||||
Mbed TLS.
|
||||
|
||||
Remove support for TLS record-level compression
|
||||
-----------------------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
This only affects TLS users who enabled `MBEDTLS_ZLIB_SUPPORT`. This will not
|
||||
cause any failures however if you used to enable TLS record-level compression
|
||||
you may find that your bandwidth usage increases without compression. There's
|
||||
no general solution to this problem; application protocols might have their
|
||||
own compression mechanisms and are in a better position than the TLS stack to
|
||||
avoid variants of the CRIME and BREACH attacks.
|
||||
|
||||
Remove support for TLS RC4-based ciphersuites
|
||||
---------------------------------------------
|
||||
|
||||
This does not affect people who used the default `config.h` and the default
|
||||
list of ciphersuites, as RC4-based ciphersuites were already not negotiated in
|
||||
that case.
|
||||
|
||||
Please switch to any of the modern, recommended ciphersuites (based on
|
||||
AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support
|
||||
any, encourage them to upgrade their software.
|
||||
|
||||
Remove support for TLS single-DES ciphersuites
|
||||
----------------------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
Please switch to any of the modern, recommended ciphersuites (based on
|
||||
AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support
|
||||
any, encourage them to upgrade their software.
|
||||
|
||||
Remove support for TLS record-level hardware acceleration
|
||||
---------------------------------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
This feature had been broken for a while so we doubt anyone still used it.
|
||||
However if you did, please reach out on the mailing list and let us know about
|
||||
your use case.
|
||||
|
||||
Remove wrapper for libpkcs11-helper
|
||||
-----------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration as it was already
|
||||
disabled by default.
|
||||
|
||||
If you used to rely on this module in order to store your private keys
|
||||
securely, please have a look at the key management facilities provided by the
|
||||
PSA crypto API. If you have a use case that's not covered yet by this API,
|
||||
please reach out on the mailing list.
|
||||
|
||||
Remove config option `MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME`
|
||||
----------------------------------------------------------
|
||||
|
||||
This doesn't affect people using the default configuration.
|
||||
|
||||
This option has not had any effect for a long time. Please use the `lifetime`
|
||||
parameter of `mbedtls_ssl_ticket_setup()` instead.
|
||||
|
||||
Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0
|
||||
-------------------------------------------------------------------
|
||||
|
||||
This only affects people who've been using Mbed TLS since before version 2.0
|
||||
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.
|
||||
Loading…
Reference in a new issue