1# Migrating from Mbed TLS 2.x to Mbed TLS 3.0 2 3This guide details the steps required to migrate from Mbed TLS version 2.x to 4Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks 5compatibility with previous versions, so users (and alt implementers) might 6need to change their own code in order to make it work with Mbed TLS 3.0. 7 8Here's the list of breaking changes; each entry should help you answer these 9two questions: (1) am I affected? (2) if yes, what's my migration path? 10 11The changes are detailed below, and include: 12 13- Removal of many insecure or obsolete features 14- Tidying up of configuration options (including removing some less useful options). 15- Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const. 16- Removal of functions, macros, and types previously marked as deprecated. 17 18Much of the information needed to determine a migration path can be found in the Mbed TLS 2.x documentation. 19 20 21## Accessing the Mbed TLS 2.x documentation 22 23For features previously marked as deprecated, Mbed TLS 2.x documentation may 24explain how to upgrade, and should be referred to when migrating code. Where a 25migration path is not provided in prior documentation, changes made and the 26upgrade steps required will be explained later in this guide. 27 28It's best to use the latest version of Mbed TLS 2.x for this purpose, which is the 2.28 LTS release. 29So to generate the documentation, checkout the `mbedtls-2.28` branch and follow 30the instructions in the [Documentation section of the README](https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-2.28/README.md#documentation). 31Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code. 32 33For some deprecated functions, 2.x documentation will suggest using a variant 34suffixed with `_ret`. In Mbed TLS 3.x, this change may not be required, as most 35of these variants have been renamed without the suffix. The section 36[Rename mbedtls_*_ret...](#rename-mbedtls__ret-cryptography-functions-whose-deprecated-variants-have-been-removed) 37has further detail on which functions this applies to. 38 39 40## General changes 41 42### Introduce a level of indirection and versioning in the config files 43 44`config.h` was split into `build_info.h` and `mbedtls_config.h`. 45 46* In code, use `#include <mbedtls/build_info.h>`. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`. 47* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before. 48* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros. 49 50Also, if you have a custom configuration file: 51 52* Don't include `check_config.h` or `config_psa.h` anymore. 53* Don't define `MBEDTLS_CONFIG_H` anymore. 54 55A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced. 56Defining it to a particular value will ensure that Mbed TLS interprets 57the config file in a way that's compatible with the config file format 58used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same 59value. 60The only value supported by Mbed TLS 3.0.0 is `0x03000000`. 61 62### Most structure fields are now private 63 64Direct access to fields of structures (`struct` types) declared in public headers is no longer supported. In Mbed TLS 3, the layout of structures is not considered part of the stable API, and minor versions (3.1, 3.2, etc.) may add, remove, rename, reorder or change the type of structure fields. 65 66There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the structure inconsistent; check the documentation in each case. 67 68Attempting to access a private field directly will result in a compilation error. 69 70If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls_<MODULE>_{get,set}_<FIELD>` or `mbedtls_<MODULE>_<STRUCTURE>_{get,set}_<FIELD>`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string. 71 72If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/Mbed-TLS/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). 73 74As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. 75 76### Move part of timing module out of the library 77 78The change affects users who use any of the following functions: 79`mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`, 80`mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`. 81 82If you were relying on these functions, you'll now need to change to using your 83platform's corresponding functions directly. 84 85### Deprecated net.h file was removed 86 87The file `include/mbedtls/net.h` was removed because its only function was to 88include `mbedtls/net_sockets.h` which now should be included directly. 89 90### Remove `MBEDTLS_CHECK_PARAMS` option 91 92This change does not affect users who use the default configuration; it only 93affects users who enabled that option. 94 95The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enabled certain kinds 96of “parameter validation”. It covered two kinds of validations: 97 98- In some functions that require a valid pointer, “parameter validation” checks 99that the pointer is non-null. With the feature disabled, a null pointer is not 100treated differently from any other invalid pointer, and typically leads to a 101runtime crash. 90% of the uses of the feature are of this kind. 102- In some functions that take an enum-like argument, “parameter validation” 103checks that the value is a valid one. With the feature disabled, an invalid 104value causes a silent default to one of the valid values. 105 106The default reaction to a failed check was to call a function 107`mbedtls_param_failed()` which the application had to provide. If this function 108returned, its caller returned an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`. 109 110This feature was only used in some classic (non-PSA) cryptography modules. It was 111not used in X.509, TLS or in PSA crypto, and it was not implemented in all 112classic crypto modules. 113 114This feature has been removed. The library no longer checks for NULL pointers; 115checks for enum-like arguments will be kept or re-introduced on a case-by-case 116basis, but their presence will no longer be dependent on a compile-time option. 117 118Validation of enum-like values is somewhat useful, but not extremely important, 119because the parameters concerned are usually constants in applications. 120 121For more information see issue #4313. 122 123### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option 124 125This does not affect users who use the default `mbedtls_config.h`, as this option was 126already off by default. 127 128If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform 129doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` 130and make sure your device is provisioned with a strong random seed. 131Alternatively, for testing purposes only, you can create and register a fake 132entropy function. 133 134### Remove the HAVEGE module 135 136This doesn't affect people using the default configuration as it was already 137disabled by default. 138 139This only affects users who called the HAVEGE modules directly (not 140recommended), or users who used it through the entropy module but had it as the 141only source of entropy. If you're in that case, please declare OS or hardware 142RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed 143file created securely during device provisioning. See 144<https://mbed-tls.readthedocs.io/en/latest/kb/how-to/add-entropy-sources-to-entropy-pool> for more 145information. 146 147### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0 148 149This only affects people who've been using Mbed TLS since before version 2.0 150and still relied on `compat-1.3.h` in their code. 151 152Please use the new names directly in your code; `scripts/rename.pl` (from any 153of the 2.x releases — no longer included in 3.0) might help you do that. 154 155 156## Low-level crypto 157 158Please also refer to the section [High-level crypto](#high-level-crypto) for 159changes that could sit in either category. 160 161### Deprecated functions were removed from bignum 162 163The function `mbedtls_mpi_is_prime()` was removed. Please use 164`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the 165number of Miller-Rabin rounds. 166 167### Deprecated functions were removed from DRBGs 168 169The functions `mbedtls_ctr_drbg_update_ret()` and `mbedtls_hmac_drbg_update_ret()` 170were renamed to replace the corresponding functions without `_ret` appended. Please call 171the name without `_ret` appended and check the return value. 172 173### Deprecated hex-encoded primes were removed from DHM 174 175The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, 176`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, 177`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`, 178`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were 179removed. The primes from RFC 5114 are deprecated because their derivation is not 180documented and therefore their usage constitutes a security risk; they are fully 181removed from the library. Please use parameters from RFC 3526 (still in the 182library, only in binary form) or RFC 7919 (also available in the library) or 183other trusted sources instead. 184 185### Deprecated functions were removed from hashing modules 186 187Modules: MD5, SHA1, SHA256, SHA512, MD. 188 189- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, 190 `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace 191 the corresponding functions without `_ret` appended. Please call the name without `_ret` appended and check the return value. 192- The function `mbedtls_md_init_ctx()` was removed; please use 193 `mbedtls_md_setup()` instead. 194- The functions `mbedtls_xxx_process()` were removed. You normally don't need 195 to call that from application code. However if you do (or if you want to 196 provide your own version of that function), please use 197 `mbedtls_internal_xxx_process()` instead, and check the return value. 198 199### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior 200 201The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does 202not increase peak RAM usage anymore. 203 204If you are limited by code size, you can define `MBEDTLS_ECP_FIXED_POINT_OPTIM` 205to `0` in your config file. The impact depends on the number and size of 206enabled curves. For example, for P-256 the difference is 1KB; see the documentation 207of this option for details. 208 209### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` 210 211This does not affect users who use the default `mbedtls_config.h`. `MBEDTLS_SHA256_C` 212was enabled by default. Now both `MBEDTLS_SHA256_C` and `MBEDTLS_SHA224_C` are 213enabled. 214 215If you were using custom config file with `MBEDTLS_SHA256_C` enabled, then 216you will need to add `#define MBEDTLS_SHA224_C` option to your config. 217Current version of the library does not support enabling `MBEDTLS_SHA256_C` 218without `MBEDTLS_SHA224_C`. 219 220### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` 221 222This does not affect users who use the default `mbedtls_config.h`. 223`MBEDTLS_SHA512_NO_SHA384` was disabled by default, now `MBEDTLS_SHA384_C` is 224enabled by default. 225 226If you were using a config file with both `MBEDTLS_SHA512_C` and 227MBEDTLS_SHA512_NO_SHA384, then just remove the `MBEDTLS_SHA512_NO_SHA384`. 228If you were using a config file with `MBEDTLS_SHA512_C` and without 229`MBEDTLS_SHA512_NO_SHA384` and you need the SHA-384 algorithm, then add 230`#define MBEDTLS_SHA384_C` to your config file. 231 232### GCM multipart interface: application changes 233 234The GCM module now supports arbitrary chunked input in the multipart interface. 235This changes the interface for applications using the GCM module directly for multipart operations. 236Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. 237 238* `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. 239* `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: 240 * As long as the input remains block-aligned, the output length is exactly the input length, as before. 241 * 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()`. 242* `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. 243 244### GCM interface changes: impact for alternative implementations 245 246The 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: 247 248* `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. 249* `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: 250 * Always return the partial output immediately, even if it does not consist of a whole number of blocks. 251 * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. 252* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. 253 254### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed 255 256This doesn't affect users of the default configuration; it only affects people 257who were explicitly setting this option. 258 259This was a trade-off between code size and countermeasures; it is no longer 260relevant as the countermeasure is now always on at no cost in code size. 261 262### SHA-512 and SHA-256 output type change 263 264The output parameter of `mbedtls_sha256_finish()`, `mbedtls_sha256()`, `mbedtls_sha512_finish()`, `mbedtls_sha512()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. 265 266This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. 267 268Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. 269 270### Deprecated error codes for hardware failures were removed 271 272- The macros `MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE` from various crypto modules 273 were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used 274 instead. 275- The macro `MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION` was removed; 276 `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead. 277- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules 278 were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead. 279 280### Deprecated error codes for invalid input data were removed 281 282- The macros `MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH` from ARIA and Camellia 283 modules were removed; `MBEDTLS_ERR_xxx_BAD_INPUT_DATA` is now used instead. 284 285### Remove the mode parameter from RSA functions 286 287This affects all users who use the RSA encrypt, decrypt, sign and 288verify APIs. 289 290The RSA module no longer supports private-key operations with the public key or 291vice versa. As a consequence, RSA operation functions no longer have a mode 292parameter. If you were calling RSA operations with the normal mode (public key 293for verification or encryption, private key for signature or decryption), remove 294the `MBEDTLS_RSA_PUBLIC` or `MBEDTLS_RSA_PRIVATE` argument. If you were calling 295RSA operations with the wrong mode, which rarely makes sense from a security 296perspective, this is no longer supported. 297 298### Deprecated functions were removed from AES 299 300The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were 301removed. 302 303If you're simply using the AES module, you should be calling the higher-level 304functions `mbedtls_aes_crypt_xxx()`. 305 306If you're providing an alternative implementation using 307`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be 308replacing the removed functions with `mbedtls_internal_aes_encrypt()` and 309`mbedtls_internal_aes_decrypt()` respectively. 310 311### Deprecated functions were removed from ECDSA 312 313The functions `mbedtls_ecdsa_write_signature_det()` and 314`mbedtls_ecdsa_sign_det()` were removed. They were superseded by 315`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` 316respectively. 317 318### Rename `mbedtls_*_ret()` cryptography functions whose deprecated variants have been removed 319 320This change affects users who were using the `mbedtls_*_ret()` cryptography 321functions. 322 323Those functions were created based on now-deprecated functions according to a 324requirement that a function needs to return a value. This change brings back the 325original names of those functions. The renamed functions are: 326 327| name before this change | after the change | 328|--------------------------------|----------------------------| 329| `mbedtls_ctr_drbg_update_ret` | `mbedtls_ctr_drbg_update` | 330| `mbedtls_hmac_drbg_update_ret` | `mbedtls_hmac_drbg_update` | 331| `mbedtls_md5_starts_ret` | `mbedtls_md5_starts` | 332| `mbedtls_md5_update_ret` | `mbedtls_md5_update` | 333| `mbedtls_md5_finish_ret` | `mbedtls_md5_finish` | 334| `mbedtls_md5_ret` | `mbedtls_md5` | 335| `mbedtls_ripemd160_starts_ret` | `mbedtls_ripemd160_starts` | 336| `mbedtls_ripemd160_update_ret` | `mbedtls_ripemd160_update` | 337| `mbedtls_ripemd160_finish_ret` | `mbedtls_ripemd160_finish` | 338| `mbedtls_ripemd160_ret` | `mbedtls_ripemd160` | 339| `mbedtls_sha1_starts_ret` | `mbedtls_sha1_starts` | 340| `mbedtls_sha1_update_ret` | `mbedtls_sha1_update` | 341| `mbedtls_sha1_finish_ret` | `mbedtls_sha1_finish` | 342| `mbedtls_sha1_ret` | `mbedtls_sha1` | 343| `mbedtls_sha256_starts_ret` | `mbedtls_sha256_starts` | 344| `mbedtls_sha256_update_ret` | `mbedtls_sha256_update` | 345| `mbedtls_sha256_finish_ret` | `mbedtls_sha256_finish` | 346| `mbedtls_sha256_ret` | `mbedtls_sha256` | 347| `mbedtls_sha512_starts_ret` | `mbedtls_sha512_starts` | 348| `mbedtls_sha512_update_ret` | `mbedtls_sha512_update` | 349| `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` | 350| `mbedtls_sha512_ret` | `mbedtls_sha512` | 351 352To migrate to the this change the user can keep the `*_ret` names in their code 353and include the `compat_2.x.h` header file which holds macros with proper 354renaming or to rename those functions in their code according to the list from 355mentioned header file. 356 357### Remove the RNG parameter from RSA verify functions 358 359RSA verification functions also no longer take random generator arguments (this 360was only needed when using a private key). This affects all applications using 361the RSA verify functions. 362 363### Remove the padding parameters from `mbedtls_rsa_init()` 364 365This affects all users who use the RSA encrypt, decrypt, sign and 366verify APIs. 367 368The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1 369encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If 370you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call 371to `mbedtls_rsa_init()`, to call `mbedtls_rsa_set_padding()` to set it. 372 373To choose the padding type when initializing a context, instead of 374 375```C 376 mbedtls_rsa_init(ctx, padding, hash_id); 377``` 378 379use 380 381```C 382 mbedtls_rsa_init(ctx); 383 mbedtls_rsa_set_padding(ctx, padding, hash_id); 384``` 385 386To use PKCS#1 v1.5 padding, instead of 387 388```C 389 mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, <ignored>); 390``` 391 392just use 393 394```C 395 mbedtls_rsa_init(ctx); 396``` 397 398 399## High-level crypto 400 401Please also refer to the section [Low-level crypto](#low-level-crypto) for 402changes that could sit in either category. 403 404### Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations 405 406This only affects people who use the cipher module to perform AEAD operations 407using the multi-part API. 408 409Previously, the documentation didn't state explicitly if it was OK to call 410`mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after 411the last call to `mbedtls_cipher_update()` — that is, without calling 412`mbedtls_cipher_finish()` in-between. If you code was missing that call, 413please add it and be prepared to get as much as 15 bytes of output. 414 415Currently the output is always 0 bytes, but it may be more when alternative 416implementations of the underlying primitives are in use, or with future 417versions of the library. 418 419### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms 420 421This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. 422 423They are already niche or obsolete and most of them are weak or broken. For 424those reasons possible users should consider switching to modern and safe 425alternatives to be found in literature. 426 427### Deprecated functions were removed from cipher 428 429The functions `mbedtls_cipher_auth_encrypt()` and 430`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by 431`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()` 432respectively which additionally support key wrapping algorithms such as 433NIST_KW. 434 435### Extra parameter for the output buffer size 436 437The following functions now take an extra parameter indicating the size of the output buffer: 438 439* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()` 440* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` 441 442The 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. 443 444### Signature functions now require the hash length to match the expected value 445 446This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. 447 448All the functions in the RSA module that accept a `hashlen` parameter used to 449ignore it unless the `md_alg` parameter was `MBEDTLS_MD_NONE`, indicating raw 450data was signed. The `hashlen` parameter is now always the size that is read 451from the `hash` input buffer. This length must be equal to the output size of 452the hash algorithm used when signing a hash. (The requirements when signing 453raw data are unchanged.) This affects the following functions: 454 455* `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_pkcs1_verify` 456* `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_verify` 457* `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_verify` 458* `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify_ext` 459 460The signature functions in the PK module no longer accept 0 as the `hash_len` parameter. The `hash_len` parameter is now always the size that is read from the `hash` input buffer. This affects the following functions: 461 462* `mbedtls_pk_sign`, `mbedtls_pk_verify` 463* `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable` 464* `mbedtls_pk_verify_ext` 465 466The migration path is to pass the correct value to those functions. 467 468### Some function parameters were made const 469 470Various functions in the PK and ASN.1 modules had a `const` qualifier added to 471some of their parameters. 472 473This normally doesn't affect your code, unless you use pointers to reference 474those functions. In this case, you'll need to update the type of your pointers 475in order to match the new signature. 476 477### The RNG parameter is now mandatory for all functions that accept one 478 479This change affects all users who called a function accepting a `f_rng` 480parameter with `NULL` as the value of this argument; this is no longer 481supported. 482 483The changed functions are: the X.509 CRT and CSR writing functions; the PK and 484RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM 485and ECDH that compute the shared secret; the scalar multiplication functions in 486ECP. 487 488You now need to pass a properly seeded, cryptographically secure RNG to all 489functions that accept a `f_rng` parameter. It is of course still possible to 490pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a 491context. 492 493Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` 494configuration options) may have their own internal and are free to ignore the 495`f_rng` argument but must allow users to pass one anyway. 496 497### Some functions gained an RNG parameter 498 499This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, 500`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and 501`mbedtls_pk_parse_keyfile()`. 502 503You now need to pass a properly seeded, cryptographically secure RNG when 504calling these functions. It is used for blinding, a countermeasure against 505side-channel attacks. 506 507 508## PSA 509 510### Deprecated names for PSA constants and types were removed 511 512Some constants and types that were present in beta versions of the PSA Crypto 513API were removed from version 1.0 of specification. Please switch to the new 514names provided by the 1.0 specification instead. 515 516 517## Changes that only affect alternative implementations 518 519### Internal / alt-focused headers were moved to a private location 520 521This shouldn't affect users who took care not to include headers that 522were documented as internal, despite being in the public include directory. 523 524If you're providing alt implementations of ECP or RSA, you'll need to add our 525`library` directory to your include path when building your alt 526implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been 527renamed to `ecp_internal_alt.h` and `rsa_alt_helpers.h` respectively. 528 529If you're a library user and used to rely on having access to a structure or 530function that's now in a private header, please reach out on the mailing list 531and explain your need; we'll consider adding a new API in a future version. 532 533### CCM interface changes: impact for alternative implementations 534 535The CCM interface has changed with the addition of support for 536multi-part operations. Five new API functions have been defined: 537 `mbedtls_ccm_starts()`, `mbedtls_ccm_set_lengths()`, 538 `mbedtls_ccm_update_ad()`, `mbedtls_ccm_update()` and `mbedtls_ccm_finish()`. 539Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to 540implement those additional five API functions. 541 542 543## X.509 544 545### Remove the certs module from the library 546 547This should not affect production use of the library, as the certificates and 548keys included there were never suitable for production use. 549 550However it might affect you if you relied on them for testing purposes. In 551that case, please embed your own test certificates in your test code; now that 552`certs.c` is out of the library there is no longer any stability guaranteed 553and it may change in incompatible ways at any time. 554 555### Change the API to allow adding critical extensions to CSRs 556 557This affects applications that call the `mbedtls_x509write_csr_set_extension` 558function. 559 560The API is changed to include the parameter `critical` which enables marking an 561extension included in a CSR as critical. To get the previous behavior pass 0. 562 563### Remove the config option `MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION` 564 565This change does not affect users of the default configuration; it only affects 566users who enable this option. 567 568The X.509 standard says that implementations must reject critical extensions that 569they don't recognize, and this is what Mbed TLS does by default. This option 570allowed to continue parsing those certificates but didn't provide a convenient 571way to handle those extensions. 572 573The migration path from that option is to use the 574`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally 575equivalent to `mbedtls_x509_crt_parse_der()`, and/or 576`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every 577unsupported certificate extension and additionally the "certificate policies" 578extension if it contains any unsupported certificate policies. 579 580### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` 581 582This change affects users who have chosen the configuration options to disable the 583library's verification of the `keyUsage` and `extendedKeyUsage` fields of X.509 584certificates. 585 586The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` 587configuration options are removed and the X.509 code now behaves as if they were 588always enabled. It is consequently not possible anymore to disable at compile 589time the verification of the `keyUsage` and `extendedKeyUsage` fields of X.509 590certificates. 591 592The verification of the `keyUsage` and `extendedKeyUsage` fields is important, 593disabling it can cause security issues and it is thus not recommended. If the 594verification is for some reason undesirable, it can still be disabled by means 595of the verification callback function passed to `mbedtls_x509_crt_verify()` (see 596the documentation of this function for more information). 597 598### Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option 599 600This change does not affect users who were using the default configuration, as 601this option was already disabled by default. Also, it does not affect users who 602are working with current V3 X.509 certificates. 603 604Extensions were added in V3 of the X.509 specification, so pre-V3 certificates 605containing extensions were never compliant. Mbed TLS now rejects them with a 606parsing error in all configurations, as it did previously in the default 607configuration. 608 609If you are working with the pre-V3 certificates you need to switch to the 610current ones. 611 612### Strengthen default algorithm selection for X.509 613 614This is described in the section [Strengthen default algorithm selection for X.509 and TLS](#strengthen-default-algorithm-selection-for-x.509-and-tls). 615 616### Remove wrapper for libpkcs11-helper 617 618This doesn't affect people using the default configuration as it was already 619disabled by default. 620 621If you used to rely on this module in order to store your private keys 622securely, please have a look at the key management facilities provided by the 623PSA crypto API. If you have a use case that's not covered yet by this API, 624please reach out on the mailing list. 625 626 627## SSL 628 629### Remove support for TLS 1.0, 1.1 and DTLS 1.0 630 631This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols. 632 633These versions have been deprecated by RFC 8996. 634Keeping them in the library creates opportunities for misconfiguration 635and possibly downgrade attacks. More generally, more code means a larger attack 636surface, even if the code is supposedly not used. 637 638The migration path is to adopt the latest versions of the protocol. 639 640As a consequence of removing TLS 1.0, support for CBC record splitting was 641also removed, as it was a work-around for a weakness in this particular 642version. There is no migration path since the feature is no longer relevant. 643 644As a consequence of currently supporting only one version of (D)TLS (and in the 645future 1.3 which will have a different version negotiation mechanism), support 646for fallback SCSV (RFC 7507) was also removed. There is no migration path as 647it's no longer useful with TLS 1.2 and later. 648 649As a consequence of currently supporting only one version of (D)TLS (and in the 650future 1.3 which will have a different concept of ciphersuites), support for 651configuring ciphersuites separately for each version via 652`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use 653`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS 6541.2; in the future a different API will be added for (D)TLS 1.3. 655 656### Remove support for SSL 3.0 657 658This doesn't affect people using the default configuration as it was already 659disabled by default. 660 661This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3` 662and relied on that version in order to communicate with peers that are not up 663to date. If one of your peers is in that case, please try contacting them and 664encouraging them to upgrade their software. 665 666### Remove support for parsing SSLv2 ClientHello 667 668This doesn't affect people using the default configuration as it was already 669disabled by default. 670 671This only affects TLS servers that have clients who send an SSLv2 ClientHello. 672These days clients are very unlikely to do that. If you have a client that 673does, please try contacting them and encouraging them to upgrade their 674software. 675 676### Remove support for truncated HMAC 677 678This affects users of truncated HMAC, that is, users who called 679`mbedtls_ssl_conf_truncated_hmac( ..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED)`, 680regardless of whether the standard version was used or compatibility version 681(`MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT`). 682 683The recommended migration path for people who want minimal overhead is to use a 684CCM-8 ciphersuite. 685 686### Remove support for TLS record-level compression 687 688This doesn't affect people using the default configuration as it was already 689disabled by default. 690 691This only affects TLS users who enabled `MBEDTLS_ZLIB_SUPPORT`. This will not 692cause any failures however if you used to enable TLS record-level compression 693you may find that your bandwidth usage increases without compression. There's 694no general solution to this problem; application protocols might have their 695own compression mechanisms and are in a better position than the TLS stack to 696avoid variants of the CRIME and BREACH attacks. 697 698### Remove support for TLS RC4-based ciphersuites 699 700This does not affect people who used the default `mbedtls_config.h` and the default 701list of ciphersuites, as RC4-based ciphersuites were already not negotiated in 702that case. 703 704Please switch to any of the modern, recommended ciphersuites (based on 705AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support 706any, encourage them to upgrade their software. 707 708### Remove support for TLS single-DES ciphersuites 709 710This doesn't affect people using the default configuration as it was already 711disabled by default. 712 713Please switch to any of the modern, recommended ciphersuites (based on 714AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support 715any, encourage them to upgrade their software. 716 717### Remove support for TLS record-level hardware acceleration 718 719This doesn't affect people using the default configuration as it was already 720disabled by default. 721 722This feature had been broken for a while so we doubt anyone still used it. 723However if you did, please reach out on the mailing list and let us know about 724your use case. 725 726### Remove config option `MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME` 727 728This doesn't affect people using the default configuration. 729 730This option has not had any effect for a long time. Please use the `lifetime` 731parameter of `mbedtls_ssl_ticket_setup()` instead. 732 733### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options 734 735This change affects users who modified the default `mbedtls_config.h` padding granularity 736settings, i.e. enabled at least one of the options. 737 738The `mbedtls_config.h` options `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and 739`MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` were combined into one option because 740they used exactly the same padding mechanism and hence their respective padding 741granularities can be used in exactly the same way. This change simplifies the 742code maintenance. 743 744The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used 745for both DTLS-CID and TLS 1.3. 746 747### TLS now favors faster curves over larger curves 748 749The 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. 750 751If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. 752 753### SSL key export interface change 754 755This affects users of the SSL key export APIs: 756``` 757 mbedtls_ssl_conf_export_keys_cb() 758 mbedtls_ssl_conf_export_keys_ext_cb() 759``` 760 761Those APIs have been removed and replaced by the new API 762`mbedtls_ssl_set_export_keys_cb()`. This API differs from 763the previous key export API in the following ways: 764 765- It is no longer bound to an SSL configuration, but to an 766 SSL context. This allows users to more easily identify the 767 connection an exported key belongs to. 768- It no longer exports raw keys and IV. 769- A secret type parameter has been added to identify which key 770 is being exported. For TLS 1.2, only the master secret is 771 exported, but upcoming TLS 1.3 support will add other kinds of keys. 772- The callback now specifies a void return type, rather than 773 returning an error code. It is the responsibility of the application 774 to handle failures in the key export callback, for example by 775 shutting down the TLS connection. 776 777For users which do not rely on raw keys and IV, adjusting to the new 778callback type should be straightforward — see the example programs 779`programs/ssl/ssl_client2` and `programs/ssl/ssl_server2` for callbacks 780for NSSKeylog, EAP-TLS and DTLS-SRTP. 781 782Users which require access to the raw keys used to secure application 783traffic may derive those by hand based on the master secret and the 784handshake transcript hashes which can be obtained from the raw data 785on the wire. Such users are also encouraged to reach out to the 786Mbed TLS team on the mailing list, to let the team know about their 787use case. 788 789### Remove MaximumFragmentLength (MFL) query API 790 791This affects users which use the MFL query APIs 792`mbedtls_ssl_get_{input,output}_max_frag_len()` to 793infer upper bounds on the plaintext size of incoming and 794outgoing record. 795 796Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` 797instead, which also provides such upper bounds but takes more factors 798than just the MFL configuration into account. 799 800### Relaxed semantics for PSK configuration 801 802This affects users which call the PSK configuration APIs 803`mbedtls_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()` 804multiple times on the same SSL configuration. 805 806In Mbed TLS 2.x, users would observe later calls overwriting 807the effect of earlier calls, with the prevailing PSK being 808the one that has been configured last. In Mbed TLS 3.0, 809calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times 810will return an error, leaving the first PSK intact. 811 812To achieve equivalent functionality when migrating to Mbed TLS 3.0, 813users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should 814remove all but the last call, so that only one call to _either_ 815`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()` 816remains. 817 818### Remove the configuration to enable weak ciphersuites in SSL / TLS 819 820This does not affect users who use the default `mbedtls_config.h`, as this option was 821already off by default. 822 823If you were using a weak cipher, please switch to any of the modern, 824recommended ciphersuites (based on AES-GCM, AES-CCM or ChachaPoly for example) 825and if your peer doesn't support any, encourage them to upgrade their software. 826 827If you were using a ciphersuite without encryption, you just have to 828enable `MBEDTLS_CIPHER_NULL_CIPHER` now. 829 830### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option 831 832This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to 833set the maximum length of incoming and outgoing plaintext fragments, 834which can save memory by reducing the size of the TLS I/O buffers. 835 836This option is replaced by the more fine-grained options 837`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set 838the maximum incoming and outgoing plaintext fragment lengths, respectively. 839 840### Remove the SSL API `mbedtls_ssl_get_session_pointer()` 841 842This affects two classes of users: 843 8441. Users who manually inspect parts of the current session through 845 direct structure field access. 846 8472. Users of session resumption who query the current session 848 via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting 849 it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, 850 respectively. 851 852Migration paths: 853 8541. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many 855 other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no 856 longer part of the public API in Mbed TLS 3.0, and direct structure field 857 access is no longer supported. Please see the [section on private structure fields](#most-structure-fields-are-now-private) for more details. 858 8592. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by 860 calls to `mbedtls_ssl_get_session()` as demonstrated in the example 861 program `programs/ssl/ssl_client2.c`. 862 863### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option 864 865This change does not affect users who used the default `mbedtls_config.h`, as the option 866`MBEDTLS_SSL_DTLS_BADMAC_LIMIT` was already on by default. 867 868This option was a trade-off between functionality and code size: it allowed 869users who didn't need that feature to avoid paying the cost in code size, by 870disabling it. 871 872This option is no longer present, but its functionality is now always enabled. 873 874### Deprecated functions were removed from SSL 875 876The function `mbedtls_ssl_conf_dh_param()` was removed. Please use 877`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. 878 879The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use 880`mbedtls_ssl_get_max_out_record_payload()` and 881`mbedtls_ssl_get_max_in_record_payload()` 882instead. 883 884### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default 885 886This change does not affect users who use the default `mbedtls_config.h`, as the 887option `MBEDTLS_SSL_RECORD_CHECKING` was already on by default. 888 889This option was added only to control compilation of one function, 890 `mbedtls_ssl_check_record()`, which is only useful in some specific cases, so it 891was made optional to allow users who don't need it to save some code space. 892However, the same effect can be achieved by using link-time garbage collection. 893 894Users who changed the default setting of the option need to change the config/ 895build system to remove that change. 896 897### Session Cache API Change 898 899This affects users who use `mbedtls_ssl_conf_session_cache()` 900to configure a custom session cache implementation different 901from the one Mbed TLS implements in `library/ssl_cache.c`. 902 903Those users will need to modify the API of their session cache 904implementation to that of a key-value store with keys being 905session IDs and values being instances of `mbedtls_ssl_session`: 906 907```C 908typedef int mbedtls_ssl_cache_get_t( void *data, 909 unsigned char const *session_id, 910 size_t session_id_len, 911 mbedtls_ssl_session *session ); 912typedef int mbedtls_ssl_cache_set_t( void *data, 913 unsigned char const *session_id, 914 size_t session_id_len, 915 const mbedtls_ssl_session *session ); 916``` 917 918Since the structure of `mbedtls_ssl_session` is no longer public from 3.0 919onwards, portable session cache implementations must not access fields of 920`mbedtls_ssl_session`. See the corresponding migration guide. Users that 921find themselves unable to migrate their session cache functionality without 922accessing fields of `mbedtls_ssl_session` should describe their use case 923on the Mbed TLS mailing list. 924 925### Changes in the SSL error code space 926 927This affects users manually checking for the following error codes: 928 929- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` 930- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` 931- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` 932- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` 933- `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` 934- `MBEDTLS_ERR_SSL_BAD_HS_XXX` 935 936Migration paths: 937- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and 938 `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate 939 is too large to fit into the output buffers. 940 941 Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially 942 compare the size of their own certificate against the configured size of the output buffer to 943 understand if the error is due to an overly large certificate. 944 945- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been 946 replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. 947 948- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives, which give more information about the type of error raised. 949 950 Users should check for the newly introduced generic error codes 951 952 * `MBEDTLS_ERR_SSL_DECODE_ERROR` 953 * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`, 954 * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` 955 * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION` 956 * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE` 957 * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME` 958 * `MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION` 959 * `MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL` 960 961 and the pre-existing generic error codes 962 963 * `MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE` 964 * `MBEDTLS_ERR_SSL_INTERNAL_ERROR` 965 966 instead. 967 968### Modified semantics of `mbedtls_ssl_{get,set}_session()` 969 970This affects users who call `mbedtls_ssl_get_session()` or 971`mbedtls_ssl_set_session()` multiple times on the same SSL context 972representing an established TLS 1.2 connection. 973Those users will now observe the second call to fail with 974`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. 975 976Migration path: 977- Exporting the same TLS 1.2 connection multiple times via 978 `mbedtls_ssl_get_session()` leads to multiple copies of 979 the same session. This use of `mbedtls_ssl_get_session()` 980 is discouraged, and the following should be considered: 981 * If the various session copies are later loaded into 982 fresh SSL contexts via `mbedtls_ssl_set_session()`, 983 export via `mbedtls_ssl_get_session()` only once and 984 load the same session into different contexts via 985 `mbedtls_ssl_set_session()`. Since `mbedtls_ssl_set_session()` 986 makes a copy of the session that's being loaded, this 987 is functionally equivalent. 988 * If the various session copies are later serialized 989 via `mbedtls_ssl_session_save()`, export and serialize 990 the session only once via `mbedtls_ssl_get_session()` and 991 `mbedtls_ssl_session_save()` and make copies of the raw 992 data instead. 993- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x 994 is not useful since subsequent calls overwrite the effect of previous 995 calls. Applications achieve equivalent functional behavior by 996 issuing only the very last call to `mbedtls_ssl_set_session()`. 997 998### Turn `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` configuration option into a runtime option 999 1000This change affects users who were enabling `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` 1001option in the `mbedtls_config.h` 1002 1003This option has been removed and a new function with similar functionality has 1004been introduced into the SSL API. 1005 1006This new function `mbedtls_ssl_conf_preference_order()` can be used to 1007change the preferred order of ciphersuites on the server to those used on the client, 1008e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)` 1009has the same effect as enabling the removed option. The default state is to use 1010the server order of suites. 1011 1012### Strengthen default algorithm selection for X.509 and TLS 1013 1014The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. 1015 1016Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. 1017 1018The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. 1019 1020The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. 1021 1022If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: 1023```C 1024mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; 1025my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); 1026``` 1027 1028If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. 1029 1030### Remove 3DES ciphersuites 1031 1032This change does not affect users using default settings for 3DES in `mbedtls_config.h` 1033because the 3DES ciphersuites were disabled by that. 1034 10353DES has weaknesses/limitations and there are better alternatives, and more and 1036more standard bodies are recommending against its use in TLS. 1037 1038The migration path here is to chose from the alternatives recommended in the 1039literature, such as AES. 1040