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