Squashed 'lib/mbedtls/external/mbedtls/' content from commit 2ca6c285a0dd
git-subtree-dir: lib/mbedtls/external/mbedtls
git-subtree-split: 2ca6c285a0dd3f33982dd57299012dacab1ff206
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..11f197b
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,4 @@
+*.html
+*.pdf
+_build/
+api/
diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md
new file mode 100644
index 0000000..63a13ad
--- /dev/null
+++ b/docs/3.0-migration-guide.md
@@ -0,0 +1,1039 @@
+# Migrating from Mbed TLS 2.x to Mbed TLS 3.0
+
+This guide details the steps required to migrate from Mbed TLS version 2.x to
+Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks
+compatibility with previous versions, so users (and alt implementers) might
+need to change their own code in order to make it work with Mbed TLS 3.0.
+
+Here's the list of breaking changes; each entry should help you answer these
+two questions: (1) am I affected? (2) if yes, what's my migration path?
+
+The changes are detailed below, and include:
+
+- Removal of many insecure or obsolete features
+- Tidying up of configuration options (including removing some less useful options).
+- Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const.
+- Removal of functions, macros, and types previously marked as deprecated.
+
+Much of the information needed to determine a migration path can be found in the Mbed TLS 2.x documentation.
+
+
+## Accessing the Mbed TLS 2.x documentation
+
+For features previously marked as deprecated, Mbed TLS 2.x documentation may
+explain how to upgrade, and should be referred to when migrating code. Where a
+migration path is not provided in prior documentation, changes made and the
+upgrade steps required will be explained later in this guide.
+
+It's best to use the latest version of Mbed TLS 2.x for this purpose, which is the 2.28 LTS release.
+So to generate the documentation, checkout the `mbedtls-2.28` branch and follow
+the instructions in the [Documentation section of the README](https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-2.28/README.md#documentation).
+Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code.
+
+For some deprecated functions, 2.x documentation will suggest using a variant
+suffixed with `_ret`. In Mbed TLS 3.x, this change may not be required, as most
+of these variants have been renamed without the suffix. The section
+[Rename mbedtls_*_ret...](#rename-mbedtls__ret-cryptography-functions-whose-deprecated-variants-have-been-removed)
+has further detail on which functions this applies to.
+
+
+## General changes
+
+### Introduce a level of indirection and versioning in the config files
+
+`config.h` was split into `build_info.h` and `mbedtls_config.h`.
+
+* In code, use `#include <mbedtls/build_info.h>`. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`.
+* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before.
+* 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.
+
+Also, if you have a custom configuration file:
+
+* Don't include `check_config.h` or `config_psa.h` anymore.
+* Don't define `MBEDTLS_CONFIG_H` anymore.
+
+A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced.
+Defining it to a particular value will ensure that Mbed TLS interprets
+the config file in a way that's compatible with the config file format
+used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same
+value.
+The only value supported by Mbed TLS 3.0.0 is `0x03000000`.
+
+### Most structure fields are now private
+
+Direct 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.
+
+There 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.
+
+Attempting to access a private field directly will result in a compilation error.
+
+If 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.
+
+If 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.).
+
+As 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.
+
+### Move part of timing module out of the library
+
+The change affects users who use any of the following functions:
+`mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`,
+`mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`.
+
+If you were relying on these functions, you'll now need to change to using your
+platform's corresponding functions directly.
+
+### Deprecated net.h file was removed
+
+The file `include/mbedtls/net.h` was removed because its only function was to
+include `mbedtls/net_sockets.h` which now should be included directly.
+
+### Remove `MBEDTLS_CHECK_PARAMS` option
+
+This change does not affect users who use the default configuration; it only
+affects users who enabled that option.
+
+The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enabled certain kinds
+of “parameter validation”. It covered two kinds of validations:
+
+- In some functions that require a valid pointer, “parameter validation” checks
+that the pointer is non-null. With the feature disabled, a null pointer is not
+treated differently from any other invalid pointer, and typically leads to a
+runtime crash. 90% of the uses of the feature are of this kind.
+- In some functions that take an enum-like argument, “parameter validation”
+checks that the value is a valid one. With the feature disabled, an invalid
+value causes a silent default to one of the valid values.
+
+The default reaction to a failed check was to call a function
+`mbedtls_param_failed()` which the application had to provide. If this function
+returned, its caller returned an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`.
+
+This feature was only used in some classic (non-PSA) cryptography modules. It was
+not used in X.509, TLS or in PSA crypto, and it was not implemented in all
+classic crypto modules.
+
+This feature has been removed. The library no longer checks for NULL pointers;
+checks for enum-like arguments will be kept or re-introduced on a case-by-case
+basis, but their presence will no longer be dependent on a compile-time option.
+
+Validation of enum-like values is somewhat useful, but not extremely important,
+because the parameters concerned are usually constants in applications.
+
+For more information see issue #4313.
+
+### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option
+
+This does not affect users who use the default `mbedtls_config.h`, as this option was
+already off by default.
+
+If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform
+doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED`
+and make sure your device is provisioned with a strong random seed.
+Alternatively, for testing purposes only, you can create and register a fake
+entropy function.
+
+### Remove the HAVEGE module
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects users who called the HAVEGE modules directly (not
+recommended), or users who used it through the entropy module but had it as the
+only source of entropy. If you're in that case, please declare OS or hardware
+RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed
+file created securely during device provisioning. See
+<https://mbed-tls.readthedocs.io/en/latest/kb/how-to/add-entropy-sources-to-entropy-pool> for more
+information.
+
+### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0
+
+This only affects people who've been using Mbed TLS since before version 2.0
+and still relied on `compat-1.3.h` in their code.
+
+Please use the new names directly in your code; `scripts/rename.pl` (from any
+of the 2.x releases — no longer included in 3.0) might help you do that.
+
+
+## Low-level crypto
+
+Please also refer to the section [High-level crypto](#high-level-crypto) for
+changes that could sit in either category.
+
+### Deprecated functions were removed from bignum
+
+The function `mbedtls_mpi_is_prime()` was removed. Please use
+`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the
+number of Miller-Rabin rounds.
+
+### Deprecated functions were removed from DRBGs
+
+The functions `mbedtls_ctr_drbg_update_ret()` and `mbedtls_hmac_drbg_update_ret()`
+were renamed to replace the corresponding functions without `_ret` appended. Please call
+the name without `_ret` appended and check the return value.
+
+### Deprecated hex-encoded primes were removed from DHM
+
+The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`,
+`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`,
+`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`,
+`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were
+removed. The primes from RFC 5114 are deprecated because their derivation is not
+documented and therefore their usage constitutes a security risk; they are fully
+removed from the library. Please use parameters from RFC 3526 (still in the
+library, only in binary form) or RFC 7919 (also available in the library) or
+other trusted sources instead.
+
+### Deprecated functions were removed from hashing modules
+
+Modules: MD5, SHA1, SHA256, SHA512, MD.
+
+- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`,
+ `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace
+ the corresponding functions without `_ret` appended. Please call the name without `_ret` appended and check the return value.
+- The function `mbedtls_md_init_ctx()` was removed; please use
+ `mbedtls_md_setup()` instead.
+- The functions `mbedtls_xxx_process()` were removed. You normally don't need
+ to call that from application code. However if you do (or if you want to
+ provide your own version of that function), please use
+ `mbedtls_internal_xxx_process()` instead, and check the return value.
+
+### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior
+
+The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does
+not increase peak RAM usage anymore.
+
+If you are limited by code size, you can define `MBEDTLS_ECP_FIXED_POINT_OPTIM`
+to `0` in your config file. The impact depends on the number and size of
+enabled curves. For example, for P-256 the difference is 1KB; see the documentation
+of this option for details.
+
+### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C`
+
+This does not affect users who use the default `mbedtls_config.h`. `MBEDTLS_SHA256_C`
+was enabled by default. Now both `MBEDTLS_SHA256_C` and `MBEDTLS_SHA224_C` are
+enabled.
+
+If you were using custom config file with `MBEDTLS_SHA256_C` enabled, then
+you will need to add `#define MBEDTLS_SHA224_C` option to your config.
+Current version of the library does not support enabling `MBEDTLS_SHA256_C`
+without `MBEDTLS_SHA224_C`.
+
+### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C`
+
+This does not affect users who use the default `mbedtls_config.h`.
+`MBEDTLS_SHA512_NO_SHA384` was disabled by default, now `MBEDTLS_SHA384_C` is
+enabled by default.
+
+If you were using a config file with both `MBEDTLS_SHA512_C` and
+MBEDTLS_SHA512_NO_SHA384, then just remove the `MBEDTLS_SHA512_NO_SHA384`.
+If you were using a config file with `MBEDTLS_SHA512_C` and without
+`MBEDTLS_SHA512_NO_SHA384` and you need the SHA-384 algorithm, then add
+`#define MBEDTLS_SHA384_C` to your config file.
+
+### GCM multipart interface: application changes
+
+The GCM module now supports arbitrary chunked input in the multipart interface.
+This changes the interface for applications using the GCM module directly for multipart operations.
+Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes.
+
+* `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.
+* `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:
+ * As long as the input remains block-aligned, the output length is exactly the input length, as before.
+ * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`.
+* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time.
+
+### GCM interface changes: impact for alternative implementations
+
+The 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:
+
+* `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.
+* `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:
+ * Always return the partial output immediately, even if it does not consist of a whole number of blocks.
+ * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`.
+* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed.
+
+### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed
+
+This doesn't affect users of the default configuration; it only affects people
+who were explicitly setting this option.
+
+This was a trade-off between code size and countermeasures; it is no longer
+relevant as the countermeasure is now always on at no cost in code size.
+
+### SHA-512 and SHA-256 output type change
+
+The 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.
+
+This 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.
+
+Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly.
+
+### Deprecated error codes for hardware failures were removed
+
+- The macros `MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE` from various crypto modules
+ were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used
+ instead.
+- The macro `MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION` was removed;
+ `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead.
+- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules
+ were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead.
+
+### Deprecated error codes for invalid input data were removed
+
+- The macros `MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH` from ARIA and Camellia
+ modules were removed; `MBEDTLS_ERR_xxx_BAD_INPUT_DATA` is now used instead.
+
+### Remove the mode parameter from RSA functions
+
+This affects all users who use the RSA encrypt, decrypt, sign and
+verify APIs.
+
+The RSA module no longer supports private-key operations with the public key or
+vice versa. As a consequence, RSA operation functions no longer have a mode
+parameter. If you were calling RSA operations with the normal mode (public key
+for verification or encryption, private key for signature or decryption), remove
+the `MBEDTLS_RSA_PUBLIC` or `MBEDTLS_RSA_PRIVATE` argument. If you were calling
+RSA operations with the wrong mode, which rarely makes sense from a security
+perspective, this is no longer supported.
+
+### Deprecated functions were removed from AES
+
+The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were
+removed.
+
+If you're simply using the AES module, you should be calling the higher-level
+functions `mbedtls_aes_crypt_xxx()`.
+
+If you're providing an alternative implementation using
+`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be
+replacing the removed functions with `mbedtls_internal_aes_encrypt()` and
+`mbedtls_internal_aes_decrypt()` respectively.
+
+### Deprecated functions were removed from ECDSA
+
+The functions `mbedtls_ecdsa_write_signature_det()` and
+`mbedtls_ecdsa_sign_det()` were removed. They were superseded by
+`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()`
+respectively.
+
+### Rename `mbedtls_*_ret()` cryptography functions whose deprecated variants have been removed
+
+This change affects users who were using the `mbedtls_*_ret()` cryptography
+functions.
+
+Those functions were created based on now-deprecated functions according to a
+requirement that a function needs to return a value. This change brings back the
+original names of those functions. The renamed functions are:
+
+| name before this change | after the change |
+|--------------------------------|----------------------------|
+| `mbedtls_ctr_drbg_update_ret` | `mbedtls_ctr_drbg_update` |
+| `mbedtls_hmac_drbg_update_ret` | `mbedtls_hmac_drbg_update` |
+| `mbedtls_md5_starts_ret` | `mbedtls_md5_starts` |
+| `mbedtls_md5_update_ret` | `mbedtls_md5_update` |
+| `mbedtls_md5_finish_ret` | `mbedtls_md5_finish` |
+| `mbedtls_md5_ret` | `mbedtls_md5` |
+| `mbedtls_ripemd160_starts_ret` | `mbedtls_ripemd160_starts` |
+| `mbedtls_ripemd160_update_ret` | `mbedtls_ripemd160_update` |
+| `mbedtls_ripemd160_finish_ret` | `mbedtls_ripemd160_finish` |
+| `mbedtls_ripemd160_ret` | `mbedtls_ripemd160` |
+| `mbedtls_sha1_starts_ret` | `mbedtls_sha1_starts` |
+| `mbedtls_sha1_update_ret` | `mbedtls_sha1_update` |
+| `mbedtls_sha1_finish_ret` | `mbedtls_sha1_finish` |
+| `mbedtls_sha1_ret` | `mbedtls_sha1` |
+| `mbedtls_sha256_starts_ret` | `mbedtls_sha256_starts` |
+| `mbedtls_sha256_update_ret` | `mbedtls_sha256_update` |
+| `mbedtls_sha256_finish_ret` | `mbedtls_sha256_finish` |
+| `mbedtls_sha256_ret` | `mbedtls_sha256` |
+| `mbedtls_sha512_starts_ret` | `mbedtls_sha512_starts` |
+| `mbedtls_sha512_update_ret` | `mbedtls_sha512_update` |
+| `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` |
+| `mbedtls_sha512_ret` | `mbedtls_sha512` |
+
+To migrate to the this change the user can keep the `*_ret` names in their code
+and include the `compat_2.x.h` header file which holds macros with proper
+renaming or to rename those functions in their code according to the list from
+mentioned header file.
+
+### Remove the RNG parameter from RSA verify functions
+
+RSA verification functions also no longer take random generator arguments (this
+was only needed when using a private key). This affects all applications using
+the RSA verify functions.
+
+### Remove the padding parameters from `mbedtls_rsa_init()`
+
+This affects all users who use the RSA encrypt, decrypt, sign and
+verify APIs.
+
+The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1
+encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If
+you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call
+to `mbedtls_rsa_init()`, to call `mbedtls_rsa_set_padding()` to set it.
+
+To choose the padding type when initializing a context, instead of
+
+```C
+ mbedtls_rsa_init(ctx, padding, hash_id);
+```
+
+use
+
+```C
+ mbedtls_rsa_init(ctx);
+ mbedtls_rsa_set_padding(ctx, padding, hash_id);
+```
+
+To use PKCS#1 v1.5 padding, instead of
+
+```C
+ mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, <ignored>);
+```
+
+just use
+
+```C
+ mbedtls_rsa_init(ctx);
+```
+
+
+## High-level crypto
+
+Please also refer to the section [Low-level crypto](#low-level-crypto) for
+changes that could sit in either category.
+
+### Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations
+
+This only affects people who use the cipher module to perform AEAD operations
+using the multi-part API.
+
+Previously, the documentation didn't state explicitly if it was OK to call
+`mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after
+the last call to `mbedtls_cipher_update()` — that is, without calling
+`mbedtls_cipher_finish()` in-between. If you code was missing that call,
+please add it and be prepared to get as much as 15 bytes of output.
+
+Currently the output is always 0 bytes, but it may be more when alternative
+implementations of the underlying primitives are in use, or with future
+versions of the library.
+
+### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms
+
+This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms.
+
+They are already niche or obsolete and most of them are weak or broken. For
+those reasons possible users should consider switching to modern and safe
+alternatives to be found in literature.
+
+### Deprecated functions were removed from cipher
+
+The functions `mbedtls_cipher_auth_encrypt()` and
+`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by
+`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()`
+respectively which additionally support key wrapping algorithms such as
+NIST_KW.
+
+### Extra parameter for the output buffer size
+
+The following functions now take an extra parameter indicating the size of the output buffer:
+
+* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()`
+* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()`
+
+The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer.
+
+### Signature functions now require the hash length to match the expected value
+
+This 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.
+
+All the functions in the RSA module that accept a `hashlen` parameter used to
+ignore it unless the `md_alg` parameter was `MBEDTLS_MD_NONE`, indicating raw
+data was signed. The `hashlen` parameter is now always the size that is read
+from the `hash` input buffer. This length must be equal to the output size of
+the hash algorithm used when signing a hash. (The requirements when signing
+raw data are unchanged.) This affects the following functions:
+
+* `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_pkcs1_verify`
+* `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_verify`
+* `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_verify`
+* `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify_ext`
+
+The 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:
+
+* `mbedtls_pk_sign`, `mbedtls_pk_verify`
+* `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable`
+* `mbedtls_pk_verify_ext`
+
+The migration path is to pass the correct value to those functions.
+
+### Some function parameters were made const
+
+Various functions in the PK and ASN.1 modules had a `const` qualifier added to
+some of their parameters.
+
+This normally doesn't affect your code, unless you use pointers to reference
+those functions. In this case, you'll need to update the type of your pointers
+in order to match the new signature.
+
+### The RNG parameter is now mandatory for all functions that accept one
+
+This change affects all users who called a function accepting a `f_rng`
+parameter with `NULL` as the value of this argument; this is no longer
+supported.
+
+The changed functions are: the X.509 CRT and CSR writing functions; the PK and
+RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM
+and ECDH that compute the shared secret; the scalar multiplication functions in
+ECP.
+
+You now need to pass a properly seeded, cryptographically secure RNG to all
+functions that accept a `f_rng` parameter. It is of course still possible to
+pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a
+context.
+
+Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT`
+configuration options) may have their own internal and are free to ignore the
+`f_rng` argument but must allow users to pass one anyway.
+
+### Some functions gained an RNG parameter
+
+This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`,
+`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and
+`mbedtls_pk_parse_keyfile()`.
+
+You now need to pass a properly seeded, cryptographically secure RNG when
+calling these functions. It is used for blinding, a countermeasure against
+side-channel attacks.
+
+
+## PSA
+
+### Deprecated names for PSA constants and types were removed
+
+Some constants and types that were present in beta versions of the PSA Crypto
+API were removed from version 1.0 of specification. Please switch to the new
+names provided by the 1.0 specification instead.
+
+
+## Changes that only affect alternative implementations
+
+### Internal / alt-focused headers were moved to a private location
+
+This shouldn't affect users who took care not to include headers that
+were documented as internal, despite being in the public include directory.
+
+If you're providing alt implementations of ECP or RSA, you'll need to add our
+`library` directory to your include path when building your alt
+implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been
+renamed to `ecp_internal_alt.h` and `rsa_alt_helpers.h` respectively.
+
+If you're a library user and used to rely on having access to a structure or
+function that's now in a private header, please reach out on the mailing list
+and explain your need; we'll consider adding a new API in a future version.
+
+### CCM interface changes: impact for alternative implementations
+
+The CCM interface has changed with the addition of support for
+multi-part operations. Five new API functions have been defined:
+ `mbedtls_ccm_starts()`, `mbedtls_ccm_set_lengths()`,
+ `mbedtls_ccm_update_ad()`, `mbedtls_ccm_update()` and `mbedtls_ccm_finish()`.
+Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to
+implement those additional five API functions.
+
+
+## X.509
+
+### Remove the certs module from the library
+
+This should not affect production use of the library, as the certificates and
+keys included there were never suitable for production use.
+
+However it might affect you if you relied on them for testing purposes. In
+that case, please embed your own test certificates in your test code; now that
+`certs.c` is out of the library there is no longer any stability guaranteed
+and it may change in incompatible ways at any time.
+
+### Change the API to allow adding critical extensions to CSRs
+
+This affects applications that call the `mbedtls_x509write_csr_set_extension`
+function.
+
+The API is changed to include the parameter `critical` which enables marking an
+extension included in a CSR as critical. To get the previous behavior pass 0.
+
+### Remove the config option `MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION`
+
+This change does not affect users of the default configuration; it only affects
+users who enable this option.
+
+The X.509 standard says that implementations must reject critical extensions that
+they don't recognize, and this is what Mbed TLS does by default. This option
+allowed to continue parsing those certificates but didn't provide a convenient
+way to handle those extensions.
+
+The migration path from that option is to use the
+`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally
+equivalent to `mbedtls_x509_crt_parse_der()`, and/or
+`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every
+unsupported certificate extension and additionally the "certificate policies"
+extension if it contains any unsupported certificate policies.
+
+### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h`
+
+This change affects users who have chosen the configuration options to disable the
+library's verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
+certificates.
+
+The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE`
+configuration options are removed and the X.509 code now behaves as if they were
+always enabled. It is consequently not possible anymore to disable at compile
+time the verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
+certificates.
+
+The verification of the `keyUsage` and `extendedKeyUsage` fields is important,
+disabling it can cause security issues and it is thus not recommended. If the
+verification is for some reason undesirable, it can still be disabled by means
+of the verification callback function passed to `mbedtls_x509_crt_verify()` (see
+the documentation of this function for more information).
+
+### Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option
+
+This change does not affect users who were using the default configuration, as
+this option was already disabled by default. Also, it does not affect users who
+are working with current V3 X.509 certificates.
+
+Extensions were added in V3 of the X.509 specification, so pre-V3 certificates
+containing extensions were never compliant. Mbed TLS now rejects them with a
+parsing error in all configurations, as it did previously in the default
+configuration.
+
+If you are working with the pre-V3 certificates you need to switch to the
+current ones.
+
+### Strengthen default algorithm selection for X.509
+
+This is described in the section [Strengthen default algorithm selection for X.509 and TLS](#strengthen-default-algorithm-selection-for-x.509-and-tls).
+
+### Remove wrapper for libpkcs11-helper
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+If you used to rely on this module in order to store your private keys
+securely, please have a look at the key management facilities provided by the
+PSA crypto API. If you have a use case that's not covered yet by this API,
+please reach out on the mailing list.
+
+
+## SSL
+
+### Remove support for TLS 1.0, 1.1 and DTLS 1.0
+
+This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols.
+
+These versions have been deprecated by RFC 8996.
+Keeping them in the library creates opportunities for misconfiguration
+and possibly downgrade attacks. More generally, more code means a larger attack
+surface, even if the code is supposedly not used.
+
+The migration path is to adopt the latest versions of the protocol.
+
+As a consequence of removing TLS 1.0, support for CBC record splitting was
+also removed, as it was a work-around for a weakness in this particular
+version. There is no migration path since the feature is no longer relevant.
+
+As a consequence of currently supporting only one version of (D)TLS (and in the
+future 1.3 which will have a different version negotiation mechanism), support
+for fallback SCSV (RFC 7507) was also removed. There is no migration path as
+it's no longer useful with TLS 1.2 and later.
+
+As a consequence of currently supporting only one version of (D)TLS (and in the
+future 1.3 which will have a different concept of ciphersuites), support for
+configuring ciphersuites separately for each version via
+`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use
+`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS
+1.2; in the future a different API will be added for (D)TLS 1.3.
+
+### Remove support for SSL 3.0
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3`
+and relied on that version in order to communicate with peers that are not up
+to date. If one of your peers is in that case, please try contacting them and
+encouraging them to upgrade their software.
+
+### Remove support for parsing SSLv2 ClientHello
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS servers that have clients who send an SSLv2 ClientHello.
+These days clients are very unlikely to do that. If you have a client that
+does, please try contacting them and encouraging them to upgrade their
+software.
+
+### Remove support for truncated HMAC
+
+This affects users of truncated HMAC, that is, users who called
+`mbedtls_ssl_conf_truncated_hmac( ..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED)`,
+regardless of whether the standard version was used or compatibility version
+(`MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT`).
+
+The recommended migration path for people who want minimal overhead is to use a
+CCM-8 ciphersuite.
+
+### Remove support for TLS record-level compression
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS users who enabled `MBEDTLS_ZLIB_SUPPORT`. This will not
+cause any failures however if you used to enable TLS record-level compression
+you may find that your bandwidth usage increases without compression. There's
+no general solution to this problem; application protocols might have their
+own compression mechanisms and are in a better position than the TLS stack to
+avoid variants of the CRIME and BREACH attacks.
+
+### Remove support for TLS RC4-based ciphersuites
+
+This does not affect people who used the default `mbedtls_config.h` and the default
+list of ciphersuites, as RC4-based ciphersuites were already not negotiated in
+that case.
+
+Please switch to any of the modern, recommended ciphersuites (based on
+AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support
+any, encourage them to upgrade their software.
+
+### Remove support for TLS single-DES ciphersuites
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+Please switch to any of the modern, recommended ciphersuites (based on
+AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support
+any, encourage them to upgrade their software.
+
+### Remove support for TLS record-level hardware acceleration
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This feature had been broken for a while so we doubt anyone still used it.
+However if you did, please reach out on the mailing list and let us know about
+your use case.
+
+### Remove config option `MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME`
+
+This doesn't affect people using the default configuration.
+
+This option has not had any effect for a long time. Please use the `lifetime`
+parameter of `mbedtls_ssl_ticket_setup()` instead.
+
+### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options
+
+This change affects users who modified the default `mbedtls_config.h` padding granularity
+settings, i.e. enabled at least one of the options.
+
+The `mbedtls_config.h` options `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and
+`MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` were combined into one option because
+they used exactly the same padding mechanism and hence their respective padding
+granularities can be used in exactly the same way. This change simplifies the
+code maintenance.
+
+The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used
+for both DTLS-CID and TLS 1.3.
+
+### TLS now favors faster curves over larger curves
+
+The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves.
+
+If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection.
+
+### SSL key export interface change
+
+This affects users of the SSL key export APIs:
+```
+ mbedtls_ssl_conf_export_keys_cb()
+ mbedtls_ssl_conf_export_keys_ext_cb()
+```
+
+Those APIs have been removed and replaced by the new API
+`mbedtls_ssl_set_export_keys_cb()`. This API differs from
+the previous key export API in the following ways:
+
+- It is no longer bound to an SSL configuration, but to an
+ SSL context. This allows users to more easily identify the
+ connection an exported key belongs to.
+- It no longer exports raw keys and IV.
+- A secret type parameter has been added to identify which key
+ is being exported. For TLS 1.2, only the master secret is
+ exported, but upcoming TLS 1.3 support will add other kinds of keys.
+- The callback now specifies a void return type, rather than
+ returning an error code. It is the responsibility of the application
+ to handle failures in the key export callback, for example by
+ shutting down the TLS connection.
+
+For users which do not rely on raw keys and IV, adjusting to the new
+callback type should be straightforward — see the example programs
+`programs/ssl/ssl_client2` and `programs/ssl/ssl_server2` for callbacks
+for NSSKeylog, EAP-TLS and DTLS-SRTP.
+
+Users which require access to the raw keys used to secure application
+traffic may derive those by hand based on the master secret and the
+handshake transcript hashes which can be obtained from the raw data
+on the wire. Such users are also encouraged to reach out to the
+Mbed TLS team on the mailing list, to let the team know about their
+use case.
+
+### Remove MaximumFragmentLength (MFL) query API
+
+This affects users which use the MFL query APIs
+`mbedtls_ssl_get_{input,output}_max_frag_len()` to
+infer upper bounds on the plaintext size of incoming and
+outgoing record.
+
+Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()`
+instead, which also provides such upper bounds but takes more factors
+than just the MFL configuration into account.
+
+### Relaxed semantics for PSK configuration
+
+This affects users which call the PSK configuration APIs
+`mbedtls_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()`
+multiple times on the same SSL configuration.
+
+In Mbed TLS 2.x, users would observe later calls overwriting
+the effect of earlier calls, with the prevailing PSK being
+the one that has been configured last. In Mbed TLS 3.0,
+calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times
+will return an error, leaving the first PSK intact.
+
+To achieve equivalent functionality when migrating to Mbed TLS 3.0,
+users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should
+remove all but the last call, so that only one call to _either_
+`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()`
+remains.
+
+### Remove the configuration to enable weak ciphersuites in SSL / TLS
+
+This does not affect users who use the default `mbedtls_config.h`, as this option was
+already off by default.
+
+If you were using a weak cipher, please switch to any of the modern,
+recommended ciphersuites (based on AES-GCM, AES-CCM or ChachaPoly for example)
+and if your peer doesn't support any, encourage them to upgrade their software.
+
+If you were using a ciphersuite without encryption, you just have to
+enable `MBEDTLS_CIPHER_NULL_CIPHER` now.
+
+### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option
+
+This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to
+set the maximum length of incoming and outgoing plaintext fragments,
+which can save memory by reducing the size of the TLS I/O buffers.
+
+This option is replaced by the more fine-grained options
+`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set
+the maximum incoming and outgoing plaintext fragment lengths, respectively.
+
+### Remove the SSL API `mbedtls_ssl_get_session_pointer()`
+
+This affects two classes of users:
+
+1. Users who manually inspect parts of the current session through
+ direct structure field access.
+
+2. Users of session resumption who query the current session
+ via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting
+ it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`,
+ respectively.
+
+Migration paths:
+
+1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many
+ other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no
+ longer part of the public API in Mbed TLS 3.0, and direct structure field
+ access is no longer supported. Please see the [section on private structure fields](#most-structure-fields-are-now-private) for more details.
+
+2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by
+ calls to `mbedtls_ssl_get_session()` as demonstrated in the example
+ program `programs/ssl/ssl_client2.c`.
+
+### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option
+
+This change does not affect users who used the default `mbedtls_config.h`, as the option
+`MBEDTLS_SSL_DTLS_BADMAC_LIMIT` was already on by default.
+
+This option was a trade-off between functionality and code size: it allowed
+users who didn't need that feature to avoid paying the cost in code size, by
+disabling it.
+
+This option is no longer present, but its functionality is now always enabled.
+
+### Deprecated functions were removed from SSL
+
+The function `mbedtls_ssl_conf_dh_param()` was removed. Please use
+`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead.
+
+The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use
+`mbedtls_ssl_get_max_out_record_payload()` and
+`mbedtls_ssl_get_max_in_record_payload()`
+instead.
+
+### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default
+
+This change does not affect users who use the default `mbedtls_config.h`, as the
+option `MBEDTLS_SSL_RECORD_CHECKING` was already on by default.
+
+This option was added only to control compilation of one function,
+ `mbedtls_ssl_check_record()`, which is only useful in some specific cases, so it
+was made optional to allow users who don't need it to save some code space.
+However, the same effect can be achieved by using link-time garbage collection.
+
+Users who changed the default setting of the option need to change the config/
+build system to remove that change.
+
+### Session Cache API Change
+
+This affects users who use `mbedtls_ssl_conf_session_cache()`
+to configure a custom session cache implementation different
+from the one Mbed TLS implements in `library/ssl_cache.c`.
+
+Those users will need to modify the API of their session cache
+implementation to that of a key-value store with keys being
+session IDs and values being instances of `mbedtls_ssl_session`:
+
+```C
+typedef int mbedtls_ssl_cache_get_t( void *data,
+ unsigned char const *session_id,
+ size_t session_id_len,
+ mbedtls_ssl_session *session );
+typedef int mbedtls_ssl_cache_set_t( void *data,
+ unsigned char const *session_id,
+ size_t session_id_len,
+ const mbedtls_ssl_session *session );
+```
+
+Since the structure of `mbedtls_ssl_session` is no longer public from 3.0
+onwards, portable session cache implementations must not access fields of
+`mbedtls_ssl_session`. See the corresponding migration guide. Users that
+find themselves unable to migrate their session cache functionality without
+accessing fields of `mbedtls_ssl_session` should describe their use case
+on the Mbed TLS mailing list.
+
+### Changes in the SSL error code space
+
+This affects users manually checking for the following error codes:
+
+- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED`
+- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH`
+- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE`
+- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN`
+- `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE`
+- `MBEDTLS_ERR_SSL_BAD_HS_XXX`
+
+Migration paths:
+- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and
+ `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate
+ is too large to fit into the output buffers.
+
+ Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially
+ compare the size of their own certificate against the configured size of the output buffer to
+ understand if the error is due to an overly large certificate.
+
+- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been
+ replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`.
+
+- 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.
+
+ Users should check for the newly introduced generic error codes
+
+ * `MBEDTLS_ERR_SSL_DECODE_ERROR`
+ * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`,
+ * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`
+ * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION`
+ * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE`
+ * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME`
+ * `MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION`
+ * `MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL`
+
+ and the pre-existing generic error codes
+
+ * `MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE`
+ * `MBEDTLS_ERR_SSL_INTERNAL_ERROR`
+
+ instead.
+
+### Modified semantics of `mbedtls_ssl_{get,set}_session()`
+
+This affects users who call `mbedtls_ssl_get_session()` or
+`mbedtls_ssl_set_session()` multiple times on the same SSL context
+representing an established TLS 1.2 connection.
+Those users will now observe the second call to fail with
+`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`.
+
+Migration path:
+- Exporting the same TLS 1.2 connection multiple times via
+ `mbedtls_ssl_get_session()` leads to multiple copies of
+ the same session. This use of `mbedtls_ssl_get_session()`
+ is discouraged, and the following should be considered:
+ * If the various session copies are later loaded into
+ fresh SSL contexts via `mbedtls_ssl_set_session()`,
+ export via `mbedtls_ssl_get_session()` only once and
+ load the same session into different contexts via
+ `mbedtls_ssl_set_session()`. Since `mbedtls_ssl_set_session()`
+ makes a copy of the session that's being loaded, this
+ is functionally equivalent.
+ * If the various session copies are later serialized
+ via `mbedtls_ssl_session_save()`, export and serialize
+ the session only once via `mbedtls_ssl_get_session()` and
+ `mbedtls_ssl_session_save()` and make copies of the raw
+ data instead.
+- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x
+ is not useful since subsequent calls overwrite the effect of previous
+ calls. Applications achieve equivalent functional behavior by
+ issuing only the very last call to `mbedtls_ssl_set_session()`.
+
+### Turn `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` configuration option into a runtime option
+
+This change affects users who were enabling `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE`
+option in the `mbedtls_config.h`
+
+This option has been removed and a new function with similar functionality has
+been introduced into the SSL API.
+
+This new function `mbedtls_ssl_conf_preference_order()` can be used to
+change the preferred order of ciphersuites on the server to those used on the client,
+e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)`
+has the same effect as enabling the removed option. The default state is to use
+the server order of suites.
+
+### Strengthen default algorithm selection for X.509 and TLS
+
+The 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.
+
+Hashes 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.
+
+The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available.
+
+The 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.
+
+If 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:
+```C
+mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default;
+my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 );
+```
+
+If 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.
+
+### Remove 3DES ciphersuites
+
+This change does not affect users using default settings for 3DES in `mbedtls_config.h`
+because the 3DES ciphersuites were disabled by that.
+
+3DES has weaknesses/limitations and there are better alternatives, and more and
+more standard bodies are recommending against its use in TLS.
+
+The migration path here is to chose from the alternatives recommended in the
+literature, such as AES.
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..47510f9
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,40 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help clean apidoc breathe_apidoc Makefile
+
+# Intercept the 'clean' target so we can do the right thing for apidoc as well
+clean:
+ @# Clean the apidoc
+ $(MAKE) -C .. apidoc_clean
+ @# Clean the breathe-apidoc generated files
+ rm -rf ./api
+ @# Clean the sphinx docs
+ @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+apidoc:
+ @# Generate doxygen from source using the main Makefile
+ $(MAKE) -C .. apidoc
+
+breathe_apidoc: apidoc
+ @# Remove existing files - breathe-apidoc skips them if they're present
+ rm -rf ./api
+ @# Generate RST file structure with breathe-apidoc
+ breathe-apidoc -o ./api ../apidoc/xml
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile breathe_apidoc
+ @# Build the relevant target with sphinx
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/architecture/Makefile b/docs/architecture/Makefile
new file mode 100644
index 0000000..5bee504
--- /dev/null
+++ b/docs/architecture/Makefile
@@ -0,0 +1,21 @@
+PANDOC = pandoc
+
+default: all
+
+all_markdown = $(wildcard *.md */*.md)
+
+html: $(all_markdown:.md=.html)
+pdf: $(all_markdown:.md=.pdf)
+all: html pdf
+
+.SUFFIXES:
+.SUFFIXES: .md .html .pdf
+
+.md.html:
+ $(PANDOC) -o $@ $<
+.md.pdf:
+ $(PANDOC) -o $@ $<
+
+clean:
+ rm -f *.html *.pdf
+ rm -f testing/*.html testing/*.pdf
diff --git a/docs/architecture/alternative-implementations.md b/docs/architecture/alternative-implementations.md
new file mode 100644
index 0000000..eacdea7
--- /dev/null
+++ b/docs/architecture/alternative-implementations.md
@@ -0,0 +1,91 @@
+Alternative implementations of Mbed TLS functionality
+=====================================================
+
+This document describes how parts of the Mbed TLS functionality can be replaced at compile time to integrate the library on a platform.
+
+This document is an overview. It is not exhaustive. Please consult the documentation of individual modules and read the library header files for more details.
+
+## Platform integration
+
+Mbed TLS works out of the box on Unix/Linux/POSIX-like systems and on Windows. On embedded platforms, you may need to customize some aspects of how Mbed TLS interacts with the underlying platform. This section discusses the main areas that can be configured.
+
+The platform module (`include/mbedtls/platform.h`) controls how Mbed TLS accesses standard library features such as memory management (`calloc`, `free`), `printf`, `exit`. You can define custom functions instead of the ones from the C standard library through `MBEDTLS_PLATFORM_XXX` options in the configuration file. Many options have two mechanisms: either define `MBEDTLS_PLATFORM_XXX_MACRO` to the name of a function to call instead of the standard function `xxx`, or define `MBEDTLS_PLATFORM_XXX_ALT` and [register an alternative implementation during the platform setup](#alternative-implementations-of-platform-functions).
+
+The storage of the non-volatile seed for random generation, enabled with `MBEDTLS_ENTROPY_NV_SEED`, is also controlled via the platform module.
+
+For timing functions, you can [declare an alternative implementation of the timing module](#module-alternative-implementations).
+
+On multithreaded platforms, [declare an alternative implementation of the threading module](#module-alternative-implementations).
+
+To configure entropy sources (hardware random generators), see the `MBEDTLS_ENTROPY_XXX` options in the configuration file.
+
+For networking, the `net_sockets` module does not currently support alternative implementations. If this module does not work on your platform, disable `MBEDTLS_NET_C` and use custom functions for TLS.
+
+If your platform has a cryptographic accelerator, you can use it via a [PSA driver](#psa-cryptography-drivers) or declare an [alternative implementation of the corresponding module(s)](#module-alternative-implementations) or [of specific functions](#function-alternative-implementations). PSA drivers will ultimately replace the alternative implementation mechanism, but alternative implementation will remain supported in at least all Mbed TLS versions of the form 3.x. The interface of PSA drivers is currently still experimental and subject to change.
+
+## PSA cryptography drivers
+
+On platforms where a hardware cryptographic engine is present, you can implement a driver for this engine in the PSA interface. Drivers are supported for cryptographic operations with transparent keys (keys available in cleartext), for cryptographic operations with opaque keys (keys that are only available inside the cryptographic engine), and for random generation. Calls to `psa_xxx` functions that perform cryptographic operations are directed to drivers instead of the built-in code as applicable. See the [PSA cryptography driver interface specification](docs/proposed/psa-driver-interface.md), the [Mbed TLS PSA driver developer guide](docs/proposed/psa-driver-developer-guide.md) and the [Mbed TLS PSA driver integration guide](docs/proposed/psa-driver-integration-guide.md) for more information.
+
+As of Mbed TLS 3.0, this interface is still experimental and subject to change, and not all operations support drivers yet. The configuration option `MBEDTLS_USE_PSA_CRYPTO` causes parts of the `mbedtls_xxx` API to use PSA crypto and therefore to support drivers, however it is not yet compatible with all drivers.
+
+## Module alternative implementations
+
+You can replace the code of some modules of Mbed TLS at compile time by a custom implementation. This is possible for low-level cryptography modules (symmetric algorithms, DHM, RSA, ECP, ECJPAKE) and for some platform-related modules (threading, timing). Such custom implementations are called “alternative implementations”, or “ALT implementations” for short.
+
+The general principle of an alternative implementation is:
+* Enable `MBEDTLS_XXX_ALT` in the compile-time configuration where XXX is the module name. For example, `MBEDTLS_AES_ALT` for an implementation of the AES module. This is in addition to enabling `MBEDTLS_XXX_C`.
+* Create a header file `xxx_alt.h` that defines the context type(s) used by the module. For example, `mbedtls_aes_context` for AES.
+* Implement all the functions from the module, i.e. the functions declared in `include/mbedtls/xxx.h`.
+
+See https://mbed-tls.readthedocs.io/en/latest/kb/development/hw_acc_guidelines for a more detailed guide.
+
+### Constraints on context types
+
+Generally, alternative implementations can define their context types to any C type except incomplete and array types (although they would normally be `struct` types). This section lists some known limitations where the context type needs to be a structure with certain fields.
+
+Where a context type needs to have a certain field, the field must have the same type and semantics as in the built-in implementation, but does not need to be at the same position in the structure. Furthermore, unless otherwise indicated, only read access is necessary: the field can be `const`, and modifications to it do not need to be supported. For example, if an alternative implementation of asymmetric cryptography uses a different representation of large integers, it is sufficient to provide a read-only copy of the fields listed here of type `mbedtls_mpi`.
+
+* AES: if `MBEDTLS_AESNI_C` or `MBEDTLS_PADLOCK_C` is enabled, `mbedtls_aes_context` must have the fields `nr` and `rk`.
+* DHM: if `MBEDTLS_DEBUG_C` is enabled, `mbedtls_dhm_context` must have the fields `P`, `Q`, `G`, `GX`, `GY` and `K`.
+* ECP: `mbedtls_ecp_group` must have the fields `id`, `P`, `A`, `B`, `G`, `N`, `pbits` and `nbits`.
+ * If `MBEDTLS_PK_PARSE_EC_EXTENDED` is enabled, those fields must be writable, and `mbedtls_ecp_point_read_binary()` must support a group structure where only `P`, `pbits`, `A` and `B` are set.
+
+It must be possible to move a context object in memory (except during the execution of a library function that takes this context as an argument). (This is necessary, for example, to support applications that populate a context on the stack of an inner function and then copy the context upwards through the call chain, or applications written in a language with automatic memory management that can move objects on the heap.) That is, call sequences like the following must work:
+```
+mbedtls_xxx_context ctx1, ctx2;
+mbedtls_xxx_init(&ctx1);
+mbedtls_xxx_setup(&ctx1, …);
+ctx2 = ctx1;
+memset(&ctx1, 0, sizeof(ctx1));
+mbedtls_xxx_do_stuff(&ctx2, …);
+mbedtls_xxx_free(&ctx2);
+```
+In practice, this means that a pointer to a context or to a part of a context does not remain valid across function calls. Alternative implementations do not need to support copying of contexts: contexts can only be cloned through explicit `clone()` functions.
+
+## Function alternative implementations
+
+In some cases, it is possible to replace a single function or a small set of functions instead of [providing an alternative implementation of the whole module](#module-alternative-implementations).
+
+### Alternative implementations of cryptographic functions
+
+Options to replace individual functions of cryptographic modules generally have a name obtained by upper-casing the function name and appending `_ALT`. If the function name contains `_internal`, `_ext` or `_ret`, this is removed in the `_ALT` symbol. When the corresponding option is enabled, the built-in implementation of the function will not be compiled, and you must provide an alternative implementation at link time.
+
+For example, enable `MBEDTLS_AES_ENCRYPT_ALT` at compile time and provide your own implementation of `mbedtls_aes_encrypt()` to provide an accelerated implementation of AES encryption that is compatible with the built-in key schedule. If you wish to implement key schedule differently, you can also enable `MBEDTLS_AES_SETKEY_ENC_ALT` and implement `mbedtls_aes_setkey_enc()`.
+
+Another example: enable `MBEDTLS_SHA256_PROCESS_ALT` and implement `mbedtls_internal_sha256_process()` to provide an accelerated implementation of SHA-256 and SHA-224.
+
+Note that since alternative implementations of individual functions cooperate with the built-in implementation of other functions, you must use the same layout for context objects as the built-in implementation. If you want to use different context types, you need to [provide an alternative implementation of the whole module](#module-alternative-implementations).
+
+### Alternative implementations of platform functions
+
+Several platform functions can be reconfigured dynamically by following the process described here. To reconfigure how Mbed TLS calls the standard library function `xxx()`:
+
+* Define the symbol `MBEDTLS_PLATFORM_XXX_ALT` at compile time.
+* During the initialization of your application, set the global variable `mbedtls_xxx` to an alternative implementation of `xxx()`.
+
+For example, to provide a custom `printf` function at run time, enable `MBEDTLS_PLATFORM_PRINTF_ALT` at compile time and assign to `mbedtls_printf` during the initialization of your application.
+
+Merely enabling `MBEDTLS_PLATFORM_XXX_ALT` does not change the behavior: by default, `mbedtls_xxx` points to the standard function `xxx`.
+
+Note that there are variations on the naming pattern. For example, some configurable functions are activated in pairs, such as `mbedtls_calloc` and `mbedtls_free` via `MBEDTLS_PLATFORM_MEMORY`. Consult the documentation of individual configuration options and of the platform module for details.
diff --git a/docs/architecture/mbed-crypto-storage-specification.md b/docs/architecture/mbed-crypto-storage-specification.md
new file mode 100644
index 0000000..3c8370d
--- /dev/null
+++ b/docs/architecture/mbed-crypto-storage-specification.md
@@ -0,0 +1,467 @@
+Mbed TLS storage specification
+=================================
+
+This document specifies how Mbed TLS uses storage.
+Key storage was originally introduced in a product called Mbed Crypto, which was re-distributed via Mbed TLS and has since been merged into Mbed TLS.
+This document contains historical information both from before and after this merge.
+
+Mbed Crypto may be upgraded on an existing device with the storage preserved. Therefore:
+
+1. Any change may break existing installations and may require an upgrade path.
+1. This document retains historical information about all past released versions. Do not remove information from this document unless it has always been incorrect or it is about a version that you are sure was never released.
+
+Mbed Crypto 0.1.0
+-----------------
+
+Tags: mbedcrypto-0.1.0b, mbedcrypto-0.1.0b2
+
+Released in November 2018. <br>
+Integrated in Mbed OS 5.11.
+
+Supported backends:
+
+* [PSA ITS](#file-namespace-on-its-for-0.1.0)
+* [C stdio](#file-namespace-on-stdio-for-0.1.0)
+
+Supported features:
+
+* [Persistent transparent keys](#key-file-format-for-0.1.0) designated by a [slot number](#key-names-for-0.1.0).
+* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0) on ITS only.
+
+This is a beta release, and we do not promise backward compatibility, with one exception:
+
+> On Mbed OS, if a device has a nonvolatile random seed file produced with Mbed OS 5.11.x and is upgraded to a later version of Mbed OS, the nonvolatile random seed file is preserved or upgraded.
+
+We do not make any promises regarding key storage, or regarding the nonvolatile random seed file on other platforms.
+
+### Key names for 0.1.0
+
+Information about each key is stored in a dedicated file whose name is constructed from the key identifier. The way in which the file name is constructed depends on the storage backend. The content of the file is described [below](#key-file-format-for-0.1.0).
+
+The valid values for a key identifier are the range from 1 to 0xfffeffff. This limitation on the range is not documented in user-facing documentation: according to the user-facing documentation, arbitrary 32-bit values are valid.
+
+The code uses the following constant in an internal header (note that despite the name, this value is actually one plus the maximum permitted value):
+
+ #define PSA_MAX_PERSISTENT_KEY_IDENTIFIER 0xffff0000
+
+There is a shared namespace for all callers.
+
+### Key file format for 0.1.0
+
+All integers are encoded in little-endian order in 8-bit bytes.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`
+* version (4 bytes): 0
+* type (4 bytes): `psa_key_type_t` value
+* policy usage flags (4 bytes): `psa_key_usage_t` value
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value
+* key material length (4 bytes)
+* key material: output of `psa_export_key`
+* Any trailing data is rejected on load.
+
+### Nonvolatile random seed file format for 0.1.0
+
+The nonvolatile random seed file contains a seed for the random generator. If present, it is rewritten at each boot as part of the random generator initialization.
+
+The file format is just the seed as a byte string with no metadata or encoding of any kind.
+
+### File namespace on ITS for 0.1.0
+
+Assumption: ITS provides a 32-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+* File 0: unused.
+* Files 1 through 0xfffeffff: [content](#key-file-format-for-0.1.0) of the [key whose identifier is the file identifier](#key-names-for-0.1.0).
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0).
+* Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff: unused.
+
+### File namespace on stdio for 0.1.0
+
+Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
+
+An undocumented build-time configuration value `CRYPTO_STORAGE_FILE_LOCATION` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
+
+* `CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_0"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
+* `sprintf(CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_%lu", key_id)` [content](#key-file-format-for-0.1.0) of the [key whose identifier](#key-names-for-0.1.0) is `key_id`.
+* Other files: unused.
+
+Mbed Crypto 1.0.0
+-----------------
+
+Tags: mbedcrypto-1.0.0d4, mbedcrypto-1.0.0
+
+Released in February 2019. <br>
+Integrated in Mbed OS 5.12.
+
+Supported integrations:
+
+* [PSA platform](#file-namespace-on-a-psa-platform-for-1.0.0)
+* [library using PSA ITS](#file-namespace-on-its-as-a-library-for-1.0.0)
+* [library using C stdio](#file-namespace-on-stdio-for-1.0.0)
+
+Supported features:
+
+* [Persistent transparent keys](#key-file-format-for-1.0.0) designated by a [key identifier and owner](#key-names-for-1.0.0).
+* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0) on ITS only.
+
+Backward compatibility commitments: TBD
+
+### Key names for 1.0.0
+
+Information about each key is stored in a dedicated file designated by the key identifier. In integrations where there is no concept of key owner (in particular, in library integrations), the key identifier is exactly the key identifier as defined in the PSA Cryptography API specification (`psa_key_id_t`). In integrations where there is a concept of key owner (integration into a service for example), the key identifier is made of an owner identifier (its semantics and type are integration specific) and of the key identifier (`psa_key_id_t`) from the key owner point of view.
+
+The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-1.0.0).
+
+* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value.
+* PSA service integration: the key file name is `(uint64_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
+
+### Key file format for 1.0.0
+
+The layout is identical to [0.1.0](#key-file-format-for-0.1.0) so far. However note that the encoding of key types, algorithms and key material has changed, therefore the storage format is not compatible (despite using the same value in the version field so far).
+
+### Nonvolatile random seed file format for 1.0.0
+
+The nonvolatile random seed file contains a seed for the random generator. If present, it is rewritten at each boot as part of the random generator initialization.
+
+The file format is just the seed as a byte string with no metadata or encoding of any kind.
+
+This is unchanged since [the feature was introduced in Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
+
+### File namespace on a PSA platform for 1.0.0
+
+Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+Assumption: the owner identifier is a nonzero value of type `int32_t`.
+
+* Files 0 through 0xffffff51, 0xffffff53 through 0xffffffff: unused, reserved for internal use of the crypto library or crypto service.
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0).
+* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). The upper 32 bits determine the owner.
+
+### File namespace on ITS as a library for 1.0.0
+
+Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
+
+* File 0: unused.
+* Files 1 through 0xfffeffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0).
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0).
+* Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff, 0x100000000 through 0xffffffffffffffff: unused.
+
+### File namespace on stdio for 1.0.0
+
+This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
+
+[Identical to 0.1.0](#file-namespace-on-stdio-for-0.1.0).
+
+### Upgrade from 0.1.0 to 1.0.0.
+
+* Delete files 1 through 0xfffeffff, which contain keys in a format that is no longer supported.
+
+### Suggested changes to make before 1.0.0
+
+The library integration and the PSA platform integration use different sets of file names. This is annoyingly non-uniform. For example, if we want to store non-key files, we have room in different ranges (0 through 0xffffffff on a PSA platform, 0xffff0000 through 0xffffffffffffffff in a library integration).
+
+It would simplify things to always have a 32-bit owner, with a nonzero value, and thus reserve the range 0–0xffffffff for internal library use.
+
+Mbed Crypto 1.1.0
+-----------------
+
+Tags: mbedcrypto-1.1.0
+
+Released in early June 2019. <br>
+Integrated in Mbed OS 5.13.
+
+Changes since [1.0.0](#mbed-crypto-1.0.0):
+
+* The stdio backend for storage has been replaced by an implementation of [PSA ITS over stdio](#file-namespace-on-stdio-for-1.1.0).
+* [Some changes in the key file format](#key-file-format-for-1.1.0).
+
+### File namespace on stdio for 1.1.0
+
+Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
+
+An undocumented build-time configuration value `PSA_ITS_STORAGE_PREFIX` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
+
+* `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
+* `sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)`: a key or non-key file. The `key_id` in the name is the 64-bit file identifier, which is the [key identifier](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a non-key file (currently: only the [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0)). The contents of the file are:
+ * Magic header (8 bytes): `"PSA\0ITS\0"`
+ * File contents.
+
+### Key file format for 1.1.0
+
+The key file format is identical to [1.0.0](#key-file-format-for-1.0.0), except for the following changes:
+
+* A new policy field, marked as [NEW:1.1.0] below.
+* The encoding of key types, algorithms and key material has changed, therefore the storage format is not compatible (despite using the same value in the version field so far).
+
+A self-contained description of the file layout follows.
+
+All integers are encoded in little-endian order in 8-bit bytes.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`
+* version (4 bytes): 0
+* type (4 bytes): `psa_key_type_t` value
+* policy usage flags (4 bytes): `psa_key_usage_t` value
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value
+* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value [NEW:1.1.0]
+* key material length (4 bytes)
+* key material: output of `psa_export_key`
+* Any trailing data is rejected on load.
+
+Mbed Crypto TBD
+---------------
+
+Tags: TBD
+
+Released in TBD 2019. <br>
+Integrated in Mbed OS TBD.
+
+### Changes introduced in TBD
+
+* The layout of a key file now has a lifetime field before the type field.
+* Key files can store references to keys in a secure element. In such key files, the key material contains the slot number.
+
+### File namespace on a PSA platform on TBD
+
+Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+Assumption: the owner identifier is a nonzero value of type `int32_t`.
+
+* Files 0 through 0xfffeffff: unused.
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd).
+* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). The upper 32 bits determine the owner.
+
+### File namespace on ITS as a library on TBD
+
+Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
+
+* File 0: unused.
+* Files 1 through 0xfffeffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0).
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd).
+* Files 0x100000000 through 0xffffffffffffffff: unused.
+
+### Non-key files on TBD
+
+File identifiers in the range 0xffff0000 through 0xffffffff are reserved for internal use in Mbed Crypto.
+
+* Files 0xfffffe02 through 0xfffffeff (`PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime`): secure element driver storage. The content of the file is the secure element driver's persistent data.
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0).
+* File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-tbd).
+* Other files are unused and reserved for future use.
+
+### Key file format for TBD
+
+All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`.
+* version (4 bytes): 0.
+* lifetime (4 bytes): `psa_key_lifetime_t` value.
+* type (4 bytes): `psa_key_type_t` value.
+* policy usage flags (4 bytes): `psa_key_usage_t` value.
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value.
+* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value.
+* key material length (4 bytes).
+* key material:
+ * For a transparent key: output of `psa_export_key`.
+ * For an opaque key (unified driver interface): driver-specific opaque key blob.
+ * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness.
+* Any trailing data is rejected on load.
+
+### Transaction file format for TBD
+
+The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction.
+
+All integers are encoded in platform endianness.
+
+All currently existing transactions concern a key in a secure element.
+
+The layout of a transaction file is:
+
+* type (2 bytes): the [transaction type](#transaction-types-on-tbd).
+* unused (2 bytes)
+* lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element.
+* slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver.
+* key identifier (4 bytes in a library integration, 8 bytes on a PSA platform): the internal representation of the key identifier. On a PSA platform, this encodes the key owner in the same way as [in file identifiers for key files](#file-namespace-on-a-psa-platform-on-tbd)).
+
+#### Transaction types on TBD
+
+* 0x0001: key creation. The following locations may or may not contain data about the key that is being created:
+ * The slot in the secure element designated by the slot number.
+ * The file containing the key metadata designated by the key identifier.
+ * The driver persistent data.
+* 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed:
+ * The slot in the secure element designated by the slot number.
+ * The file containing the key metadata designated by the key identifier.
+ * The driver persistent data.
+
+Mbed Crypto TBD
+---------------
+
+Tags: TBD
+
+Released in TBD 2020. <br>
+Integrated in Mbed OS TBD.
+
+### Changes introduced in TBD
+
+* The type field has been split into a type and a bits field of 2 bytes each.
+
+### Key file format for TBD
+
+All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`.
+* version (4 bytes): 0.
+* lifetime (4 bytes): `psa_key_lifetime_t` value.
+* type (2 bytes): `psa_key_type_t` value.
+* bits (2 bytes): `psa_key_bits_t` value.
+* policy usage flags (4 bytes): `psa_key_usage_t` value.
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value.
+* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value.
+* key material length (4 bytes).
+* key material:
+ * For a transparent key: output of `psa_export_key`.
+ * For an opaque key (unified driver interface): driver-specific opaque key blob.
+ * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness.
+* Any trailing data is rejected on load.
+
+Mbed TLS 2.25.0
+---------------
+
+Tags: `mbedtls-2.25.0`, `mbedtls-2.26.0`, `mbedtls-2.27.0`, `mbedtls-2.28.0`, `mbedtls-3.0.0`, `mbedtls-3.1.0`
+
+First released in December 2020.
+
+Note: this is the first version that is officially supported. The version number is still 0.
+
+Backward compatibility commitments: we promise backward compatibility for stored keys when Mbed TLS is upgraded from x to y if x >= 2.25 and y < 4. See [`BRANCHES.md`](../../BRANCHES.md) for more details.
+
+Supported integrations:
+
+* [PSA platform](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0)
+* [library using PSA ITS](#file-namespace-on-its-as-a-library-on-mbed-tls-2.25.0)
+* [library using C stdio](#file-namespace-on-stdio-for-mbed-tls-2.25.0)
+
+Supported features:
+
+* [Persistent keys](#key-file-format-for-mbed-tls-2.25.0) designated by a [key identifier and owner](#key-names-for-mbed-tls-2.25.0). Keys can be:
+ * Transparent, stored in the export format.
+ * Opaque, using the PSA driver interface with statically registered drivers. The driver determines the content of the opaque key blob.
+ * Opaque, using the deprecated secure element interface with dynamically registered drivers (`MBEDTLS_PSA_CRYPTO_SE_C`). The driver picks a slot number which is stored in the place of the key material.
+* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0) on ITS only.
+
+### Changes introduced in Mbed TLS 2.25.0
+
+* The numerical encodings of `psa_key_type_t`, `psa_key_usage_t` and `psa_algorithm_t` have changed.
+
+### File namespace on a PSA platform on Mbed TLS 2.25.0
+
+Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+Assumption: the owner identifier is a nonzero value of type `int32_t`.
+
+* Files 0 through 0xfffeffff: unused.
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0).
+* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0). The upper 32 bits determine the owner.
+
+### File namespace on ITS as a library on Mbed TLS 2.25.0
+
+Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
+
+* File 0: unused.
+* Files 1 through 0xfffeffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0).
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0).
+* Files 0x100000000 through 0xffffffffffffffff: unused.
+
+### File namespace on stdio for Mbed TLS 2.25.0
+
+Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
+
+An undocumented build-time configuration value `PSA_ITS_STORAGE_PREFIX` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
+
+* `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
+* `sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)`: a key or non-key file. The `key_id` in the name is the 64-bit file identifier, which is the [key identifier](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a [non-key file](#non-key-files-on-mbed-tls-2.25.0). The contents of the file are:
+ * Magic header (8 bytes): `"PSA\0ITS\0"`
+ * File contents.
+
+### Key names for Mbed TLS 2.25.0
+
+Information about each key is stored in a dedicated file designated by the key identifier. In integrations where there is no concept of key owner (in particular, in library integrations), the key identifier is exactly the key identifier as defined in the PSA Cryptography API specification (`psa_key_id_t`). In integrations where there is a concept of key owner (integration into a service for example), the key identifier is made of an owner identifier (its semantics and type are integration specific) and of the key identifier (`psa_key_id_t`) from the key owner point of view.
+
+The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-mbed-tls-2.25.0).
+
+* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value which must be in the range 0x00000001..0x3fffffff (`PSA_KEY_ID_USER_MIN`..`PSA_KEY_ID_USER_MAX`).
+* PSA service integration: the key file name is `(uint64_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
+
+### Key file format for Mbed TLS 2.25.0
+
+All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`.
+* version (4 bytes): 0.
+* lifetime (4 bytes): `psa_key_lifetime_t` value.
+* type (2 bytes): `psa_key_type_t` value.
+* bits (2 bytes): `psa_key_bits_t` value.
+* policy usage flags (4 bytes): `psa_key_usage_t` value.
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value.
+* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value.
+* key material length (4 bytes).
+* key material:
+ * For a transparent key: output of `psa_export_key`.
+ * For an opaque key (unified driver interface): driver-specific opaque key blob.
+ * For an opaque key (key in a dynamic secure element): slot number (8 bytes), in platform endianness.
+* Any trailing data is rejected on load.
+
+### Non-key files on Mbed TLS 2.25.0
+
+File identifiers that are outside the range of persistent key identifiers are reserved for internal use by the library. The only identifiers currently in use have the owner id (top 32 bits) set to 0.
+
+* Files 0xfffffe02 through 0xfffffeff (`PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime`): dynamic secure element driver storage. The content of the file is the secure element driver's persistent data.
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0).
+* File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-mbed-tls-2.25.0).
+* Other files are unused and reserved for future use.
+
+### Nonvolatile random seed file format for Mbed TLS 2.25.0
+
+[Identical to Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
+
+### Transaction file format for Mbed TLS 2.25.0
+
+The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction.
+
+All integers are encoded in platform endianness.
+
+All currently existing transactions concern a key in a dynamic secure element.
+
+The layout of a transaction file is:
+
+* type (2 bytes): the [transaction type](#transaction-types-on-mbed-tls-2.25.0).
+* unused (2 bytes)
+* lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element.
+* slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver.
+* key identifier (4 bytes in a library integration, 8 bytes on a PSA platform): the internal representation of the key identifier. On a PSA platform, this encodes the key owner in the same way as [in file identifiers for key files](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0)).
+
+#### Transaction types on Mbed TLS 2.25.0
+
+* 0x0001: key creation. The following locations may or may not contain data about the key that is being created:
+ * The slot in the secure element designated by the slot number.
+ * The file containing the key metadata designated by the key identifier.
+ * The driver persistent data.
+* 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed:
+ * The slot in the secure element designated by the slot number.
+ * The file containing the key metadata designated by the key identifier.
+ * The driver persistent data.
diff --git a/docs/architecture/psa-crypto-implementation-structure.md b/docs/architecture/psa-crypto-implementation-structure.md
new file mode 100644
index 0000000..d7e4f9c
--- /dev/null
+++ b/docs/architecture/psa-crypto-implementation-structure.md
@@ -0,0 +1,175 @@
+PSA Cryptography API implementation and PSA driver interface
+===========================================================
+
+## Introduction
+
+The [PSA Cryptography API specification](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) defines an interface to cryptographic operations for which the Mbed TLS library provides a reference implementation. The PSA Cryptography API specification is complemented by the PSA driver interface specification which defines an interface for cryptoprocessor drivers.
+
+This document describes the high level organization of the Mbed TLS PSA Cryptography API implementation which is tightly related to the PSA driver interface.
+
+## High level organization of the Mbed TLS PSA Cryptography API implementation
+In one sentence, the Mbed TLS PSA Cryptography API implementation is made of a core and PSA drivers as defined in the PSA driver interface. The key point is that software cryptographic operations are organized as PSA drivers: they interact with the core through the PSA driver interface.
+
+### Rationale
+
+* Addressing software and hardware cryptographic implementations through the same C interface reduces the core code size and its call graph complexity. The core and its dispatching to software and hardware implementations are consequently easier to test and validate.
+* The organization of the software cryptographic implementations in drivers promotes modularization of those implementations.
+* As hardware capabilities, software cryptographic functionalities can be described by a JSON driver description file as defined in the PSA driver interface.
+* Along with JSON driver description files, the PSA driver specification defines the deliverables for a driver to be included into the Mbed TLS PSA Cryptography implementation. This provides a natural framework to integrate third party or alternative software implementations of cryptographic operations.
+
+## The Mbed TLS PSA Cryptography API implementation core
+
+The core implements all the APIs as defined in the PSA Cryptography API specification but does not perform on its own any cryptographic operation. The core relies on PSA drivers to actually
+perform the cryptographic operations. The core is responsible for:
+
+* the key store.
+* checking PSA API arguments and translating them into valid arguments for the necessary calls to the PSA driver interface.
+* dispatching the cryptographic operations to the appropriate PSA drivers.
+
+The sketch of an Mbed TLS PSA cryptographic API implementation is thus:
+```C
+psa_status_t psa_api( ... )
+{
+ psa_status_t status;
+
+ /* Pre driver interface call processing: validation of arguments, building
+ * of arguments for the call to the driver interface, ... */
+
+ ...
+
+ /* Call to the driver interface */
+ status = psa_driver_wrapper_<entry_point>( ... );
+ if( status != PSA_SUCCESS )
+ return( status );
+
+ /* Post driver interface call processing: validation of the values returned
+ * by the driver, finalization of the values to return to the caller,
+ * clean-up in case of error ... */
+}
+```
+The code of most PSA APIs is expected to match precisely the above layout. However, it is likely that the code structure of some APIs will be more complicated with several calls to the driver interface, mainly to encompass a larger variety of hardware designs. For example, to encompass hardware accelerators that are capable of verifying a MAC and those that are only capable of computing a MAC, the psa_mac_verify() API could call first psa_driver_wrapper_mac_verify() and then fallback to psa_driver_wrapper_mac_compute().
+
+The implementations of `psa_driver_wrapper_<entry_point>` functions are generated by the build system based on the JSON driver description files of the various PSA drivers making up the Mbed TLS PSA Cryptography API implementation. The implementations are splited into two parts. The static ones are generated in a psa_crypto_driver_wrappers.h header file, the non-static ones are generated in a psa_crypto_driver_wrappers_no_static.c C file and the function prototypes declared in a psa_crypto_driver_wrappers_no_static.h header file.
+
+The psa_driver_wrapper_<entry_point>() functions dispatch cryptographic operations to accelerator drivers, secure element drivers as well as to the software implementations of cryptographic operations.
+
+Note that the implementation allows to build the library with only a C compiler by shipping a generated file corresponding to a pure software implementation. The driver entry points and their code in this generated file are guarded by pre-processor directives based on PSA_WANT_xyz macros (see [Conditional inclusion of cryptographic mechanism through the PSA API in Mbed TLS](psa-conditional-inclusion-c.html). That way, it is possible to compile and include in the library only the desired cryptographic operations.
+
+### Key creation
+
+Key creation implementation in Mbed TLS PSA core is articulated around three internal functions: psa_start_key_creation(), psa_finish_key_creation() and psa_fail_key_creation(). Implementations of key creation PSA APIs, namely psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() and psa_copy_key() go by the following sequence:
+ 1. Check the input parameters.
+ 2. Call psa_start_key_creation() that allocates a key slot, prepares it with the specified key attributes, and in case of a volatile key assign it a volatile key identifier.
+ 3. Generate or copy the key material into the key slot. This entails the allocation of the buffer to store the key material.
+ 4. Call psa_finish_key_creation() that mostly saves persistent keys into persistent storage.
+
+In case of any error occurring at step 3 or 4, psa_fail_key_creation() is called. It wipes and cleans the slot especially the key material: reset to zero of the RAM memory that contained the key material, free the allocated buffer.
+
+
+## Mbed TLS PSA Cryptography API implementation drivers
+
+A driver of the Mbed TLS PSA Cryptography API implementation (Mbed TLS PSA driver in the following) is a driver in the sense that it is compliant with the PSA driver interface specification. But it is not an actual driver that drives some hardware. It implements cryptographic operations purely in software.
+
+An Mbed TLS PSA driver C file is named psa_crypto_<driver_name>.c and its associated header file psa_crypto_<driver_name>.h. The functions implementing a driver entry point as defined in the PSA driver interface specification are named as mbedtls_psa_<driver name>_<entry point>(). As an example, the psa_crypto_rsa.c and psa_crypto_rsa.h are the files containing the Mbed TLS PSA driver implementing RSA cryptographic operations. This RSA driver implements among other entry points the "import_key" entry point. The function implementing this entry point is named mbedtls_psa_rsa_import_key().
+
+## How to implement a new cryptographic mechanism
+
+Summary of files to modify when adding a new algorithm or key type:
+
+* [ ] PSA Crypto API draft, if not already done — [PSA standardization](#psa-standardization)
+* [ ] `include/psa/crypto_values.h` or `include/psa/crypto_extra.h` — [New functions and macros](#new-functions-and-macros)
+* [ ] `include/psa/crypto_config.h`, `tests/include/test/drivers/crypto_config_test_driver_extension.h` — [Preprocessor symbols](#preprocessor-symbols)
+* Occasionally `library/check_crypto_config.h` — [Preprocessor symbols](#preprocessor-symbols)
+* [ ] `include/mbedtls/config_psa.h` — [Preprocessor symbols](#preprocessor-symbols)
+* [ ] `library/psa_crypto.c`, `library/psa_crypto_*.[hc]` — [Implementation of the mechanisms](#implementation-of-the-mechanisms)
+* [ ] `include/psa/crypto_builtin_*.h` — [Translucent data structures](#translucent-data-structures)
+* [ ] `tests/suites/test_suite_psa_crypto_metadata.data` — [New functions and macros](#new-functions-and-macros)
+* (If adding `PSA_IS_xxx`) `tests/suites/test_suite_psa_crypto_metadata.function` — [New functions and macros](#new-functions-and-macros)
+* [ ] `tests/suites/test_suite_psa_crypto*.data`, `tests/suites/test_suite_psa_crypto*.function` — [Unit tests](#unit-tests)
+* [ ] `scripts/mbedtls_dev/crypto_knowledge.py`, `scripts/mbedtls_dev/asymmetric_key_data.py` — [Unit tests](#unit-tests)
+* [ ] `ChangeLog.d/*.txt` — changelog entry
+
+Summary of files to modify when adding new API functions:
+
+* [ ] `include/psa/crypto.h` and `include/psa/crypto_sizes.h`, or `include/psa/crypto_extra.h` — [New functions and macros](#new-functions-and-macros)
+* [ ] `library/psa_crypto.c`, `scripts/data_files/driver_templates/*.jinja` — [Implementation of the mechanisms](#implementation-of-the-mechanisms)
+* [ ] If adding stateful functions: `include/psa/crypto_struct.h`, `include/psa/crypto_builtin_*.h`, `include/psa/crypto_driver_contexts_*.h` — [Translucent data structures](#translucent-data-structures)
+* [ ] `tests/suites/test_suite_psa_crypto.data`, `tests/suites/test_suite_psa_crypto.function`, `tests/suites/test_suite_psa_crypto_driver_wrappers.*` — [Unit tests](#unit-tests)
+
+Note that this is just a basic guide. In some cases, you won't need to change all the files listed here. In some cases, you may need to change other files.
+
+### PSA standardization
+
+Typically, if there's enough demand for a cryptographic mechanism in Mbed TLS, there's enough demand for it to be part of the official PSA Cryptography specification. Therefore the first step before implementing a new mechanism should be to approach the PSA Cryptography working group in Arm for standardization.
+
+At the time of writing, all cryptographic mechanisms that are accessible through `psa_xxx` APIs in in Mbed TLS are current or upcoming PSA standards. Mbed TLS implements some extensions to the PSA API that offer extra integration customization or extra key policies.
+
+Mbed TLS routinely implements cryptographic mechanisms that are not yet part of a published PSA standard, but that are scheduled to be part of a future version of the standard. The Mbed TLS implementation validates the feasibility of the upcoming PSA standard. The PSA Cryptography working group and the Mbed TLS development team communicate during the elaboration of the new interfaces.
+
+### New functions and macros
+
+If a mechanism requires new functions, they should follow the design guidelines in the PSA Cryptography API specification.
+
+Functions that are part of the current or upcoming API are declared in `include/psa/crypto.h`, apart from structure accessors defined in `include/psa/crypto_struct.h`. Functions that have output buffers have associated sufficient-output-size macros in `include/psa/crypto_sizes.h`.
+
+Constants (algorithm identifiers, key type identifiers, etc.) and associated destructor macros (e.g. `PSA_IS_xxx()`) are defined in `include/psa/crypto_values.h`.
+
+Functions and macros that are not intended for standardization, or that are at a stage where the draft standard might still evolve significantly, are declared in `include/psa/crypto_extra.h`.
+
+The PSA Cryptography API specification defines both names and values for certain kinds of constants: algorithms (`PSA_ALG_xxx`), key types (`PSA_KEY_TYPE_xxx`), ECC curve families (`PSA_ECC_FAMILY_xxx`), DH group families (`PSA_DH_FAMILY_xxx`). If Mbed TLS defines an algorithm or a key type that is not part of a current or upcoming PSA standard, pick a value with the `VENDOR` flag set. If Mbed TLS defines an ECC curve or DH group family that is not part of a current or upcoming PSA standard, define a vendor key type and use the family identifier only with this vendor key type.
+
+New constants must have a test case in `tests/suites/test_suite_psa_crypto_metadata.data` that verifies that `PSA_IS_xxx` macros behave properly with the new constant. New `PSA_IS_xxx` macros must be declared in `tests/suites/test_suite_psa_crypto_metadata.function`.
+
+### Preprocessor symbols
+
+Each cryptographic mechanism is optional and can be selected by the application at build time. For each feature `PSA_ttt_xxx`:
+
+* The feature is available to applications when the preprocessor symbol `PSA_WANT_ttt_xxx` is defined. These symbols are set:
+ * If `MBEDTLS_PSA_CRYPTO_CONFIG` is disabled: based on the available mechanisms in Mbed TLS, deduced from `mbedtls/mbedtls_config.h` by code in `include/mbedtls/config_psa.h`.
+ * if `MBEDTLS_PSA_CRYPTO_CONFIG` is enabled: in the application configuration file `include/psa/crypto_config.h` (or `MBEDTLS_PSA_CRYPTO_CONFIG_FILE`, plus `MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE`), with code in `include/mbedtls/config_psa.h` deducing the necessary underlying `MBEDTLS_xxx` symbols.
+* For transparent keys (keys that are not in a secure element), the feature is implemented by Mbed TLS if `MBEDTLS_PSA_BUILTIN_ttt_xxx` is defined, and by an accelerator driver if `MBEDTLS_PSA_ACCEL_ttt_xxx` is defined. `MBEDTLS_PSA_BUILTIN_ttt_xxx` constants are set in `include/mbedtls/config_psa.h` based on the application requests `PSA_WANT_ttt_xxx` and the accelerator driver declarations `MBEDTLS_PSA_ACCEL_ttt_xxx`.
+* For the testing of the driver dispatch code, `tests/include/test/drivers/crypto_config_test_driver_extension.h` sets additional `MBEDTLS_PSA_ACCEL_xxx` symbols.
+
+For more details, see *[Conditional inclusion of cryptographic mechanism through the PSA API in Mbed TLS](../proposed/psa-conditional-inclusion-c.html)*.
+
+Some mechanisms require other mechanisms. For example, you can't do GCM without a block cipher, or RSA-PSS without RSA keys. When mechanism A requires mechanism B, `include/mbedtls/config_psa.h` ensures that B is enabled whenever A is enabled. When mechanism A requires at least one of a set {B1, B2, B3, ...} but there is no particular reason why enabling A would enable any of the specific Bi's, it's up to the application to choose Bi's and the file `library/check_crypto_config.h` contains compile-time constraints to ensure that at least one Bi is enabled.
+
+### Implementation of the mechanisms
+
+The general structure of a cryptographic operation function is:
+
+1. API function defined in `library/psa_crypto.c`. The entry point performs generic checks that don't depend on whether the mechanism is implemented in software or in a driver and looks up keys in the key store.
+2. Driver dispatch code in `scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja`, `scripts/data_files/driver_templates/psa_crypto_driver_wrappers_no_static.c.jinja` or files included from there.
+3. Built-in implementation in `library/psa_crypto_*.c` (with function declarations in the corresponding `.h` file). These files typically contain the implementation of modes of operation over basic building blocks that are defined elsewhere. For example, HMAC is implemented in `library/psa_crypto_mac.c` but the underlying hash functions are implemented in `library/sha*.c` and `library/md*.c`.
+4. Basic cryptographic building blocks in `library/*.c`.
+
+When implementing a new algorithm or key type, there are typically things to change in `library/crypto.c` (e.g. buffer size calculations, algorithm/key-type compatibility) and in the built-in implementation, but not in the driver dispatch code.
+
+### Translucent data structures
+
+Some mechanisms require state to be kept between function calls. Keys and key-like data is kept in the key store, which PSA manages internally. Other state, for example the state of multipart operations, is kept in structures allocated by the caller.
+
+The size of operation structures needs to be known at compile time, since callers may allocate them on the stack. Therefore these structures are defined in a public header: `include/psa/crypto_struct.h` for the parts that are independent of the underlying implementation, `include/psa/crypto_builtin_*` for parts that are specific to the Mbed TLS built-in implementation, `include/psa/crypto_driver_*.h` for structures implemented by drivers.
+
+### Unit tests
+
+A number of unit tests are automatically generated by `tests/scripts/generate_psa_tests.py` based on the algorithms and key types declared in `include/psa/crypto_values.h` and `include/psa/crypto_extra.h`:
+
+* Attempt to create a key with a key type that is not supported.
+* Attempt to perform an operation with a combination of key type and algorithm that is not valid or not supported.
+* Storage and retrieval of a persistent key.
+
+When adding a new key type or algorithm:
+
+* `scripts/mbedtls_dev/crypto_knowledge.py` contains knowledge about the compatibility of key types, key sizes and algorithms.
+* `scripts/mbedtls_dev/asymmetric_key_data.py` contains valid key data for asymmetric key types.
+
+Other things need to be tested manually, either in `tests/suites/test_sutie_psa_crypto.data` or in another file. For example (this is not an exhaustive list):
+
+* Known answer tests.
+* Potential edge cases (e.g. data less/equal/more than the block size, number equal to zero in asymmetric cryptography).
+* Tests with invalid keys (e.g. wrong size or format).
+* Tests with invalid data (e.g. wrong size or format, output buffer too small, invalid padding).
+* For new functions: incorrect function call sequence, driver dispatch (in `tests/suites/test_suite_psa_crypto_driver_wrappers.*`).
+* For key derivation algorithms: variation on the sequence of input steps, variation on the output size.
+
diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md
new file mode 100644
index 0000000..eda65a3
--- /dev/null
+++ b/docs/architecture/psa-migration/md-cipher-dispatch.md
@@ -0,0 +1,616 @@
+PSA migration strategy for hashes and ciphers
+=============================================
+
+## Introduction
+
+This document discusses a migration strategy for code that is not subject to `MBEDTLS_USE_PSA_CRYPTO`, is currently using legacy cryptography APIs, and should transition to PSA, without a major version change.
+
+### Relationship with the main strategy document
+
+This is complementary to the main [strategy document](strategy.html) and is intended as a refinement. However, at this stage, there may be contradictions between the strategy proposed here and some of the earlier strategy.
+
+A difference between the original strategy and the current one is that in this work, we are not treating PSA as a black box. We can change experimental features, and we can call internal interfaces.
+
+## Requirements
+
+### User stories
+
+#### Backward compatibility user story
+
+As a developer of an application that uses Mbed TLS's interfaces (including legacy crypto),
+I want Mbed TLS to preserve backward compatibility,
+so that my code keeps working in new minor versions of Mbed TLS.
+
+#### Interface design user story
+
+As a developer of library code that uses Mbed TLS to perform cryptographic operations,
+I want to know which functions to call and which feature macros to check,
+so that my code works in all Mbed TLS configurations.
+
+Note: this is the same problem we face in X.509 and TLS.
+
+#### Hardware accelerator vendor user stories
+
+As a vendor of a platform with hardware acceleration for some crypto,
+I want to build Mbed TLS in a way that uses my hardware wherever relevant,
+so that my customers maximally benefit from my hardware.
+
+As a vendor of a platform with hardware acceleration for some crypto,
+I want to build Mbed TLS without software that replicates what my hardware does,
+to minimize the code size.
+
+#### Maintainer user stories
+
+As a maintainer of Mbed TLS,
+I want to have clear rules for when to use which interface,
+to avoid bugs in “unusual” configurations.
+
+As a maintainer of Mbed TLS,
+I want to avoid duplicating code,
+because this is inefficient and error-prone.
+
+### Use PSA more
+
+In the long term, all code using cryptography should use PSA interfaces, to benefit from PSA drivers, allow eliminating legacy interfaces (less code size, less maintenance). However, this can't be done without breaking [backward compatibility](#backward-compatibility).
+
+The goal of this work is to arrange for more non-PSA interfaces to use PSA interfaces under the hood, without breaking code in the cases where this doesn't work. Using PSA interfaces has two benefits:
+
+* Where a PSA driver is available, it likely has better performance, and sometimes better security, than the built-in software implementation.
+* In many scenarios, where a PSA driver is available, this allows removing the software implementation altogether.
+* We may be able to get rid of some redundancies, for example the duplication between the implementations of HMAC in `md.c` and in `psa_crypto_mac.c`, and HKDF in `hkdf.c` and `psa_crypto.c`.
+
+### Correct dependencies
+
+Traditionally, to determine whether a cryptographic mechanism was available, you had to check whether the corresponding Mbed TLS module or submodule was present: `MBEDTLS_SHA256_C` for SHA256, `MBEDTLS_AES_C && MBEDTLS_CIPHER_MODE_CBC` for AES-CBC, etc. In code that uses the PSA interfaces, this needs to change to `PSA_WANT_xxx` symbols.
+
+### Backward compatibility
+
+All documented behavior must be preserved, except for interfaces currently described as experimental or unstable. Those interfaces can change, but we should minimize disruption by providing a transition path for reasonable use cases.
+
+#### Changeable configuration options
+
+The following configuration options are described as experimental, and are likely to change at least marginally:
+
+* `MBEDTLS_PSA_CRYPTO_CLIENT`: “This interface is experimental and may change or be removed without notice.” In practice we don't want to remove this, but we may constrain how it's used.
+* `MBEDTLS_PSA_CRYPTO_DRIVERS`: “This interface is experimental. We intend to maintain backward compatibility with application code that relies on drivers, but the driver interfaces may change without notice.” In practice, this may mean constraints not only on how to write drivers, but also on how to integrate drivers into code that is platform code more than application code.
+* `MBEDTLS_PSA_CRYPTO_CONFIG`: “This feature is still experimental and is not ready for production since it is not completed.” We may want to change this, for example, to automatically enable more mechanisms (although this wouldn't be considered a backward compatibility break anyway, since we don't promise that you will not get a feature if you don't enable its `PSA_WANT_xxx`).
+
+### Non-goals
+
+It is not a goal at this stage to make more code directly call `psa_xxx` functions. Rather, the goal is to make more code call PSA drivers where available. How dispatch is done is secondary.
+
+## Problem analysis
+
+### Scope analysis
+
+#### Limitations of `MBEDTLS_USE_PSA_CRYPTO`
+
+The option `MBEDTLS_USE_PSA_CRYPTO` causes parts of the library to call the PSA API instead of legacy APIs for cryptographic calculations. `MBEDTLS_USE_PSA_CRYPTO` only applies to `pk.h`, X.509 and TLS. When this option is enabled, applications must call `psa_crypto_init()` before calling any of the functions in these modules.
+
+In this work, we want two things:
+
+* Make non-covered modules call PSA, but only [when this will actually work](#why-psa-is-not-always-possible). This effectively brings those modules to a partial use-PSA behavior (benefiting from PSA accelerators when they're usable) regardless of whether the option is enabled.
+* Call PSA when a covered module calls a non-covered module which calls another module, for example X.509 calling pk for PSS verification which calls RSA which calculates a hash ([see issue \#6497](https://github.com/Mbed-TLS/mbedtls/issues/6497)). This effectively extends the option to modules that aren't directly covered.
+
+#### Classification of callers
+
+We can classify code that implements or uses cryptographic mechanisms into several groups:
+
+* Software implementations of primitive cryptographic mechanisms. These are not expected to change.
+* Software implementations of constructed cryptographic mechanisms (e.g. HMAC, CTR_DRBG, RSA (calling a hash for PSS/OAEP, and needing to know the hash length in PKCS1v1.5 sign/verify), …). These need to keep working whenever a legacy implementation of the auxiliary mechanism is available, regardless of whether a PSA implementation is also available.
+* Code implementing the PSA crypto interface. This is not expected to change, except perhaps to expose some internal functionality to overhauled glue code.
+* Code that's subject to `MBEDTLS_USE_PSA_CRYPTO`: `pk.h`, X.509, TLS (excluding parts specific TLS 1.3).
+* Code that always uses PSA for crypto: TLS 1.3 (except things common with 1.2), LMS.
+
+For the purposes of this work, three domains emerge:
+
+* **Legacy domain**: does not interact with PSA. Implementations of hashes, of cipher primitives, of arithmetic.
+* **Mixed domain**: does not currently use PSA, but should [when possible](#why-psa-is-not-always-possible). This consists of the constructed cryptographic primitives (except LMS), as well as pk, X.509 and TLS when `MBEDTLS_USE_PSA_CRYPTO` is disabled.
+* **PSA domain**: includes pk, X.509 and TLS when `MBEDTLS_USE_PSA_CRYPTO` is enabled. Also TLS 1.3, LMS.
+
+#### Non-use-PSA modules
+
+The following modules in Mbed TLS call another module to perform cryptographic operations which, in the long term, will be provided through a PSA interface, but cannot make any PSA-related assumption.
+
+Hashes and HMAC (after the work on driver-only hashes):
+
+* entropy (hashes via MD-light)
+* ECDSA (HMAC\_DRBG; `md.h` exposed through API)
+* ECJPAKE (hashes via MD-light; `md.h` exposed through API)
+* MD (hashes and HMAC)
+* HKDF (HMAC via `md.h`; `md.h` exposed through API)
+* HMAC\_DRBG (hashes and HMAC via `md.h`; `md.h` exposed through API)
+* PKCS12 (hashes via MD-light)
+* PKCS5 (HMAC via `md.h`; `md.h` exposed through API)
+* PKCS7 (hashes via MD)
+* RSA (hash via MD-light for PSS and OAEP; `md.h` exposed through API)
+* PEM (MD5 hash via MD-light)
+
+Symmetric ciphers and AEADs (before work on driver-only cipher):
+
+* PEM:
+ * AES, DES or 3DES in CBC mode without padding, decrypt only (!).
+ * Currently using low-level non-generic APIs.
+ * No hard dependency, features guarded by `AES_C` resp. `DES_C`.
+ * Functions called: `setkey_dec()` + `crypt_cbc()`.
+* PKCS12:
+ * In practice: 2DES or 3DES in CBC mode with PKCS7 padding, decrypt only
+ (when called from pkparse).
+ * In principle: any cipher-mode (default padding), passed an
+ `mbedtls_cipher_type_t` as an argument, no documented restriction.
+ * Cipher, generically, selected from ASN.1 or function parameters;
+ no documented restriction but in practice TODO (inc. padding and
+ en/decrypt, look at standards and tests)
+ * Unconditional dependency on `CIPHER_C` in `check_config.h`.
+ * Note: `cipher.h` exposed through API.
+ * Functions called: `setup`, `setkey`, `set_iv`, `reset`, `update`, `finish` (in sequence, once).
+* PKCS5 (PBES2, `mbedtls_pkcs5_pbes2()`):
+ * 3DES or DES in CBC mode with PKCS7 padding, both encrypt and decrypt.
+ * Note: could also be AES in the future, see #7038.
+ * Unconditional dependency on `CIPHER_C` in `check_config.h`.
+ * Functions called: `setup`, `setkey`, `crypt`.
+* CTR\_DRBG:
+ * AES in ECB mode, encrypt only.
+ * Currently using low-level non-generic API (`aes.h`).
+ * Unconditional dependency on `AES_C` in `check_config.h`.
+ * Functions called: `setkey_enc`, `crypt_ecb`.
+* CCM:
+ * AES, Camellia or Aria in ECB mode, encrypt only.
+ * Unconditional dependency on `AES_C || CAMELLIA_C || ARIA_C` in `check_config.h`.
+ * Unconditional dependency on `CIPHER_C` in `check_config.h`.
+ * Note: also called by `cipher.c` if enabled.
+ * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish)
+* CMAC:
+ * AES or DES in ECB mode, encrypt only.
+ * Unconditional dependency on `AES_C || DES_C` in `check_config.h`.
+ * Unconditional dependency on `CIPHER_C` in `check_config.h`.
+ * Note: also called by `cipher.c` if enabled.
+ * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish)
+* GCM:
+ * AES, Camellia or Aria in ECB mode, encrypt only.
+ * Unconditional dependency on `AES_C || CAMELLIA_C || ARIA_C` in `check_config.h`.
+ * Unconditional dependency on `CIPHER_C` in `check_config.h`.
+ * Note: also called by `cipher.c` if enabled.
+ * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish)
+* NIST\_KW:
+ * AES in ECB mode, both encryt and decrypt.
+ * Unconditional dependency on `AES_C || DES_C` in `check_config.h`.
+ * Unconditional dependency on `CIPHER_C` in `check_config.h`.
+ * Note: also called by `cipher.c` if enabled.
+ * Note: `cipher.h` exposed through API.
+ * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish)
+* Cipher:
+ * potentially any cipher/AEAD in any mode and any direction
+
+Note: PSA cipher is built on Cipher, but PSA AEAD directly calls the underlying AEAD modules (GCM, CCM, ChachaPoly).
+
+### Difficulties
+
+#### Why PSA is not always possible
+
+Here are some reasons why calling `psa_xxx()` to perform a hash or cipher calculation might not be desirable in some circumstances, explaining why the application would arrange to call the legacy software implementation instead.
+
+* `MBEDTLS_PSA_CRYPTO_C` is disabled.
+* There is a PSA driver which has not been initialized (this happens in `psa_crypto_init()`).
+* For ciphers, the keystore is not initialized yet, and Mbed TLS uses a custom implementation of PSA ITS where the file system is not accessible yet (because something else needs to happen first, and the application takes care that it happens before it calls `psa_crypto_init()`). A possible workaround may be to dispatch to the internal functions that are called after the keystore lookup, rather than to the PSA API functions (but this is incompatible with `MBEDTLS_PSA_CRYPTO_CLIENT`).
+* The requested mechanism is enabled in the legacy interface but not in the PSA interface. This was not really intended, but is possible, for example, if you enable `MBEDTLS_MD5_C` for PEM decoding with PBKDF1 but don't want `PSA_ALG_WANT_MD5` because it isn't supported for `PSA_ALG_RSA_PSS` and `PSA_ALG_DETERMINISTIC_ECDSA`.
+* `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled, and the client has not yet activated the connection to the server (this happens in `psa_crypto_init()`).
+* `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled, but the operation is part of the implementation of an encrypted communication with the crypto service, or the local implementation is faster because it avoids a costly remote procedure call.
+
+#### Indirect knowledge
+
+Consider for example the code in `rsa.c` to perform an RSA-PSS signature. It needs to calculate a hash. If `mbedtls_rsa_rsassa_pss_sign()` is called directly by application code, it is supposed to call the built-in implementation: calling a PSA accelerator would be a behavior change, acceptable only if this does not add a risk of failure or performance degradation ([PSA is impossible or undesirable in some circumstances](#why-psa-is-not-always-possible)). Note that this holds regardless of the state of `MBEDTLS_USE_PSA_CRYPTO`, since `rsa.h` is outside the scope of `MBEDTLS_USE_PSA_CRYPTO`. On the other hand, if `mbedtls_rsa_rsassa_pss_sign()` is called from X.509 code, it should use PSA to calculate hashes. It doesn't, currently, which is [bug \#6497](https://github.com/Mbed-TLS/mbedtls/issues/6497).
+
+Generally speaking, modules in the mixed domain:
+
+* must call PSA if called by a module in the PSA domain;
+* must not call PSA (or must have a fallback) if their caller is not in the PSA domain and the PSA call is not guaranteed to work.
+
+#### Non-support guarantees: requirements
+
+Generally speaking, just because some feature is not enabled in `mbedtls_config.h` or `psa_config.h` doesn't guarantee that it won't be enabled in the build. We can enable additional features through `build_info.h`.
+
+If `PSA_WANT_xxx` is disabled, this should guarantee that attempting xxx through the PSA API will fail. This is generally guaranteed by the test suite `test_suite_psa_crypto_not_supported` with automatically enumerated test cases, so it would be inconvenient to carve out an exception.
+
+### Technical requirements
+
+Based on the preceding analysis, the core of the problem is: for code in the mixed domain (see [“Classification of callers”](#classification-of-callers)), how do we handle a cryptographic mechanism? This has several related subproblems:
+
+* How the mechanism is encoded (e.g. `mbedtls_md_type_t` vs `const *mbedtls_md_info_t` vs `psa_algorithm_t` for hashes).
+* How to decide whether a specific algorithm or key type is supported (eventually based on `MBEDTLS_xxx_C` vs `PSA_WANT_xxx`).
+* How to obtain metadata about algorithms (e.g. hash/MAC/tag size, key size).
+* How to perform the operation (context type, which functions to call).
+
+We need a way to decide this based on the available information:
+
+* Who's the ultimate caller — see [indirect knowledge](#indirect-knowledge) — which is not actually available.
+* Some parameter indicating which algorithm to use.
+* The available cryptographic implementations, based on preprocessor symbols (`MBEDTLS_xxx_C`, `PSA_WANT_xxx`, `MBEDTLS_PSA_ACCEL_xxx`, etc.).
+* Possibly additional runtime state (for example, we might check whether `psa_crypto_init` has been called).
+
+And we need to take care of the [the cases where PSA is not possible](#why-psa-is-not-always-possible): either make sure the current behavior is preserved, or (where allowed by backward compatibility) document a behavior change and, preferably, a workaround.
+
+### Working through an example: RSA-PSS
+
+Let us work through the example of RSA-PSS which calculates a hash, as in [see issue \#6497](https://github.com/Mbed-TLS/mbedtls/issues/6497).
+
+RSA is in the [mixed domain](#classification-of-callers). So:
+
+* When called from `psa_sign_hash` and other PSA functions, it must call the PSA hash accelerator if there is one.
+* When called from user code, it must call the built-in hash implementation if PSA is not available (regardless of whether this is because `MBEDTLS_PSA_CRYPTO_C` is disabled, or because `PSA_WANT_ALG_xxx` is disabled for this hash, or because there is an accelerator driver which has not been initialized yet).
+
+RSA knows which hash algorithm to use based on a parameter of type `mbedtls_md_type_t`. (More generally, all mixed-domain modules that take an algorithm specification as a parameter take it via a numerical type, except HMAC\_DRBG and HKDF which take a `const mbedtls_md_info_t*` instead, and CMAC which takes a `const mbedtls_cipher_info_t *`.)
+
+#### Double encoding solution
+
+A natural solution is to double up the encoding of hashes in `mbedtls_md_type_t`. Pass `MBEDTLS_MD_SHA256` and `md` will dispatch to the legacy code, pass a new constant `MBEDTLS_MD_SHA256_USE_PSA` and `md` will dispatch through PSA.
+
+This maximally preserves backward compatibility, but then no non-PSA code benefits from PSA accelerators, and there's little potential for removing the software implementation.
+
+#### Availability of hashes in RSA-PSS
+
+Here we try to answer the question: As a caller of RSA-PSS via `rsa.h`, how do I know whether it can use a certain hash?
+
+* For a caller in the legacy domain: if e.g. `MBEDTLS_SHA256_C` is enabled, then I want RSA-PSS to support SHA-256. I don't care about negative support. So `MBEDTLS_SHA256_C` must imply support for RSA-PSS-SHA-256. It must work at all times, regardless of the state of PSA (e.g. drivers not initialized).
+* For a caller in the PSA domain: if e.g. `PSA_WANT_ALG_SHA_256` is enabled, then I want RSA-PSS to support SHA-256, provided that `psa_crypto_init()` has been called. In some limited cases, such as `test_suite_psa_crypto_not_supported` when PSA implements RSA-PSS in software, we care about negative support: if `PSA_WANT_ALG_SHA_256` is disabled then `psa_verify_hash` must reject `PSA_WANT_ALG_SHA_256`. This can be done at the level of PSA before it calls the RSA module, though, so it doesn't have any implication on the RSA module. As far as `rsa.c` is concerned, what matters is that `PSA_WANT_ALG_SHA_256` implies that SHA-256 is supported after `psa_crypto_init()` has been called.
+* For a caller in the mixed domain: requirements depend on the caller. Whatever solution RSA has to determine the availability of algorithms will apply to its caller as well.
+
+Conclusion so far: RSA must be able to do SHA-256 if either `MBEDTLS_SHA256_C` or `PSA_WANT_ALG_SHA_256` is enabled. If only `PSA_WANT_ALG_SHA_256` and not `MBEDTLS_SHA256_C` is enabled (which implies that PSA's SHA-256 comes from an accelerator driver), then SHA-256 only needs to work if `psa_crypto_init()` has been called.
+
+#### More in-depth discussion of compile-time availability determination
+
+The following combinations of compile-time support are possible:
+
+* `MBEDTLS_PSA_CRYPTO_CLIENT`. Then calling PSA may or may not be desirable for performance. There are plausible use cases where only the server has access to an accelerator so it's best to call the server, and plausible use cases where calling the server has overhead that negates the savings from using acceleration, if there are savings at all. In any case, calling PSA only works if the connection to the server has been established, meaning `psa_crypto_init` has been called successfully. In the rest of this case enumeration, assume `MBEDTLS_PSA_CRYPTO_CLIENT` is disabled.
+* No PSA accelerator. Then just call `mbedtls_sha256`, it's all there is, and it doesn't matter (from an API perspective) exactly what call chain leads to it.
+* PSA accelerator, no software implementation. Then we might as well call the accelerator, unless it's important that the call fails. At the time of writing, I can't think of a case where we would want to guarantee that if `MBEDTLS_xxx_C` is not enabled, but xxx is enabled through PSA, then a request to use algorithm xxx through some legacy interface must fail.
+* Both PSA acceleration and the built-in implementation. In this case, we would prefer PSA for the acceleration, but we can only do this if the accelerator driver is working. For hashes, it's enough to assume the driver is initialized; we've [considered requiring hash drivers to work without initialization](https://github.com/Mbed-TLS/mbedtls/pull/6470). For ciphers, this is more complicated because the cipher functions require the keystore, and plausibly a cipher accelerator might want entropy (for side channel countermeasures) which might not be available at boot time.
+
+Note that it's a bit tricky to determine which algorithms are available. In the case where there is a PSA accelerator but no software implementation, we don't want the preprocessor symbols to indicate that the algorithm is available through the legacy domain, only through the PSA domain. What does this mean for the interfaces in the mixed domain? They can't guarantee the availability of the algorithm, but they must try if requested.
+
+### Designing an interface for hashes
+
+In this section, we specify a hash metadata and calculation for the [mixed domain](#classification-of-callers), i.e. code that can be called both from legacy code and from PSA code.
+
+#### Availability of hashes
+
+Generalizing the analysis in [“Availability of hashes in RSA-PSS”](#availability-of-hashes-in-RSA-PSS):
+
+A hash is available through the mixed-domain interface iff either of the following conditions is true:
+
+* A legacy hash interface is available and the hash algorithm is implemented in software.
+* PSA crypto is enabled and the hash algorithm is implemented via PSA.
+
+We could go further and make PSA accelerators available to legacy callers that call any legacy hash interface, e.g. `md.h` or `shaX.h`. There is little point in doing this, however: callers should just use the mixed-domain interface.
+
+#### Implications between legacy availability and PSA availability
+
+* When `MBEDTLS_PSA_CRYPTO_CONFIG` is disabled, all legacy mechanisms are automatically enabled through PSA. Users can manually enable PSA mechanisms that are available through accelerators but not through legacy, but this is not officially supported (users are not supposed to manually define PSA configuration symbols when `MBEDTLS_PSA_CRYPTO_CONFIG` is disabled).
+* When `MBEDTLS_PSA_CRYPTO_CONFIG` is enabled, there is no mandatory relationship between PSA support and legacy support for a mechanism. Users can configure legacy support and PSA support independently. Legacy support is automatically enabled if PSA support is requested, but only if there is no accelerator.
+
+It is strongly desirable to allow mechanisms available through PSA but not legacy: this allows saving code size when an accelerator is present.
+
+There is no strong reason to allow mechanisms available through legacy but not PSA when `MBEDTLS_PSA_CRYPTO_C` is enabled. This would only save at best a very small amount of code size in the PSA dispatch code. This may be more desirable when `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled (having a mechanism available only locally and not in the crypto service), but we do not have an explicit request for this and it would be entirely reasonable to forbid it.
+
+In this analysis, we have not found a compelling reason to require all legacy mechanisms to also be available through PSA. However, this can simplify both the implementation and the use of dispatch code thanks to some simplifying properties:
+
+* Mixed-domain code can call PSA code if it knows that `psa_crypto_init()` has been called, without having to inspect the specifics of algorithm support.
+* Mixed-domain code can assume that PSA buffer calculations work correctly for all algorithms that it supports.
+
+#### Shape of the mixed-domain hash interface
+
+We now need to create an abstraction for mixed-domain hash calculation. (We could not create an abstraction, but that would require every piece of mixed-domain code to replicate the logic here. We went that route in Mbed TLS 3.3, but it made it effectively impossible to get something that works correctly.)
+
+Requirements: given a hash algorithm,
+
+* Obtain some metadata about it (size, block size).
+* Calculate the hash.
+* Set up a multipart operation to calculate the hash. The operation must support update, finish, reset, abort, clone.
+
+The existing interface in `md.h` is close to what we want, but not perfect. What's wrong with it?
+
+* It has an extra step of converting from `mbedtls_md_type_t` to `const mbedtls_md_info_t *`.
+* It includes extra fluff such as names and HMAC. This costs code size.
+* The md module has some legacy baggage dating from when it was more open, which we don't care about anymore. This may cost code size.
+
+These problems are easily solvable.
+
+* `mbedtls_md_info_t` can become a very thin type. We can't remove the extra function call from the source code of callers, but we can make it a very thin abstraction that compilers can often optimize.
+* We can make names and HMAC optional. The mixed-domain hash interface won't be the full `MBEDTLS_MD_C` but a subset.
+* We can optimize `md.c` without making API changes to `md.h`.
+
+### Scope reductions and priorities for 3.x
+
+This section documents things that we chose to temporarily exclude from the scope in the 3.x branch (which will eventually be in scope again after 4.0) as well as things we chose to prioritize if we don't have time to support everything.
+
+#### Don't support PK, X.509 and TLS without `MBEDTLS_USE_PSA_CRYPTO`
+
+We do not need to support driver-only hashes and ciphers in PK. X.509 and TLS without `MBEDTLS_USE_PSA_CRYPTO`. Users who want to take full advantage of drivers will need to enabled this macro.
+
+Note that this applies to TLS 1.3 as well, as some uses of hashes and all uses of ciphers there are common with TLS 1.2, hence governed by `MBEDTLS_USE_PSA_CRYPTO`, see [this macro's extended documentation](../../docs/use-psa-crypto.html).
+
+This will go away naturally in 4.0 when this macros is not longer an option (because it's always on).
+
+#### Don't support for `MBEDTLS_PSA_CRYPTO_CLIENT` without `MBEDTLS_PSA_CRYPTO_C`
+
+We generally don't really support builds with `MBEDTLS_PSA_CRYPTO_CLIENT` without `MBEDTLS_PSA_CRYPTO_C`. For example, both `MBEDTLS_USE_PSA_CRYPTO` and `MBEDTLS_SSL_PROTO_TLS1_3` require `MBEDTLS_PSA_CRYPTO_C`, while in principle they should only require `MBEDTLS_PSA_CRYPTO_CLIENT`.
+
+Considering this existing restriction which we do not plan to lift before 4.0, it is acceptable driver-only hashes and cipher support to have the same restriction in 3.x.
+
+It is however desirable for the design to keep support for `MBEDTLS_PSA_CRYPTO_CLIENT` in mind, in order to avoid making it more difficult to add in the future.
+
+#### For cipher: prioritize constrained devices and modern TLS
+
+The primary target is a configuration like TF-M's medium profile, plus TLS with only AEAD ciphersuites.
+
+This excludes things like:
+- Support for encrypted PEM, PKCS5 and PKCS12 encryption, and PKCS8 encrypted keys in PK parse. (Not widely used on highly constrained devices.)
+- Support for NIST-KW. (Same justification.)
+- Support for CMAC. (Same justification, plus can be directly accelerated.)
+- Support for CBC ciphersuites in TLS. (They've been recommended against for a while now.)
+
+### Dual-dispatch for block cipher primitives
+
+Considering the priorities stated above, initially we want to support GCM, CCM and CTR-DRBG. All three of them use the block cipher primitive only in the encrypt direction. Currently, GCM and CCM use the Cipher layer in order to work with AES, Aria and Camellia (DES is excluded by the standards due to its smaller block size) and CTR-DRBG directly uses the low-level API from `aes.h`. In all cases, access to the "block cipher primitive" is done by using "ECB mode" (which for both Cipher and `aes.h` only allows a single block, contrary to PSA which implements actual ECB mode).
+
+The two AEAD modes, GCM and CCM, have very similar needs and positions in the stack, strongly suggesting using the same design for both. On the other hand, there are a number of differences between CTR-DRBG and them.
+- CTR-DRBG only uses AES (and there is no plan to extend it to other block ciphers at the moment), while GCM and CCM need to work with 3 block ciphers already.
+- CTR-DRBG holds a special position in the stack: most users don't care about it per se, they only care about getting random numbers - in fact PSA users don't even need to know what DRBG is used. In particular, no part of the stack is asking questions like "is CTR-DRBG-AES available?" - an RNG needs to be available and that's it - contrary to similar questions about AES-GCM etc. which are asked for example by TLS.
+
+So, it makes sense to use different designs for CTR-DRBG on one hand, and GCM/CCM on the other hand:
+- CTR-DRBG can just check if `AES_C` is present and "fall back" to PSA if not.
+- GCM and CCM need an common abstraction layer that allows:
+ - Using AES, Aria or Camellia in a uniform way.
+ - Dispatching to built-in or driver.
+
+The abstraction layer used by GCM and CCM may either be a new internal module, or a subset of the existing Cipher API, extended with the ability to dispatch to a PSA driver.
+
+Reasons for making this layer's API a subset of the existing Cipher API:
+- No need to design, implement and test a new module. (Will need to test the new subset though, as well as the extended behaviour.)
+- No code change in GCM and CCM - only need to update dependencies.
+- No risk for code duplication between a potential new module and Cipher: source-level, and in in particular in builds that still have `CIPHER_C` enabled. (Compiled-code duplication could be avoided by excluding the new module in such builds, though.)
+- If want to support other users of Cipher later (such as NIST-KW, CMAC, PKCS5 and PKCS12), we can just extend dual-dispatch support to other modes/operations in Cipher and keep those extra modules unchanged as well.
+
+Possible costs of re-using (a subset of) the existing Cipher API instead of defining a new one:
+- We carry over costs associated with `cipher_info_t` structures. (Currently the info structure is used for 3 things: (1) to check if the cipher is supported, (2) to check its block size, (3) because `setup()` requires it).
+- We carry over questionable implementation decisions, like dynamic allocation of context.
+
+Those costs could be avoided by refactoring (parts of) Cipher, but that would probably mean either:
+- significant differences in how the `cipher.h` API is implemented between builds with the full Cipher or only a subset;
+- or more work to apply the simplifications to all of Cipher.
+
+Prototyping both approaches showed better code size savings and cleaner code with a new internal module (see section "Internal "block cipher" abstraction (Cipher light)" below).
+
+## Specification
+
+### MD light
+
+#### Definition of MD light
+
+MD light is a subset of `md.h` that implements the hash calculation interface described in ”[Designing an interface for hashes](#designing-an-interface-for-hashes)”. It is activated by `MBEDTLS_MD_LIGHT` in `mbedtls_config.h`.
+
+The following things enable MD light automatically in `build_info.h`:
+
+* A [mixed-domain](#classification-of-callers) module that needs to calculate hashes is enabled.
+* `MBEDTLS_MD_C` is enabled.
+
+MD light includes the following types:
+
+* `mbedtls_md_type_t`
+* `mbedtls_md_info_t`
+* `mbedtls_md_context_t`
+
+MD light includes the following functions:
+
+* `mbedtls_md_info_from_type`
+* `mbedtls_md_init`
+* `mbedtls_md_free`
+* `mbedtls_md_setup` — but `hmac` must be 0 if `MBEDTLS_MD_C` is disabled.
+* `mbedtls_md_clone`
+* `mbedtls_md_get_size`
+* `mbedtls_md_get_type`
+* `mbedtls_md_starts`
+* `mbedtls_md_update`
+* `mbedtls_md_finish`
+* `mbedtls_md`
+
+Unlike the full MD, MD light does not support null pointers as `mbedtls_md_context_t *`. At least some functions still need to support null pointers as `const mbedtls_md_info_t *` because this arises when you try to use an unsupported algorithm (`mbedtls_md_info_from_type` returns `NULL`).
+
+#### MD algorithm support macros
+
+For each hash algorithm, `md.h` defines a macro `MBEDTLS_MD_CAN_xxx` whenever the corresponding hash is available through MD light. These macros are only defined when `MBEDTLS_MD_LIGHT` is enabled. Per “[Availability of hashes](#availability-of-hashes)”, `MBEDTLS_MD_CAN_xxx` is enabled if:
+
+* the corresponding `MBEDTLS_xxx_C` is defined; or
+* one of `MBEDTLS_PSA_CRYPTO_C` or `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled, and the corresponding `PSA_WANT_ALG_xxx` is enabled.
+
+Note that some algorithms have different spellings in legacy and PSA. Since MD is a legacy interface, we'll use the legacy names. Thus, for example:
+
+```
+#if defined(MBEDTLS_MD_LIGHT)
+#if defined(MBEDTLS_SHA256_C) || \
+ (defined(MBEDTLS_PSA_CRYPTO_C) && PSA_WANT_ALG_SHA_256)
+#define MBEDTLS_MD_CAN_SHA256
+#endif
+#endif
+```
+
+Note: in the future, we may want to replace `defined(MBEDTLS_PSA_CRYPTO_C)`
+with `defined(MBEDTLS_PSA_CRYTO_C) || defined(MBEDTLS_PSA_CRYPTO_CLIENT)` but
+for now this is out of scope.
+
+#### MD light internal support macros
+
+* If at least one hash has a PSA driver, define `MBEDTLS_MD_SOME_PSA`.
+* If at least one hash has a legacy implementation, defined `MBEDTLS_MD_SOME_LEGACY`.
+
+#### Support for PSA in the MD context
+
+An MD context needs to contain either a legacy module's context (or a pointer to one, as is the case now), or a PSA context (or a pointer to one).
+
+I am inclined to remove the pointer indirection, but this means that an MD context would always be as large as the largest supported hash context. So for the time being, this specification keeps a pointer. For uniformity, PSA will also have a pointer (we may simplify this later).
+
+```
+enum {
+ MBEDTLS_MD_ENGINE_LEGACY,
+ MBEDTLS_MD_ENGINE_PSA,
+} mbedtls_md_engine_t; // private type
+
+typedef struct mbedtls_md_context_t {
+ mbedtls_md_type_t type;
+#if defined(MBEDTLS_MD_SOME_PSA)
+ mbedtls_md_engine_t engine;
+#endif
+ void *md_ctx; // mbedtls_xxx_context or psa_hash_operation
+#if defined(MBEDTLS_MD_C)
+ void *hmac_ctx;
+#endif
+} mbedtls_md_context_t;
+```
+
+All fields are private.
+
+The `engine` field is almost redundant with knowledge about `type`. However, when an algorithm is available both via a legacy module and a PSA accelerator, we will choose based on the runtime availability of the accelerator when the context is set up. This choice needs to be recorded in the context structure.
+
+#### Inclusion of MD info structures
+
+MD light needs to support hashes that are only enabled through PSA. Therefore the `mbedtls_md_info_t` structures must be included based on `MBEDTLS_MD_CAN_xxx` instead of just the legacy module.
+
+The same criterion applies in `mbedtls_md_info_from_type`.
+
+#### Conversion to PSA encoding
+
+The implementation needs to convert from a legacy type encoding to a PSA encoding.
+
+```
+static inline psa_algorithm_t psa_alg_of_md_info(
+ const mbedtls_md_info_t *md_info );
+```
+
+#### Determination of PSA support at runtime
+
+```
+int psa_can_do_hash(psa_algorithm_t hash_alg);
+```
+
+The job of this private function is to return 1 if `hash_alg` can be performed through PSA now, and 0 otherwise. It is only defined on algorithms that are enabled via PSA.
+
+As a starting point, return 1 if PSA crypto's driver subsystem has been initialized.
+
+Usage note: for algorithms that are not enabled via PSA, calling `psa_can_do_hash` is generally safe: whether it returns 0 or 1, you can call a PSA hash function on the algorithm and it will return `PSA_ERROR_NOT_SUPPORTED`.
+
+#### Support for PSA dispatch in hash operations
+
+Each function that performs some hash operation or context management needs to know whether to dispatch via PSA or legacy.
+
+If given an established context, use its `engine` field.
+
+If given an algorithm as an `mbedtls_md_type_t type` (possibly being the `type` field of a `const mbedtls_md_info_t *`):
+
+* If there is a PSA accelerator for this hash and `psa_can_do_hash(alg)`, call the corresponding PSA function, and if applicable set the engine to `MBEDTLS_MD_ENGINE_PSA`. (Skip this is `MBEDTLS_MD_SOME_PSA` is not defined.)
+* Otherwise dispatch to the legacy module based on the type as currently done. (Skip this is `MBEDTLS_MD_SOME_LEGACY` is not defined.)
+* If no dispatch is possible, return `MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE`.
+
+Note that this assumes that an operation that has been started via PSA can be completed. This implies that `mbedtls_psa_crypto_free` must not be called while an operation using PSA is in progress. Document this.
+
+#### Error code conversion
+
+After calling a PSA function, MD light calls `mbedtls_md_error_from_psa` to convert its status code.
+
+### Support all legacy algorithms in PSA
+
+As discussed in [“Implications between legacy availability and PSA availability”](#implications-between-legacy-availability-and-psa-availability), we require the following property:
+
+> If an algorithm has a legacy implementation, it is also available through PSA.
+
+When `MBEDTLS_PSA_CRYPTO_CONFIG` is disabled, this is already the case. When is enabled, we will now make it so as well. Change `include/mbedtls/config_psa.h` accordingly.
+
+### MD light optimizations
+
+This section is not necessary to implement MD light, but will cut down its code size.
+
+#### Split names out of MD light
+
+Remove hash names from `mbedtls_md_info_t`. Use a simple switch-case or a separate list to implement `mbedtls_md_info_from_string` and `mbedtls_md_get_name`.
+
+#### Remove metadata from the info structure
+
+In `mbedtls_md_get_size` and in modules that want a hash's block size, instead of looking up hash metadata in the info structure, call the PSA macros.
+
+#### Optimize type conversions
+
+To allow optimizing conversions between `mbedtls_md_type_t` and `psa_algorithm_t`, renumber the `mbedtls_md_type_t` enum so that the values are the 8 lower bits of the PSA encoding.
+
+With this optimization,
+```
+static inline psa_algorithm_t psa_alg_of_md_info(
+ const mbedtls_md_info_t *md_info )
+{
+ if( md_info == NULL )
+ return( PSA_ALG_NONE );
+ return( PSA_ALG_CATEGORY_HASH | md_info->type );
+}
+```
+
+Work in progress on this conversion is at https://github.com/gilles-peskine-arm/mbedtls/tree/hash-unify-ids-wip-1
+
+#### Unify HMAC with PSA
+
+PSA has its own HMAC implementation. In builds with both `MBEDTLS_MD_C` and `PSA_WANT_ALG_HMAC` not fully provided by drivers, we should have a single implementation. Replace the one in `md.h` by calls to the PSA driver interface. This will also give mixed-domain modules access to HMAC accelerated directly by a PSA driver (eliminating the need to a HMAC interface in software if all supported hashes have an accelerator that includes HMAC support).
+
+### Improving support for `MBEDTLS_PSA_CRYPTO_CLIENT`
+
+So far, MD light only dispatches to PSA if an algorithm is available via `MBEDTLS_PSA_CRYPTO_C`, not if it's available via `MBEDTLS_PSA_CRYPTO_CLIENT`. This is acceptable because `MBEDTLS_USE_PSA_CRYPTO` requires `MBEDTLS_PSA_CRYPTO_C`, hence mixed-domain code never invokes PSA.
+
+The architecture can be extended to support `MBEDTLS_PSA_CRYPTO_CLIENT` with a little extra work. Here is an overview of the task breakdown, which should be fleshed up after we've done the first [migration](#migration-to-md-light):
+
+* Compile-time dependencies: instead of checking `defined(MBEDTLS_PSA_CRYPTO_C)`, check `defined(MBEDTLS_PSA_CRYPTO_C) || defined(MBEDTLS_PSA_CRYPTO_CLIENT)`.
+* Implementers of `MBEDTLS_PSA_CRYPTO_CLIENT` will need to provide `psa_can_do_hash()` (or a more general function `psa_can_do`) alongside `psa_crypto_init()`. Note that at this point, it will become a public interface, hence we won't be able to change it at a whim.
+
+### Internal "block cipher" abstraction (previously known as "Cipher light")
+
+#### Definition
+
+The new module is automatically enabled in `config_adjust_legacy_crypto.h` by modules that need
+it (namely: CCM, GCM) only when `CIPHER_C` is not available, or the new module
+is needed for PSA dispatch (see next section). Note: CCM and GCM currently
+depend on the full `CIPHER_C` (enforced by `check_config.h`); this hard
+dependency would be replaced by the above auto-enablement.
+
+The following API functions are offered:
+```
+void mbedtls_block_cipher_init(mbedtls_block_cipher_context_t *ctx);
+void mbedtls_block_cipher_free(mbedtls_block_cipher_context_t *ctx);
+int mbedtls_block_cipher_setup(mbedtls_block_cipher_context_t *ctx,
+ mbedtls_cipher_id_t cipher_id);
+int mbedtls_block_cipher_setkey(mbedtls_block_cipher_context_t *ctx,
+ const unsigned char *key,
+ unsigned key_bitlen);
+int mbedtls_block_cipher_encrypt(mbedtls_block_cipher_context_t *ctx,
+ const unsigned char input[16],
+ unsigned char output[16]);
+```
+
+The only supported ciphers are AES, ARIA and Camellia. They are identified by
+an `mbedtls_cipher_id_t` in the `setup()` function, because that's how they're
+identifed by callers (GCM/CCM).
+
+#### Block cipher dual dispatch
+
+Support for dual dispatch in the new internal module `block_cipher` is extremely similar to that in MD light.
+
+A block cipher context contains either a legacy module's context (AES, ARIA, Camellia) or a PSA key identifier; it has a field indicating which one is in use. All fields are private.
+
+The `engine` field is almost redundant with knowledge about `type`. However, when an algorithm is available both via a legacy module and a PSA accelerator, we will choose based on the runtime availability of the accelerator when the context is set up. This choice needs to be recorded in the context structure.
+
+Support is determined at runtime using the new internal function
+```
+int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg);
+```
+
+The job of this private function is to return 1 if `hash_alg` can be performed through PSA now, and 0 otherwise. It is only defined on algorithms that are enabled via PSA. As a starting point, return 1 if PSA crypto's driver subsystem has been initialized.
+
+Each function in the module needs to know whether to dispatch via PSA or legacy. All functions consult the context's `engine` field, except `setup()` which will set it according to the key type and the return value of `psa_can_do_cipher()` as discussed above.
+
+Note that this assumes that an operation that has been started via PSA can be completed. This implies that `mbedtls_psa_crypto_free` must not be called while an operation using PSA is in progress.
+
+After calling a PSA function, `block_cipher` functions call `mbedtls_cipher_error_from_psa` to convert its status code.
diff --git a/docs/architecture/psa-migration/outcome-analysis.sh b/docs/architecture/psa-migration/outcome-analysis.sh
new file mode 100755
index 0000000..1805a3c
--- /dev/null
+++ b/docs/architecture/psa-migration/outcome-analysis.sh
@@ -0,0 +1,140 @@
+#!/bin/sh
+
+# This script runs tests before and after a PR and analyzes the results in
+# order to highlight any difference in the set of tests skipped.
+#
+# It can be used to check the first testing criterion mentioned in strategy.md,
+# end of section "Supporting builds with drivers without the software
+# implementation", namely: the sets of tests skipped in the default config and
+# the full config must be the same before and after the PR.
+#
+# USAGE:
+# - First, commit any uncommited changes. (Also, see warning below.)
+# - Then launch --> [SKIP_SSL_OPT=1] docs/architecture/psa-migration/outcome-analysis.sh
+# - SKIP_SSL_OPT=1 can optionally be set to skip ssl-opt.sh tests
+#
+# WARNING: this script checks out a commit other than the head of the current
+# branch; it checks out the current branch again when running successfully,
+# but while the script is running, or if it terminates early in error, you
+# should be aware that you might be at a different commit than expected.
+#
+# NOTE: you can comment out parts that don't need to be re-done when
+# re-running this script (for example "get numbers before this PR").
+
+set -eu
+
+: ${SKIP_SSL_OPT:=0}
+
+cleanup() {
+ make clean
+ git checkout -- include/mbedtls/mbedtls_config.h include/psa/crypto_config.h
+}
+
+record() {
+ export MBEDTLS_TEST_OUTCOME_FILE="$PWD/outcome-$1.csv"
+ rm -f $MBEDTLS_TEST_OUTCOME_FILE
+
+ make check
+
+ if [ $SKIP_SSL_OPT -eq 0 ]; then
+ make -C programs ssl/ssl_server2 ssl/ssl_client2 \
+ test/udp_proxy test/query_compile_time_config
+ tests/ssl-opt.sh
+ fi
+}
+
+# save current HEAD.
+# Note: this can optionally be updated to
+# HEAD=$(git branch --show-current)
+# when using a Git version above 2.22
+HEAD=$(git rev-parse --abbrev-ref HEAD)
+
+# get the numbers before this PR for default and full
+cleanup
+git checkout $(git merge-base HEAD development)
+
+record "before-default"
+
+cleanup
+
+scripts/config.py full
+record "before-full"
+
+# get the numbers now for default and full
+cleanup
+git checkout $HEAD
+
+record "after-default"
+
+cleanup
+
+scripts/config.py full
+record "after-full"
+
+cleanup
+
+# analysis
+
+populate_suites () {
+ SUITES=''
+ make generated_files >/dev/null
+ data_files=$(cd tests/suites && echo *.data)
+ for data in $data_files; do
+ suite=${data%.data}
+ SUITES="$SUITES $suite"
+ done
+ make neat
+
+ if [ $SKIP_SSL_OPT -eq 0 ]; then
+ SUITES="$SUITES ssl-opt"
+ extra_files=$(cd tests/opt-testcases && echo *.sh)
+ for extra in $extra_files; do
+ suite=${extra%.sh}
+ SUITES="$SUITES $suite"
+ done
+ fi
+}
+
+compare_suite () {
+ ref="outcome-$1.csv"
+ new="outcome-$2.csv"
+ suite="$3"
+
+ pattern_suite=";$suite;"
+ total=$(grep -c "$pattern_suite" "$ref")
+ sed_cmd="s/^.*$pattern_suite\(.*\);SKIP.*/\1/p"
+ sed -n "$sed_cmd" "$ref" > skipped-ref
+ sed -n "$sed_cmd" "$new" > skipped-new
+ nb_ref=$(wc -l <skipped-ref)
+ nb_new=$(wc -l <skipped-new)
+
+ name=${suite#test_suite_}
+ printf "%40s: total %4d; skipped %4d -> %4d\n" \
+ $name $total $nb_ref $nb_new
+ if diff skipped-ref skipped-new | grep '^> '; then
+ ret=1
+ else
+ ret=0
+ fi
+ rm skipped-ref skipped-new
+ return $ret
+}
+
+compare_builds () {
+ printf "\n*** Comparing $1 -> $2 ***\n"
+ failed=''
+ for suite in $SUITES; do
+ if compare_suite "$1" "$2" "$suite"; then :; else
+ failed="$failed $suite"
+ fi
+ done
+ if [ -z "$failed" ]; then
+ printf "No coverage gap found.\n"
+ else
+ printf "Suites with less coverage:%s\n" "$failed"
+ fi
+}
+
+populate_suites
+compare_builds before-default after-default
+compare_builds before-full after-full
diff --git a/docs/architecture/psa-migration/psa-legacy-bridges.md b/docs/architecture/psa-migration/psa-legacy-bridges.md
new file mode 100644
index 0000000..912344e
--- /dev/null
+++ b/docs/architecture/psa-migration/psa-legacy-bridges.md
@@ -0,0 +1,344 @@
+Bridges between legacy and PSA crypto APIs
+==========================================
+
+## Introduction
+
+### Goal of this document
+
+This document explores the needs of applications that use both Mbed TLS legacy crypto interfaces and PSA crypto interfaces. Based on [requirements](#requirements), we [analyze gaps](#gap-analysis) and [API design](#api-design).
+
+This is a design document. The target audience is library maintainers. See the companion document [“Transitioning to the PSA API”](../../psa-transition.md) for a user focus on the same topic.
+
+### Keywords
+
+* [TODO] A part of the analysis that isn't finished.
+* [OPEN] Open question: a specific aspect of the design where there are several plausible decisions.
+* [ACTION] A finalized part of the design that will need to be carried out.
+
+### Context
+
+Mbed TLS 3.x supports two cryptographic APIs:
+
+* The legacy API `mbedtls_xxx` is inherited from PolarSSL.
+* The PSA API `psa_xxx` was introduced in Mbed TLS 2.17.
+
+Mbed TLS is gradually shifting from the legacy API to the PSA API. Mbed TLS 4.0 will be the first version where the PSA API is considered the main API, and large parts of the legacy API will be removed.
+
+In Mbed TLS 4.0, the cryptography will be provided by a separate project [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto). For simplicity, in this document, we just refer to the whole as “Mbed TLS”.
+
+### Document history
+
+This document was originally written when preparing Mbed TLS 3.6. Mbed TLS 3.6 includes both PSA and legacy APIs covering largely overlapping ground. Many legacy APIs will be removed in Mbed TLS 4.0.
+
+## Requirements
+
+### Why mix APIs?
+
+There is functionality that is tied to one API and is not directly available in the other API:
+
+* Only PSA fully supports PSA accelerators and secure element integration.
+* Only PSA supports isolating cryptographic material in a secure service.
+* The legacy API has features that are not present (yet) in PSA, notably parsing and formatting asymmetric keys.
+
+The legacy API can partially leverage PSA features via `MBEDTLS_USE_PSA_CRYPTO`, but this has limited scope.
+
+In addition, many applications cannot be migrated in a single go. For large projects, it is impractical to rewrite a significant part of the code all at once. (For example, Mbed TLS itself will have taken more than 6 years to transition.) Projects that use one or more library in addition to Mbed TLS must follow the evolution of these libraries, each of which might have its own pace.
+
+### Where mixing happens
+
+Mbed TLS can be, and normally is, built with support for both APIs. Therefore no special effort is necessary to allow an application to use both APIs.
+
+Special effort is necessary to use both APIs as part of the implementation of the same feature. From an informal analysis of typical application requirements, we identify four parts of the use of cryptography which can be provided by different APIs:
+
+* Metadata manipulation: parsing and producing encrypted or signed files, finding mutually supported algorithms in a network protocol negotiation, etc.
+* Key management: parsing, generating, deriving and formatting cryptographic keys.
+* Data manipulation other than keys. In practice, most data formats within the scope of the legacy crypto APIs are trivial (ciphertexts, hashes, MACs, shared secrets). The one exception is ECDSA signatures.
+* Cryptographic operations: hash, sign, encrypt, etc.
+
+From this, we deduce the following requirements:
+
+* Convert between PSA and legacy metadata.
+* Creating a key with the legacy API and consuming it in the PSA API.
+* Creating a key with the PSA API and consuming it in the legacy API.
+* Manipulating data formats, other than keys, where the PSA API is lacking.
+
+### Scope limitations
+
+The goal of this document is to bridge the legacy API and the PSA API. The goal is not to provide a PSA way to do everything that is currently possible with the legacy API. The PSA API is less flexible in some regards, and extending it is out of scope in the present study.
+
+With respect to the legacy API, we do not consider functionality of low-level modules for individual algorithms. Our focus is on applications that use high-level legacy crypto modules (md, cipher, pk) and need to combine that with uses of the PSA APIs.
+
+## Gap analysis
+
+The document [“Transitioning to the PSA API”](../../psa-transition.md) enumerates the public header files in Mbed TLS 3.4 and the API elements (especially enums and functions) that they provide, listing PSA equivalents where they exist. There are gaps in two cases:
+
+* Where the PSA equivalents do not provide the same functionality. A typical example is parsing and formatting asymmetric keys.
+* To convert between data representations used by legacy APIs and data representations used by PSA APIs.
+
+Based on “[Where mixing happens](#where-mixing-happens)”, we focus the gap analysis on two topics: metadata and keys. This chapter explores the gaps in each family of cryptographic mechanisms.
+
+### Generic metadata gaps
+
+#### Need for error code conversion
+
+Do we need public functions to convert between `MBEDTLS_ERR_xxx` error codes and `PSA_ERROR_xxx` error codes? We have such functions for internal use.
+
+Mbed TLS needs these conversions because it has many functions that expose one API (legacy/API) but are implemented on top of the other API. Most applications would convert legacy and PSA error code to their own error codes, and converting between `MBEDTLS_ERR_xxx` error codes and `PSA_ERROR_xxx` is not particularly helpful for that. Application code might need such conversion functions when implementing an X.509 or TLS callback (returning `MBEDTLS_ERR_xxx`) on top of PSA functions, but this is a very limited use case.
+
+Conclusion: no need for public error code conversion functions.
+
+### Hash gap analysis
+
+Hashes do not involve keys, and involves no nontrivial data format. Therefore the only gap is with metadata, namely specifying a hash algorithm.
+
+Hashes are often used as building blocks for other mechanisms (HMAC, signatures, key derivation, etc.). Therefore metadata about hashes is relevant not only when calculating hashes, but also when performing many other cryptographic operations.
+
+Gap: functions to convert between `psa_algorithm_t` hash algorithms and `mbedtls_md_type_t`. Such functions exist in Mbed TLS 3.5 (`mbedtls_md_psa_alg_from_type`, `mbedtls_md_type_from_psa_alg`) but they are declared only in private headers.
+
+### MAC gap analysis
+
+[TODO]
+
+### Cipher and AEAD gap analysis
+
+[TODO]
+
+### Key derivation gap analysis
+
+[TODO]
+
+### Random generation gap analysis
+
+[TODO]
+
+### Asymmetric cryptography gap analysis
+
+#### Asymmetric cryptography metadata
+
+The legacy API only has generic support for two key types: RSA and ECC, via the pk module. ECC keys can also be further classified according to their curve. The legacy API also supports DHM (Diffie-Hellman-Merkle = FFDH: finite-field Diffie-Hellman) keys, but those are not integrated in the pk module.
+
+An RSA or ECC key can potentially be used for different algorithms in the scope of the pk module:
+
+* RSA: PKCS#1v1.5 signature, PSS signature, PKCS#1v1.5 encryption, OAEP encryption.
+* ECC: ECDSA signature (randomized or deterministic), ECDH key agreement (via `mbedtls_pk_ec`).
+
+ECC keys are also involved in EC-JPAKE, but this happens internally: the EC-JPAKE interface only needs one piece of metadata, namely, to identify a curve.
+
+Since there is no algorithm that can be used with multiple types, and PSA keys have a policy that (for the most part) limits them to one algorithm, there does not seem to be a need to convert between legacy and PSA asymmetric key types on their own. The useful metadata conversions are:
+
+* Selecting an **elliptic curve**.
+
+ This means converting between an `mbedtls_ecp_group_id` and a pair of `{psa_ecc_family_t; size_t}`.
+
+ This is fulfilled by `mbedtls_ecc_group_to_psa` and `mbedtls_ecc_group_from_psa`, which were introduced into the public API between Mbed TLS 3.5 and 3.6 ([#8664](https://github.com/Mbed-TLS/mbedtls/pull/8664)).
+
+* Selecting A **DHM group**.
+
+ PSA only supports predefined groups, whereas legacy only supports ad hoc groups. An existing application referring to `MBEDTLS_DHM_RFC7919_FFDHExxx` values would need to refer to `PSA_DH_FAMILY_RFC7919`; an existing application using arbitrary groups cannot migrate to PSA.
+
+* Simultaneously supporting **a key type and an algorithm**.
+
+ On the legacy side, this is an `mbedtls_pk_type_t` value and more. For ECDSA, the choice between randomized and deterministic is made at compile time. For RSA, the choice of encryption or signature algorithm is made either by configuring the underlying `mbedtls_rsa_context` or when calling the operation function.
+
+ On the PSA side, this is a `psa_key_type_t` value and an algorithm which is normally encoded as policy information in a `psa_key_attributes_t`. The algorithm is also needed in its own right when calling operation functions.
+
+#### Using a legacy key pair or public key with PSA
+
+There are several scenarios where an application has a legacy key pair or public key (`mbedtls_pk_context`) and needs to create a PSA key object (`psa_key_id_t`).
+
+Reasons for first creating a legacy key object, where it's impossible or impractical to directly create a PSA key:
+
+* A very common case where the input is a legacy key object is parsing. PSA does not (yet) have an equivalent of the `mbedtls_pk_parse_xxx` functions.
+* The PSA key creation interface is less flexible in some cases. In particular, PSA RSA key generation does not (yet) allow choosing the public exponent.
+* The pk object may be created by a part of the application (or a third-party library) that hasn't been migrated to the PSA API yet.
+
+Reasons for needing a PSA key object:
+
+* Using the key with third-party interface that takes a PSA key identifier as input. (Mbed TLS itself has a few TLS functions that take PSA key identifiers, but as of Mbed TLS 3.5, it is always possible to use a legacy key instead.)
+* Benefiting from a PSA accelerator, or from PSA's world separation, even without `MBEDTLS_USE_PSA_CRYPTO`. (Not a priority scenario: we generally expect people to activate `MBEDTLS_USE_PSA_CRYPTO` at an early stage of their migration to PSA.)
+
+Gap: a way to create a PSA key object from an `mbedtls_pk_context`. This partially exists in the form of `mbedtls_pk_wrap_as_opaque`, but it is not fully satisfactory, for reasons that are detailed in “[API to create a PSA key from a PK context](#api-to-create-a-psa-key-from-a-pk-context)” below.
+
+#### Using a PSA key as a PK context
+
+There are several scenarios where an application has a PSA key and needs to use it through an interface that wants an `mbedtls_pk_context` object. Typically, there is an existing key in the PSA key store (possibly in a secure element and non-exportable), and the key needs to be used in an interface that requires a `mbedtls_pk_context *` input, such as Mbed TLS's X.509 and TLS APIs or a similar third-party interface, or the `mbedtls_pk_write_xxx` interfaces which do not (yet) have PSA equivalents.
+
+There is a function `mbedtls_pk_setup_opaque` that mostly does this. However, it has several limitations:
+
+* It creates a PK key of type `MBEDTLS_PK_OPAQUE` that wraps the PSA key. This is good enough in some scenarios, but not others. For example, it's ok for pkwrite, because we've upgraded the pkwrite code to handle `MBEDTLS_PK_OPAQUE`. That doesn't help users of third-party libraries that haven't yet been upgraded.
+* It ties the lifetime of the PK object to the PSA key, which is error-prone: if the PSA key is destroyed but the PK object isn't, there is no way to reliably detect any subsequent misuse of the PK object.
+* It is only available under `MBEDTLS_USE_PSA_CRYPTO`. This is not a priority concern, since we generally expect people to activate `MBEDTLS_USE_PSA_CRYPTO` at an early stage of their migration to PSA. However, this function is useful to use specific PSA keys in X.509/TLS regardless of whether X.509/TLS use the PSA API for all cryptographic operations, so this is a wart in the current API.
+
+It therefore appears that we need two ways to “convert” a PSA key to PK:
+
+* Wrapping, which is what `mbedtls_pk_setup_opaque` does. This works for any PSA key but is limited by the key's lifetime and creates a PK object with limited functionality.
+* Copying, which requires a new function. This requires an exportable key but creates a fully independent, fully functional PK object.
+
+Gap: a way to copy a PSA key into a PK context. This can only be expected to work if the PSA key is exportable.
+
+After some discussion, have not identified anything we want to change in the behavior of `mbedtls_pk_setup_opaque`. We only want to generalize it to non-`MBEDTLS_USE_PSA_CRYPTO` and to document it better.
+
+#### Signature formats
+
+The pk module uses signature formats intended for X.509. The PSA module uses the simplest sensible signature format.
+
+* For RSA, the formats are the same.
+* For ECDSA, PSA uses a fixed-size concatenation of (r,s), whereas X.509 and pk use an ASN.1 DER encoding of the sequence (r,s).
+
+Gap: We need APIs to convert between these two formats. The conversion code already exists under the hood, but it's in pieces that can't be called directly.
+
+There is a design choice here: do we provide conversions functions for ECDSA specifically, or do we provide conversion functions that take an algorithm as argument and just happen to be a no-op with RSA? One factor is plausible extensions. These conversions functions will remain useful in Mbed TLS 4.x and perhaps beyond. We will at least add EdDSA support, and its signature encoding is the fixed-size concatenation (r,s) even in X.509. We may well also add support for some post-quantum signatures, and their concrete format is still uncertain.
+
+Given the uncertainty, it would be nice to provide a sufficiently generic interface to convert between the PSA and the pk signature format, parametrized by the algorithm. However, it is difficult to predict exactly what parameters are needed. For example, converting from an ASN.1 ECDSA signature to (r,s) requires the knowledge of the curve, or at least the curve's size. Therefore we are not going to add a generic function at this stage.
+
+For ECDSA, there are two plausible APIs: follow the ASN.1/X.509 write/parse APIs, or present an ordinary input/output API. The ASN.1 APIs are the way they are to accommodate nested TLV structures. But ECDSA signatures do not appear nested in TLV structures in either TLS (there's just a signature field) or X.509 (the signature is inside a BITSTRING, not directly in a SEQUENCE). So there does not seem to be a need for an ASN.1-like API for the ASN.1 format, just the format conversion itself in a buffer that just contains the signature.
+
+#### Asymmetric cryptography TODO
+
+[TODO] Other gaps?
+
+## New APIs
+
+This section presents new APIs to implement based on the [gap analysis](#gap-analysis).
+
+### General notes
+
+Each action to implement a function entails:
+
+* Implement the library function.
+* Document it precisely, including error conditions.
+* Unit-test it.
+* Mention it where relevant in the PSA transition guide.
+
+### Hash APIs
+
+Based on the [gap analysis](#hash-gap-analysis):
+
+[ACTION] [#8340](https://github.com/Mbed-TLS/mbedtls/issues/8340) Move `mbedtls_md_psa_alg_from_type` and `mbedtls_md_type_from_psa_alg` from `library/md_psa.h` to `include/mbedtls/md.h`.
+
+### MAC APIs
+
+[TODO]
+
+### Cipher and AEAD APIs
+
+[TODO]
+
+### Key derivation APIs
+
+[TODO]
+
+### Random generation APIs
+
+[TODO]
+
+### Asymmetric cryptography APIs
+
+#### Asymmetric cryptography metadata APIs
+
+Based on the [gap analysis](#asymmetric-cryptography-metadata):
+
+* No further work is needed about RSA specifically. The amount of metadata other than hashes is sufficiently small to be handled in ad hoc ways in applications, and hashes have [their own conversions](#hash-apis).
+* No further work is needed about ECC specifically. We have just added adequate functions.
+* No further work is needed about DHM specifically. There is no good way to translate the relevant information.
+* [OPEN] Is there a decent way to convert between `mbedtls_pk_type_t` plus extra information, and `psa_key_type_t` plus policy information? The two APIs are different in crucial ways, with different splits between key type, policy information and operation algorithm.
+ Thinking so far: there isn't really a nice way to present this conversion. For a specific key, `mbedtls_pk_get_psa_attributes` and `mbedtls_pk_copy_from_psa` do the job.
+
+#### API to create a PSA key from a PK context
+
+Based on the [gap analysis](#using-a-legacy-key-pair-or-public-key-with-psa):
+
+Given an `mbedtls_pk_context`, we want a function that creates a PSA key with the same key material and algorithm. “Same key material” is straightforward, but “same algorithm” is not, because a PK context has incomplete algorithm information. For example, there is no way to distinguish between an RSA key that is intended for signature or for encryption. Between algorithms of the same nature, there is no way to distinguish a key intended for PKCS#1v1.5 and one intended for PKCS#1v2.1 (OAEP/PSS): this is indicated in the underlying RSA context, but the indication there is only a default that can be overridden by calling `mbedtls_pk_{sign,verify}_ext`. Also there is no way to distinguish between `PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg)` and `PSA_ALG_RSA_PKCS1V15_SIGN_RAW`: in the legacy interface, this is only determined when actually doing a signature/verification operation. Therefore the function that creates the PSA key needs extra information to indicate which algorithm to put in the key's policy.
+
+When creating a PSA key, apart from the key material, the key is determined by attributes, which fall under three categories:
+
+* Type and size. These are directly related to the key material and can be deduced from it if the key material is in a structured format, which is the case with an `mbedtls_pk_context` input.
+* Policy. This includes the chosen algorithm, which as discussed above cannot be fully deduced from the `mbedtls_pk_context` object. Just choosing one algorithm is problematic because it doesn't allow implementation-specific extensions, such as Mbed TLS's enrollment algorithm. The intended usage flags cannot be deduced from the PK context either, but the conversion function could sensibly just enable all the relevant usage flags. Users who want a more restrictive usage can call `psa_copy_key` and `psa_destroy_key` to obtain a PSA key object with a more restrictive usage.
+* Persistence and location. This is completely orthogonal to the information from the `mbedtls_pk_context` object. It is convenient, but not necessary, for the conversion function to allow customizing these aspects. If it doesn't, users can call the conversion function and then call `psa_copy_key` and `psa_destroy_key` to move the key to its desired location.
+
+To allow the full flexibility around policies, and make the creation of a persistent key more convenient, the conversion function shall take a `const psa_key_attributes_t *` input, like all other functions that create a PSA key. In addition, there shall be a helper function to populate a `psa_key_attributes_t` with a sensible default. This lets the caller choose a more flexible, or just different usage policy, unlike the default-then-copy approach which only allows restricting the policy.
+
+This is close to the existing function `mbedtls_pk_wrap_as_opaque`, but does not bake in the implementation-specific consideration that a PSA key has exactly two algorithms, and also allows the caller to benefit from default for the policy in more cases.
+
+[ACTION] [#8708](https://github.com/Mbed-TLS/mbedtls/issues/8708) Implement `mbedtls_pk_get_psa_attributes` and `mbedtls_pk_import_into_psa` as described below. These functions are available whenever `MBEDTLS_PK_C` and `MBEDTLS_PSA_CRYPTO_CLIENT` are both defined. Deprecate `mbedtls_pk_wrap_as_opaque`.
+
+```
+int mbedtls_pk_get_psa_attributes(const mbedtls_pk_context *pk,
+ psa_key_usage_flags_t usage,
+ psa_key_attributes_t *attributes);
+int mbedtls_pk_import_into_psa(const mbedtls_pk_context *pk,
+ const psa_key_attributes_t *attributes,
+ mbedtls_svc_key_id_t *key_id);
+```
+
+* `mbedtls_pk_get_psa_attributes` does not change the id/lifetime fields of the attributes (which indicate a volatile key by default).
+ * [OPEN] Or should it reset them to 0? Resetting is more convenient for the case where the pk key is a `MBEDTLS_PK_OPAQUE`. But that's an uncommon use case. It's probably less surprising if this function leaves the lifetime-related alone, since its job is to set the type-related and policy-related attributes.
+* `mbedtls_pk_get_psa_attributes` sets the type and size based on what's in the pk context.
+ * The key type is a key pair if the context contains a private key and the indicated usage is a private-key usage. The key type is a public key if the context only contains a public key, in which case a private-key usage is an error.
+* `mbedtls_pk_get_psa_attributes` sets the usage flags based on the `usage` parameter. It extends the usage to other usage that is possible:
+ * `EXPORT` and `COPY` are always set.
+ * If `SIGN_{HASH,MESSAGE}` is set then so is `VERIFY_{HASH,MESSAGE}`.
+ * If `DECRYPT` is set then so is `ENCRYPT`.
+ * It is an error if `usage` has more than one flag set, or has a usage that is incompatible with the key type.
+* `mbedtls_pk_get_psa_attributes` sets the algorithm usage policy based on information in the key object and on `usage`.
+ * For an RSA key with the `MBEDTLS_RSA_PKCS_V15` padding mode, the algorithm policy is `PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` for a sign/verify usage, and `PSA_ALG_RSA_PKCS1V15_CRYPT` for an encrypt/decrypt usage.
+ * For an RSA key with the `MBEDTLS_RSA_PKCS_V21` padding mode, the algorithm policy is `PSA_ALG_RSA_PSS_ANY_SALT(PSA_ALG_ANY_HASH)` for a sign/verify usage, and `PSA_ALG_RSA_OAEP(hash)` for an encrypt/decrypt usage where `hash` is from the RSA key's parameters. (Note that `PSA_ALG_ANY_HASH` is only allowed in signature algorithms.)
+ * For an `MBEDTLS_PK_ECKEY` or `MBEDTLS_PK_ECDSA` with a sign/verify usage, the algorithm policy is `PSA_ALG_DETERMINISTIC_ECDSA` if `MBEDTLS_ECDSA_DETERMINISTIC` is enabled and `PSA_ALG_ECDSA` otherwise. In either case, the hash policy is `PSA_ALG_ANY_HASH`.
+ * For an `MBEDTLS_PK_ECKEY` or `MBEDTLS_PK_ECDKEY_DH` with the usage `PSA_KEY_USAGE_DERIVE`, the algorithm is `PSA_ALG_ECDH`.
+ * For a `MBEDTLS_PK_OPAQUE`, this function reads the attributes of the existing PK key and copies them (without overriding the lifetime and key identifier in `attributes`), then applies a public-key restriction if needed.
+ * Public-key restriction: if `usage` is a public-key usage, change the type to the corresponding public-key type, and remove private-key usage flags from the usage flags read from the existing key.
+* `mbedtls_pk_import_into_psa` checks that the type field in the attributes is consistent with the content of the `mbedtls_pk_context` object (RSA/ECC, and availability of the private key).
+ * The key type can be a public key even if the private key is available.
+* `mbedtls_pk_import_into_psa` does not need to check the bit-size in the attributes: `psa_import_key` will do enough checks.
+* `mbedtls_pk_import_into_psa` does not check that the policy in the attributes is sensible. That's on the user.
+
+#### API to copy a PSA key to a PK context
+
+Based on the [gap analysis](#using-a-psa-key-as-a-pk-context):
+
+[ACTION] [#8709](https://github.com/Mbed-TLS/mbedtls/issues/8709) Implement `mbedtls_pk_copy_from_psa` as described below.
+
+```
+int mbedtls_pk_copy_from_psa(mbedtls_svc_key_id_t key_id,
+ mbedtls_pk_context *pk);
+```
+
+* `pk` must be initialized, but not set up.
+* It is an error if the key is neither a key pair nor a public key.
+* It is an error if the key is not exportable.
+* The resulting pk object has a transparent type, not `MBEDTLS_PK_OPAQUE`. That's `MBEDTLS_PK_RSA` for RSA keys (since pk objects don't use `MBEDTLS_PK_RSASSA_PSS` as a type), and `MBEDTLS_PK_ECKEY` for ECC keys (following the example of pkparse).
+* Once this function returns, the pk object is completely independent of the PSA key.
+* Calling `mbedtls_pk_sign`, `mbedtls_pk_verify`, `mbedtls_pk_encrypt`, `mbedtls_pk_decrypt` on the resulting pk context will perform an algorithm that is compatible with the PSA key's primary algorithm policy (`psa_get_key_algorithm`) if that is a matching operation type (sign/verify, encrypt/decrypt), but with no restriction on the hash (as if the policy had `PSA_ALG_ANY_HASH` instead of a specific hash, and with `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` merged with `PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg)`).
+ * For ECDSA, the choice of deterministic vs randomized will be based on the compile-time setting `MBEDTLS_ECDSA_DETERMINISTIC`, like `mbedtls_pk_sign` today.
+ * For an RSA key, the output key will allow both encrypt/decrypt and sign/verify regardless of the original key's policy. The original key's policy determines the output key's padding mode.
+ * The primary intent of this requirement is to allow an application to switch to PSA for creating the key material (for example to benefit from a PSA accelerator driver, or to start using a secure element), without modifying the code that consumes the key. For RSA keys, the PSA primary algorithm policy is how one conveys the same information as RSA key padding information in the legacy API. Convey this in the documentation.
+
+#### API to create a PK object that wraps a PSA key
+
+Based on the [gap analysis](#using-a-psa-key-as-a-pk-context):
+
+[ACTION] [#8712](https://github.com/Mbed-TLS/mbedtls/issues/8712) Clarify the documentation of `mbedtls_pk_setup_opaque` regarding which algorithms the resulting key will perform with `mbedtls_pk_sign`, `mbedtls_pk_verify`, `mbedtls_pk_encrypt`, `mbedtls_pk_decrypt`.
+
+[ACTION] [#8710](https://github.com/Mbed-TLS/mbedtls/issues/8710) Provide `mbedtls_pk_setup_opaque` whenever `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled, not just when `MBEDTLS_USE_PSA_CRYPTO` is enabled. This is nice-to-have, not critical. Update `use-psa-crypto.md` accordingly.
+
+[OPEN] What about `mbedtls_pk_sign_ext` and `mbedtls_pk_verify_ext`?
+
+#### API to convert between signature formats
+
+Based on the [gap analysis](#signature-formats):
+
+[ACTION] [#7765](https://github.com/Mbed-TLS/mbedtls/issues/7765) Implement `mbedtls_ecdsa_raw_to_der` and `mbedtls_ecdsa_der_to_raw` as described below.
+
+```
+int mbedtls_ecdsa_raw_to_der(size_t bits,
+ const unsigned char *raw, size_t raw_len,
+ unsigned char *der, size_t der_size, size_t *der_len);
+int mbedtls_ecdsa_der_to_raw(size_t bits,
+ const unsigned char *der, size_t der_len,
+ unsigned char *raw, size_t raw_size, size_t *raw_len);
+```
+
+* These functions convert between the signature format used by `mbedtls_pk_{sign,verify}{,_ext}` and the signature format used by `psa_{sign,verify}_{hash,message}`.
+* The input and output buffers can overlap.
+* The `bits` parameter is necessary in the DER-to-raw direction because the DER format lacks leading zeros, so something else needs to convey the size of (r,s). The `bits` parameter is redundant in the raw-to-DER direction, but we have it anyway because [it helps catch errors](https://github.com/Mbed-TLS/mbedtls/pull/8681#discussion_r1445980971), and it isn't a burden on the caller because the information is readily available in practice.
+* Should these functions rely on the ASN.1 module? We experimented [calling ASN.1 functions](https://github.com/Mbed-TLS/mbedtls/pull/8681), [reimplementing simpler ASN.1 functions](https://github.com/Mbed-TLS/mbedtls/pull/8696), and [providing the functions from the ASN.1 module](https://github.com/Mbed-TLS/mbedtls/pull/8703). Providing the functions from the ASN.1 module [won on a compromise of code size and simplicity](https://github.com/Mbed-TLS/mbedtls/issues/7765#issuecomment-1893670015).
diff --git a/docs/architecture/psa-migration/psa-limitations.md b/docs/architecture/psa-migration/psa-limitations.md
new file mode 100644
index 0000000..29d7c53
--- /dev/null
+++ b/docs/architecture/psa-migration/psa-limitations.md
@@ -0,0 +1,337 @@
+This document lists current limitations of the PSA Crypto API (as of version
+1.1) that may impact our ability to (1) use it for all crypto operations in
+TLS and X.509 and (2) support isolation of all long-term secrets in TLS (that
+is, goals G1 and G2 in [strategy.md](strategy.md) in the same directory).
+
+This is supposed to be a complete list, based on a exhaustive review of crypto
+operations done in TLS and X.509 code, but of course it's still possible that
+subtle-but-important issues have been missed. The only way to be really sure
+is, of course, to actually do the migration work.
+
+Limitations relevant for G1 (performing crypto operations)
+==========================================================
+
+Restartable (aka interruptible) ECC operations
+----------------------------------------------
+
+Support for interruptible ECDSA sign/verify was added to PSA in Mbed TLS 3.4.
+However, support for interruptible ECDH is not present yet. Also, PK, X.509 and
+TLS have not yet been adapted to take advantage of the new PSA APIs. See:
+- <https://github.com/Mbed-TLS/mbedtls/issues/7292>;
+- <https://github.com/Mbed-TLS/mbedtls/issues/7293>;
+- <https://github.com/Mbed-TLS/mbedtls/issues/7294>.
+
+Currently, when `MBEDTLS_USE_PSA_CRYPTO` and `MBEDTLS_ECP_RESTARTABLE` are
+both enabled, some operations that should be restartable are not (ECDH in TLS
+1.2 clients using ECDHE-ECDSA), as they are using PSA instead, and some
+operations that should use PSA do not (signature generation & verification) as
+they use the legacy API instead, in order to get restartable behaviour.
+
+Things that are in the API but not implemented yet
+--------------------------------------------------
+
+PSA Crypto has an API for FFDH, but it's not implemented in Mbed TLS yet.
+(Regarding FFDH, see the next section as well.) See issue [3261][ffdh] on
+github.
+
+[ffdh]: https://github.com/Mbed-TLS/mbedtls/issues/3261
+
+Arbitrary parameters for FFDH
+-----------------------------
+
+(See also the first paragraph in the previous section.)
+
+Currently, the PSA Crypto API can only perform FFDH with a limited set of
+well-known parameters (some of them defined in the spec, but implementations
+are free to extend that set).
+
+TLS 1.2 (and earlier) on the other hand have the server send explicit
+parameters (P and G) in its ServerKeyExchange message. This has been found to
+be suboptimal for security, as it is prohibitively hard for the client to
+verify the strength of these parameters. This led to the development of RFC
+7919 which allows use of named groups in TLS 1.2 - however as this is only an
+extension, servers can still send custom parameters if they don't support the
+extension.
+
+In TLS 1.3 the situation will be simpler: named groups are the only
+option, so the current PSA Crypto API is a good match for that. (Not
+coincidentally, all the groups used by RFC 7919 and TLS 1.3 are included
+in the PSA specification.)
+
+There are several options here:
+
+1. Implement support for custom FFDH parameters in PSA Crypto: this would pose
+ non-trivial API design problem, but most importantly seems backwards, as
+the crypto community is moving away from custom FFDH parameters. (Could be
+done any time.)
+2. Drop the DHE-RSA and DHE-PSK key exchanges in TLS 1.2 when moving to PSA.
+ (For people who want some algorithmic variety in case ECC collapses, FFDH
+would still be available in TLS 1.3, just not in 1.2.) (Can only be done in
+4.0 or another major version.)
+3. Variant of the precedent: only drop client-side support. Server-side is
+ easy to support in terms of API/protocol, as the server picks the
+parameters: we just need remove the existing `mbedtls_ssl_conf_dh_param_xxx()`
+APIs and tell people to use `mbedtls_ssl_conf_groups()` instead. (Can only be
+done in 4.0 or another major version.)
+4. Implement RFC 7919, support DHE-RSA and DHE-PSK only in conjunction with it
+ when moving to PSA. Server-side would work as above; unfortunately
+client-side the only option is to offer named groups and break the handshake
+if the server didn't take on our offer. This is not fully satisfying, but is
+perhaps the least unsatisfying option in terms of result; it's also probably
+the one that requires the most work, but it would deliver value beyond PSA
+migration by implementing RFC 7919. (Implementing RFC 7919 could be done any
+time; making it mandatory can only be done in 4.0 or another major version.)
+
+As of early 2023, the plan is to go with option 2 in Mbed TLS 4.0, which has
+been announced on the mailing-list and got no push-back, see
+<https://github.com/Mbed-TLS/mbedtls/issues/5278>.
+
+RSA-PSS parameters
+------------------
+
+RSA-PSS signatures are defined by PKCS#1 v2, re-published as RFC 8017
+(previously RFC 3447).
+
+As standardized, the signature scheme takes several parameters, in addition to
+the hash algorithm potentially used to hash the message being signed:
+- a hash algorithm used for the encoding function
+- a mask generation function
+ - most commonly MGF1, which in turn is parametrized by a hash algorithm
+- a salt length
+- a trailer field - the value is fixed to 0xBC by PKCS#1 v2.1, but was left
+ configurable in the original scheme; 0xBC is used everywhere in practice.
+
+Both the existing `mbedtls_` API and the PSA API support only MGF1 as the
+generation function (and only 0xBC as the trailer field), but there are
+discrepancies in handling the salt length and which of the various hash
+algorithms can differ from each other.
+
+### API comparison
+
+- RSA:
+ - signature: `mbedtls_rsa_rsassa_pss_sign()`
+ - message hashed externally
+ - encoding hash = MGF1 hash (from context, or argument = message hash)
+ - salt length: always using the maximum legal value
+ - signature: `mbedtls_rsa_rsassa_pss_sign_ext()`
+ - message hashed externally
+ - encoding hash = MGF1 hash (from context, or argument = message hash)
+ - salt length: specified explicitly
+ - verification: `mbedtls_rsassa_pss_verify()`
+ - message hashed externally
+ - encoding hash = MGF1 hash (from context, or argument = message hash)
+ - salt length: any valid length accepted
+ - verification: `mbedtls_rsassa_pss_verify_ext()`
+ - message hashed externally
+ - encoding hash = MGF1 hash from dedicated argument
+ - expected salt length: specified explicitly, can specify "ANY"
+- PK:
+ - signature: not supported
+ - verification: `mbedtls_pk_verify_ext()`
+ - message hashed externally
+ - encoding hash = MGF1 hash, specified explicitly
+ - expected salt length: specified explicitly, can specify "ANY"
+- PSA:
+ - algorithm specification:
+ - hash alg used for message hashing, encoding and MGF1
+ - salt length can be either "standard" (<= hashlen, see note) or "any"
+ - signature generation:
+ - salt length: always <= hashlen (see note) and random salt
+ - verification:
+ - salt length: either <= hashlen (see note), or any depending on algorithm
+
+Note: above, "<= hashlen" means that hashlen is used if possible, but if it
+doesn't fit because the key is too short, then the maximum length that fits is
+used.
+
+The RSA/PK API is in principle more flexible than the PSA Crypto API. The
+following sub-sections study whether and how this matters in practice.
+
+### Use in X.509
+
+RFC 4055 Section 3.1 defines the encoding of RSA-PSS that's used in X.509.
+It allows independently specifying the message hash (also used for encoding
+hash), the MGF (and its hash if MGF1 is used), and the salt length (plus an
+extra parameter "trailer field" that doesn't vary in practice"). These can be
+encoded as part of the key, and of the signature. If both encoding are
+presents, all values must match except possibly for the salt length, where the
+value from the signature parameters is used.
+
+In Mbed TLS, RSA-PSS parameters can be parsed and displayed for various
+objects (certificates, CRLs, CSRs). During parsing, the following properties
+are enforced:
+- the extra "trailer field" parameter must have its default value
+- the mask generation function is MGF1
+- encoding hash = message hashing algorithm (may differ from MGF1 hash)
+
+When it comes to cryptographic operations, only two things are supported:
+- verifying the signature on a certificate from its parent;
+- verifying the signature on a CRL from the issuing CA.
+
+The verification is done using `mbedtls_pk_verify_ext()`.
+
+Note: since X.509 parsing ensures that message hash = encoding hash, and
+`mbedtls_pk_verify_ext()` uses encoding hash = mgf1 hash, it looks like all
+three hash algorithms must be equal, which would be good news as it would
+match a limitation of the PSA API.
+
+It is unclear what parameters people use in practice. It looks like by default
+OpenSSL picks saltlen = keylen - hashlen - 2 (tested with openssl 1.1.1f).
+The `certtool` command provided by GnuTLS seems to be picking saltlen = hashlen
+by default (tested with GnuTLS 3.6.13). FIPS 186-4 requires 0 <= saltlen <=
+hashlen.
+
+### Use in TLS
+
+In TLS 1.2 (or lower), RSA-PSS signatures are never used, except via X.509.
+
+In TLS 1.3, RSA-PSS signatures can be used directly in the protocol (in
+addition to indirect use via X.509). It has two sets of three signature
+algorithm identifiers (for SHA-256, SHA-384 and SHA-512), depending of what
+the OID of the public key is (rsaEncryption or RSASSA-PSS).
+
+In both cases, it specifies that:
+- the mask generation function is MGF1
+- all three hashes are equal
+- the length of the salt MUST be equal to the length of the digest algorithm
+
+When signing, the salt length picked by PSA is the one required by TLS 1.3
+(unless the key is unreasonably small).
+
+When verifying signatures, PSA will by default enforce the salt len is the one
+required by TLS 1.3.
+
+### Current testing - X509
+
+All test files use the default trailer field of 0xBC, as enforced by our
+parser. (There's a negative test for that using the
+`x509_parse_rsassa_pss_params` test function and hex data.)
+
+Files with "bad" in the name are expected to be invalid and rejected in tests.
+
+**Test certificates:**
+
+server9-bad-mgfhash.crt (announcing mgf1(sha224), signed with another mgf)
+ Hash Algorithm: sha256
+ Mask Algorithm: mgf1 with sha224
+ Salt Length: 0xDE
+server9-bad-saltlen.crt (announcing saltlen = 0xDE, signed with another len)
+ Hash Algorithm: sha256
+ Mask Algorithm: mgf1 with sha256
+ Salt Length: 0xDE
+server9-badsign.crt (one bit flipped in the signature)
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0xEA
+server9-defaults.crt
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0x14 (default)
+server9-sha224.crt
+ Hash Algorithm: sha224
+ Mask Algorithm: mgf1 with sha224
+ Salt Length: 0xE2
+server9-sha256.crt
+ Hash Algorithm: sha256
+ Mask Algorithm: mgf1 with sha256
+ Salt Length: 0xDE
+server9-sha384.crt
+ Hash Algorithm: sha384
+ Mask Algorithm: mgf1 with sha384
+ Salt Length: 0xCE
+server9-sha512.crt
+ Hash Algorithm: sha512
+ Mask Algorithm: mgf1 with sha512
+ Salt Length: 0xBE
+server9-with-ca.crt
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0xEA
+server9.crt
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0xEA
+
+These certificates are signed with a 2048-bit key. It appears that they are
+all using saltlen = keylen - hashlen - 2, except for server9-defaults which is
+using saltlen = hashlen.
+
+**Test CRLs:**
+
+crl-rsa-pss-sha1-badsign.pem
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0xEA
+crl-rsa-pss-sha1.pem
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0xEA
+crl-rsa-pss-sha224.pem
+ Hash Algorithm: sha224
+ Mask Algorithm: mgf1 with sha224
+ Salt Length: 0xE2
+crl-rsa-pss-sha256.pem
+ Hash Algorithm: sha256
+ Mask Algorithm: mgf1 with sha256
+ Salt Length: 0xDE
+crl-rsa-pss-sha384.pem
+ Hash Algorithm: sha384
+ Mask Algorithm: mgf1 with sha384
+ Salt Length: 0xCE
+crl-rsa-pss-sha512.pem
+ Hash Algorithm: sha512
+ Mask Algorithm: mgf1 with sha512
+ Salt Length: 0xBE
+
+These CRLs are signed with a 2048-bit key. It appears that they are
+all using saltlen = keylen - hashlen - 2.
+
+**Test CSRs:**
+
+server9.req.sha1
+ Hash Algorithm: sha1 (default)
+ Mask Algorithm: mgf1 with sha1 (default)
+ Salt Length: 0x6A
+server9.req.sha224
+ Hash Algorithm: sha224
+ Mask Algorithm: mgf1 with sha224
+ Salt Length: 0x62
+server9.req.sha256
+ Hash Algorithm: sha256
+ Mask Algorithm: mgf1 with sha256
+ Salt Length: 0x5E
+server9.req.sha384
+ Hash Algorithm: sha384
+ Mask Algorithm: mgf1 with sha384
+ Salt Length: 0x4E
+server9.req.sha512
+ Hash Algorithm: sha512
+ Mask Algorithm: mgf1 with sha512
+ Salt Length: 0x3E
+
+These CSRs are signed with a 2048-bit key. It appears that they are
+all using saltlen = keylen - hashlen - 2.
+
+### Possible courses of action
+
+There's no question about what to do with TLS (any version); the only question
+is about X.509 signature verification. Options include:
+
+1. Doing all verifications with `PSA_ALG_RSA_PSS_ANY_SALT` - while this
+ wouldn't cause a concrete security issue, this would be non-compliant.
+2. Doing verifications with `PSA_ALG_RSA_PSS` when we're lucky and the encoded
+ saltlen happens to match hashlen, and falling back to `ANY_SALT` otherwise.
+Same issue as with the previous point, except more contained.
+3. Reject all certificates with saltlen != hashlen. This includes all
+ certificates generated with OpenSSL using the default parameters, so it's
+probably not acceptable.
+4. Request an extension to the PSA Crypto API and use one of the above options
+ in the meantime. Such an extension seems inconvenient and not motivated by
+strong security arguments, so it's unclear whether it would be accepted.
+
+Since Mbed TLS 3.4, option 1 is implemented.
+
+Limitations relevant for G2 (isolation of long-term secrets)
+============================================================
+
+Currently none.
diff --git a/docs/architecture/psa-migration/strategy.md b/docs/architecture/psa-migration/strategy.md
new file mode 100644
index 0000000..b985a77
--- /dev/null
+++ b/docs/architecture/psa-migration/strategy.md
@@ -0,0 +1,486 @@
+This document explains the strategy that was used so far in starting the
+migration to PSA Crypto and mentions future perspectives and open questions.
+
+Goals
+=====
+
+Several benefits are expected from migrating to PSA Crypto:
+
+G1. Use PSA Crypto drivers when available.
+G2. Allow isolation of long-term secrets (for example, private keys).
+G3. Allow isolation of short-term secrets (for example, TLS session keys).
+G4. Have a clean, unified API for Crypto (retire the legacy API).
+G5. Code size: compile out our implementation when a driver is available.
+
+As of Mbed TLS 3.2, most of (G1) and all of (G2) is implemented when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled. For (G2) to take effect, the application
+needs to be changed to use new APIs. For a more detailed account of what's
+implemented, see `docs/use-psa-crypto.md`, where new APIs are about (G2), and
+internal changes implement (G1).
+
+As of early 2023, work towards G5 is in progress: Mbed TLS 3.3 and 3.4 saw
+some improvements in this area, and more will be coming in future releases.
+
+Generally speaking, the numbering above doesn't mean that each goal requires
+the preceding ones to be completed.
+
+
+Compile-time options
+====================
+
+We currently have a few compile-time options that are relevant to the migration:
+
+- `MBEDTLS_PSA_CRYPTO_C` - enabled by default, controls the presence of the PSA
+ Crypto APIs.
+- `MBEDTLS_USE_PSA_CRYPTO` - disabled by default (enabled in "full" config),
+ controls usage of PSA Crypto APIs to perform operations in X.509 and TLS
+(G1 above), as well as the availability of some new APIs (G2 above).
+- `PSA_CRYPTO_CONFIG` - disabled by default, supports builds with drivers and
+ without the corresponding software implementation (G5 above).
+
+The reasons why `MBEDTLS_USE_PSA_CRYPTO` is optional and disabled by default
+are:
+- it's not fully compatible with `MBEDTLS_ECP_RESTARTABLE`: you can enable
+ both, but then you won't get the full effect of RESTARTBLE (see the
+documentation of this option in `mbedtls_config.h`);
+- to avoid a hard/default dependency of TLS, X.509 and PK on
+ `MBEDTLS_PSA_CRYPTO_C`, for backward compatibility reasons:
+ - When `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
+ `psa_crypto_init()` before TLS/X.509 uses PSA functions. (This prevents us
+from even enabling the option by default.)
+ - `MBEDTLS_PSA_CRYPTO_C` has a hard dependency on `MBEDTLS_ENTROPY_C ||
+ MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` but it's
+ currently possible to compile TLS and X.509 without any of the options.
+ Also, we can't just auto-enable `MBEDTLS_ENTROPY_C` as it doesn't build
+ out of the box on all platforms, and even less
+ `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` as it requires a user-provided RNG
+ function.
+
+The downside of this approach is that until we are able to make
+`MBDEDTLS_USE_PSA_CRYPTO` non-optional (always enabled), we have to maintain
+two versions of some parts of the code: one using PSA, the other using the
+legacy APIs. However, see next section for strategies that can lower that
+cost. The rest of this section explains the reasons for the
+incompatibilities mentioned above.
+
+At the time of writing (early 2022) it is unclear what could be done about the
+backward compatibility issues, and in particular if the cost of implementing
+solutions to these problems would be higher or lower than the cost of
+maintaining dual code paths until the next major version. (Note: these
+solutions would probably also solve other problems at the same time.)
+
+### `MBEDTLS_ECP_RESTARTABLE`
+
+Currently this option controls not only the presence of restartable APIs in
+the crypto library, but also their use in the TLS and X.509 layers. Since PSA
+Crypto does not support restartable operations, there's a clear conflict: the
+TLS and X.509 layers can't both use only PSA APIs and get restartable
+behaviour.
+
+Support for restartable (aka interruptible) ECDSA sign/verify operation was
+added to PSA in Mbed TLS 3.4, but support for ECDH is not present yet.
+
+It will then require follow-up work to make use of the new PSA APIs in
+PK/X.509/TLS in all places where we currently allow restartable operations.
+
+### Backward compatibility issues with making `MBEDTLS_USE_PSA_CRYPTO` always on
+
+1. Existing applications may not be calling `psa_crypto_init()` before using
+ TLS, X.509 or PK. We can try to work around that by calling (the relevant
+part of) it ourselves under the hood as needed, but that would likely require
+splitting init between the parts that can fail and the parts that can't (see
+<https://github.com/ARM-software/psa-crypto-api/pull/536> for that).
+2. It's currently not possible to enable `MBEDTLS_PSA_CRYPTO_C` in
+ configurations that don't have `MBEDTLS_ENTROPY_C`, and we can't just
+auto-enable the latter, as it won't build or work out of the box on all
+platforms. There are two kinds of things we'd need to do if we want to work
+around that:
+ 1. Make it possible to enable the parts of PSA Crypto that don't require an
+ RNG (typically, public key operations, symmetric crypto, some key
+management functions (destroy etc)) in configurations that don't have
+`ENTROPY_C`. This requires going through the PSA code base to adjust
+dependencies. Risk: there may be annoying dependencies, some of which may be
+surprising.
+ 2. For operations that require an RNG, provide an alternative function
+ accepting an explicit `f_rng` parameter (see #5238), that would be
+available in entropy-less builds. (Then code using those functions still needs
+to have one version using it, for entropy-less builds, and one version using
+the standard function, for driver support in build with entropy.)
+
+See <https://github.com/Mbed-TLS/mbedtls/issues/5156>.
+
+Taking advantage of the existing abstractions layers - or not
+=============================================================
+
+The Crypto library in Mbed TLS currently has 3 abstraction layers that offer
+algorithm-agnostic APIs for a class of algorithms:
+
+- MD for messages digests aka hashes (including HMAC)
+- Cipher for symmetric ciphers (included AEAD)
+- PK for asymmetric (aka public-key) cryptography (excluding key exchange)
+
+Note: key exchange (FFDH, ECDH) is not covered by an abstraction layer.
+
+These abstraction layers typically provide, in addition to the API for crypto
+operations, types and numerical identifiers for algorithms (for
+example `mbedtls_cipher_mode_t` and its values). The
+current strategy is to keep using those identifiers in most of the code, in
+particular in existing structures and public APIs, even when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled. (This is not an issue for G1, G2, G3
+above, and is only potentially relevant for G4.)
+
+The are multiple strategies that can be used regarding the place of those
+layers in the migration to PSA.
+
+Silently call to PSA from the abstraction layer
+-----------------------------------------------
+
+- Provide a new definition (conditionally on `USE_PSA_CRYPTO`) of wrapper
+ functions in the abstraction layer, that calls PSA instead of the legacy
+crypto API.
+- Upside: changes contained to a single place, no need to change TLS or X.509
+ code anywhere.
+- Downside: tricky to implement if the PSA implementation is currently done on
+ top of that layer (dependency loop).
+
+This strategy is currently (early 2023) used for all operations in the PK
+layer; the MD layer uses a variant where it dispatches to PSA if a driver is
+available and the driver subsystem has been initialized, regardless of whether
+`USE_PSA_CRYPTO` is enabled; see `md-cipher-dispatch.md` in the same directory
+for details.
+
+This strategy is not very well suited to the Cipher layer, as the PSA
+implementation is currently done on top of that layer.
+
+This strategy will probably be used for some time for the PK layer, while we
+figure out what the future of that layer is: parts of it (parse/write, ECDSA
+signatures in the format that X.509 & TLS want) are not covered by PSA, so
+they will need to keep existing in some way. (Also, the PK layer is a good
+place for dispatching to either PSA or `mbedtls_xxx_restartable` while that
+part is not covered by PSA yet, if we decide to do that.)
+
+Replace calls for each operation
+--------------------------------
+
+- For every operation that's done through this layer in TLS or X.509, just
+ replace function call with calls to PSA (conditionally on `USE_PSA_CRYPTO`)
+- Upside: conceptually simple, and if the PSA implementation is currently done
+ on top of that layer, avoids concerns about dependency loops.
+- Upside: opens the door to building TLS/X.509 without that layer, saving some
+ code size.
+- Downside: TLS/X.509 code has to be done for each operation.
+
+This strategy is currently (early 2023) used for the MD layer and the Cipher
+layer in X.509 and TLS. Crypto modules however always call to MD which may
+then dispatch to PSA, see `md-cipher-dispatch.md`.
+
+Opt-in use of PSA from the abstraction layer
+--------------------------------------------
+
+- Provide a new way to set up a context that causes operations on that context
+ to be done via PSA.
+- Upside: changes mostly contained in one place, TLS/X.509 code only needs to
+ be changed when setting up the context, but not when using it. In
+ particular, no changes to/duplication of existing public APIs that expect a
+ key to be passed as a context of this layer (eg, `mbedtls_pk_context`).
+- Upside: avoids dependency loop when PSA implemented on top of that layer.
+- Downside: when the context is typically set up by the application, requires
+ changes in application code.
+
+This strategy is not useful when no context is used, for example with the
+one-shot function `mbedtls_md()`.
+
+There are two variants of this strategy: one where using the new setup
+function also allows for key isolation (the key is only held by PSA,
+supporting both G1 and G2 in that area), and one without isolation (the key is
+still stored outside of PSA most of the time, supporting only G1).
+
+This strategy, with support for key isolation, is currently (early 2022) used for
+private-key operations in the PK layer - see `mbedtls_pk_setup_opaque()`. This
+allows use of PSA-held private ECDSA keys in TLS and X.509 with no change to
+the TLS/X.509 code, but a contained change in the application.
+
+This strategy, without key isolation, was also previously used (until 3.1
+included) in the Cipher layer - see `mbedtls_cipher_setup_psa()`. This allowed
+use of PSA for cipher operations in TLS with no change to the application
+code, and a contained change in TLS code. (It only supported a subset of
+ciphers.)
+
+Note: for private key operations in the PK layer, both the "silent" and the
+"opt-in" strategy can apply, and can complement each other, as one provides
+support for key isolation, but at the (unavoidable) code of change in
+application code, while the other requires no application change to get
+support for drivers, but fails to provide isolation support.
+
+Summary
+-------
+
+Strategies currently (early 2022) used with each abstraction layer:
+
+- PK (for G1): silently call PSA
+- PK (for G2): opt-in use of PSA (new key type)
+- Cipher (G1): replace calls at each call site
+- MD (G1, X.509 and TLS): replace calls at each call site (depending on
+ `USE_PSA_CRYPTO`)
+- MD (G5): silently call PSA when a driver is available, see
+ `md-cipher-dispatch.md`.
+
+
+Supporting builds with drivers without the software implementation
+==================================================================
+
+This section presents a plan towards G5: save code size by compiling out our
+software implementation when a driver is available.
+
+Let's expand a bit on the definition of the goal: in such a configuration
+(driver used, software implementation and abstraction layer compiled out),
+we want:
+
+a. the library to build in a reasonably-complete configuration,
+b. with all tests passing,
+c. and no more tests skipped than the same configuration with software
+ implementation.
+
+Criterion (c) ensures not only test coverage, but that driver-based builds are
+at feature parity with software-based builds.
+
+We can roughly divide the work needed to get there in the following steps:
+
+0. Have a working driver interface for the algorithms we want to replace.
+1. Have users of these algorithms call to PSA or an abstraction layer than can
+ dispatch to PSA, but not the low-level legacy API, for all operations.
+(This is G1, and for PK, X.509 and TLS this is controlled by
+`MBEDTLS_USE_PSA_CRYPTO`.) This needs to be done in the library and tests.
+2. Have users of these algorithms not depend on the legacy API for information
+ management (getting a size for a given algorithm, etc.)
+3. Adapt compile-time guards used to query availability of a given algorithm;
+ this needs to be done in the library (for crypto operations and data) and
+tests.
+
+Note: the first two steps enable use of drivers, but not by themselves removal
+of the software implementation.
+
+Note: the fact that step 1 is not achieved for all of libmbedcrypto (see
+below) is the reason why criterion (a) has "a reasonably-complete
+configuration", to allow working around internal crypto dependencies when
+working on other parts such as X.509 and TLS - for example, a configuration
+without RSA PKCS#1 v2.1 still allows reasonable use of X.509 and TLS.
+
+Note: this is a conceptual division that will sometimes translate to how the
+work is divided into PRs, sometimes not. For example, in situations where it's
+not possible to achieve good test coverage at the end of step 1 or step 2, it
+is preferable to group with the next step(s) in the same PR until good test
+coverage can be reached.
+
+**Status as of end of March 2023 (shortly after 3.4):**
+
+- Step 0 is achieved for most algorithms, with only a few gaps remaining.
+- Step 1 is achieved for most of PK, X.509, and TLS when
+ `MBEDTLS_USE_PSA_CRYPTO` is enabled with only a few gaps remaining (see
+ docs/use-psa-crypto.md).
+- Step 1 is achieved for the crypto library regarding hashes: everything uses
+ MD (not low-level hash APIs), which then dispatches to PSA if applicable.
+- Step 1 is not achieved for all of the crypto library when it come to
+ ciphers. For example,`ctr_drbg.c` calls the legacy API `mbedtls_aes`.
+- Step 2 is achieved for most of X.509 and TLS (same gaps as step 1) when
+ `MBEDTLS_USE_PSA_CRYPTO` is enabled.
+- Step 3 is done for hashes and top-level ECC modules (ECDSA, ECDH, ECJPAKE).
+
+**Strategy for step 1:**
+
+Regarding PK, X.509, and TLS, this is mostly achieved with only a few gaps.
+(The strategy was outlined in the previous section.)
+
+Regarding libmbedcrypto:
+- for hashes and ciphers, see `md-cipher-dispatch.md` in the same directory;
+- for ECC, we have no internal uses of the top-level algorithms (ECDSA, ECDH,
+ ECJPAKE), however they all depend on `ECP_C` which in turn depends on
+`BIGNUM_C`. So, direct calls from TLS, X.509 and PK to ECP and Bignum will
+need to be replaced; see <https://github.com/Mbed-TLS/mbedtls/issues/6839> and
+linked issues for a summary of intermediate steps and open points.
+
+**Strategy for step 2:**
+
+The most satisfying situation here is when we can just use the PSA Crypto API
+for information management as well. However sometimes it may not be
+convenient, for example in parts of the code that accept old-style identifiers
+(such as `mbedtls_md_type_t`) in their API and can't assume PSA to be
+compiled in (such as `rsa.c`).
+
+When using an existing abstraction layer such as MD, it can provide
+information management functions. In other cases, information that was in a
+low-level module but logically belongs in a higher-level module can be moved
+to that module (for example, TLS identifiers of curves and there conversion
+to/from PSA or legacy identifiers belongs in TLS, not `ecp.c`).
+
+**Strategy for step 3:**
+
+There are currently two (complementary) ways for crypto-using code to check if a
+particular algorithm is supported: using `MBEDTLS_xxx` macros, and using
+`PSA_WANT_xxx` macros. For example, PSA-based code that want to use SHA-256
+will check for `PSA_WANT_ALG_SHA_256`, while legacy-based code that wants to
+use SHA-256 will check for `MBEDTLS_SHA256_C` if using the `mbedtls_sha256`
+API, or for `MBEDTLS_MD_C && MBEDTLS_SHA256_C` if using the `mbedtls_md` API.
+
+Code that obeys `MBEDTLS_USE_PSA_CRYPTO` will want to use one of the two
+dependencies above depending on whether `MBEDTLS_USE_PSA_CRYPTO` is defined:
+if it is, the code want the algorithm available in PSA, otherwise, it wants it
+available via the legacy API(s) is it using (MD and/or low-level).
+
+As much as possible, we're trying to create for each algorithm a single new
+macro that can be used to express dependencies everywhere (except pure PSA
+code that should always use `PSA_WANT`). For example, for hashes this is the
+`MBEDTLS_MD_CAN_xxx` family. For ECC algorithms, we have similar
+`MBEDTLS_PK_CAN_xxx` macros.
+
+Note that in order to achieve that goal, even for code that obeys
+`USE_PSA_CRYPTO`, it is useful to impose that all algorithms that are
+available via the legacy APIs are also available via PSA.
+
+Executing step 3 will mostly consist of using the right dependency macros in
+the right places (once the previous steps are done).
+
+**Note on testing**
+
+Since supporting driver-only builds is not about adding features, but about
+supporting existing features in new types of builds, testing will not involve
+adding cases to the test suites, but instead adding new components in `all.sh`
+that build and run tests in newly-supported configurations. For example, if
+we're making some part of the library work with hashes provided only by
+drivers when `MBEDTLS_USE_PSA_CRYPTO` is defined, there should be a place in
+`all.sh` that builds and run tests in such a configuration.
+
+There is however a risk, especially in step 3 where we change how dependencies
+are expressed (sometimes in bulk), to get things wrong in a way that would
+result in more tests being skipped, which is easy to miss. Care must be
+taken to ensure this does not happen. The following criteria can be used:
+
+1. The sets of tests skipped in the default config and the full config must be
+ the same before and after the PR that implements step 3. This is tested
+manually for each PR that changes dependency declarations by using the script
+`outcome-analysis.sh` in the present directory.
+2. The set of tests skipped in the driver-only build is the same as in an
+ equivalent software-based configuration. This is tested automatically by the
+CI in the "Results analysis" stage, by running
+`tests/scripts/analyze_outcomes.py`. See the
+`analyze_driver_vs_reference_xxx` actions in the script and the comments above
+their declaration for how to do that locally.
+
+
+Migrating away from the legacy API
+==================================
+
+This section briefly introduces questions and possible plans towards G4,
+mainly as they relate to choices in previous stages.
+
+The role of the PK/Cipher/MD APIs in user migration
+---------------------------------------------------
+
+We're currently taking advantage of the existing PK layer in order
+to reduce the number of places where library code needs to be changed. It's
+only natural to consider using the same strategy (with the PK, MD and Cipher
+layers) for facilitating migration of application code.
+
+Note: a necessary first step for that would be to make sure PSA is no longer
+implemented of top of the concerned layers
+
+### Zero-cost compatibility layer?
+
+The most favourable case is if we can have a zero-cost abstraction (no
+runtime, RAM usage or code size penalty), for example just a bunch of
+`#define`s, essentially mapping `mbedtls_` APIs to their `psa_` equivalent.
+
+Unfortunately that's unlikely to fully work. For example, the MD layer uses the
+same context type for hashes and HMACs, while the PSA API (rightfully) has
+distinct operation types. Similarly, the Cipher layer uses the same context
+type for unauthenticated and AEAD ciphers, which again the PSA API
+distinguishes.
+
+It is unclear how much value, if any, a zero-cost compatibility layer that's
+incomplete (for example, for MD covering only hashes, or for Cipher covering
+only AEAD) or differs significantly from the existing API (for example,
+introducing new context types) would provide to users.
+
+### Low-cost compatibility layers?
+
+Another possibility is to keep most or all of the existing API for the PK, MD
+and Cipher layers, implemented on top of PSA, aiming for the lowest possible
+cost. For example, `mbedtls_md_context_t` would be defined as a (tagged) union
+of `psa_hash_operation_t` and `psa_mac_operation_t`, then `mbedtls_md_setup()`
+would initialize the correct part, and the rest of the functions be simple
+wrappers around PSA functions. This would vastly reduce the complexity of the
+layers compared to the existing (no need to dispatch through function
+pointers, just call the corresponding PSA API).
+
+Since this would still represent a non-zero cost, not only in terms of code
+size, but also in terms of maintenance (testing, etc.) this would probably
+be a temporary solution: for example keep the compatibility layers in 4.0 (and
+make them optional), but remove them in 5.0.
+
+Again, this provides the most value to users if we can manage to keep the
+existing API unchanged. Their might be conflicts between this goal and that of
+reducing the cost, and judgment calls may need to be made.
+
+Note: when it comes to holding public keys in the PK layer, depending on how
+the rest of the code is structured, it may be worth holding the key data in
+memory controlled by the PK layer as opposed to a PSA key slot, moving it to a
+slot only when needed (see current `ecdsa_verify_wrap` when
+`MBEDTLS_USE_PSA_CRYPTO` is defined) For example, when parsing a large
+number, N, of X.509 certificates (for example the list of trusted roots), it
+might be undesirable to use N PSA key slots for their public keys as long as
+the certs are loaded. OTOH, this could also be addressed by merging the "X.509
+parsing on-demand" (#2478), and then the public key data would be held as
+bytes in the X.509 CRT structure, and only moved to a PK context / PSA slot
+when it's actually used.
+
+Note: the PK layer actually consists of two relatively distinct parts: crypto
+operations, which will be covered by PSA, and parsing/writing (exporting)
+from/to various formats, which is currently not fully covered by the PSA
+Crypto API.
+
+### Algorithm identifiers and other identifiers
+
+It should be easy to provide the user with a bunch of `#define`s for algorithm
+identifiers, for example `#define MBEDTLS_MD_SHA256 PSA_ALG_SHA_256`; most of
+those would be in the MD, Cipher and PK compatibility layers mentioned above,
+but there might be some in other modules that may be worth considering, for
+example identifiers for elliptic curves.
+
+### Lower layers
+
+Generally speaking, we would retire all of the low-level, non-generic modules,
+such as AES, SHA-256, RSA, DHM, ECDH, ECP, bignum, etc, without providing
+compatibility APIs for them. People would be encouraged to switch to the PSA
+API. (The compatibility implementation of the existing PK, MD, Cipher APIs
+would mostly benefit people who already used those generic APis rather than
+the low-level, alg-specific ones.)
+
+### APIs in TLS and X.509
+
+Public APIs in TLS and X.509 may be affected by the migration in at least two
+ways:
+
+1. APIs that rely on a legacy `mbedtls_` crypto type: for example
+ `mbedtls_ssl_conf_own_cert()` to configure a (certificate and the
+associated) private key. Currently the private key is passed as a
+`mbedtls_pk_context` object, which would probably change to a `psa_key_id_t`.
+Since some users would probably still be using the compatibility PK layer, it
+would need a way to easily extract the PSA key ID from the PK context.
+
+2. APIs the accept list of identifiers: for example
+ `mbedtls_ssl_conf_curves()` taking a list of `mbedtls_ecp_group_id`s. This
+could be changed to accept a list of pairs (`psa_ecc_family_t`, size) but we
+should probably take this opportunity to move to a identifier independent from
+the underlying crypto implementation and use TLS-specific identifiers instead
+(based on IANA values or custom enums), as is currently done in the new
+`mbedtls_ssl_conf_groups()` API, see #4859).
+
+Testing
+-------
+
+An question that needs careful consideration when we come around to removing
+the low-level crypto APIs and making PK, MD and Cipher optional compatibility
+layers is to be sure to preserve testing quality. A lot of the existing test
+cases use the low level crypto APIs; we would need to either keep using that
+API for tests, or manually migrate tests to the PSA Crypto API. Perhaps a
+combination of both, perhaps evolving gradually over time.
diff --git a/docs/architecture/psa-migration/syms.sh b/docs/architecture/psa-migration/syms.sh
new file mode 100755
index 0000000..6c9686e
--- /dev/null
+++ b/docs/architecture/psa-migration/syms.sh
@@ -0,0 +1,73 @@
+#!/bin/sh
+#
+# Copyright The Mbed TLS Contributors
+# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
+#
+# Purpose
+#
+# Show external links in built libraries (X509 or TLS) or modules. This is
+# usually done to list Crypto dependencies or to check modules'
+# interdependencies.
+#
+# Usage:
+# - build the library with debug symbols and the config you're interested in
+# (default, full minus MBEDTLS_USE_PSA_CRYPTO, full, etc.)
+# - launch this script with 1 or more arguments depending on the analysis' goal:
+# - if only 1 argument is used (which is the name of the used config,
+# ex: full), then the analysis is done on libmbedx509 and libmbedtls
+# libraries by default
+# - if multiple arguments are provided, then modules' names (ex: pk,
+# pkparse, pkwrite, etc) are expected after the 1st one and the analysis
+# will be done on those modules instead of the libraries.
+
+set -eu
+
+# list mbedtls_ symbols of a given type in a static library
+syms() {
+ TYPE="$1"
+ FILE="$2"
+
+ nm "$FILE" | sed -n "s/[0-9a-f ]*${TYPE} \(mbedtls_.*\)/\1/p" | sort -u
+}
+
+# Check if the provided name refers to a module or library and return the
+# same path with proper extension
+get_file_with_extension() {
+ BASE=$1
+ if [ -f $BASE.o ]; then
+ echo $BASE.o
+ elif [ -f $BASE.a ]; then
+ echo $BASE.a
+ fi
+}
+
+# create listings for the given library
+list() {
+ NAME="$1"
+ FILE=$(get_file_with_extension "library/${NAME}")
+ PREF="${CONFIG}-$NAME"
+
+ syms '[TRrD]' $FILE > ${PREF}-defined
+ syms U $FILE > ${PREF}-unresolved
+
+ diff ${PREF}-defined ${PREF}-unresolved \
+ | sed -n 's/^> //p' > ${PREF}-external
+ sed 's/mbedtls_\([^_]*\).*/\1/' ${PREF}-external \
+ | uniq -c | sort -rn > ${PREF}-modules
+
+ rm ${PREF}-defined ${PREF}-unresolved
+}
+
+CONFIG="${1:-unknown}"
+
+# List of modules to check is provided as parameters
+if [ $# -gt 1 ]; then
+ shift 1
+ ITEMS_TO_CHECK="$@"
+else
+ ITEMS_TO_CHECK="libmbedx509 libmbedtls"
+fi
+
+for ITEM in $ITEMS_TO_CHECK; do
+ list $ITEM
+done
diff --git a/docs/architecture/psa-migration/testing.md b/docs/architecture/psa-migration/testing.md
new file mode 100644
index 0000000..f205c16
--- /dev/null
+++ b/docs/architecture/psa-migration/testing.md
@@ -0,0 +1,99 @@
+Testing strategy for `MBEDTLS_USE_PSA_CRYPTO`
+=============================================
+
+This document records the testing strategy used so far in implementing
+`MBEDTLS_USE_PSA_CRYPTO`.
+
+
+General considerations
+----------------------
+
+There needs to be at least one build in `all.sh` that enables
+`MBEDTLS_USE_PSA_CRYPTO` and runs the full battery of tests; currently that's
+ensured by the fact that `scripts/config.py full` enables
+`MBEDTLS_USE_PSA_CRYPTO`. There needs to be at least one build with
+`MBEDTLS_USE_PSA_CRYPTO` disabled (as long as it's optional); currently that's
+ensured by the fact that it's disabled in the default config.
+
+Generally, code review is enough to ensure that PSA APIs are indeed used where
+they should be when `MBEDTLS_USE_PSA_CRYPTO` is enabled.
+
+However, when it comes to TLS, we also have the option of using debug messages
+to confirm which code path is taken. This is generally unnecessary, except when
+a decision is made at run-time about whether to use the PSA or legacy code
+path. (For example, for record protection, previously (until 3.1), some ciphers were supported
+via PSA while some others weren't, with a run-time fallback. In this case, it's
+good to have a debug message checked by the test case to confirm that the
+right decision was made at run-time, i. e. that we didn't use the fallback for
+ciphers that are supposed to be supported.)
+
+
+New APIs meant for application use
+----------------------------------
+
+For example, `mbedtls_pk_setup_opaque()` is meant to be used by applications
+in order to create PK contexts that can then be passed to existing TLS and
+X.509 APIs (which remain unchanged).
+
+In that case, we want:
+
+- unit testing of the new API and directly-related APIs - for example:
+ - in `test_suite_pk` we have a new test function `pk_psa_utils` that exercises
+ `mbedtls_pk_setup_opaque()` and checks that various utility functions
+ (`mbedtls_pk_get_type()` etc.) work and the functions that are expected to
+ fail (`mbedtls_pk_verify()` etc) return the expected error.
+ - in `test_suite_pk` we modified the existing `pk_psa_sign` test function to
+ check that signature generation works as expected
+ - in `test_suite_pkwrite` we should have a new test function checking that
+ exporting (writing out) the public part of the key works as expected and
+ that exporting the private key fails as expected.
+- integration testing of the new API with each existing API which should
+ accepts a context created this way - for example:
+ - in `programs/ssl/ssl_client2` a new option `key_opaque` that causes the
+ new API to be used, and one or more tests in `ssl-opt.sh` using that.
+ (We should have the same server-side.)
+ - in `test_suite_x509write` we have a new test function
+ `x509_csr_check_opaque()` checking integration of the new API with the
+ existing `mbedtls_x509write_csr_set_key()`. (And also
+ `mbedtls_x509write_crt_set_issuer_key()` since #5710.)
+
+For some APIs, for example with `mbedtls_ssl_conf_psk_opaque()`, testing in
+`test_suite_ssl` was historically not possible, so we only have testing in
+`ssl-opt.sh`.
+
+New APIs meant for internal use
+-------------------------------
+
+For example, `mbedtls_cipher_setup_psa()` (no longer used, soon to be
+deprecated - #5261) was meant to be used by the TLS layer, but probably not
+directly by applications.
+
+In that case, we want:
+
+- unit testing of the new API and directly-related APIs - for example:
+ - in `test_suite_cipher`, the existing test functions `auth_crypt_tv` and
+ `test_vec_crypt` gained a new parameter `use_psa` and corresponding test
+ cases
+- integration testing:
+ - usually already covered by existing tests for higher-level modules:
+ - for example simple use of `mbedtls_cipher_setup_psa()` in TLS is already
+ covered by running the existing TLS tests in a build with
+ `MBEDTLS_USA_PSA_CRYPTO` enabled
+ - however if use of the new API in higher layers involves more logic that
+ use of the old API, specific integrations test may be required
+ - for example, the logic to fall back from `mbedtls_cipher_setup_psa()` to
+ `mbedtls_cipher_setup()` in TLS is tested by `run_test_psa` in
+ `ssl-opt.sh`.
+
+Internal changes
+----------------
+
+For example, use of PSA to compute the TLS 1.2 PRF.
+
+Changes in this category rarely require specific testing, as everything should
+be already be covered by running the existing tests in a build with
+`MBEDTLS_USE_PSA_CRYPTO` enabled; however we need to make sure the existing
+test have sufficient coverage, and improve them if necessary.
+
+However, if additional logic is involved, or there are run-time decisions about
+whether to use the PSA or legacy code paths, specific tests might be in order.
diff --git a/docs/architecture/psa-shared-memory.md b/docs/architecture/psa-shared-memory.md
new file mode 100644
index 0000000..ef3a6b0
--- /dev/null
+++ b/docs/architecture/psa-shared-memory.md
@@ -0,0 +1,685 @@
+PSA API functions and shared memory
+===================================
+
+## Introduction
+
+This document discusses the security architecture of systems where PSA API functions might receive arguments that are in memory that is shared with an untrusted process. On such systems, the untrusted process might access a shared memory buffer while the cryptography library is using it, and thus cause unexpected behavior in the cryptography code.
+
+### Core assumptions
+
+We assume the following scope limitations:
+
+* Only PSA Crypto API functions are in scope (including Mbed TLS extensions to the official API specification). Legacy crypto, X.509, TLS, or any other function which is not called `psa_xxx` is out of scope.
+* We only consider [input buffers](https://arm-software.github.io/psa-api/crypto/1.1/overview/conventions.html#input-buffer-sizes) and [output buffers](https://arm-software.github.io/psa-api/crypto/1.1/overview/conventions.html#output-buffer-sizes). Any other data is assumed to be in non-shared memory.
+
+## System architecture discussion
+
+### Architecture overview
+
+We consider a system that has memory separation between partitions: a partition can't access another partition's memory directly. Partitions are meant to be isolated from each other: a partition may only affect the integrity of another partition via well-defined system interfaces. For example, this can be a Unix/POSIX-like system that isolates processes, or isolation between the secure world and the non-secure world relying on a mechanism such as TrustZone, or isolation between secure-world applications on such a system.
+
+More precisely, we consider such a system where our PSA Crypto implementation is running inside one partition, called the **crypto service**. The crypto service receives remote procedure calls (RPC) from other partitions, validates their arguments (e.g. validation of key identifier ownership), and calls a PSA Crypto API function. This document is concerned with environments where the arguments passed to a PSA Crypto API function may be in shared memory (as opposed to environments where the inputs are always copied into memory that is solely accessible by the crypto service before calling the API function, and likewise with output buffers after the function returns).
+
+When the data is accessible to another partition, there is a risk that this other partition will access it while the crypto implementation is working. Although this could be prevented by suspending the whole system while crypto is working, such a limitation is rarely desirable and most systems don't offer a way to do it. (Even systems that have absolute thread priorities, and where crypto has a higher priority than any untrusted partition, may be vulnerable due to having multiple cores or asynchronous data transfers with peripherals.)
+
+The crypto service must guarantee that it behaves as if the rest of the world was suspended while it is executed. A behavior that is only possible if an untrusted entity accesses a buffer while the crypto service is processing the data is a security violation.
+
+### Risks and vulnerabilities
+
+We consider a security architecture with two or three entities:
+
+* a crypto service, which offers PSA crypto API calls over RPC (remote procedure call) using shared memory for some input or output arguments;
+* a client of the crypto service, which makes a RPC to the crypto service;
+* in some scenarios, a client of the client, which makes a RPC to the crypto client which re-shares the memory with the crypto service.
+
+The behavior of RPC is defined for in terms of values of inputs and outputs. This models an ideal world where the content of input and output buffers is not accessible outside the crypto service while it is processing an RPC. It is a security violation if the crypto service behaves in a way that cannot be achieved by setting the inputs before the RPC call, and reading the outputs after the RPC call is finished.
+
+#### Read-read inconsistency
+
+If an input argument is in shared memory, there is a risk of a **read-read inconsistency**:
+
+1. The crypto code reads part of the input and validates it, or injects it into a calculation.
+2. The client (or client's client) modifies the input.
+3. The crypto code reads the same part again, and performs an action which would be impossible if the input had had the same value all along.
+
+Vulnerability example (parsing): suppose the input contains data with a type-length-value or length-value encoding (for example, importing an RSA key). The crypto code reads the length field and checks that it fits within the buffer. (This could be the length of the overall data, or the length of an embedded field) Later, the crypto code reads the length again and uses it without validation. A malicious client can modify the length field in the shared memory between the two reads and thus cause a buffer overread on the second read.
+
+Vulnerability example (dual processing): consider an RPC to perform authenticated encryption, using a mechanism with an encrypt-and-MAC structure. The authenticated encryption implementation separately calculates the ciphertext and the MAC from the plaintext. A client sets the plaintext input to `"PPPP"`, then starts the RPC call, then changes the input buffer to `"QQQQ"` while the crypto service is working.
+
+* Any of `enc("PPPP")+mac("PPPP")`, `enc("PPQQ")+mac("PPQQ")` or `enc("QQQQ")+mac("QQQQ")` are valid outputs: they are outputs that can be produced by this authenticated encryption RPC.
+* If the authenticated encryption calculates the ciphertext before the client changes the output buffer and calculates the MAC after that change, reading the input buffer again each time, the output will be `enc("PPPP")+mac("QQQQ")`. There is no input that can lead to this output, hence this behavior violates the security guarantees of the crypto service.
+
+#### Write-read inconsistency
+
+If an output argument is in shared memory, there is a risk of a **write-read inconsistency**:
+
+1. The crypto code writes some intermediate data into the output buffer.
+2. The client (or client's client) modifies the intermediate data.
+3. The crypto code reads the intermediate data back and continues the calculation, leading to an outcome that would not be possible if the intermediate data had not been modified.
+
+Vulnerability example: suppose that an RSA signature function works by formatting the data in place in the output buffer, then applying the RSA private-key operation in place. (This is how `mbedtls_rsa_pkcs1_sign` works.) A malicious client may write badly formatted data into the buffer, so that the private-key operation is not a valid signature (e.g. it could be a decryption), violating the RSA key's usage policy.
+
+Vulnerability example with chained calls: we consider the same RSA signature operation as before. In this example, we additionally assume that the data to sign comes from an attestation application which signs some data on behalf of a final client: the key and the data to sign are under the attestation application's control, and the final client must not be able to obtain arbitrary signatures. The final client shares an output buffer for the signature with the attestation application, and the attestation application re-shares this buffer with the crypto service. A malicious final client can modify the intermediate data and thus sign arbitrary data.
+
+#### Write-write disclosure
+
+If an output argument is in shared memory, there is a risk of a **write-write disclosure**:
+
+1. The crypto code writes some intermediate data into the output buffer. This intermediate data must remain confidential.
+2. The client (or client's client) reads the intermediate data.
+3. The crypto code overwrites the intermediate data.
+
+Vulnerability example with chained calls (temporary exposure): an application encrypts some data, and lets its clients store the ciphertext. Clients may not have access to the plaintext. To save memory, when it calls the crypto service, it passes an output buffer that is in the final client's memory. Suppose the encryption mechanism works by copying its input to the output buffer then encrypting in place (for example, to simplify considerations related to overlap, or because the implementation relies on a low-level API that works in place). In this scenario, the plaintext is exposed to the final client while the encryption in progress, which violates the confidentiality of the plaintext.
+
+Vulnerability example with chained calls (backtrack): we consider a provisioning application that provides a data encryption service on behalf of multiple clients, using a single shared key. Clients are not allowed to access each other's data. The provisioning application isolates clients by including the client identity in the associated data. Suppose that an AEAD decryption function processes the ciphertext incrementally by simultaneously writing the plaintext to the output buffer and calculating the tag. (This is how AEAD decryption usually works.) At the end, if the tag is wrong, the decryption function wipes the output buffer. Assume that the output buffer for the plaintext is shared from the client to the provisioning application, which re-shares it with the crypto service. A malicious client can read another client (the victim)'s encrypted data by passing the ciphertext to the provisioning application, which will attempt to decrypt it with associated data identifying the requesting client. Although the operation will fail beacuse the tag is wrong, the malicious client still reads the victim plaintext.
+
+#### Write-read feedback
+
+If a function both has an input argument and an output argument in shared memory, and processes its input incrementally to emit output incrementally, the following sequence of events is possible:
+
+1. The crypto code processes part of the input and writes the corresponding part of the output.
+2. The client reads the early output and uses that to calculate the next part of the input.
+3. The crypto code processes the rest of the input.
+
+There are cryptographic mechanisms for which this breaks security properties. An example is [CBC encryption](https://link.springer.com/content/pdf/10.1007/3-540-45708-9_2.pdf): if the client can choose the content of a plaintext block after seeing the immediately preceding ciphertext block, this gives the client a decryption oracle. This is a security violation if the key policy only allowed the client to encrypt, not to decrypt.
+
+TODO: is this a risk we want to take into account? Although this extends the possible behaviors of the one-shot interface, the client can do the same thing legitimately with the multipart interface.
+
+### Possible countermeasures
+
+In this section, we briefly discuss generic countermeasures.
+
+#### Copying
+
+Copying is a valid countermeasure. It is conceptually simple. However, it is often unattractive because it requires additional memory and time.
+
+Note that although copying is very easy to write into a program, there is a risk that a compiler (especially with whole-program optimization) may optimize the copy away, if it does not understand that copies between shared memory and non-shared memory are semantically meaningful.
+
+Example: the PSA Firmware Framework 1.0 forbids shared memory between partitions. This restriction is lifted in version 1.1 due to concerns over RAM usage.
+
+#### Careful accesses
+
+The following rules guarantee that shared memory cannot result in a security violation other than [write-read feedback](#write-read-feedback):
+
+* Never read the same input twice at the same index.
+* Never read back from an output.
+* Never write to the output twice at the same index.
+ * This rule can usefully be relaxed in many circumstances. It is ok to write data that is independent of the inputs (and not otherwise confidential), then overwrite it. For example, it is ok to zero the output buffer before starting to process the input.
+
+These rules are very difficult to enforce.
+
+Example: these are the rules that a GlobalPlatform TEE Trusted Application (application running on the secure side of TrustZone on Cortex-A) must follow.
+
+## Protection requirements
+
+### Responsibility for protection
+
+A call to a crypto service to perform a crypto operation involves the following components:
+
+1. The remote procedure call framework provided by the operating system.
+2. The code of the crypto service.
+3. The code of the PSA Crypto dispatch layer (also known as the core), which is provided by Mbed TLS.
+4. The driver implementing the cryptographic mechanism, which may be provided by Mbed TLS (built-in driver) or by a third-party driver.
+
+The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/1.1/overview/conventions.html#stability-of-parameters) puts the responsibility for protection on the implementation of the PSA Crypto API, i.e. (3) or (4).
+
+> In an environment with multiple threads or with shared memory, the implementation carefully accesses non-overlapping buffer parameters in order to prevent any security risk resulting from the content of the buffer being modified or observed during the execution of the function. (...)
+
+In Mbed TLS 2.x and 3.x up to and including 3.5.0, there is no defense against buffers in shared memory. The responsibility shifts to (1) or (2), but this is not documented.
+
+In the remainder of this chapter, we will discuss how to implement this high-level requirement where it belongs: inside the implementation of the PSA Crypto API. Note that this allows two possible levels: in the dispatch layer (independently of the implementation of each mechanism) or in the driver (specific to each implementation).
+
+#### Protection in the dispatch layer
+
+The dispatch layer has no control over how the driver layer will access buffers. Therefore the only possible protection at this layer method is to ensure that drivers have no access to shared memory. This means that any buffer located in shared memory must be copied into or out of a buffer in memory owned by the crypto service (heap or stack). This adds inefficiency, mostly in terms of RAM usage.
+
+For buffers with a small static size limit, this is something we often do for convenience, especially with output buffers. However, as of Mbed TLS 3.5.0, it is not done systematically.
+
+It is ok to skip the copy if it is known for sure that a buffer is not in shared memory. However, the location of the buffer is not under the control of Mbed TLS. This means skipping the copy would have to be a compile-time or run-time option which has to be set by the application using Mbed TLS. This is both an additional maintenance cost (more code to analyze, more testing burden), and a residual security risk in case the party who is responsible for setting this option does not set it correctly. As a consequence, Mbed TLS will not offer this configurability unless there is a compelling argument.
+
+#### Protection in the driver layer
+
+Putting the responsibility for protection in the driver layer increases the overall amount of work since there are more driver implementations than dispatch implementations. (This is true even inside Mbed TLS: almost all API functions have multiple underlying implementations, one for each algorithm.) It also increases the risk to the ecosystem since some drivers might not protect correctly. Therefore having drivers be responsible for protection is only a good choice if there is a definite benefit to it, compared to allocating an internal buffer and copying. An expected benefit in some cases is that there are practical protection methods other than copying.
+
+Some cryptographic mechanisms are naturally implemented by processing the input in a single pass, with a low risk of ever reading the same byte twice, and by writing the final output directly into the output buffer. For such mechanism, it is sensible to mandate that drivers respect these rules.
+
+In the next section, we will analyze how susceptible various cryptographic mechanisms are to shared memory vulnerabilities.
+
+### Susceptibility of different mechanisms
+
+#### Operations involving small buffers
+
+For operations involving **small buffers**, the cost of copying is low. For many of those, the risk of not copying is high:
+
+* Any parsing of formatted data has a high risk of [read-read inconsistency](#read-read-inconsistency).
+* An internal review shows that for RSA operations, it is natural for an implementation to have a [write-read inconsistency](#write-read-inconsistency) or a [write-write disclosure](#write-write-disclosure).
+
+Note that in this context, a “small buffer” is one with a size limit that is known at compile time, and small enough that copying the data is not prohibitive. For example, an RSA key fits in a small buffer. A hash input is not a small buffer, even if it happens to be only a few bytes long in one particular call.
+
+The following buffers are considered small buffers:
+
+* Any input or output directly related to asymmetric cryptography (signature, encryption/decryption, key exchange, PAKE), including key import and export.
+ * Note that this does not include inputs or outputs that are not processed by an asymmetric primitives, for example the message input to `psa_sign_message` or `psa_verify_message`.
+* Cooked key derivation output.
+* The output of a hash or MAC operation.
+
+**Design decision: the dispatch layer shall copy all small buffers**.
+
+#### Symmetric cryptography inputs with small output
+
+Message inputs to hash, MAC and key derivation operations are at a low risk of [read-read inconsistency](#read-read-inconsistency) because they are unformatted data, and for all specified algorithms, it is natural to process the input one byte at a time.
+
+**Design decision: require symmetric cryptography drivers to read their input without a risk of read-read inconsistency**.
+
+TODO: what about IV/nonce inputs? They are typically small, but don't necessarily have a static size limit (e.g. GCM recommends a 12-byte nonce, but also allows large nonces).
+
+#### Key derivation outputs
+
+Key derivation typically emits its output as a stream, with no error condition detected after setup other than operational failures (e.g. communication failure with an accelerator) or running out of data to emit (which can easily be checked before emitting any data, since the data size is known in advance).
+
+(Note that this is about raw byte output, not about cooked key derivation, i.e. deriving a structured key, which is considered a [small buffer](#operations-involving-small-buffers).)
+
+**Design decision: require key derivation drivers to emit their output without reading back from the output buffer**.
+
+#### Cipher and AEAD
+
+AEAD decryption is at risk of [write-write disclosure](#write-write-disclosure) when the tag does not match.
+
+AEAD encryption and decryption are at risk of [read-read inconsistency](#read-read-inconsistency) if they process the input multiple times, which is natural in a number of cases:
+
+* when encrypting with an encrypt-and-authenticate or authenticate-then-encrypt structure (one read to calculate the authentication tag and another read to encrypt);
+* when decrypting with an encrypt-then-authenticate structure (one read to decrypt and one read to calculate the authentication tag);
+* with SIV modes (not yet present in the PSA API, but likely to come one day) (one full pass to calculate the IV, then another full pass for the core authenticated encryption);
+
+Cipher and AEAD outputs are at risk of [write-read inconsistency](#write-read-inconsistency) and [write-write disclosure](#write-write-disclosure) if they are implemented by copying the input into the output buffer with `memmove`, then processing the data in place. In particular, this approach makes it easy to fully support overlapping, since `memmove` will take care of overlapping cases correctly, which is otherwise hard to do portably (C99 does not offer an efficient, portable way to check whether two buffers overlap).
+
+**Design decision: the dispatch layer shall allocate an intermediate buffer for cipher and AEAD plaintext/ciphertext inputs and outputs**.
+
+Note that this can be a single buffer for the input and the output if the driver supports in-place operation (which it is supposed to, since it is supposed to support arbitrary overlap, although this is not always the case in Mbed TLS, a [known issue](https://github.com/Mbed-TLS/mbedtls/issues/3266)). A side benefit of doing this intermediate copy is that overlap will be supported.
+
+For all currently implemented AEAD modes, the associated data is only processed once to calculate an intermediate value of the authentication tag.
+
+**Design decision: for now, require AEAD drivers to read the additional data without a risk of read-read inconsistency**. Make a note to revisit this when we start supporting an SIV mode, at which point the dispatch layer shall copy the input for modes that are not known to be low-risk.
+
+#### Message signature
+
+For signature algorithms with a hash-and-sign framework, the input to sign/verify-message is passed to a hash, and thus can follow the same rules as [symmetric cryptography inputs with small output](#symmetric-cryptography-inputs-with-small-output). This is also true for `PSA_ALG_RSA_PKCS1V15_SIGN_RAW`, which is the only non-hash-and-sign signature mechanism implemented in Mbed TLS 3.5. This is not true for PureEdDSA (`#PSA_ALG_PURE_EDDSA`), which is not yet implemented: [PureEdDSA signature](https://www.rfc-editor.org/rfc/rfc8032#section-5.1.6) processes the message twice. (However, PureEdDSA verification only processes the message once.)
+
+**Design decision: for now, require sign/verify-message drivers to read their input without a risk of read-read inconsistency**. Make a note to revisit this when we start supporting PureEdDSA, at which point the dispatch layer shall copy the input for algorithms such as PureEdDSA that are not known to be low-risk.
+
+## Design of shared memory protection
+
+This section explains how Mbed TLS implements the shared memory protection strategy summarized below.
+
+### Shared memory protection strategy
+
+* The core (dispatch layer) shall make a copy of the following buffers, so that drivers do not receive arguments that are in shared memory:
+ * Any input or output from asymmetric cryptography (signature, encryption/decryption, key exchange, PAKE), including key import and export.
+ * Plaintext/ciphertext inputs and outputs for cipher and AEAD.
+ * The output of a hash or MAC operation.
+ * Cooked key derivation output.
+
+* A document shall explain the requirements on drivers for arguments whose access needs to be protected:
+ * Hash and MAC input.
+ * Cipher/AEAD IV/nonce (to be confirmed).
+ * AEAD associated data (to be confirmed).
+ * Key derivation input (excluding key agreement).
+ * Raw key derivation output (excluding cooked key derivation output).
+
+* The built-in implementations of cryptographic mechanisms with arguments whose access needs to be protected shall protect those arguments.
+
+Justification: see “[Susceptibility of different mechanisms](#susceptibility-of-different-mechanisms)”.
+
+### Implementation of copying
+
+Copy what needs copying. This is broadly straightforward, however there are a few things to consider.
+
+#### Compiler optimization of copies
+
+It is unclear whether the compiler will attempt to optimize away copying operations.
+
+Once the copying code is implemented, it should be evaluated to see whether compiler optimization is a problem. Specifically, for the major compilers supported by Mbed TLS:
+* Write a small program that uses a PSA function which copies inputs or outputs.
+* Build the program with link-time optimization / full-program optimization enabled (e.g. `-flto` with `gcc`). Try also enabling the most extreme optimization options such as `-Ofast` (`gcc`) and `-Oz` (`clang`).
+* Inspect the generated code with `objdump` or a similar tool to see if copying operations are preserved.
+
+If copying behaviour is preserved by all major compilers then assume that compiler optimization is not a problem.
+
+If copying behaviour is optimized away by the compiler, further investigation is needed. Experiment with using the `volatile` keyword to force the compiler not to optimize accesses to the copied buffers. If the `volatile` keyword is not sufficient, we may be able to use compiler or target-specific techniques to prevent optimization, for example memory barriers or empty `asm` blocks. These may be implemented and verified for important platforms while retaining a C implementation that is likely to be correct on most platforms as a fallback - the same approach taken by the constant-time module.
+
+**Open questions: Will the compiler optimize away copies? If so, can it be prevented from doing so in a portable way?**
+
+#### Copying code
+
+We may either copy buffers on an ad-hoc basis using `memcpy()` in each PSA function, or use a unified set of functions for copying input and output data. The advantages of the latter are obvious:
+
+* Any test hooks need only be added in one place.
+* Copying code must only be reviewed for correctness in one place, rather than in all functions where it occurs.
+* Copy bypass is simpler as we can just replace these functions with no-ops in a single place.
+* Any complexity needed to prevent the compiler optimizing copies away does not have to be duplicated.
+
+On the other hand, the only advantage of ad-hoc copying is slightly greater flexibility.
+
+**Design decision: Create a unified set of functions for copying input and output data.**
+
+#### Copying in multipart APIs
+
+Multipart APIs may follow one of 2 possible approaches for copying of input:
+
+##### 1. Allocate a buffer and copy input on each call to `update()`
+
+This is simple and mirrors the approach for one-shot APIs nicely. However, allocating memory in the middle of a multi-part operation is likely to be bad for performance. Multipart APIs are designed in part for systems that do not have time to perform an operation at once, so introducing poor performance may be a problem here.
+
+**Open question: Does memory allocation in `update()` cause a performance problem? If so, to what extent?**
+
+##### 2. Allocate a buffer at the start of the operation and subdivide calls to `update()`
+
+In this approach, input and output buffers are allocated at the start of the operation that are large enough to hold the expected average call to `update()`. When `update()` is called with larger buffers than these, the PSA API layer makes multiple calls to the driver, chopping the input into chunks of the temporary buffer size and filling the output from the results until the operation is finished.
+
+This would be more complicated than approach (1) and introduces some extra issues. For example, if one of the intermediate calls to the driver's `update()` returns an error, it is not possible for the driver's state to be rolled back to before the first call to `update()`. It is unclear how this could be solved.
+
+However, this approach would reduce memory usage in some cases and prevent memory allocation during an operation. Additionally, since the input and output buffers would be fixed-size it would be possible to allocate them statically, avoiding the need for any dynamic memory allocation at all.
+
+**Design decision: Initially use approach (1) and treat approach (2) as an optimization to be done if necessary.**
+
+### Validation of copying
+
+#### Validation of copying by review
+
+This is fairly self-explanatory. Review all functions that use shared memory and ensure that they each copy memory. This is the simplest strategy to implement but is less reliable than automated validation.
+
+#### Validation of copying with memory pools
+
+Proposed general idea: have tests where the test code calling API functions allocates memory in a certain pool, and code in the library allocates memory in a different pool. Test drivers check that needs-copying arguments are within the library pool, not within the test pool.
+
+#### Validation of copying by memory poisoning
+
+Proposed general idea: in test code, “poison” the memory area used by input and output parameters that must be copied. Poisoning means something that prevents accessing memory while it is poisoned. This could be via memory protection (allocate with `mmap` then disable access with `mprotect`), or some kind of poisoning for an analyzer such as MSan or Valgrind.
+
+In the library, the code that does the copying temporarily unpoisons the memory by calling a test hook.
+
+```c
+static void copy_to_user(void *copy_buffer, void *const input_buffer, size_t length) {
+#if defined(MBEDTLS_TEST_HOOKS)
+ if (memory_poison_hook != NULL) {
+ memory_poison_hook(copy_buffer, length);
+ }
+#endif
+ memcpy(copy_buffer, input_buffer, length);
+#if defined(MBEDTLS_TEST_HOOKS)
+ if (memory_unpoison_hook != NULL) {
+ memory_unpoison_hook(copy_buffer, length);
+ }
+#endif
+}
+```
+The reason to poison the memory before calling the library, rather than after the copy-in (and symmetrically for output buffers) is so that the test will fail if we forget to copy, or we copy the wrong thing. This would not be the case if we relied on the library's copy function to do the poisoning: that would only validate that the driver code does not access the memory on the condition that the copy is done as expected.
+
+##### Options for implementing poisoning
+
+There are several different ways that poisoning could be implemented:
+
+1. Using Valgrind's memcheck tool. Valgrind provides a macro `VALGRIND_MAKE_MEM_NO_ACCESS` that allows manual memory poisoning. Valgrind memory poisoning is already used for constant-flow testing in Mbed TLS.
+2. Using Memory Sanitizer (MSan), which allows us to mark memory as uninitialized. This is also used for constant-flow testing. It is suitable for input buffers only, since it allows us to detect when a poisoned buffer is read but not when it is written.
+3. Using Address Sanitizer (ASan). This provides `ASAN_POISON_MEMORY_REGION` which marks memory as inaccessible.
+4. Allocating buffers separate pages and calling `mprotect()` to set pages as inaccessible. This has the disadvantage that we will have to manually ensure that buffers sit in their own pages, which likely means making a copy.
+5. Filling buffers with random data, keeping a copy of the original. For input buffers, keep a copy of the original and copy it back once the PSA function returns. For output buffers, fill them with random data and keep a separate copy of it. In the memory poisoning hooks, compare the copy of random data with the original to ensure that the output buffer has not been written directly.
+
+Approach (2) is insufficient for the full testing we require as we need to be able to check both input and output buffers.
+
+Approach (5) is simple and requires no extra tooling. It is likely to have good performance as it does not use any sanitizers. However, it requires the memory poisoning test hooks to maintain extra copies of the buffers, which seems difficult to implement in practice. Additionally, it does not precisely test the property we want to validate, so we are relying on the tests to fail if given random data as input. It is possible (if unlikely) that the PSA function will access the poisoned buffer without causing the test to fail. This becomes more likely when we consider test cases that call PSA functions on incorrect inputs to check that the correct error is returned. For these reasons, this memory poisoning approach seems unsuitable.
+
+All three remaining approaches are suitable for our purposes. However, approach (4) is more complex than the other two. To implement it, we would need to allocate poisoned buffers in separate memory pages. They would require special handling and test code would likely have to be designed around this special handling.
+
+Meanwhile, approaches (1) and (3) are much more convenient. We are simply required to call a special macro on some buffer that was allocated by us and the sanitizer takes care of everything else. Of these two, ASan appears to have a limitation related to buffer alignment. From code comments quoted in [the documentation](https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning):
+
+> This function is not guaranteed to poison the whole region - it may poison only subregion of [addr, addr+size) due to ASan alignment restrictions.
+
+Specifically, ASan will round the buffer size down to 8 bytes before poisoning due to details of its implementation. For more information on this, see [Microsoft documentation of this feature](https://learn.microsoft.com/en-us/cpp/sanitizers/asan-runtime?view=msvc-170#alignment-requirements-for-addresssanitizer-poisoning).
+
+It should be possible to work around this by manually rounding buffer lengths up to the nearest multiple of 8 in the poisoning function, although it's remotely possible that this will cause other problems. Valgrind does not appear to have this limitation (unless Valgrind is simply more poorly documented). However, running tests under Valgrind causes a much greater slowdown compared with ASan. As a result, it would be beneficial to implement support for both Valgrind and ASan, to give the extra flexibility to choose either performance or accuracy as required. This should be simple as both have very similar memory poisoning interfaces.
+
+**Design decision: Implement memory poisoning tests with both Valgrind's memcheck and ASan manual poisoning.**
+
+##### Validation with new tests
+
+Validation with newly created tests would be simpler to implement than using existing tests, since the tests can be written to take into account memory poisoning. It is also possible to build such a testsuite using existing tests as a starting point - `mbedtls_test_psa_exercise_key` is a test helper that already exercises many PSA operations on a key. This would need to be extended to cover operations without keys (e.g. hashes) and multipart operations, but it provides a good base from which to build all of the required testing.
+
+Additionally, we can ensure that all functions are exercised by automatically generating test data files.
+
+##### Validation with existing tests
+
+An alternative approach would be to integrate memory poisoning validation with existing tests. This has two main advantages:
+
+* All of the tests are written already, potentially saving development time.
+* The code coverage of these tests is greater than would be achievable writing new tests from scratch. In practice this advantage is small as buffer copying will take place in the dispatch layer. The tests are therefore independent of the values of parameters passed to the driver, so extra coverage in these parameters does not gain anything.
+
+It may be possible to transparently implement memory poisoning so that existing tests can work without modification. This would be achieved by replacing the implementation of `malloc()` with one that allocates poisoned buffers. However, there are some difficulties with this:
+
+* Not all buffers allocated by tests are used as inputs and outputs to PSA functions being tested.
+* Those buffers that are inputs to a PSA function need to be unpoisoned right up until the function is called, so that they can be filled with input data.
+* Those buffers that are outputs from a PSA function need to be unpoisoned straight after the function returns, so that they can be read to check the output is correct.
+
+These issues may be solved by creating some kind of test wrapper around every PSA function call that poisons the memory. However, it is unclear how straightforward this will be in practice. If this is simple to achieve, the extra coverage and time saved on new tests will be a benefit. If not, writing new tests is the best strategy.
+
+**Design decision: Add memory poisoning transparently to existing tests.**
+
+#### Discussion of copying validation
+
+Of all discussed approaches, validation by memory poisoning appears as the best. This is because it:
+
+* Does not require complex linking against different versions of `malloc()` (as is the case with the memory pool approach).
+* Allows automated testing (unlike the review approach).
+
+**Design decision: Use a memory poisoning approach to validate copying.**
+
+### Shared memory protection requirements
+
+TODO: write document and reference it here.
+
+### Validation of careful access for built-in drivers
+
+For PSA functions whose inputs and outputs are not copied, it is important that we validate that the builtin drivers are correctly accessing their inputs and outputs so as not to cause a security issue. Specifically, we must check that each memory location in a shared buffer is not accessed more than once by a driver function. In this section we examine various possible methods for performing this validation.
+
+Note: We are focusing on read-read inconsistencies for now, as most of the cases where we aren't copying are inputs.
+
+#### Review
+
+As with validation of copying, the simplest method of validation we can implement is careful code review. This is the least desirable method of validation for several reasons:
+
+1. It is tedious for the reviewers.
+2. Reviewers are prone to make mistakes (especially when performing tedious tasks).
+3. It requires engineering time linear in the number of PSA functions to be tested.
+4. It cannot assure the quality of third-party drivers, whereas automated tests can be ported to any driver implementation in principle.
+
+If all other approaches turn out to be prohibitively difficult, code review exists as a fallback option. However, it should be understood that this is far from ideal.
+
+#### Tests using `mprotect()`
+
+Checking that a memory location is not accessed more than once may be achieved by using `mprotect()` on a Linux system to cause a segmentation fault whenever a memory access happens. Tests based on this approach are sketched below.
+
+##### Linux mprotect+ptrace
+
+Idea: call `mmap` to allocate memory for arguments and `mprotect` to deny or reenable access. Use `ptrace` from a parent process to react to SIGSEGV from a denied access. On SIGSEGV happening in the faulting region:
+
+1. Use `ptrace` to execute a `mprotect` system call in the child to enable access. TODO: How? `ptrace` can modify registers and memory in the child, which includes changing parameters of a syscall that's about to be executed, but not directly cause the child process to execute a syscall that it wasn't about to execute.
+2. Use `ptrace` with `PTRACE_SINGLESTEP` to re-execute the failed load/store instrution.
+3. Use `ptrace` to execute a `mprotect` system call in the child to disable access.
+4. Use `PTRACE_CONT` to resume the child execution.
+
+Record the addresses that are accessed. Mark the test as failed if the same address is read twice.
+
+##### Debugger + mprotect
+
+Idea: call `mmap` to allocate memory for arguments and `mprotect` to deny or reenable access. Use a debugger to handle SIGSEGV (Gdb: set signal catchpoint). If the segfault was due to accessing the protected region:
+
+1. Execute `mprotect` to allow access.
+2. Single-step the load/store instruction.
+3. Execute `mprotect` to disable access.
+4. Continue execution.
+
+Record the addresses that are accessed. Mark the test as failed if the same address is read twice. This part might be hard to do in the gdb language, so we may want to just log the addresses and then use a separate program to analyze the logs, or do the gdb tasks from Python.
+
+#### Instrumentation (Valgrind)
+
+An alternative approach is to use a dynamic instrumentation tool (the most obvious being Valgrind) to trace memory accesses and check that each of the important memory addresses is accessed no more than once.
+
+Valgrind has no tool specifically that checks the property that we are looking for. However, it is possible to generate a memory trace with Valgrind using the following:
+
+```
+valgrind --tool=lackey --trace-mem=yes --log-file=logfile ./myprogram
+```
+This will execute `myprogram` and dump a record of every memory access to `logfile`, with its address and data width. If `myprogram` is a test that does the following:
+
+1. Set up input and output buffers for a PSA function call.
+2. Leak the start and end address of each buffer via `print()`.
+3. Write data into the input buffer exactly once.
+4. Call the PSA function.
+5. Read data from the output buffer exactly once.
+
+Then it should be possible to parse the output from the program and from Valgrind and check that each location was accessed exactly twice: once by the program's setup and once by the PSA function.
+
+#### Fixed Virtual Platform testing
+
+It may be possible to measure double accesses by running tests on a Fixed Virtual Platform such as Corstone 310 ecosystem FVP, available [here](https://developer.arm.com/downloads/-/arm-ecosystem-fvps). There exists a pre-packaged example program for the Corstone 310 FVP available as part of the Open IoT SDK [here](https://git.gitlab.arm.com/iot/open-iot-sdk/examples/sdk-examples/-/tree/main/examples/mbedtls/cmsis-rtx/corstone-310) that could provide a starting point for a set of tests.
+
+Running on an FVP allows two approaches to careful-access testing:
+
+* Convenient scripted use of a debugger with [Iris](https://developer.arm.com/documentation/101196/latest/). This allows memory watchpoints to be set, perhaps more flexibly than with GDB.
+* Tracing of all memory accesses with [Tarmac Trace](https://developer.arm.com/documentation/100964/1123/Plug-ins-for-Fast-Models/TarmacTrace). To validate the single-access properties, the [processor memory access trace source](https://developer.arm.com/documentation/100964/1123/Plug-ins-for-Fast-Models/TarmacTrace/Processor-memory-access-trace) can be used to output all memory accesses happening on the FVP. This output can then be easily parsed and processed to ensure that the input and output buffers are accessed only once. The addresses of buffers can either be leaked by the program through printing to the serial port or set to fixed values in the FVP's linker script.
+
+#### Discussion of careful-access validation
+
+The best approach for validating the correctness of memory accesses is an open question that requires further investigation. To answer this question, each of the test strategies discussed above must be prototyped as follows:
+
+1. Take 1-2 days to create a basic prototype of a test that uses the approach.
+2. Document the prototype - write a short guide that can be followed to arrive at the same prototype.
+3. Evaluate the prototype according to its usefulness. The criteria of evaluation should include:
+ * Ease of implementation - Was the prototype simple to implement? Having implemented it, is it simple to extend it to do all of the required testing?
+ * Flexibility - Could the prototype be extended to cover other careful-access testing that may be needed in future?
+ * Performance - Does the test method perform well? Will it cause significant slowdown to CI jobs?
+ * Ease of reproduction - Does the prototype require a particular platform or tool to be set up? How easy would it be for an external user to run the prototype?
+ * Comprehensibility - Accounting for the lower code quality of a prototype, would developers unfamiliar with the tests based on the prototype be able to understand them easily?
+ * Portability - How well can this approach be ported to multiple platforms? This would allow us to ensure that there are no double-accesses due to a bug that only affects a specific target.
+
+Once each prototype is complete, choose the best approach to implement the careful-access testing. Implement tests using this approach for each of the PSA interfaces that require careful-access testing:
+
+* Hash
+* MAC
+* AEAD (additional data only)
+* Key derivation
+* Asymmetric signature (input only)
+
+##### New vs existing tests
+
+Most of the test methods discussed above need extra setup. Some require leaking of buffer bounds, predictable memory access patterns or allocation of special buffers. FVP testing even requires the tests to be run on a non-host target.
+
+With this complexity in mind it does not seem feasible to run careful-access tests using existing testsuites. Instead, new tests should be written that exercise the drivers in the required way. Fortunately, the only interfaces that need testing are hash, MAC, AEAD (testing over AD only), Key derivation and Asymmetric signature, which limits the number of new tests that must be written.
+
+#### Validation of validation for careful-access
+
+In order to ensure that the careful-access validation works, it is necessary to write tests to check that we can correctly detect careful-access violations when they occur. To do this, write a test function that:
+
+* Reads its input multiple times at the same location.
+* Writes to its output multiple times at the same location.
+
+Then, write a careful-access test for this function and ensure that it fails.
+
+## Analysis of argument protection in built-in drivers
+
+TODO: analyze the built-in implementations of mechanisms for which there is a requirement on drivers. By code inspection, how satisfied are we that they meet the requirement?
+
+## Copy bypass
+
+For efficiency, we are likely to want mechanisms to bypass the copy and process buffers directly in builds that are not affected by shared memory considerations.
+
+Expand this section to document any mechanisms that bypass the copy.
+
+Make sure that such mechanisms preserve the guarantees when buffers overlap.
+
+## Detailed design
+
+### Implementation by module
+
+Module | Input protection strategy | Output protection strategy | Notes
+---|---|---|---
+Hash and MAC | Careful access | Careful access | Low risk of multiple-access as the input and output are raw unformatted data.
+Cipher | Copying | Copying |
+AEAD | Copying (careful access for additional data) | Copying |
+Key derivation | Careful access | Careful access |
+Asymmetric signature | Careful access | Copying | Inputs to signatures are passed to a hash. This will no longer hold once PureEdDSA support is implemented.
+Asymmetric encryption | Copying | Copying |
+Key agreement | Copying | Copying |
+PAKE | Copying | Copying |
+Key import / export | Copying | Copying | Keys may be imported and exported in DER format, which is a structured format and therefore susceptible to read-read inconsistencies and potentially write-read inconsistencies.
+
+### Copying functions
+
+As discussed in [Copying code](#copying-code), it is simpler to use a single unified API for copying. Therefore, we create the following functions:
+
+* `psa_crypto_copy_input(const uint8_t *input, size_t input_length, uint8_t *input_copy, size_t input_copy_length)`
+* `psa_crypto_copy_output(const uint8_t *output_copy, size_t output_copy_length, uint8_t *output, size_t output_length)`
+
+These seem to be a repeat of the same function, however it is useful to retain two separate functions for input and output parameters so that we can use different test hooks in each when using memory poisoning for tests.
+
+Given that the majority of functions will be allocating memory on the heap to copy, it is helpful to build convenience functions that allocate the memory as well.
+
+In order to keep track of allocated copies on the heap, we can create new structs:
+
+```c
+typedef struct psa_crypto_local_input_s {
+ uint8_t *buffer;
+ size_t length;
+} psa_crypto_local_input_t;
+
+typedef struct psa_crypto_local_output_s {
+ uint8_t *original;
+ uint8_t *buffer;
+ size_t length;
+} psa_crypto_local_output_t;
+```
+
+These may be used to keep track of input and output copies' state, and ensure that their length is always stored with them. In the case of output copies, we keep a pointer to the original buffer so that it is easy to perform a writeback to the original once we have finished outputting.
+
+With these structs we may create 2 pairs of functions, one pair for input copies:
+
+```c
+psa_status_t psa_crypto_local_input_alloc(const uint8_t *input, size_t input_len,
+ psa_crypto_local_input_t *local_input);
+
+void psa_crypto_local_input_free(psa_crypto_local_input_t *local_input);
+```
+
+* `psa_crypto_local_input_alloc()` calls `calloc()` to allocate a new buffer of length `input_len`, copies the contents across from `input`. It then stores `input_len` and the pointer to the copy in the struct `local_input`.
+* `psa_crypto_local_input_free()` calls `free()` on the local input that is referred to by `local_input` and sets the pointer in the struct to `NULL`.
+
+We also create a pair of functions for output copies:
+
+```c
+psa_status_t psa_crypto_local_output_alloc(uint8_t *output, size_t output_len,
+ psa_crypto_local_output_t *local_output);
+
+psa_status_t psa_crypto_local_output_free(psa_crypto_local_output_t *local_output);
+```
+
+* `psa_crypto_local_output_alloc()` calls `calloc()` to allocate a new buffer of length `output_len` and stores `output_len` and the pointer to the buffer in the struct `local_output`. It also stores a pointer to `output` in `local_output->original`.
+* `psa_crypto_local_output_free()` copies the contents of the output buffer `local_output->buffer` into the buffer `local_output->original`, calls `free()` on `local_output->buffer` and sets it to `NULL`.
+
+Some PSA functions may not use these convenience functions as they may have local optimizations that reduce memory usage. For example, ciphers may be able to use a single intermediate buffer for both input and output.
+
+In order to abstract the management of the copy state further, to make it simpler to add, we create the following 6 convenience macros:
+
+For inputs:
+
+* `LOCAL_INPUT_DECLARE(input, input_copy_name)`, which declares and initializes a `psa_crypto_local_input_t` and a pointer with the name `input_copy_name` in the current scope.
+* `LOCAL_INPUT_ALLOC(input, input_size, input_copy)`, which tries to allocate an input using `psa_crypto_local_input_alloc()`. On failure, it sets an error code and jumps to an exit label. On success, it sets `input_copy` to point to the copy of the buffer.
+* `LOCAL_INPUT_FREE(input, input_copy)`, which frees the input copy using `psa_crypto_local_input_free()` and sets `input_copy` to `NULL`.
+
+For outputs:
+
+* `LOCAL_OUTPUT_DECLARE(output, output_copy_name)`, analogous to `LOCAL_INPUT_DECLARE()` for `psa_crypto_local_output_t`.
+* `LOCAL_OUTPUT_ALLOC(output, output_size, output_copy)`, analogous to `LOCAL_INPUT_ALLOC()` for outputs, calling `psa_crypto_local_output_alloc()`.
+* `LOCAL_OUTPUT_FREE(output, output_copy)`, analogous to `LOCAL_INPUT_FREE()` for outputs. If the `psa_crypto_local_output_t` is in an invalid state (the copy pointer is valid, but the original pointer is `NULL`) this macro sets an error status.
+
+These macros allow PSA functions to have copying added while keeping the code mostly unmodified. Consider a hypothetical PSA function:
+
+```c
+psa_status_t psa_foo(const uint8_t *input, size_t input_length,
+ uint8_t *output, size_t output_size, size_t *output_length)
+{
+ /* Do some operation on input and output */
+}
+```
+
+By changing the name of the input and output parameters, we can retain the original variable name as the name of the local copy while using a new name (e.g. with the suffix `_external`) for the original buffer. This allows copying to be added near-seamlessly as follows:
+
+```c
+psa_status_t psa_foo(const uint8_t *input_external, size_t input_length,
+ uint8_t *output_external, size_t output_size, size_t *output_length)
+{
+ psa_status_t status;
+
+ LOCAL_INPUT_DECLARE(input_external, input);
+ LOCAL_OUTPUT_DECLARE(output_external, output);
+
+ LOCAL_INPUT_ALLOC(input_external, input);
+ LOCAL_OUTPUT_ALLOC(output_external, output);
+
+ /* Do some operation on input and output */
+
+exit:
+ LOCAL_INPUT_FREE(input_external, input);
+ LOCAL_OUTPUT_FREE(output_external, output);
+}
+```
+
+A second advantage of using macros for the copying (other than simple convenience) is that it allows copying to be easily disabled by defining alternate macros that function as no-ops. Since buffer copying is specific to systems where shared memory is passed to PSA functions, it is useful to be able to disable it where it is not needed, to save code size.
+
+To this end, the macros above are defined conditionally on a new config option, `MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS`, which may be set whenever PSA functions are assumed to have exclusive access to their input and output buffers. When `MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS` is set, the macros do not perform copying.
+
+### Implementation of copying validation
+
+As discussed in the [design exploration of copying validation](#validation-of-copying), the best strategy for validation of copies appears to be validation by memory poisoning, implemented using Valgrind and ASan.
+
+To perform memory poisoning, we must implement the functions alluded to in [Validation of copying by memory poisoning](#validation-of-copying-by-memory-poisoning):
+```c
+void mbedtls_test_memory_poison(const unsigned char *ptr, size_t size);
+void mbedtls_test_memory_unpoison(const unsigned char *ptr, size_t size);
+```
+This should poison or unpoison the given buffer, respectively.
+
+* `mbedtls_test_memory_poison()` is equivalent to calling `VALGRIND_MAKE_MEM_NOACCESS(ptr, size)` or `ASAN_POISON_MEMORY_REGION(ptr, size)`.
+* `mbedtls_test_memory_unpoison()` is equivalent to calling `VALGRIND_MAKE_MEM_DEFINED(ptr, size)` or `ASAN_UNPOISON_MEMORY_REGION(ptr, size)`.
+
+The PSA copying function must then have test hooks implemented as outlined in [Validation of copying by memory poisoning](#validation-of-copying-by-memory-poisoning).
+
+As discussed in [the design exploration](#validation-with-existing-tests), the preferred approach for implementing copy-testing is to implement it transparently using existing tests. This is specified in more detail below.
+
+#### Transparent allocation-based memory poisoning
+
+In order to implement transparent memory poisoning we require a wrapper around all PSA function calls that poisons any input and output buffers.
+
+The easiest way to do this is to create wrapper functions that poison the memory and then `#define` PSA function names to be wrapped versions of themselves. For example, to replace `psa_aead_update()`:
+```c
+psa_status_t mem_poison_psa_aead_update(psa_aead_operation_t *operation,
+ const uint8_t *input,
+ size_t input_length,
+ uint8_t *output,
+ size_t output_size,
+ size_t *output_length)
+{
+ mbedtls_test_memory_poison(input, input_length);
+ mbedtls_test_memory_poison(output, output_size);
+ psa_status_t status = psa_aead_update(operation, input, input_length,
+ output, output_size, output_length);
+ mbedtls_test_memory_unpoison(input, input_length);
+ mbedtls_test_memory_unpoison(output, output_size);
+
+ return status;
+}
+
+#define psa_aead_update(...) mem_poison_psa_aead_update(__VA_ARGS__)
+```
+
+There now exists a more generic mechanism for making exactly this kind of transformation - the PSA test wrappers, which exist in the files `tests/include/test/psa_test_wrappers.h` and `tests/src/psa_test_wrappers.c`. These are wrappers around all PSA functions that allow testing code to be inserted at the start and end of a PSA function call.
+
+The test wrappers are generated by a script, although they are not automatically generated as part of the build process. Instead, they are checked into source control and must be manually updated when functions change by running `tests/scripts/generate_psa_wrappers.py`.
+
+Poisoning code is added to these test wrappers where relevant in order to pre-poison and post-unpoison the parameters to the functions.
+
+#### Configuration of poisoning tests
+
+Since the memory poisoning tests will require the use of interfaces specific to the sanitizers used to poison memory, they must only be enabled when we are building with ASan or Valgrind. For now, we can auto-detect ASan at compile-time and set an option: `MBEDTLS_TEST_MEMORY_CAN_POISON`. When this option is enabled, we build with memory-poisoning support. This enables transparent testing with ASan without needing any extra configuration options.
+
+Auto-detection and memory-poisoning with Valgrind is left for future work.
+
+#### Validation of validation for copying
+
+To make sure that we can correctly detect functions that access their input/output buffers rather than the copies, it would be best to write a test function that misbehaves and test it with memory poisoning. Specifically, the function should:
+
+* Read its input buffer and after calling the input-buffer-copying function to create a local copy of its input.
+* Write to its output buffer before and after calling the output-buffer-copying function to copy-back its output.
+
+Then, we could write a test that uses this function with memory poisoning and ensure that it fails. Since we are expecting a failure due to memory-poisoning, we would run this test separately from the rest of the memory-poisoning testing.
+
+This testing is implemented in `programs/test/metatest.c`, which is a program designed to check that test failures happen correctly. It may be run via the script `tests/scripts/run-metatests.sh`.
diff --git a/docs/architecture/psa-storage-resilience.md b/docs/architecture/psa-storage-resilience.md
new file mode 100644
index 0000000..2f190d3
--- /dev/null
+++ b/docs/architecture/psa-storage-resilience.md
@@ -0,0 +1,536 @@
+# PSA storage resilience design
+
+## Introduction
+
+The PSA crypto subsystem includes a persistent key store. It is possible to create a persistent key and read it back later. This must work even if the underlying storage exhibits non-nominal behavior. In this document, _resilience_ means correct behavior of the key store even under if the underlying platform behaves in a non-nominal, but still partially controlled way.
+
+At this point, we are only concerned about one specific form of resilience: to a system crash or power loss. That is, we assume that the underlying platform behaves nominally, except that occasionally it may restart. In the field, this can happen due to a sudden loss of power.
+
+This document explores the problem space, defines a library design and a test design.
+
+## Resilience goals for API functions
+
+**Goal: PSA Crypto API functions are atomic and committing.**
+
+_Atomic_ means that when an application calls an API function, as far as the application is concerned, at any given point in time, the system is either in a state where the function has not started yet, or in a state where the function has returned. The application never needs to worry about an intermediate state.
+
+_Committing_ means that when a function returns, the data has been written to the persistent storage. As a consequence, if the system restarts during a sequence of storage modifications $M_1, M_2, \ldots, M_n$, we know that when the system restarts, a prefix of the sequence has been performed. For example, there will never be a situation where $M_2$ has been performed but not $M_1$.
+
+The committing property is important not only for sequences of operations, but also when reporting the result of an operation to an external system. For example, if a key creation function in the PSA Crypto API reports to the application that a key has been created, and the application reports to a server that the key has been created, it is guaranteed that the key exists even if the system restarts.
+
+## Assumptions on the underlying file storage
+
+PSA relies on a PSA ITS (Internal Trusted Storage) interface, which exposes a simple API. There are two functions to modify files:
+
+* `set()` writes a whole file (either creating it, or replacing the previous content).
+* `remove()` removes a file (returning a specific error code if the file does not exist).
+
+**Assumption: the underlying ITS functions are atomic and committing.**
+
+Since the underlying functions are atomic, the content of a file is always a version that was previously passed to `set()`. We do not try to handle the case where a file might be partially written.
+
+## Overview of API functions
+
+For a transparent key, all key management operations (creation or destruction) on persistent keys rely on a single call to the underlying storage (`set()` for a key creation, `remove()` for a key destruction). This also holds for an opaque key stored in a secure element that does not have its own key store: in this case, the core stores a wrapped (i.e. encrypted) copy of the key material, but this does not impact how the core interacts with the storage. Other API functions do not modify the storage.
+
+The following case requires extra work related to resilience:
+
+* [Key management for stateful secure element keys](#designing-key-management-for-secure-element-keys).
+
+As a consequence, apart from the listed cases, the API calls inherit directly from the [resilience properties of the underyling storage](#assumptions-on-the-underlying-file-storage). We do not need to take any special precautions in the library design, and we do not need to perform any testing of resilience for transparent keys.
+
+(This section was last updated for Mbed TLS 3.4.0 implementing PSA Crypto API 1.1.)
+
+## Designing key management for secure element keys
+
+In this section, we use “(stateful) secure element key” to mean a key stored in a stateful secure element, i.e. a secure element that stores keys. This excludes keys in a stateleess secure element for which the core stores a wrapped copy of the key. We study the problem of how key management in stateful secure elements interacts with storage and explore the design space.
+
+### Assumptions on stateful secure elements
+
+**Assumption: driver calls for key management in stateful secure elements are atomic and committing.**
+
+(For stateless secure elements, this assumption is vacuously true.)
+
+### Dual management of keys: the problem
+
+For a secure element key, key management requires a commitment on both sites. For example, consider a successful key creation operation:
+
+1. The core sends a request to the secure element to create a key.
+2. The secure element modifies its key store to create the key.
+3. The secure element reports to the core that the key has been created.
+4. The core reports to the application that the key has been created.
+
+If the core loses power between steps 1 and 2, the key does not exist yet. This is fine from an application's perspective since the core has not committed to the key's existence, but the core needs to take care not to leave resources in storage that are related to the non-existent key. If the core loses power between steps 2 and 3, the key exists in the secure element. From an application's perspective, the core may either report that the key exists or that it does not exist, but in the latter case, the core needs to free the key in the secure element, to avoid leaving behind inaccessible resources.
+
+As a consequence, the content of the storage cannot remain the same between the end of step 1 and the end of step 3, since the core must behave differently depending on whether step 2 has taken place.
+
+Accomplishing a transaction across system boundaries is a well-known problem in database management, with a well-known solution: two-phase commit.
+
+### Overview of two-phase commit with stateful secure elements
+
+With a key in a stateful secure element, a successful creation process goes as follows (see [“Key management in a secure element with storage” in the driver interface specification](../../proposed/psa-driver-interface.html#key-management-in-a-secure-element-with-storage)):
+
+1. The core calls the driver's `"allocate_key"` entry point.
+2. The driver allocates a unique identifier _D_ for the key. This is unrelated to the key identifier _A_ used by the application interface. This step must not modify the state of the secure element.
+3. The core updates the storage to indicate that key identifier _A_ has the identifier _D_ in the driver, and that _A_ is in a half-created state.
+4. The core calls the driver's key creation entry point, passing it the driver's chosen identifier _D_.
+5. The driver creates the key in the secure element. When this happens, it concludes the voting phase of the two-phase commit: effectively, the secure element decides to commit. (It is however possible to revert this commitment by giving the secure element the order to destroy the key.)
+6. The core updates the storage to indicate that _A_ is now in a fully created state. This concludes the commit phase of the two-phase commit.
+
+If there is a loss of power:
+
+* Before step 3: the system state has not changed at all. As far as the world is concerned, the key creation attempt never happened.
+* Between step 3 and step 6: upon restart, the core needs to find out whether the secure element completed step 5 or not, and reconcile the state of the storage with the state of the secure element.
+* After step 6: the key has been created successfully.
+
+Key destruction goes as follows:
+
+1. The core updates the storage indicating that the key is being destroyed.
+2. The core calls the driver's `"destroy_key"` entry point.
+3. The secure element destroys the key.
+4. The core updates the storage to indicate that the key has been destroyed.
+
+If there is a loss of power:
+
+* Before step 1: the system state has not changed at all. As far as the world is concerned, the key destruction attempt never happened.
+* Between step 1 and step 4: upon restart, the core needs to find out whether the secure element completed step 3 or not, and reconcile the state of the storage with the state of the secure element.
+* After step 4: the key has been destroyed successfully.
+
+In both cases, upon restart, the core needs to perform a transaction recovery. When a power loss happens, the core decides whether to commit or abort the transaction.
+
+Note that the analysis in this section assumes that the driver does not update its persistent state during a key management operation (or at least not in a way that is influences the key management process — for example, it might renew an authorization token).
+
+### Optimization considerations for transactions
+
+We assume that power failures are rare. Therefore we will primarily optimize for the normal case. Transaction recovery needs to be practical, but does not have to be fully optimized.
+
+The main quantity we will optimize for is the number of storage updates in the nominal case. This is good for performance because storage writes are likely to dominate the runtime in some hardware configurations where storage writes are slow and communication with the secure element is fast, for key management operations that require a small amount of computation. In addition, minimizing the number of storage updates is good for the longevity of flash media.
+
+#### Information available during recovery
+
+The PSA ITS API does not support enumerating files in storage: an ITS call can only access one file identifier. Therefore transaction recovery cannot be done by traversing files whose name is or encodes the key identifier. It must start by traversing a small number of files whose names are independent of the key identifiers involved.
+
+#### Minimum effort for a transaction
+
+Per the [assumptions on the underlying file storage](#assumptions-on-the-underlying-file-storage), each atomic operation in the internal storage concerns a single file: either removing it, or setting its content. Furthermore there is no way to enumerate the files in storage.
+
+A key creation function must transform the internal storage from a state where file `id` does not exist, to a state where file `id` exists and has its desired final content (containing the key attributes and the driver's key identifier). The situation is similar with key destruction, except that the initial and final states are exchanged. Neither the initial state nor the final state reference `id` otherwise.
+
+For a key that is not in a stateful element, the transaction consists of a single write operation. As discussed previously, this is not possible with a stateful secure element because the state of the internal storage needs to change both before and after the state change in the secure element. No other single-write algorithm works.
+
+If there is a power failure around the time of changing the state of the secure element, there must be information in the internal storage that indicates that key `id` has a transaction in progress. The file `id` cannot be used for this purpose because there is no way to enumerate all keys (and even if there was, it would not be practical). Therefore the transaction will need to modify some other file `t` with a fixed name (a name that doesn't depend on the key). Since the final system state should be identical to the initial state except for the file `id`, the minimum number of storage operations for a transaction is 3:
+
+* Write (create or update) a file `t` referencing `id`.
+* Write the final state of `id`.
+* Restore `t` to its initial state.
+
+The strategies discussed in the [overview above](#overview-of-two-phase-commit-with-stateful-secure-elements) follow this pattern, with `t` being the file containing the transaction list that the recovery consults. We have just proved that this pattern is optimal.
+
+Note that this pattern requires the state of `id` to be modified only once. In particular, if a key management involves writing an intermediate state for `id` before modifying the secure element state and writing a different state after that, this will require a total of 4 updates to internal storage. Since we want to minimize the number of storage updates, we will not explore designs that involved updating `id` twice or more.
+
+### Recovery strategies
+
+When the core starts, it needs to know about transaction(s) that need to be resumed. This information will be stored in a persistent “transaction list”, with one entry per key. In this section, we explore recovery strategies, and we determine what the transaction list needs to contain as well as when it needs to be updated. Other sections will explore the format of the transaction list, as well as how many keys it needs to contain.
+
+#### Exploring the recovery decision tree
+
+There are four cases for recovery when a transaction is in progress. In each case, the core can either decide to commit the transaction (which may require replaying the interrupted part) or abort it (which may require a rewind in the secure element). It may call the secure element driver's `"get_key_attributes"` entry point to find out whether the key is present.
+
+* Key creation, key not present in the secure element:
+ * Committing means replaying the driver call in the key creation. This requires all the input, for example the data to import. This seems impractical in general. Also, the second driver call require a new call to `"allocate_key"` which will in general changing the key's driver identifier, which complicates state management in the core. Given the likely complexity, we exclude this strategy.
+ * Aborting means removing any trace of the key creation.
+* Key creation, key present in the secure element:
+ * Committing means finishing the update of the core's persistent state, as would have been done if the transaction had not been interrupted.
+ * Aborting means destroying the key in the secure element and removing any local storage used for that key.
+* Key destruction, key not present in the secure element:
+ * Committing means finishing the update of the core's persistent state, as would have been done if the transaction had not been interrupted, by removing any remaining local storage used for that key.
+ * Aborting would mean re-creating the key in the secure element, which is impossible in general since the key material is no longer present.
+* Key destruction, key present in the secure element:
+ * Committing means finishing the update of the core's persistent state, as would have been done if the transaction had not been interrupted, by removing any remaining local storage used for that key and destroying the key in the secure element.
+ * Aborting means keeping the key. This requires no action on the secure element, and is only practical locally if the local storage is intact.
+
+#### Comparing recovery strategies
+
+From the analysis above, assuming that all keys are treated in the same way, there are 4 possible strategies.
+
+* [Always follow the state of the secure element](#exploring-the-follow-the-secure-element-strategy). This requires the secure element driver to have a `"get_key_attributes"` entry point. Recovery means resuming the operation where it left off. For key creation, this means that the key metadata needs to be saved before calling the secure element's key creation entry point.
+* Minimize the information processing: [always destroy the key](#exploring-the-always-destroy-strategy), i.e. abort all key creations and commit all key destructions. This does not require querying the state of the secure element. This does not require any special precautions to preserve information about the key during the transaction. It simplifies recovery in that the recovery process might not even need to know whether it's recovering a key creation or a key destruction.
+* Follow the state of the secure element for key creation, but always go ahead with key destruction. This requires the secure element driver to have a `"get_key_attributes"` entry point. Compared to always following the state of the secure element, this has the advantage of maximizing the chance that a command to destroy key material is effective. Compared to always destroying the key, this has a performance advantage if a key creation is interrupted. These do not seem like decisive advantages, so we will not consider this strategy further.
+* Always abort key creation, but follow the state of the secure element for key destruction. I can't think of a good reason to choose this strategy.
+
+Requiring the driver to have a `"get_key_attributes"` entry point is potentially problematic because some secure elements don't have room to store key attributes: a key slot always exists, and it's up to the user to remember what, if anything, they put in it. The driver has to remember anyway, so that it can find a free slot when creating a key. But with a recovery strategy that doesn't involve a `"get_key_attributes"` entry point, the driver design is easier: the driver doesn't need to protect the information about slots in use against a power failure, the core takes care of that.
+
+#### Exploring the follow-the-secure-element strategy
+
+Each entry in the transaction list contains the API key identifier, the key lifetime (or at least the location), the driver key identifier (not constant-size), and an indication of whether the key is being created or destroyed.
+
+For key creation, we have all the information to store in the key file once the `"allocate_key"` call returns. We must store all the information that will go in the key file before calling the driver's key creation entry point. Therefore the normal sequence of operations is:
+
+1. Call the driver's `"allocate_key"` entry point.
+2. Add the key to the transaction list, indicating that it is being created.
+3. Write the key file.
+4. Call the driver's key creation entry point.
+5. Remove the key from the transaction list.
+
+During recovery, for each key in the transaction list that was being created:
+
+* If the key exists in the secure element, just remove it from the transaction list.
+* If the key does not exist in the secure element, first remove the key file if it is present, then remove the key from the transaction list.
+
+For key destruction, we need to preserve the key file until after the key has been destroyed. Therefore the normal sequence of operations is:
+
+1. Add the key to the transaction list, indicating that it is being destroyed.
+2. Call the driver's `"destroy_key"` entry point.
+3. Remove the key file.
+4. Remove the key from the transaction list.
+
+During recovery, for each key in the transaction list that was being created:
+
+* If the key exists in the secure element, call the driver's `"destroy_key"` entry point, then remove the key file, and finally remote the key from the transaction lits.
+* If the key does not exist in the secure element, remove the key file if it is still present, then remove the key from the transaction list.
+
+#### Exploring the always-destroy strategy
+
+Each entry in the transaction list contains the API key identifier, the key lifetime (or at least the location), and the driver key identifier (not constant-size).
+
+For key creation, we do not need to store the key's metadata until it has been created in the secure element. Therefore the normal sequence of operations is:
+
+1. Call the driver's `"allocate_key"` entry point.
+2. Add the key to the transaction list.
+3. Call the driver's key creation entry point.
+4. Write the key file.
+5. Remove the key from the transaction list.
+
+For key destruction, we can remove the key file before contacting the secure element. Therefore the normal sequence of operations is:
+
+1. Add the key to the transaction list.
+2. Remove the key file.
+3. Call the driver's `"destroy_key"` entry point.
+4. Remove the key from the transaction list.
+
+Recovery means removing all traces of all keys on the transaction list. This means following the destruction process, starting after the point where the key has been added to the transaction list, and ignoring any failure of a removal action if the item to remove does not exist:
+
+1. Remove the key file, treating `DOES_NOT_EXIST` as a success.
+2. Call the driver's `"destroy_key"` entry point, treating `DOES_NOT_EXIST` as a success.
+3. Remove the key from the transaction list.
+
+#### Always-destroy strategy with a simpler transaction file
+
+We can modify the [always-destroy strategy](#exploring-the-always-destroy-strategy) to make the transaction file simpler: if we ensure that the key file always exists if the key exists in the secure element, then the transaction list does not need to include the driver key identifier: it can be read from the key file.
+
+For key creation, we need to store the key's metadata before creating in the secure element. Therefore the normal sequence of operations is:
+
+1. Call the driver's `"allocate_key"` entry point.
+2. Add the key to the transaction list.
+3. Write the key file.
+4. Call the driver's key creation entry point.
+5. Remove the key from the transaction list.
+
+For key destruction, we need to contact the secure element before removing the key file. Therefore the normal sequence of operations is:
+
+1. Add the key to the transaction list.
+2. Call the driver's `"destroy_key"` entry point.
+3. Remove the key file.
+4. Remove the key from the transaction list.
+
+Recovery means removing all traces of all keys on the transaction list. This means following the destruction process, starting after the point where the key has been added to the transaction list, and ignoring any failure of a removal action if the item to remove does not exist:
+
+1. Load the driver key identifier from the key file. If the key file does not exist, skip to step 4.
+2. Call the driver's `"destroy_key"` entry point, treating `DOES_NOT_EXIST` as a success.
+3. Remove the key file, treating `DOES_NOT_EXIST` as a success.
+4. Remove the key from the transaction list.
+
+Compared with the basic always-destroy strategy:
+
+* The transaction file handling is simpler since its entries have a fixed size.
+* The flow of information is somewhat different from transparent keys and keys in stateless secure elements: we aren't just replacing “create the key material” by “tell the secure element to create the key material”, those happen at different times. But there's a different flow for stateful secure elements anyway, since the call to `"allocate_key"` has no analog in the stateless secure element or transparent cases.
+
+#### Assisting secure element drivers with recovery
+
+The actions of the secure element driver may themselves be non-atomic. So the driver must be given a chance to perform recovery.
+
+To simplify the design of the driver, the core should guarantee that the driver will know if a transaction was in progress and the core cannot be sure about the state of the secure element. Merely calling a read-only entry point such as `"get_key_attributes"` does not provide enough information to the driver for it to know that it should actively perform recovery related to that key.
+
+This gives an advantage to the “always destroy” strategy. Under this strategy, if the key might be in a transitional state, the core will request a key destruction from the driver. This means that, if the driver has per-key auxiliary data to clean up, it can bundle that as part of the key's destruction.
+
+### Testing non-atomic processes
+
+In this section, we discuss how to test non-atomic processes that must implement an atomic and committing interface. As discussed in [“Overview of API functions”](#overview-of-api-functions), this concerns key management in stateful secure elements.
+
+#### Naive test strategy for non-atomic processes
+
+Non-atomic processes consist of a series of atomic, committing steps.
+
+Our general strategy to test them is as follows: every time there is a modification of persistent state, either in storage or in the (simulated) secure element, try both the nominal case and simulating a power loss. If a power loss occurs, restart the system (i.e. clean up and call `psa_crypto_init()`), and check that the system ends up in a consistent state.
+
+Note that this creates a binary tree of possibilities: after each state modification, there may or may not be a restart, and after that different state modifications may occur, each of which may or may not be followed by a restart.
+
+For example, consider testing of one key creation operation (see [“Overview of two-phase commit with stateful secure elements”](#overview-of-two-phase-commit-with-stateful-secure-elements), under the simplifying assumption that each storage update step, as well as the recovery after a restart, each make a single (atomic) storage modification and no secure element access. The nominal case consists of three state modifications: storage modification (start transaction), creation on the secure element, storage modification (commit transaction). We need to test the following sequences:
+
+* Start transaction, restart, recovery.
+* Start transaction, secure element operation, restart, recovery.
+* Start transaction, secure element operation, commit transaction.
+
+If, for example, recovery consists of two atomic steps, the tree of possibilities expands and may be infinite:
+
+* Start transaction, restart, recovery step 1, restart, recovery step 1, recovery step 2.
+* Start transaction, restart, recovery step 1, restart, recovery step 1, restart, recovery step 1, recovery step 2.
+* Start transaction, restart, recovery step 1, restart, recovery step 1, restart, recovery step 1, restart, recovery step 1, recovery step 2.
+* etc.
+* Start transaction, secure element operation, restart, ...
+* Start transaction, secure element operation, commit transaction.
+
+In order to limit the possibilities, we need to make some assumptions about the recovery step. For example, if we have confidence that recovery step 1 is idempotent (i.e. doing it twice is the same as doing it once), we don't need to test what happens in execution sequences that take recovery step 1 more than twice in a row.
+
+### Splitting normal behavior and transaction recovery
+
+We introduce an abstraction level in transaction recovery:
+
+* Normal operation must maintain a certain invariant on the state of the world (internal storage and secure element).
+* Transaction recovery is defined over all states of the world that satisfy this invariant.
+
+This separation of concerns greatly facilitates testing, since it is now split into two parts:
+
+* During the testing of normal operation, we can use read-only invasive testing to ensure that the invariant is maintained. No modification of normal behavior (such as simulated power failures) is necessary.
+* Testing of transaction recovery is independent of how the system state was reached. We only need to artificially construct a representative sample of system states that match the invariant. Transaction recovery is itself an operation that must respect the invariant, and so we do not need any special testing for the case of an interrupted recovery.
+
+Another benefit of this approach is that it is easier to specify and test what happens if the library is updated on a device with leftovers from an interrupted transaction. We will require and test that the new version of the library supports recovery of the old library's states, without worrying how those states were reached.
+
+#### Towards an invariant for transactions
+
+As discussed in the section [“Recovery strategies”](#recovery-strategies), the information about active transactions is stored in a transaction list file. The name of the transaction list file does not depend on the identifiers of the keys in the list, but there may be more than one transaction list, for example one per secure element. If so, each transaction list can be considered independently.
+
+When no transaction is in progress, the transaction list does not exist, or is empty. The empty case must be supported because this is the initial state of the filesystem. When no transaction is in progress, the state of the secure element must be consistent with references to keys in that secure element contained in key files. More generally, if a key is not in the transaction list, then the key must be present in the secure element if and only if the key file is in the internal storage.
+
+For the purposes of the state invariant, it matters whether the transaction list file contains the driver key identifier, or if the driver key identifier is only stored in the key file. This is because the core needs to know the driver key id in order to access the secure element. If the transaction list does not contain the driver key identifier, and the key file does not exist, the key must not be present in the secure element.
+
+We thus have two scenarios, each with their own invariant: one where the transaction list contains only key identifiers, and one where it also contains the secure element's key identifier (as well as the location of the secure element if this is not encoded in the name of the transaction list file).
+
+#### Storage invariant if the transaction list contains application key identifiers only
+
+Invariants:
+
+* If the file `id` does not exist, then no resources corresponding to that key are in a secure element. This holds whether `id` is in the transaction list or not.
+* If `id` is not in the transaction list and the file `id` exists and references a key in a stateful secure element, then the key is present in the secure element.
+
+If `id` is in the transaction list and the file `id` exists, the key may or may not be present in the secure element.
+
+The invariant imposes constraints on the [order of operations for the two-phase commit](#overview-of-two-phase-commit-with-stateful-secure-elements): key creation must create `id` before calling the secure element's key creation entry point, and key destruction must remove `id` after calling the secure element's key destruction entry point.
+
+For recovery:
+
+* If the file `id` does not exist, then nothing needs to be done for recovery, other than removing `id` from the transaction list.
+* If the file `id` exists:
+ * It is correct to destroy the key in the secure element (treating a `DOES_NOT_EXIST` error as a success), then remove `id`.
+ * It is correct to check whether the key exists in the secure element, and if it does, keep it and keep `id`. If not, remove `id` from the internal storage.
+
+#### Storage invariant if the transaction list contains driver key identifiers
+
+Invariants:
+
+* If `id` is not in the transaction list and the file `id` does not exist, then no resources corresponding to that key are in a secure element.
+* If `id` is not in the transaction list and the file `id` exists, then the key is present in the secure element.
+
+If `id` is in the transaction list, neither the state of `id` in the internal storage nor the state of the key in the secure element is known.
+
+For recovery:
+
+* If the file `id` does not exist, then destroy the key in the secure element (treating a `DOES_NOT_EXIST` error as a success).
+* If the file `id` exists:
+ * It is correct to destroy the key in the secure element (treating a `DOES_NOT_EXIST` error as a success), then remove `id`.
+ * It is correct to check whether the key exists in the secure element, and if it does, keep it and keep `id`. If not, remove `id` from the internal storage.
+
+#### Coverage of states that respect the invariant
+
+For a given key, we have to consider three a priori independent boolean states:
+
+* Whether the key file exists.
+* Whether the key is in the secure element.
+* Whether the key is in the transaction list.
+
+There is full coverage for one key if we have tests of recovery for the states among these $2^3 = 8$ possibilities that satisfy the storage invariant.
+
+In addition, testing should adequately cover the case of multiple keys in the transaction list. How much coverage is adequate depends on the layout of the list as well as white-box considerations of how the list is manipulated.
+
+### Choice of a transaction design
+
+#### Chosen transaction algorithm
+
+Based on [“Optimization considerations for transactions”](#optimization-considerations-for-transactions), we choose a transaction algorithm that consists in the following operations:
+
+1. Add the key identifier to the transaction list.
+2. Call the secure element's key creation or destruction entry point.
+3. Remove the key identifier from the transaction list.
+
+In addition, before or after step 2, create or remove the key file in the internal storage.
+
+In order to conveniently support multiple transactions at the same time, we pick the simplest possible layout for the transaction list: a simple array of key identifiers. Since the transaction list does not contain the driver key identifier:
+
+* During key creation, create the key file in internal storage in the internal storage before calling the secure element's key creation entry point.
+* During key destruction, call the secure element's key destruction entry point before removing the key file in internal storage.
+
+This choice of algorithm does not require the secure element driver to have a `"get_key_attributes"` entry point.
+
+#### Chosen storage invariant
+
+The [storage invariant](#storage-invariant-if-the-transaction-list-contains-application-key-identifiers-only) is as follows:
+
+* If the file `id` does not exist, then no resources corresponding to that key are in a secure element. This holds whether `id` is in the transaction list or not.
+* If `id` is not in the transaction list and the file `id` exists and references a key in a stateful secure element, then the key is present in the secure element.
+* If `id` is in the transaction list and a key exists by that identifier, the key's location is a stateful secure element.
+
+#### Chosen recovery process
+
+To [assist secure element drivers with recovery](#assisting-secure-element-drivers-with-recovery), we pick the [always-destroy recovery strategy with a simple transaction file](#always-destroy-strategy-with-a-simpler-transaction-file). The the recovery process is as follows:
+
+* If the file `id` does not exist, then nothing needs to be done for recovery, other than removing `id` from the transaction list.
+* If the file `id` exists, call the secure element's key destruction entry point (treating a `DOES_NOT_EXIST` error as a success), then remove `id`.
+
+## Specification of key management in stateful secure elements
+
+This section only concerns stateful secure elements as discussed in [“Designing key management for secure element keys”](#designing-key-management-for-secure-element-keys), i.e. secure elements with an `"allocate_key"` entry point. The design follows the general principle described in [“Overview of two-phase commit with stateful secure elements”](#overview-of-two-phase-commit-with-stateful-secure-elements) and the specific choices justified in [“Choice of a transaction design”](choice-of-a-transaction-design).
+
+### Transaction list file manipulation
+
+The transaction list is a simple array of key identifiers.
+
+To add a key identifier to the list:
+
+1. Load the current list from the transaction list if it exists and it is not already cached in memory.
+2. Append the key identifier to the array.
+3. Write the updated list file.
+
+To remove a key identifier from the list:
+
+1. Load the current list if it is not already cached in memory. It is an error if the file does not exist since it must contain this identifier.
+2. Remove the key identifier from the array. If it wasn't the last element in array, move array elements to fill the hole.
+3. If the list is now empty, remove the transaction list file. Otherwise write the updated list to the file.
+
+### Key creation process in the core
+
+Let _A_ be the application key identifier.
+
+1. Call the driver's `"allocate_key"` entry point, obtaining the driver key identifier _D_ chosen by the driver.
+2. Add _A_ [to the transaction list file](#transaction-list-file-manipulation).
+3. Create the key file _A_ in the internal storage. Note that this is done at a different time from what happens when creating a transparent key or a key in a stateless secure element: in those cases, creating the key file happens after the actual creation of the key material.
+4. Call the secure element's key creation entry point.
+5. Remove _A_ [from the transaction list file](#transaction-list-file-manipulation).
+
+If any step fails:
+
+* If the secure element's key creation entry point has been called and succeeded, call the secure element's destroy entry point.
+* If the key file has been created in the internal storage, remove it.
+* Remove the key from the transaction list.
+
+Note that this process is identical to key destruction, except that the key is already in the transaction list.
+
+### Key destruction process in the core
+
+Let _A_ be the application key identifier.
+
+We assume that the key is loaded in a key slot in memory: the core needs to know the key's location in order to determine whether the key is in a stateful secure element, and if so to know the driver key identifier. A possible optimization would be to load only that information in local variables, without occupying a key store; this has the advantage that key destruction works even if the key store is full.
+
+1. Add _A_ [to the transaction list file](#transaction-list-file-manipulation).
+2. Call the secure element's `"destroy_key"` entry point.
+3. Remove the key file _A_ from the internal storage.
+4. Remove _A_ [from the transaction list file](#transaction-list-file-manipulation).
+5. Free the corresponding key slot in memory.
+
+If any step fails, remember the error but continue the process, to destroy the resources associated with the key as much as is practical.
+
+### Transaction recovery
+
+For each key _A_ in the transaction list file, if the file _A_ exists in the internal storage:
+
+1. Load the key into a key slot in memory (to get its location and the driver key identifier, although we could get the location from the transaction list).
+2. Call the secure element's `"destroy_key"` entry point.
+3. Remove the key file _A_ from the internal storage.
+4. Remove _A_ [from the transaction list file](#transaction-list-file-manipulation).
+5. Free the corresponding key slot in memory.
+
+The transaction list file can be processed in any order.
+
+It is correct to update the transaction list after recovering each key, or to only delete the transaction list file once the recovery is over.
+
+### Concrete format of the transaction list file
+
+The transaction list file contains a [fixed header](#transaction-list-header-format) followed by a list of [fixed-size elements](#transaction-list-element-format).
+
+The file uid is `PSA_CRYPTO_ITS_TRANSACTION_LIST_UID` = 0xffffff53.
+
+#### Transaction list header format
+
+* Version (2 bytes): 0x0003. (Chosen to differ from the first two bytes of a [dynamic secure element transaction file](#dynamic-secure-element-transaction-file), to reduce the risk of a mix-up.)
+* Key name size (2 bytes): `sizeof(psa_storage_uid_t)`. Storing this size avoids reading bad data if Mbed TLS is upgraded to a different integration that names keys differently.
+
+#### Transaction list element format
+
+In practice, there will rarely be more than one active transaction at a time, so the size of an element is not critical for efficiency. Therefore, in addition to the key identifier which is required, we add some potentially useful information in case it becomes useful later. We do not put the driver key identifier because its size is not a constant.
+
+* Key id: `sizeof(psa_storage_uid_t)` bytes.
+* Key lifetime: 4 bytes (`sizeof(psa_key_lifetime_t)`). Currently unused during recovery.
+* Operation type: 1 byte. Currently unused during recovery.
+ * 0: destroy key.
+ * 1: import key.
+ * 2: generate key.
+ * 3: derive key.
+ * 4: import key.
+* Padding: 3 bytes. Reserved for future use. Currently unused during recovery.
+
+#### Dynamic secure element transaction file
+
+Note that the code base already references a “transaction file” (`PSA_CRYPTO_ITS_TRANSACTION_UID` = 0xffffff54), used by dynamic secure elements (feature enabled with `MBEDTLS_PSA_CRYPTO_SE_C`). This is a deprecated feature that has not been fully implemented: when this feature is enabled, the transaction file gets written during transactions, but if it exists when PSA crypto starts, `psa_crypto_init()` fails because [recovery has never been implemented](https://github.com/ARMmbed/mbed-crypto/issues/218).
+
+For the new kind of secure element driver, we pick a different file name to avoid any mixup.
+
+## Testing key management in secure elements
+
+### Instrumentation for checking the storage invariant
+
+#### Test hook locations
+
+When `MBEDTLS_TEST_HOOKS` is enabled, each call to `psa_its_set()` or `psa_its_remove()` also calls a test hook, passing the file UID as an argument to the hook.
+
+When a stateful secure element driver is present in the build, we use this hook to verify that the storage respects the [storage invariant](#chosen-storage-invariant). In addition, if there is some information about key ongoing operation (set explicitly by the test function as a global variable in the test framework), the hook tests that the content of the storage is compatible with the ongoing operation.
+
+#### Test hook behavior
+
+The storage invariant check cannot check all keys in storage, and does not need to (for example, it would be pointless to check anything about transparent keys). It checks the following keys:
+
+* When invoked from the test hook on a key file: on that key.
+* When invoked from the test hook on the transaction file: on all the keys listed in the transaction file.
+* When invoked from a test secure element: on the specified key.
+
+#### Test hook extra data
+
+Some tests set global variables to indicate which persistent keys they manipulate. We instrument at least some of these tests to also indicate what operation is in progress on the key. See the GitHub issues or the source code for details.
+
+### Testing of transaction recovery
+
+When no secure element driver is present in the build, the presence of a transaction list file during initialization is an error.
+
+#### Recovery testing process
+
+When the stateful test secure element driver is present in the build, we run test cases on a representative selection of states of the internal storage and the test secure element. Each test case for transaction recovery has the following form:
+
+1. Create the initial state:
+ * Create a transaction list file with a certain content.
+ * Create key files that we want to have in the test.
+ * Call the secure element test driver to create keys without going throught the PSA API.
+2. Call `psa_crypto_init()`. Expect success if the initial state satisfies the [storage invariant](#chosen-storage-invariant) and failure otherwise.
+3. On success, check that the expected keys exist, and that keys that are expected to have been destroyed by recovery do not exist.
+4. Clean up the storage and the secure element test driver's state.
+
+#### States to test recovery on
+
+For a given key located in a secure element, the following combination of states are possible:
+
+* Key file: present, absent.
+* Key in secure element: present, absent.
+* Key in the transaction file: no, creation (import), destruction.
+
+We test all $2 \times 2 \times 3 = 12$ possibilities, each in its own test case. In each case, call the test function that checks the storage invariant and check that its result is as expected. Then, if the storage invariant is met, follow the [recovery testing process](#recovery-testing-process).
+
+In addition, have at least one positive test case for each creation method other than import, to ensure that we don't reject a valid value.
+
+Note: testing of a damaged filesystem (including a filesystem that doesn't meet the invariant) is out of scope of the present document.
diff --git a/docs/architecture/psa-thread-safety/key-slot-state-transitions.png b/docs/architecture/psa-thread-safety/key-slot-state-transitions.png
new file mode 100644
index 0000000..08e4cc0
--- /dev/null
+++ b/docs/architecture/psa-thread-safety/key-slot-state-transitions.png
Binary files differ
diff --git a/docs/architecture/psa-thread-safety/psa-thread-safety.md b/docs/architecture/psa-thread-safety/psa-thread-safety.md
new file mode 100644
index 0000000..edb94c5
--- /dev/null
+++ b/docs/architecture/psa-thread-safety/psa-thread-safety.md
@@ -0,0 +1,367 @@
+# Thread-safety of the PSA subsystem
+
+Currently, PSA Crypto API calls in Mbed TLS releases are not thread-safe.
+
+As of Mbed TLS 3.6, an MVP for making the [PSA Crypto key management API](https://arm-software.github.io/psa-api/crypto/1.1/api/keys/management.html) and [`psa_crypto_init`](https://arm-software.github.io/psa-api/crypto/1.1/api/library/library.html#c.psa_crypto_init) thread-safe has been implemented. Implementations which only ever call PSA functions from a single thread are not affected by this new feature.
+
+Summary of recent work:
+
+- Key Store:
+ - Slot states are described in the [Key slot states](#key-slot-states) section. They guarantee safe concurrent access to slot contents.
+ - Key slots are protected by a global mutex, as described in [Key store consistency and abstraction function](#key-store-consistency-and-abstraction-function).
+ - Key destruction strategy abiding by [Key destruction guarantees](#key-destruction-guarantees), with an implementation discussed in [Key destruction implementation](#key-destruction-implementation).
+- `global_data` variables in `psa_crypto.c` and `psa_crypto_slot_management.c` are now protected by mutexes, as described in the [Global data](#global-data) section.
+- The testing system has now been made thread-safe. Tests can now spin up multiple threads, see [Thread-safe testing](#thread-safe-testing) for details.
+- Some multithreaded testing of the key management API has been added, this is outlined in [Testing-and-analysis](#testing-and-analysis).
+- The solution uses the pre-existing `MBEDTLS_THREADING_C` threading abstraction.
+- The core makes no additional guarantees for drivers. See [Driver policy](#driver-policy) for details.
+
+The other functions in the PSA Crypto API are planned to be made thread-safe in future, but currently we are not testing this.
+
+## Overview of the document
+
+* The [Guarantees](#guarantees) section describes the properties that are followed when PSA functions are invoked by multiple threads.
+* The [Usage guide](#usage-guide) section gives guidance on initializing, using and freeing PSA when using multiple threads.
+* The [Current strategy](#current-strategy) section describes how thread-safety of key management and `global_data` is achieved.
+* The [Testing and analysis](#testing-and-analysis) section discusses the state of our testing, as well as how this testing will be extended in future.
+* The [Future work](#future-work) section outlines our long-term goals for thread-safety; it also analyses how we might go about achieving these goals.
+
+## Definitions
+
+*Concurrent calls*
+
+The PSA specification defines concurrent calls as: "In some environments, an application can make calls to the Crypto API in separate threads. In such an environment, concurrent calls are two or more calls to the API whose execution can overlap in time." (See PSA documentation [here](https://arm-software.github.io/psa-api/crypto/1.1/overview/conventions.html#concurrent-calls).)
+
+*Thread-safety*
+
+In general, a system is thread-safe if any valid set of concurrent calls is handled as if the effect and return code of every call is equivalent to some sequential ordering. We implement a weaker notion of thread-safety, we only guarantee thread-safety in the circumstances described in the [PSA Concurrent calling conventions](#psa-concurrent-calling-conventions) section.
+
+## Guarantees
+
+### Correctness out of the box
+
+Building with `MBEDTLS_PSA_CRYPTO_C` and `MBEDTLS_THREADING_C` gives code which is correct; there are no race-conditions, deadlocks or livelocks when concurrently calling any set of PSA key management functions once `psa_crypto_init` has been called (see the [Initialization](#initialization) section for details on how to correctly initialize the PSA subsystem when using multiple threads).
+
+We do not test or support calling other PSA API functions concurrently.
+
+There is no busy-waiting in our implementation, every API call completes in a finite number of steps regardless of the locking policy of the underlying mutexes.
+
+When only considering key management functions: Mbed TLS 3.6 abides by the minimum expectation for concurrent calls set by the PSA specification (see [PSA Concurrent calling conventions](#psa-concurrent-calling-conventions)).
+
+#### PSA Concurrent calling conventions
+
+These are the conventions which are planned to be added to the PSA 1.2 specification, Mbed TLS 3.6 abides by these when only considering [key management functions](https://arm-software.github.io/psa-api/crypto/1.1/api/keys/management.html):
+
+> The result of two or more concurrent calls must be consistent with the same set of calls being executed sequentially in some order, provided that the calls obey the following constraints:
+>
+> * There is no overlap between an output parameter of one call and an input or output parameter of another call. Overlap between input parameters is permitted.
+>
+> * A call to `psa_destroy_key()` must not overlap with a concurrent call to any of the following functions:
+> - Any call where the same key identifier is a parameter to the call.
+> - Any call in a multi-part operation, where the same key identifier was used as a parameter to a previous step in the multi-part operation.
+>
+> * Concurrent calls must not use the same operation object.
+>
+> If any of these constraints are violated, the behaviour is undefined.
+>
+> The consistency requirement does not apply to errors that arise from resource failures or limitations. For example, errors resulting from resource exhaustion can arise in concurrent execution that do not arise in sequential execution.
+>
+> As an example of this rule: suppose two calls are executed concurrently which both attempt to create a new key with the same key identifier that is not already in the key store. Then:
+> * If one call returns `PSA_ERROR_ALREADY_EXISTS`, then the other call must succeed.
+> * If one of the calls succeeds, then the other must fail: either with `PSA_ERROR_ALREADY_EXISTS` or some other error status.
+> * Both calls can fail with error codes that are not `PSA_ERROR_ALREADY_EXISTS`.
+>
+> If the application concurrently modifies an input parameter while a function call is in progress, the behaviour is undefined.
+
+### Backwards compatibility
+
+Code which was working prior to Mbed TLS 3.6 will still work. Implementations which only ever call PSA functions from a single thread, or which protect all PSA calls using a mutex, are not affected by this new feature. If an application previously worked with a 3.X version, it will still work on version 3.6.
+
+### Supported threading implementations
+
+Currently, the only threading library with support shipped in the code base is pthread (enabled by `MBEDTLS_THREADING_PTHREAD`). The only concurrency primitives we use are mutexes, see [Condition variables](#condition-variables) for discussion about implementing new primitives in future major releases.
+
+Users can add support to any platform which has mutexes using the Mbed TLS platform abstraction layer (see `include/mbedtls/threading.h` for details).
+
+We intend to ship support for other platforms including Windows in future releases.
+
+### Key destruction guarantees
+
+Much like all other API calls, `psa_destroy_key` does not block indefinitely, and when `psa_destroy_key` returns:
+
+1. The key identifier does not exist. This is a functional requirement for persistent keys: any thread can immediately create a new key with the same identifier.
+2. The resources from the key have been freed. This allows threads to create similar keys immediately after destruction, regardless of resources.
+
+When `psa_destroy_key` is called on a key that is in use, guarantee 2 may be violated. This is consistent with the PSA specification requirements, as destruction of a key in use is undefined.
+
+In future versions we aim to enforce stronger requirements for key destruction, see [Long term key destruction requirements](#long-term-key-destruction-requirements) for details.
+
+### Driver policy
+
+The core makes no additional guarantees for drivers. Driver entry points may be called concurrently from multiple threads. Threads can concurrently call entry points using the same key, there is also no protection from destroying a key which is in use.
+
+### Random number generators
+
+The PSA RNG can be accessed both from various PSA functions, and from application code via `mbedtls_psa_get_random`.
+
+When using the built-in RNG implementations, i.e. when `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` is disabled, querying the RNG is thread-safe (`mbedtls_psa_random_init` and `mbedtls_psa_random_seed` are only thread-safe when called while holding `mbedtls_threading_psa_rngdata_mutex`. `mbedtls_psa_random_free` is not thread-safe).
+
+When `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` is enabled, it is down to the external implementation to ensure thread-safety, should threading be enabled.
+
+## Usage guide
+
+### Initialization
+
+The PSA subsystem is initialized via a call to [`psa_crypto_init`](https://arm-software.github.io/psa-api/crypto/1.1/api/library/library.html#c.psa_crypto_init). This is a thread-safe function, and multiple calls to `psa_crypto_init` are explicitly allowed. It is valid to have multiple threads each calling `psa_crypto_init` followed by a call to any PSA key management function (if the init succeeds).
+
+### General usage
+
+Once initialized, threads can use any PSA function if there is no overlap between their calls. All threads share the same set of keys, as soon as one thread returns from creating/loading a key via a key management API call the key can be used by any thread. If multiple threads attempt to load the same persistent key, with the same key identifier, only one thread can succeed - the others will return `PSA_ERROR_ALREADY_EXISTS`.
+
+Applications may need careful handling of resource management errors. As explained in ([PSA Concurrent calling conventions](#psa-concurrent-calling-conventions)), operations in progress can have memory related side effects. It is possible for a lack of resources to cause errors which do not arise in sequential execution. For example, multiple threads attempting to load the same persistent key can lead to some threads returning `PSA_ERROR_INSUFFICIENT_MEMORY` if the key is not currently in the key store - while trying to load a persistent key into the key store a thread temporarily reserves a free key slot.
+
+If a mutex operation fails, which only happens if the mutex implementation fails, the error code `PSA_ERROR_SERVICE_FAILURE` will be returned. If this code is returned, execution of the PSA subsystem must be stopped. All functions which have internal mutex locks and unlocks (except for when the lock/unlock occurs in a function that has no return value) will return with this error code in this situation.
+
+### Freeing
+
+There is no thread-safe way to free all PSA resources. This is because any such operation would need to wait for all other threads to complete their tasks before wiping resources.
+
+`mbedtls_psa_crypto_free` must only be called by a single thread once all threads have completed their operations.
+
+## Current strategy
+
+This section describes how we have implemented thread-safety. There is discussion of: techniques, internal properties for enforcing thread-safe access, how the system stays consistent and our abstraction model.
+
+### Protected resources
+
+#### Global data
+
+We have added a mutex `mbedtls_threading_psa_globaldata_mutex` defined in `include/mbedtls/threading.h`, which is used to make `psa_crypto_init` thread-safe.
+
+There are two `psa_global_data_t` structs, each with a single instance `global_data`:
+
+* The struct in `library/psa_crypto.c` is protected by `mbedtls_threading_psa_globaldata_mutex`. The RNG fields within this struct are not protected by this mutex, and are not always thread-safe (see [Random number generators](#random-number-generators)).
+* The struct in `library/psa_crypto_slot_management.c` has two fields: `key_slots` is protected as described in [Key slots](#key-slots), `key_slots_initialized` is protected by the global data mutex.
+
+#### Mutex usage
+
+A deadlock would occur if a thread attempts to lock a mutex while already holding it. Functions which need to be called while holding the global mutex have documentation to say this.
+
+To avoid performance degradation, functions must hold mutexes for as short a time as possible. In particular, they must not start expensive operations (eg. doing cryptography) while holding the mutex.
+
+#### Key slots
+
+
+Keys are stored internally in a global array of key slots known as the "key store", defined in `library/psa_slot_management.c`.
+
+##### Key slot states
+
+Each key slot has a state variable and a `registered_readers` counter. These two variables dictate whether an operation can access a slot, and in what way the slot can be used.
+
+There are four possible states for a key slot:
+
+* `PSA_SLOT_EMPTY`: no thread is currently accessing the slot, and no information is stored in the slot. Any thread is able to change the slot's state to `PSA_SLOT_FILLING` and begin to load data into the slot.
+* `PSA_SLOT_FILLING`: one thread is currently loading or creating material to fill the slot, this thread is responsible for the next state transition. Other threads cannot read the contents of a slot which is in this state.
+* `PSA_SLOT_FULL`: the slot contains a key, and any thread is able to use the key after registering as a reader, increasing `registered_readers` by 1.
+* `PSA_SLOT_PENDING_DELETION`: the key within the slot has been destroyed or marked for destruction, but at least one thread is still registered as a reader (`registered_readers > 0`). No thread can register to read this slot. The slot must not be wiped until the last reader unregisters. It is during the last unregister that the contents of the slot are wiped, and the slot's state is set to `PSA_SLOT_EMPTY`.
+
+###### Key slot state transition diagram
+
+
+In the state transition diagram above, an arrow between two states `q1` and `q2` with label `f` indicates that if the state of a slot is `q1` immediately before `f`'s linearization point, it may be `q2` immediately after `f`'s linearization point. Internal functions have italicized labels. The `PSA_SLOT_PENDING_DELETION -> PSA_SLOT_EMPTY` transition can be done by any function which calls `psa_unregister_read`.
+
+The state transition diagram can be generated in https://app.diagrams.net/ via this [url](https://viewer.diagrams.net/?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1#R3Vxbd5s4EP4t%2B%2BDH5CBxf6zrJJvW7aYn7W7dFx9qZFstBg7gW379CnMxkoUtY%2BGQ%2BiVISCPQjD59mhnSU98vNg%2BRE84%2FBS7yelBxNz110IMQAEsnf9KabVZjmHnFLMJu3mhf8YxfUF6p5LVL7KKYapgEgZfgkK6cBL6PJglV50RRsKabTQOPHjV0Zuig4nnieIe1%2F2E3mWe1FjT39X8jPJsXIwPDzu4snKJx%2Fibx3HGDdaVKveup76MgSLKrxeY98tLJK%2BYl63dfc7d8sAj5iUiHH%2BBlOP338cP6i%2B37%2Ff7oV%2Fjr442aSVk53jJ%2F4R40PCKv7%2BIVuZyll%2FffhsOimsiv3OE0njvxOEKOi6K4uPszYtuzUnbzk2yLSScPTvRLCv31HCfoOXQm6Z01MbF0hGThkRIgl04cZkqf4g1yS1HVScnnaYWiBG0qVfkkPaBggZJoS5rkdzUrV1hhsUpeXlf0n1fNK6ov6pzc4mal5L1SyEWulzN0BABHSeyM%2Be671NpJaeI5cYwn9ERFwdJ30xkaKKREJifafs9v7QqjamGwqbYbbIvSBidlJ3I9qtTvu6SFoketNuJgGU3QabtMnGiGkiPttKwdcqlVfKjbiu50ju6Kugh5ToJX9NrnKTQf4SnA5M1qTUc3GJvI3jvvVV2rrCDTvrUrP4sSq6mM2GyaDsTurK2chAsMENaiBC7WcBg746UfoRmOExTtEKCy2HH9UieaGzo%2Fya5BL2wPz%2FzUmInloIhUpOsXE1h%2Bl99YYNdNZfQjFOMX5%2BdOXmpzYToLu3nR%2Bz19wLXC48uMRYpyc8lHofCbhyDKLVRMm1LZDbzMwAoxgOkSTKcxakfpIjvD3aenr6O3CfOdQ3lbOsrneK1U8BocxetyXygLo2qhZl9ojvJQEOVBt1CetpwDNBYG%2BRObRcuoXvDSU6g%2BdbA3%2Fo224wkB9QQH%2FlvD9WJhdRHXc8mQEsr2bw%2FkDzf2%2B8fh8PHzQ6exWjVeGas1kb3xrFPTX3%2FcsenVlaSLKOnp7vNgZ%2B6CehrcDe%2B%2BPv7z%2BW3qqHOkx2yL84ifUZudhZtznsKJdYrzwE5xHqiQzc%2FSoAnI2VTTDXoX1DXj1gS6CS1TJwWVES9KiIDBMCvtuozIEkEMLkciZAVFKzSeRgjtuFLsBQmfJwkCDXeYmExAwuViXBw6OWpnOVuBC12kbKUY7VosDfD4hnyYvNWbHA6zXq96POyWEzCFSkUpoNIgqEaDGkhdewVWqpZiNgNLTWHAkti6yphk237B5oA5xT6O5wLHyjcGXOVSvRi5bogVabZJQ5cqx0ItrtQrABmPkzO6nCzJRuqWFOx6YQ1xN1lzRBMNa6idQjStiNmWMdyGHi%2FdYASxB4sawCI24GwrzfLlWf%2FANo2NpqIcfy7ItAcn2mvWMfnkInvipotn0NcmAD9MQu8FLR%2Fxs%2F7uaSN2nq1hpyejMpew0pqwTzNKKjYkMZKx47tjL5j8Lvn2%2BPtFA6VyJ14Q7wj8Wb3CJbHaaq%2BDwf8wel7iuIxdDqgWvZou5Oe5ZJr0Q%2F1ae5zKS6mQQtarG5SgT6PCztuN5GiCG1u3IjnQhJSV6HrDjQ3UOdauxMRV3gmRi1UuipMo2F6OcXLwtLMQVy5jCS4IzTLoM2CxDC403xuaTdktQByXicj32nKJ%2Bym0Oh8X28e3bnltVYbX6k1D1arJOBsEibssi6t3NDR1w3YBeI4uLinUymYc9ZJwBxRujjY9CNzZuUqSjLAnlIarFj2hon4DvdPwY4Cm8MOkyhjtJUByra547orZHXCpzgKKtPSXFFCKrpKJDO3mbCP9ha%2FXK2VWn4aGJjDUHE50QTjp2Gmtxkt3NpxAhs0Y7WXe8c0O1tKZhr42eZ61NQ4PqdPbdV8dX%2FYywsvlF05yIRGorwSJPKrNaFJ6iKaxX6oryMTEGxoHSFTNvIWWpWtQszUbqpbKyqVCy1AIts6NnpC3qY4CbPohTEW9NaFS%2FtTjbwTso8IAOEeY3vzJ2gnKcLP23%2FKnMcdBQQJgKrpFc0hJFLKNbJwnvNwMp3BsWbMvqx%2F3Hye%2BH3I%2FjJHDGanEmkZf47XGGEWzFruViqMyOTI667YSxmX9hCNNHmPk2pwQYUxxBi%2FCIEsRPMtPP0M%2BipykgYM%2FCM%2BPJaT00kURXu3yfsbBMgmX1DOfn1X9GlB5FB0kIKWuAe65%2BGLvHSX0almMsLMJDCeyCeScfv6wT%2FdEAyKimUz7YFkRebtSbpNNu7IPcs6F8zEZQaIh4L0gqUvww0j7vh7F%2FW9ujL7iR%2FfmYWy1QF0KOy2JxzmWSicnvP4nF93KumPJi9n4UMmQFxOKWea550bW3W9qcrPiuCZdz4yaJ4x1gVwcXb8SyAWwDTlsQmUijIxPogmYkeL%2B3%2BJkzff%2FXEi9%2Bx8%3D).
+##### Key slot access primitives
+
+The state of a key slot is updated via the internal function `psa_key_slot_state_transition`. To change the state of `slot` from `expected_state` to `new_state`, when `new_state` is not `PSA_SLOT_EMPTY`, one must call `psa_key_slot_state_transition(slot, expected_state, new_state)`; if the state was not `expected_state` then `PSA_ERROR_CORRUPTION_DETECTED` is returned. The sole reason for having an expected state parameter here is to help guarantee that our functions work as expected, this error code cannot occur without an internal coding error.
+
+Changing a slot's state to `PSA_SLOT_EMPTY` is done via `psa_wipe_key_slot`, this function wipes the entirety of the key slot.
+
+The reader count of a slot is incremented via `psa_register_read`, and decremented via `psa_unregister_read`. Library functions register to read a slot via the `psa_get_and_lock_key_slot_X` functions, read from the slot, then call `psa_unregister_read` to make known that they have finished reading the slot's contents.
+
+##### Key store consistency and abstraction function
+
+The key store is protected by a single global mutex `mbedtls_threading_key_slot_mutex`.
+
+We maintain the consistency of the key store by ensuring that all reads and writes to `slot->state` and `slot->registered_readers` are performed under `mbedtls_threading_key_slot_mutex`. All the access primitives described above must be called while the mutex is held; there is a convenience function `psa_unregister_read_under_mutex` which wraps a call to `psa_unregister_read` in a mutex lock/unlock pair.
+
+A thread can only traverse the key store while holding `mbedtls_threading_key_slot_mutex`, the set of keys within the key store which the thread holding the mutex can access is equivalent to the set:
+
+ {mbedtls_svc_key_id_t k : (\exists slot := &global_data.key_slots[i]) [
+ (slot->state == PSA_SLOT_FULL) &&
+ (slot->attr.id == k)]}
+
+The union of this set and the set of persistent keys not currently loaded into slots is our abstraction function for the key store, any key not in this union does not currently exist as far as the code is concerned (even if the key is in a slot which has a `PSA_SLOT_FILLING` or `PSA_SLOT_PENDING_DELETION` state). Attempting to start using any key which is not a member of the union will result in a `PSA_ERROR_INVALID_HANDLE` error code.
+
+##### Locking and unlocking the mutex
+
+If a lock or unlock operation fails and this is the first failure within a function, the function will return `PSA_ERROR_SERVICE_FAILURE`. If a lock or unlock operation fails after a different failure has been identified, the status code is not overwritten.
+
+We have defined a set of macros in `library/psa_crypto_core.h` to capture the common pattern of (un)locking the mutex and returning or jumping to an exit label upon failure.
+
+##### Key creation and loading
+
+To load a new key into a slot, the following internal utility functions are used:
+
+* `psa_reserve_free_key_slot` - This function, which must be called under `mbedtls_threading_key_slot_mutex`, iterates through the key store to find a slot whose state is `PSA_SLOT_EMPTY`. If found, it reserves the slot by setting its state to `PSA_SLOT_FILLING`. If not found, it will see if there are any persistent keys loaded which do not have any readers, if there are it will kick one such key out of the key store.
+* `psa_start_key_creation` - This function wraps around `psa_reserve_free_key_slot`, if a slot has been found then the slot id is set. This second step is not done under the mutex, at this point the calling thread has exclusive access to the slot.
+* `psa_finish_key_creation` - After the contents of the key have been loaded (again this loading is not done under the mutex), the thread calls `psa_finish_key_creation`. This function takes the mutex, checks that the key does not exist in the key store (this check cannot be done before this stage), sets the slot's state to `PSA_SLOT_FULL` and releases the mutex. Upon success, any thread is immediately able to use the new key.
+* `psa_fail_key_creation` - If there is a failure at any point in the key creation stage, this clean-up function takes the mutex, wipes the slot, and releases the mutex. Immediately after this unlock, any thread can start to use the slot for another key load.
+
+##### Re-loading persistent keys
+
+As described above, persistent keys can be kicked out of the key slot array provided they are not currently being used (`registered_readers == 0`). When attempting to use a persistent key that has been kicked out of a slot, the call to `psa_get_and_lock_key_slot` will see that the key is not in a slot, call `psa_reserve_free_key_slot` and load the key back into the reserved slot. This entire sequence is done during a single mutex lock, which is necessary for thread-safety (see documentation of `psa_get_and_lock_key_slot`).
+
+If `psa_reserve_free_key_slot` cannot find a suitable slot, the key cannot be loaded back in. This will lead to a `PSA_ERROR_INSUFFICIENT_MEMORY` error.
+
+##### Using existing keys
+
+One-shot operations follow a standard pattern when using an existing key:
+
+* They call one of the `psa_get_and_lock_key_slot_X` functions, which then finds the key and registers the thread as a reader.
+* They operate on the key slot, usually copying the key into a separate buffer to be used by the operation. This step is not performed under the key slot mutex.
+* Once finished, they call `psa_unregister_read_under_mutex`.
+
+Multi-part and restartable operations each have a "setup" function where the key is passed in, these functions follow the above pattern. The key is copied into the `operation` object, and the thread unregisters from reading the key (the operations do not access the key slots again). The copy of the key will not be destroyed during a call to `psa_destroy_key`, the thread running the operation is responsible for deleting its copy in the clean-up. This may need to change to enforce the long term key requirements ([Long term key destruction requirements](#long-term-key-destruction-requirements)).
+
+##### Key destruction implementation
+
+The locking strategy here is explained in `library/psa_crypto.c`. The destroying thread (the thread calling `psa_destroy_key`) does not always wipe the key slot. The destroying thread registers to read the key, sets the slot's state to `PSA_SLOT_PENDING_DELETION`, wipes the slot from memory if the key is persistent, and then unregisters from reading the slot.
+
+`psa_unregister_read` internally calls `psa_wipe_key_slot` if and only if the slot's state is `PSA_SLOT_PENDING_DELETION` and the slot's registered reader counter is equal to 1. This implements a "last one out closes the door" approach. The final thread to unregister from reading a destroyed key will automatically wipe the contents of the slot; no readers remain to reference the slot post deletion, so there cannot be corruption.
+
+### linearizability of the system
+
+To satisfy the requirements in [Correctness out of the box](#correctness-out-of-the-box), we require our functions to be "linearizable" (under certain constraints). This means that any (constraint satisfying) set of concurrent calls are performed as if they were executed in some sequential order.
+
+The standard way of reasoning that this is the case is to identify a "linearization point" for each call, this is a single execution step where the function takes effect (this is usually a step in which the effects of the call become visible to other threads). If every call has a linearization point, the set of calls is equivalent to sequentially performing the calls in order of when their linearization point occurred.
+
+We only require linearizability to hold in the case where a resource-management error is not returned. In a set of concurrent calls, it is permitted for a call c to fail with a `PSA_ERROR_INSUFFICIENT_MEMORY` return code even if there does not exist a sequential ordering of the calls in which c returns this error. Even if such an error occurs, all calls are still required to be functionally correct.
+
+To help justify that our system is linearizable, here are the linearization points/planned linearization points of each PSA call :
+
+* Key creation functions (including `psa_copy_key`) - The linearization point for a successful call is the mutex unlock within `psa_finish_key_creation`; it is at this point that the key becomes visible to other threads. The linearization point for a failed call is the closest mutex unlock after the failure is first identified.
+* `psa_destroy_key` - The linearization point for a successful destruction is the mutex unlock, the slot is now in the state `PSA_SLOT_PENDING_DELETION` meaning that the key has been destroyed. For failures, the linearization point is the same.
+* `psa_purge_key`, `psa_close_key` - The linearization point is the mutex unlock after wiping the slot for a success, or unregistering for a failure.
+* One shot operations - The linearization point is the final unlock of the mutex within `psa_get_and_lock_key_slot`, as that is the point in which it is decided whether or not the key exists.
+* Multi-part operations - The linearization point of the key input function is the final unlock of the mutex within `psa_get_and_lock_key_slot`. All other steps have no non resource-related side effects (except for key derivation, covered in the key creation functions).
+
+Please note that one shot operations and multi-part operations are not yet considered thread-safe, as we have not yet tested whether they rely on unprotected global resources. The key slot access in these operations is thread-safe.
+
+## Testing and analysis
+
+### Thread-safe testing
+
+It is now possible for individual tests to spin up multiple threads. This work has made the global variables used in tests thread-safe. If multiple threads fail a test assert, the first failure will be reported with correct line numbers.
+
+Although the `step` feature used in some tests is thread-safe, it may produce unexpected results for multi-threaded tests. `mbedtls_test_set_step` or `mbedtls_test_increment_step` calls within threads can happen in any order, thus may not produce the desired result when precise ordering is required.
+
+### Current state of testing
+
+Our testing is a work in progress. It is not feasible to run our traditional, single-threaded, tests in such a way that tests concurrency. We need to write new test suites for concurrency testing.
+
+Our tests currently only run on pthread, we hope to expand this in the future (our API already allows this).
+
+We run tests using [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html) to detect data races. We test the key store, and test that our key slot state system is enforced. We also test the thread-safety of `psa_crypto_init`.
+
+Currently, not every API call is tested, we also cannot feasibly test every combination of concurrent API calls. API calls can in general be split into a few categories, each category calling the same internal key management functions in the same order - it is the internal functions that are in charge of locking mutexes and interacting with the key store; we test the thread-safety of these functions.
+
+Since we do not run every cryptographic operation concurrently, we do not test that operations are free of unexpected global variables.
+
+### Expanding testing
+
+Through future work on testing, it would be good to:
+
+* For every API call, have a test which runs multiple copies of the call simultaneously.
+* After implementing other threading platforms, expand the tests to these platforms.
+* Have increased testing for kicking persistent keys out of slots.
+* Explicitly test that all global variables are protected, for this we would need to cover every operation in a concurrent scenario while running ThreadSanitizer.
+* Run tests on more threading implementations, once these implementations are supported.
+
+### Performance
+
+Key loading does somewhat run in parallel, deriving the key and copying it key into the slot is not done under any mutex.
+
+Key destruction is entirely sequential, this is required for persistent keys to stop issues with re-loading keys which cannot otherwise be avoided without changing our approach to thread-safety.
+
+
+## Future work
+
+### Long term requirements
+
+As explained previously, we eventually aim to make the entirety of the PSA API thread-safe. This will build on the work that we have already completed. This requires a full suite of testing, see [Expanding testing](#expanding-testing) for details.
+
+### Long term performance requirements
+
+Our plan for cryptographic operations is that they are not performed under any global mutex. One-shot operations and multi-part operations will each only hold the global mutex for finding the relevant key in the key slot, and unregistering as a reader after the operation, using their own operation-specific mutexes to guard any shared data that they use.
+
+We aim to eventually replace some/all of the mutexes with RWLocks, if possible.
+
+### Long term key destruction requirements
+
+The [PSA Crypto Key destruction specification](https://arm-software.github.io/psa-api/crypto/1.1/api/keys/management.html#key-destruction) mandates that implementations make a best effort to ensure that the key material cannot be recovered. In the long term, it would be good to guarantee that `psa_destroy_key` wipes all copies of the key material.
+
+Here are our long term key destruction goals:
+
+`psa_destroy_key` does not block indefinitely, and when `psa_destroy_key` returns:
+
+1. The key identifier does not exist. This is a functional requirement for persistent keys: any thread can immediately create a new key with the same identifier.
+2. The resources from the key have been freed. This allows threads to create similar keys immediately after destruction, regardless of resources.
+4. No copy of the key material exists. Rationale: this is a security requirement. We do not have this requirement yet, but we need to document this as a security weakness, and we would like to satisfy this security requirement in the future.
+
+#### Condition variables
+
+It would be ideal to add these to a future major version; we cannot add these as requirements to the default `MBEDTLS_THREADING_C` for backwards compatibility reasons.
+
+Condition variables would enable us to fulfil the final requirement in [Long term key destruction requirements](#long-term-key-destruction-requirements). Destruction would then work as follows:
+
+ * When a thread calls `psa_destroy_key`, they continue as normal until the `psa_unregister_read` call.
+ * Instead of calling `psa_unregister_read`, the thread waits until the condition `slot->registered_readers == 1` is true (the destroying thread is the final reader).
+ * At this point, the destroying thread directly calls `psa_wipe_key_slot`.
+
+A few changes are needed for this to follow our destruction requirements:
+
+ * Multi-part operations will need to remain registered as readers of their key slot until their copy of the key is destroyed, i.e. at the end of the finish/abort call.
+ * The functionality where `psa_unregister_read` can wipe the key slot will need to be removed, slot wiping is now only done by the destroying/wiping thread.
+
+### Protecting operation contexts
+
+Currently, we rely on the crypto service to ensure that the same operation is not invoked concurrently. This abides by the PSA Crypto API Specification ([PSA Concurrent calling conventions](#psa-concurrent-calling-conventions)).
+
+Concurrent access to the same operation object can compromise the crypto service. For example, if the operation context has a pointer (depending on the compiler and the platform, the pointer assignment may or may not be atomic). This violates the functional correctness requirement of the crypto service.
+
+If, in future, we want to protect against this within the library then operations will require a status field protected by a global mutex. On entry, API calls would check the state and return an error if the state is ACTIVE. If the state is INACTIVE, then the call will set the state to ACTIVE, do the operation section and then restore the state to INACTIVE before returning.
+
+### Future driver work
+
+A future policy we may wish to enforce for drivers is:
+
+* By default, each driver only has at most one entry point active at any given time. In other words, each driver has its own exclusive lock.
+* Drivers have an optional `"thread_safe"` boolean property. If true, it allows concurrent calls to this driver.
+* Even with a thread-safe driver, the core never starts the destruction of a key while there are operations in progress on it, and never performs concurrent calls on the same multipart operation.
+
+In the non-thread-safe case we have these natural assumptions/requirements:
+
+1. Drivers don't call the core for any operation for which they provide an entry point.
+2. The core doesn't hold the driver mutex between calls to entry points.
+
+With these, the only way of a deadlock is when there are several drivers with circular dependencies. That is, Driver A makes a call that is dispatched to Driver B; upon executing this call Driver B makes a call that is dispatched to Driver A. For example Driver A does CCM, which calls driver B to do CBC-MAC, which in turn calls Driver A to perform AES.
+
+Potential ways for resolving this:
+
+1. Non-thread-safe drivers must not call the core.
+2. Provide a new public API that drivers can safely call.
+3. Make the dispatch layer public for drivers to call.
+4. There is a whitelist of core APIs that drivers can call. Drivers providing entry points to these must not make a call to the core when handling these calls. (Drivers are still allowed to call any core API that can't have a driver entry point.)
+
+The first is too restrictive, the second and the third would require making it a stable API, and would likely increase the code size for a relatively rare feature. We are choosing the fourth as that is the most viable option.
+
+**Thread-safe drivers:**
+
+A driver would be non-thread-safe if the `thread-safe` property is set to true.
+
+To make re-entrancy in non-thread-safe drivers work, thread-safe drivers must not make a call to the core when handling a call that is on the non-thread-safe driver core API whitelist.
+
+Thread-safe drivers have fewer guarantees from the core and need to implement more complex logic. We can reasonably expect them to be more flexible in terms of re-entrancy as well. At this point it is hard to see what further guarantees would be useful and feasible. Therefore, we don't provide any further guarantees for now.
+
+Thread-safe drivers must not make any assumption about the operation of the core beyond what is discussed here.
diff --git a/docs/architecture/testing/driver-interface-test-strategy.md b/docs/architecture/testing/driver-interface-test-strategy.md
new file mode 100644
index 0000000..380fd39
--- /dev/null
+++ b/docs/architecture/testing/driver-interface-test-strategy.md
@@ -0,0 +1,133 @@
+# Mbed TLS driver interface test strategy
+
+This document describes the test strategy for the driver interfaces in Mbed TLS. Mbed TLS has interfaces for secure element drivers, accelerator drivers and entropy drivers. This document is about testing Mbed TLS itself; testing drivers is out of scope.
+
+The driver interfaces are standardized through PSA Cryptography functional specifications.
+
+## Secure element driver interface testing
+
+### Secure element driver interfaces
+
+#### Opaque driver interface
+
+The [unified driver interface](../../proposed/psa-driver-interface.md) supports both transparent drivers (for accelerators) and opaque drivers (for secure elements).
+
+Drivers exposing this interface need to be registered at compile time by declaring their JSON description file.
+
+#### Dynamic secure element driver interface
+
+The dynamic secure element driver interface (SE interface for short) is defined by [`psa/crypto_se_driver.h`](../../../include/psa/crypto_se_driver.h). This is an interface between Mbed TLS and one or more third-party drivers.
+
+The SE interface consists of one function provided by Mbed TLS (`psa_register_se_driver`) and many functions that drivers must implement. To make a driver usable by Mbed TLS, the initialization code must call `psa_register_se_driver` with a structure that describes the driver. The structure mostly contains function pointers, pointing to the driver's methods. All calls to a driver function are triggered by a call to a PSA crypto API function.
+
+### SE driver interface unit tests
+
+This section describes unit tests that must be implemented to validate the secure element driver interface. Note that a test case may cover multiple requirements; for example a “good case” test can validate that the proper function is called, that it receives the expected inputs and that it produces the expected outputs.
+
+Many SE driver interface unit tests could be covered by running the existing API tests with a key in a secure element.
+
+#### SE driver registration
+
+This applies to dynamic drivers only.
+
+* Test `psa_register_se_driver` with valid and with invalid arguments.
+* Make at least one failing call to `psa_register_se_driver` followed by a successful call.
+* Make at least one test that successfully registers the maximum number of drivers and fails to register one more.
+
+#### Dispatch to SE driver
+
+For each API function that can lead to a driver call (more precisely, for each driver method call site, but this is practically equivalent):
+
+* Make at least one test with a key in a secure element that checks that the driver method is called. A few API functions involve multiple driver methods; these should validate that all the expected driver methods are called.
+* Make at least one test with a key that is not in a secure element that checks that the driver method is not called.
+* Make at least one test with a key in a secure element with a driver that does not have the requisite method (i.e. the method pointer is `NULL`) but has the substructure containing that method, and check that the return value is `PSA_ERROR_NOT_SUPPORTED`.
+* Make at least one test with a key in a secure element with a driver that does not have the substructure containing that method (i.e. the pointer to the substructure is `NULL`), and check that the return value is `PSA_ERROR_NOT_SUPPORTED`.
+* At least one test should register multiple drivers with a key in each driver and check that the expected driver is called. This does not need to be done for all operations (use a white-box approach to determine if operations may use different code paths to choose the driver).
+* At least one test should register the same driver structure with multiple lifetime values and check that the driver receives the expected lifetime value.
+
+Some methods only make sense as a group (for example a driver that provides the MAC methods must provide all or none). In those cases, test with all of them null and none of them null.
+
+#### SE driver inputs
+
+For each API function that can lead to a driver call (more precisely, for each driver method call site, but this is practically equivalent):
+
+* Wherever the specification guarantees parameters that satisfy certain preconditions, check these preconditions whenever practical.
+* If the API function can take parameters that are invalid and must not reach the driver, call the API function with such parameters and verify that the driver method is not called.
+* Check that the expected inputs reach the driver. This may be implicit in a test that checks the outputs if the only realistic way to obtain the correct outputs is to start from the expected inputs (as is often the case for cryptographic material, but not for metadata).
+
+#### SE driver outputs
+
+For each API function that leads to a driver call, call it with parameters that cause a driver to be invoked and check how Mbed TLS handles the outputs.
+
+* Correct outputs.
+* Incorrect outputs such as an invalid output length.
+* Expected errors (e.g. `PSA_ERROR_INVALID_SIGNATURE` from a signature verification method).
+* Unexpected errors. At least test that if the driver returns `PSA_ERROR_GENERIC_ERROR`, this is propagated correctly.
+
+Key creation functions invoke multiple methods and need more complex error handling:
+
+* Check the consequence of errors detected at each stage (slot number allocation or validation, key creation method, storage accesses).
+* Check that the storage ends up in the expected state. At least make sure that no intermediate file remains after a failure.
+
+#### Persistence of SE keys
+
+The following tests must be performed at least one for each key creation method (import, generate, ...).
+
+* Test that keys in a secure element survive `psa_close_key(); psa_open_key()`.
+* Test that keys in a secure element survive `mbedtls_psa_crypto_free(); psa_crypto_init()`.
+* Test that the driver's persistent data survives `mbedtls_psa_crypto_free(); psa_crypto_init()`.
+* Test that `psa_destroy_key()` does not leave any trace of the key.
+
+#### Resilience for SE drivers
+
+Creating or removing a key in a secure element involves multiple storage modifications (M<sub>1</sub>, ..., M<sub>n</sub>). If the operation is interrupted by a reset at any point, it must be either rolled back or completed.
+
+* For each potential interruption point (before M<sub>1</sub>, between M<sub>1</sub> and M<sub>2</sub>, ..., after M<sub>n</sub>), call `mbedtls_psa_crypto_free(); psa_crypto_init()` at that point and check that this either rolls back or completes the operation that was started.
+* This must be done for each key creation method and for key destruction.
+* This must be done for each possible flow, including error cases (e.g. a key creation that fails midway due to `OUT_OF_MEMORY`).
+* The recovery during `psa_crypto_init` can itself be interrupted. Test those interruptions too.
+* Two things need to be tested: the key that is being created or destroyed, and the driver's persistent storage.
+* Check both that the storage has the expected content (this can be done by e.g. using a key that is supposed to be present) and does not have any unexpected content (for keys, this can be done by checking that `psa_open_key` fails with `PSA_ERROR_DOES_NOT_EXIST`).
+
+This requires instrumenting the storage implementation, either to force it to fail at each point or to record successive storage states and replay each of them. Each `psa_its_xxx` function call is assumed to be atomic.
+
+### SE driver system tests
+
+#### Real-world use case
+
+We must have at least one driver that is close to real-world conditions:
+
+* With its own source tree.
+* Running on actual hardware.
+* Run the full driver validation test suite (which does not yet exist).
+* Run at least one test application (e.g. the Mbed OS TLS example).
+
+This requirement shall be fulfilled by the [Microchip ATECC508A driver](https://github.com/ARMmbed/mbed-os-atecc608a/).
+
+#### Complete driver
+
+We should have at least one driver that covers the whole interface:
+
+* With its own source tree.
+* Implementing all the methods.
+* Run the full driver validation test suite (which does not yet exist).
+
+A PKCS#11 driver would be a good candidate. It would be useful as part of our product offering.
+
+## Transparent driver interface testing
+
+The [unified driver interface](../../proposed/psa-driver-interface.md) defines interfaces for accelerators.
+
+### Test requirements
+
+#### Requirements for transparent driver testing
+
+Every cryptographic mechanism for which a transparent driver interface exists (key creation, cryptographic operations, …) must be exercised in at least one build. The test must verify that the driver code is called.
+
+#### Requirements for fallback
+
+The driver interface includes a fallback mechanism so that a driver can reject a request at runtime and let another driver handle the request. For each entry point, there must be at least three test runs with two or more drivers available with driver A configured to fall back to driver B, with one run where A returns `PSA_SUCCESS`, one where A returns `PSA_ERROR_NOT_SUPPORTED` and B is invoked, and one where A returns a different error and B is not invoked.
+
+## Entropy and randomness interface testing
+
+TODO
diff --git a/docs/architecture/testing/invasive-testing.md b/docs/architecture/testing/invasive-testing.md
new file mode 100644
index 0000000..464f761
--- /dev/null
+++ b/docs/architecture/testing/invasive-testing.md
@@ -0,0 +1,367 @@
+# Mbed TLS invasive testing strategy
+
+## Introduction
+
+In Mbed TLS, we use black-box testing as much as possible: test the documented behavior of the product, in a realistic environment. However this is not always sufficient.
+
+The goal of this document is to identify areas where black-box testing is insufficient and to propose solutions.
+
+This is a test strategy document, not a test plan. A description of exactly what is tested is out of scope.
+
+This document is structured as follows:
+
+* [“Rules”](#rules) gives general rules and is written for brevity.
+* [“Requirements”](#requirements) explores the reasons why invasive testing is needed and how it should be done.
+* [“Possible approaches”](#possible-approaches) discusses some general methods for non-black-box testing.
+* [“Solutions”](#solutions) explains how we currently solve, or intend to solve, specific problems.
+
+### TLS
+
+This document currently focuses on data structure manipulation and storage, which is what the crypto/keystore and X.509 parts of the library are about. More work is needed to fully take TLS into account.
+
+## Rules
+
+Always follow these rules unless you have a good reason not to. If you deviate, document the rationale somewhere.
+
+See the section [“Possible approaches”](#possible-approaches) for a rationale.
+
+### Interface design for testing
+
+Do not add test-specific interfaces if there's a practical way of doing it another way. All public interfaces should be useful in at least some configurations. Features with a significant impact on the code size or attack surface should have a compile-time guard.
+
+### Reliance on internal details
+
+In unit tests and in test programs, it's ok to include internal header files from `library/`. Do not define non-public interfaces in public headers. In contrast, sample programs must not include header files from `library/`.
+
+Sometimes it makes sense to have unit tests on functions that aren't part of the public API. Declare such functions in `library/*.h` and include the corresponding header in the test code. If the function should be `static` for optimization but can't be `static` for testing, declare it as `MBEDTLS_STATIC_TESTABLE`, and make the tests that use it depend on `MBEDTLS_TEST_HOOKS` (see [“rules for compile-time options”](#rules-for-compile-time-options)).
+
+If test code or test data depends on internal details of the library and not just on its documented behavior, add a comment in the code that explains the dependency. For example:
+
+> ```
+> /* This test file is specific to the ITS implementation in PSA Crypto
+> * on top of stdio. It expects to know what the stdio name of a file is
+> * based on its keystore name.
+> */
+> ```
+
+> ```
+> # This test assumes that PSA_MAX_KEY_BITS (currently 65536-8 bits = 8191 bytes
+> # and not expected to be raised any time soon) is less than the maximum
+> # output from HKDF-SHA512 (255*64 = 16320 bytes).
+> ```
+
+### Rules for compile-time options
+
+If the most practical way to test something is to add code to the product that is only useful for testing, do so, but obey the following rules. For more information, see the [rationale](#guidelines-for-compile-time-options).
+
+* **Only use test-specific code when necessary.** Anything that can be tested through the documented API must be tested through the documented API.
+* **Test-specific code must be guarded by `#if defined(MBEDTLS_TEST_HOOKS)`**. Do not create fine-grained guards for test-specific code.
+* **Do not use `MBEDTLS_TEST_HOOKS` for security checks or assertions.** Security checks belong in the product.
+* **Merely defining `MBEDTLS_TEST_HOOKS` must not change the behavior**. It may define extra functions. It may add fields to structures, but if so, make it very clear that these fields have no impact on non-test-specific fields.
+* **Where tests must be able to change the behavior, do it by function substitution.** See [“rules for function substitution”](#rules-for-function-substitution) for more details.
+
+#### Rules for function substitution
+
+This section explains how to replace a library function `mbedtls_foo()` by alternative code for test purposes. That is, library code calls `mbedtls_foo()`, and there is a mechanism to arrange for these calls to invoke different code.
+
+Often `mbedtls_foo` is a macro which is defined to be a system function (like `mbedtls_calloc` or `mbedtls_fopen`), which we replace to mock or wrap the system function. This is useful to simulate I/O failure, for example. Note that if the macro can be replaced at compile time to support alternative platforms, the test code should be compatible with this compile-time configuration so that it works on these alternative platforms as well.
+
+Sometimes the substitutable function is a `static inline` function that does nothing (not a macro, to avoid accidentally skipping side effects in its parameters), to provide a hook for test code; such functions should have a name that starts with the prefix `mbedtls_test_hook_`. In such cases, the function should generally not modify its parameters, so any pointer argument should be const. The function should return void.
+
+With `MBEDTLS_TEST_HOOKS` set, `mbedtls_foo` is a global variable of function pointer type. This global variable is initialized to the system function, or to a function that does nothing. The global variable is defined in a header in the `library` directory such as `psa_crypto_invasive.h`. This is similar to the platform function configuration mechanism with `MBEDTLS_PLATFORM_xxx_ALT`.
+
+In unit test code that needs to modify the internal behavior:
+
+* The test function (or the whole test file) must depend on `MBEDTLS_TEST_HOOKS`.
+* At the beginning of the test function, set the global function pointers to the desired value.
+* In the test function's cleanup code, restore the global function pointers to their default value.
+
+## Requirements
+
+### General goals
+
+We need to balance the following goals, which are sometimes contradictory.
+
+* Coverage: we need to test behaviors which are not easy to trigger by using the API or which cannot be triggered deterministically, for example I/O failures.
+* Correctness: we want to test the actual product, not a modified version, since conclusions drawn from a test of a modified product may not apply to the real product.
+* Effacement: the product should not include features that are solely present for test purposes, since these increase the attack surface and the code size.
+* Portability: tests should work on every platform. Skipping tests on certain platforms may hide errors that are only apparent on such platforms.
+* Maintainability: tests should only enforce the documented behavior of the product, to avoid extra work when the product's internal or implementation-specific behavior changes. We should also not give the impression that whatever the tests check is guaranteed behavior of the product which cannot change in future versions.
+
+Where those goals conflict, we should at least mitigate the goals that cannot be fulfilled, and document the architectural choices and their rationale.
+
+### Problem areas
+
+#### Allocation
+
+Resource allocation can fail, but rarely does so in a typical test environment. How does the product cope if some allocations fail?
+
+Resources include:
+
+* Memory.
+* Files in storage (PSA API only — in the Mbed TLS API, black-box unit tests are sufficient).
+* Key slots (PSA API only).
+* Key slots in a secure element (PSA SE HAL).
+* Communication handles (PSA crypto service only).
+
+#### Storage
+
+Storage can fail, either due to hardware errors or to active attacks on trusted storage. How does the code cope if some storage accesses fail?
+
+We also need to test resilience: if the system is reset during an operation, does it restart in a correct state?
+
+#### Cleanup
+
+When code should clean up resources, how do we know that they have truly been cleaned up?
+
+* Zeroization of confidential data after use.
+* Freeing memory.
+* Freeing key slots.
+* Freeing key slots in a secure element.
+* Deleting files in storage (PSA API only).
+
+#### Internal data
+
+Sometimes it is useful to peek or poke internal data.
+
+* Check consistency of internal data (e.g. output of key generation).
+* Check the format of files (which matters so that the product can still read old files after an upgrade).
+* Inject faults and test corruption checks inside the product.
+
+## Possible approaches
+
+Key to requirement tables:
+
+* ++ requirement is fully met
+* \+ requirement is mostly met
+* ~ requirement is partially met but there are limitations
+* ! requirement is somewhat problematic
+* !! requirement is very problematic
+
+### Fine-grained public interfaces
+
+We can include all the features we want to test in the public interface. Then the tests can be truly black-box. The limitation of this approach is that this requires adding a lot of interfaces that are not useful in production. These interfaces have costs: they increase the code size, the attack surface, and the testing burden (exponentially, because we need to test all these interfaces in combination).
+
+As a rule, we do not add public interfaces solely for testing purposes. We only add public interfaces if they are also useful in production, at least sometimes. For example, the main purpose of `mbedtls_psa_crypto_free` is to clean up all resources in tests, but this is also useful in production in some applications that only want to use PSA Crypto during part of their lifetime.
+
+Mbed TLS traditionally has very fine-grained public interfaces, with many platform functions that can be substituted (`MBEDTLS_PLATFORM_xxx` macros). PSA Crypto has more opacity and less platform substitution macros.
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ~ Many useful tests are not reasonably achievable |
+| Correctness | ++ Ideal |
+| Effacement | !! Requires adding many otherwise-useless interfaces |
+| Portability | ++ Ideal; the additional interfaces may be useful for portability beyond testing |
+| Maintainability | !! Combinatorial explosion on the testing burden |
+| | ! Public interfaces must remain for backward compatibility even if the test architecture changes |
+
+### Fine-grained undocumented interfaces
+
+We can include all the features we want to test in undocumented interfaces. Undocumented interfaces are described in public headers for the sake of the C compiler, but are described as “do not use” in comments (or not described at all) and are not included in Doxygen-rendered documentation. This mitigates some of the downsides of [fine-grained public interfaces](#fine-grained-public-interfaces), but not all. In particular, the extra interfaces do increase the code size, the attack surface and the test surface.
+
+Mbed TLS traditionally has a few internal interfaces, mostly intended for cross-module abstraction leakage rather than for testing. For the PSA API, we favor [internal interfaces](#internal-interfaces).
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ~ Many useful tests are not reasonably achievable |
+| Correctness | ++ Ideal |
+| Effacement | !! Requires adding many otherwise-useless interfaces |
+| Portability | ++ Ideal; the additional interfaces may be useful for portability beyond testing |
+| Maintainability | ! Combinatorial explosion on the testing burden |
+
+### Internal interfaces
+
+We can write tests that call internal functions that are not exposed in the public interfaces. This is nice when it works, because it lets us test the unchanged product without compromising the design of the public interface.
+
+A limitation is that these interfaces must exist in the first place. If they don't, this has mostly the same downside as public interfaces: the extra interfaces increase the code size and the attack surface for no direct benefit to the product.
+
+Another limitation is that internal interfaces need to be used correctly. We may accidentally rely on internal details in the tests that are not necessarily always true (for example that are platform-specific). We may accidentally use these internal interfaces in ways that don't correspond to the actual product.
+
+This approach is mostly portable since it only relies on C interfaces. A limitation is that the test-only interfaces must not be hidden at link time (but link-time hiding is not something we currently do). Another limitation is that this approach does not work for users who patch the library by replacing some modules; this is a secondary concern since we do not officially offer this as a feature.
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ~ Many useful tests require additional internal interfaces |
+| Correctness | + Does not require a product change |
+| | ~ The tests may call internal functions in a way that does not reflect actual usage inside the product |
+| Effacement | ++ Fine as long as the internal interfaces aren't added solely for test purposes |
+| Portability | + Fine as long as we control how the tests are linked |
+| | ~ Doesn't work if the users rewrite an internal module |
+| Maintainability | + Tests interfaces that are documented; dependencies in the tests are easily noticed when changing these interfaces |
+
+### Static analysis
+
+If we guarantee certain properties through static analysis, we don't need to test them. This puts some constraints on the properties:
+
+* We need to have confidence in the specification (but we can gain this confidence by evaluating the specification on test data).
+* This does not work for platform-dependent properties unless we have a formal model of the platform.
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ~ Good for platform-independent properties, if we can guarantee them statically |
+| Correctness | + Good as long as we have confidence in the specification |
+| Effacement | ++ Zero impact on the code |
+| Portability | ++ Zero runtime burden |
+| Maintainability | ~ Static analysis is hard, but it's also helpful |
+
+### Compile-time options
+
+If there's code that we want to have in the product for testing, but not in production, we can add a compile-time option to enable it. This is very powerful and usually easy to use, but comes with a major downside: we aren't testing the same code anymore.
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ++ Most things can be tested that way |
+| Correctness | ! Difficult to ensure that what we test is what we run |
+| Effacement | ++ No impact on the product when built normally or on the documentation, if done right |
+| | ! Risk of getting “no impact” wrong |
+| Portability | ++ It's just C code so it works everywhere |
+| | ~ Doesn't work if the users rewrite an internal module |
+| Maintainability | + Test interfaces impact the product source code, but at least they're clearly marked as such in the code |
+
+#### Guidelines for compile-time options
+
+* **Minimize the number of compile-time options.**<br>
+ Either we're testing or we're not. Fine-grained options for testing would require more test builds, especially if combinatorics enters the play.
+* **Merely enabling the compile-time option should not change the behavior.**<br>
+ When building in test mode, the code should have exactly the same behavior. Changing the behavior should require some action at runtime (calling a function or changing a variable).
+* **Minimize the impact on code**.<br>
+ We should not have test-specific conditional compilation littered through the code, as that makes the code hard to read.
+
+### Runtime instrumentation
+
+Some properties can be tested through runtime instrumentation: have the compiler or a similar tool inject something into the binary.
+
+* Sanitizers check for certain bad usage patterns (ASan, MSan, UBSan, Valgrind).
+* We can inject external libraries at link time. This can be a way to make system functions fail.
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ! Limited scope |
+| Correctness | + Instrumentation generally does not affect the program's functional behavior |
+| Effacement | ++ Zero impact on the code |
+| Portability | ~ Depends on the method |
+| Maintainability | ~ Depending on the instrumentation, this may require additional builds and scripts |
+| | + Many properties come for free, but some require effort (e.g. the test code itself must be leak-free to avoid false positives in a leak detector) |
+
+### Debugger-based testing
+
+If we want to do something in a test that the product isn't capable of doing, we can use a debugger to read or modify the memory, or hook into the code at arbitrary points.
+
+This is a very powerful approach, but it comes with limitations:
+
+* The debugger may introduce behavior changes (e.g. timing). If we modify data structures in memory, we may do so in a way that the code doesn't expect.
+* Due to compiler optimizations, the memory may not have the layout that we expect.
+* Writing reliable debugger scripts is hard. We need to have confidence that we're testing what we mean to test, even in the face of compiler optimizations. Languages such as gdb make it hard to automate even relatively simple things such as finding the place(s) in the binary corresponding to some place in the source code.
+* Debugger scripts are very much non-portable.
+
+| Requirement | Analysis |
+| ----------- | -------- |
+| Coverage | ++ The sky is the limit |
+| Correctness | ++ The code is unmodified, and tested as compiled (so we even detect compiler-induced bugs) |
+| | ! Compiler optimizations may hinder |
+| | ~ Modifying the execution may introduce divergence |
+| Effacement | ++ Zero impact on the code |
+| Portability | !! Not all environments have a debugger, and even if they do, we'd need completely different scripts for every debugger |
+| Maintainability | ! Writing reliable debugger scripts is hard |
+| | !! Very tight coupling with the details of the source code and even with the compiler |
+
+## Solutions
+
+This section lists some strategies that are currently used for invasive testing, or planned to be used. This list is not intended to be exhaustive.
+
+### Memory management
+
+#### Zeroization testing
+
+Goal: test that `mbedtls_platform_zeroize` does wipe the memory buffer.
+
+Solution ([debugger](#debugger-based-testing)): implemented in `tests/scripts/test_zeroize.gdb`.
+
+Rationale: this cannot be tested by adding C code, because the danger is that the compiler optimizes the zeroization away, and any C code that observes the zeroization would cause the compiler not to optimize it away.
+
+#### Memory cleanup
+
+Goal: test the absence of memory leaks.
+
+Solution ([instrumentation](#runtime-instrumentation)): run tests with ASan. (We also use Valgrind, but it's slower than ASan, so we favor ASan.)
+
+Since we run many test jobs with a memory leak detector, each test function or test program must clean up after itself. Use the cleanup code (after the `exit` label in test functions) to free any memory that the function may have allocated.
+
+#### Robustness against memory allocation failure
+
+Solution: TODO. We don't test this at all at this point.
+
+#### PSA key store memory cleanup
+
+Goal: test the absence of resource leaks in the PSA key store code, in particular that `psa_close_key` and `psa_destroy_key` work correctly.
+
+Solution ([internal interface](#internal-interfaces)): in most tests involving PSA functions, the cleanup code explicitly calls `PSA_DONE()` instead of `mbedtls_psa_crypto_free()`. `PSA_DONE` fails the test if the key store in memory is not empty.
+
+Note there must also be tests that call `mbedtls_psa_crypto_free` with keys still open, to verify that it does close all keys.
+
+`PSA_DONE` is a macro defined in `psa_crypto_helpers.h` which uses `mbedtls_psa_get_stats()` to get information about the keystore content before calling `mbedtls_psa_crypto_free()`. This feature is mostly but not exclusively useful for testing, and may be moved under `MBEDTLS_TEST_HOOKS`.
+
+### PSA storage
+
+#### PSA storage cleanup on success
+
+Goal: test that no stray files are left over in the key store after a test that succeeded.
+
+Solution: TODO. Currently the various test suites do it differently.
+
+#### PSA storage cleanup on failure
+
+Goal: ensure that no stray files are left over in the key store even if a test has failed (as that could cause other tests to fail).
+
+Solution: TODO. Currently the various test suites do it differently.
+
+#### PSA storage resilience
+
+Goal: test the resilience of PSA storage against power failures.
+
+Solution: TODO.
+
+See the [secure element driver interface test strategy](driver-interface-test-strategy.html) for more information.
+
+#### Corrupted storage
+
+Goal: test the robustness against corrupted storage.
+
+Solution ([internal interface](#internal-interfaces)): call `psa_its` functions to modify the storage.
+
+#### Storage read failure
+
+Goal: test the robustness against read errors.
+
+Solution: TODO
+
+#### Storage write failure
+
+Goal: test the robustness against write errors (`STORAGE_FAILURE` or `INSUFFICIENT_STORAGE`).
+
+Solution: TODO
+
+#### Storage format stability
+
+Goal: test that the storage format does not change between versions (or if it does, an upgrade path must be provided).
+
+Solution ([internal interface](#internal-interfaces)): call internal functions to inspect the content of the file.
+
+Note that the storage format is defined not only by the general layout, but also by the numerical values of encodings for key types and other metadata. For numerical values, there is a risk that we would accidentally modify a single value or a few values, so the tests should be exhaustive. This probably requires some compile-time analysis (perhaps the automation for `psa_constant_names` can be used here). TODO
+
+### Other fault injection
+
+#### PSA crypto init failure
+
+Goal: test the failure of `psa_crypto_init`.
+
+Solution ([compile-time option](#compile-time-options)): replace entropy initialization functions by functions that can fail. This is the only failure point for `psa_crypto_init` that is present in all builds.
+
+When we implement the PSA entropy driver interface, this should be reworked to use the entropy driver interface.
+
+#### PSA crypto data corruption
+
+The PSA crypto subsystem has a few checks to detect corrupted data in memory. We currently don't have a way to exercise those checks.
+
+Solution: TODO. To corrupt a multipart operation structure, we can do it by looking inside the structure content, but only when running without isolation. To corrupt the key store, we would need to add a function to the library or to use a debugger.
+
diff --git a/docs/architecture/testing/psa-storage-format-testing.md b/docs/architecture/testing/psa-storage-format-testing.md
new file mode 100644
index 0000000..a5c1fd1
--- /dev/null
+++ b/docs/architecture/testing/psa-storage-format-testing.md
@@ -0,0 +1,127 @@
+# Mbed TLS PSA keystore format stability testing strategy
+
+## Introduction
+
+The PSA crypto subsystem includes a persistent key store. It is possible to create a persistent key and read it back later. This must work even if Mbed TLS has been upgraded in the meantime (except for deliberate breaks in the backward compatibility of the storage).
+
+The goal of this document is to define a test strategy for the key store that not only validates that it's possible to load a key that was saved with the version of Mbed TLS under test, but also that it's possible to load a key that was saved with previous versions of Mbed TLS.
+
+Interoperability is not a goal: PSA crypto implementations are not intended to have compatible storage formats. Downgrading is not required to work.
+
+## General approach
+
+### Limitations of a direct approach
+
+The goal of storage format stability testing is: as a user of Mbed TLS, I want to store a key under version V and read it back under version W, with W ≥ V.
+
+Doing the testing this way would be difficult because we'd need to have version V of Mbed TLS available when testing version W.
+
+An alternative, semi-direct approach consists of generating test data under version V, and reading it back under version W. Done naively, this would require keeping a large amount of test data (full test coverage multiplied by the number of versions that we want to preserve backward compatibility with).
+
+### Save-and-compare approach
+
+Importing and saving a key is deterministic. Therefore we can ensure the stability of the storage format by creating test cases under a version V of Mbed TLS, where the test case parameters include both the parameters to pass to key creation and the expected state of the storage after the key is created. The test case creates a key as indicated by the parameters, then compares the actual state of the storage with the expected state.
+
+In addition, the test case also loads the key and checks that it has the expected data and metadata. Import-and-save testing and load-and-check testing can be split into separate test functions with the same payloads.
+
+If the test passes with version V, this means that the test data is consistent with what the implementation does. When the test later runs under version W ≥ V, it creates and reads back a storage state which is known to be identical to the state that V would have produced. Thus, this approach validates that W can read storage states created by V.
+
+Note that it is the combination of import-and-save passing on version V and load-and-check passing on version W with the same data that proves that version W can read back what version V wrote. From the perspective of a particular version of the library, the import-and-save tests guarantee forward compatibility while the load-and-check tests guarantee backward compatibility.
+
+Use a similar approach for files other than keys where possible and relevant.
+
+### Keeping up with storage format evolution
+
+Test cases should normally not be removed from the code base: if something has worked before, it should keep working in future versions, so we should keep testing it.
+
+This cannot be enforced solely by looking at a single version of Mbed TLS, since there would be no indication that more test cases used to exist. It can only be enforced through review of library changes. The review is be assisted by a tool that compares the old and the new version, which is implemented in `scripts/abi_check.py`. This tool fails the CI if load-and-check test case disappears (changed test cases are raised as false positives).
+
+If the way certain keys are stored changes, and we don't deliberately decide to stop supporting old keys (which should only be done by retiring a version of the storage format), then we should keep the corresponding test cases in load-only mode: create a file with the expected content, load it and check the data that it contains.
+
+## Storage architecture overview
+
+The PSA subsystem provides storage on top of the PSA trusted storage interface. The state of the storage is a mapping from file identifier (a 64-bit number) to file content (a byte array). These files include:
+
+* [Key files](#key-storage) (files containing one key's metadata and, except for some secure element keys, key material).
+* The [random generator injected seed or state file](#random-generator-state) (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`).
+* [Storage transaction file](#storage-transaction-resumption).
+* [Driver state files](#driver-state-files).
+
+For a more detailed description, refer to the [Mbed TLS storage specification](../mbed-crypto-storage-specification.md).
+
+In addition, Mbed TLS includes an implementation of the PSA trusted storage interface on top of C stdio. This document addresses the test strategy for [PSA ITS over file](#psa-its-over-file) in a separate section below.
+
+## Key storage testing
+
+This section describes the desired test cases for keys created with the current storage format version. When the storage format changes, if backward compatibility is desired, old test data should be kept as described under [“Keeping up with storage format evolution”](#keeping-up-with-storage-format-evolution).
+
+### Keystore layout
+
+Objective: test that the key file name corresponds to the key identifier.
+
+Method: Create a key with a given identifier (using `psa_import_key`) and verify that a file with the expected name is created, and no other. Repeat for different identifiers.
+
+### General key format
+
+Objective: test the format of the key file: which field goes where and how big it is.
+
+Method: Create a key with certain metadata with `psa_import_key`. Read the file content and validate that it has the expected layout, deduced from the storage specification. Repeat with different metadata. Ensure that there are test cases covering all fields.
+
+### Enumeration of test cases for keys
+
+Objective: ensure that the coverage is sufficient to have assurance that all keys are stored correctly. This requires a sufficient selection of key types, sizes, policies, etc.
+
+In particular, the tests must validate that each `PSA_xxx` constant that is stored in a key is covered by at least one test case:
+
+* Lifetimes: `PSA_KEY_LIFETIME_xxx`, `PSA_KEY_PERSISTENCE_xxx`, `PSA_KEY_LOCATION_xxx`.
+* Usage flags: `PSA_KEY_USAGE_xxx`.
+* Algorithms in policies: `PSA_ALG_xxx`.
+* Key types: `PSA_KEY_TYPE_xxx`, `PSA_ECC_FAMILY_xxx`, `PSA_DH_FAMILY_xxx`.
+
+In addition, the coverage of key material must ensure that any variation in key representation is detected. See [“Considerations on key material representations”](#Considerations-on-key-material-representations) for considerations regarding key types.
+
+Method: Each test case creates a key with `psa_import_key`, purges it from memory, then reads it back and exercises it.
+
+Generate test cases automatically based on an enumeration of available constants and some knowledge of what attributes (sizes, algorithms, …) and content to use for keys of a certain type.
+
+### Testing with alternative lifetime values
+
+Objective: have test coverage for lifetimes other than the default persistent lifetime (`PSA_KEY_LIFETIME_PERSISTENT`).
+
+Method:
+
+* For alternative locations: have tests conditional on the presence of a driver for that location.
+* For alternative persistence levels: have load-and-check tests for supported persistence levels. We may also want to have negative tests ensuring that keys with a not-supported persistence level are not accidentally created.
+
+### Considerations on key material representations
+
+The risks of incompatibilities in key representations depends on the key type and on the presence of drivers. Compatibility of and with drivers is currently out of scope of this document.
+
+Some types only have one plausible representation. Others admit alternative plausible representations (different encodings, or non-canonical representations).
+Here are some areas to watch for, with an identified risk of incompatibilities.
+
+* HMAC keys longer than the block size: pre-hashed or not?
+* DES keys: was parity enforced?
+* RSA keys: can invalid DER encodings (e.g. leading zeros, ignored sign bit) have been stored?
+* RSA private keys: can invalid CRT parameters have been stored?
+* Montgomery private keys: were they stored in masked form?
+
+## Random generator state
+
+TODO
+
+## Driver state files
+
+Not yet implemented.
+
+TODO
+
+## Storage transaction resumption
+
+Only relevant for secure element support. Not yet fully implemented.
+
+TODO
+
+## PSA ITS over file
+
+TODO
diff --git a/docs/architecture/testing/test-framework.md b/docs/architecture/testing/test-framework.md
new file mode 100644
index 0000000..80667df
--- /dev/null
+++ b/docs/architecture/testing/test-framework.md
@@ -0,0 +1,64 @@
+# Mbed TLS test framework
+
+This document is an overview of the Mbed TLS test framework and test tools.
+
+This document is incomplete. You can help by expanding it.
+
+## Unit tests
+
+See <https://mbed-tls.readthedocs.io/en/latest/kb/development/test_suites>
+
+### Unit test descriptions
+
+Each test case has a description which succinctly describes for a human audience what the test does. The first non-comment line of each paragraph in a `.data` file is the test description. The following rules and guidelines apply:
+
+* Test descriptions may not contain semicolons, line breaks and other control characters, or non-ASCII characters. <br>
+ Rationale: keep the tools that process test descriptions (`generate_test_code.py`, [outcome file](#outcome-file) tools) simple.
+* Test descriptions must be unique within a `.data` file. If you can't think of a better description, the convention is to append `#1`, `#2`, etc. <br>
+ Rationale: make it easy to relate a failure log to the test data. Avoid confusion between cases in the [outcome file](#outcome-file).
+* Test descriptions should be a maximum of **66 characters**. <br>
+ Rationale: 66 characters is what our various tools assume (leaving room for 14 more characters on an 80-column line). Longer descriptions may be truncated or may break a visual alignment. <br>
+ We have a lot of test cases with longer descriptions, but they should be avoided. At least please make sure that the first 66 characters describe the test uniquely.
+* Make the description descriptive. “foo: x=2, y=4” is more descriptive than “foo #2”. “foo: 0<x<y, both even” is even better if these inequalities and parities are why this particular test data was chosen.
+* Avoid changing the description of an existing test case without a good reason. This breaks the tracking of failures across CI runs, since this tracking is based on the descriptions.
+
+`tests/scripts/check_test_cases.py` enforces some rules and warns if some guidelines are violated.
+
+## TLS tests
+
+### SSL extension tests
+
+#### SSL test case descriptions
+
+Each test case in `ssl-opt.sh` has a description which succinctly describes for a human audience what the test does. The test description is the first parameter to `run_test`.
+
+The same rules and guidelines apply as for [unit test descriptions](#unit-test-descriptions). In addition, the description must be written on the same line as `run_test`, in double quotes, for the sake of `check_test_cases.py`.
+
+### SSL cipher suite tests
+
+Each test case in `compat.sh` has a description which succinctly describes for a human audience what the test does. The test description is `$TITLE` defined in `run_client`.
+
+The same rules and guidelines apply as for [unit test descriptions](#unit-test-descriptions). In addition, failure cause in `compat.sh` is not classified as `ssl-opt.sh`, so the information of failed log files are followed as prompt.
+
+## Running tests
+
+### Outcome file
+
+#### Generating an outcome file
+
+Unit tests, `ssl-opt.sh` and `compat.sh` record the outcome of each test case in a **test outcome file**. This feature is enabled if the environment variable `MBEDTLS_TEST_OUTCOME_FILE` is set. Set it to the path of the desired file.
+
+If you run `all.sh --outcome-file test-outcome.csv`, this collects the outcome of all the test cases in `test-outcome.csv`.
+
+#### Outcome file format
+
+The outcome file is in a CSV format using `;` (semicolon) as the delimiter and no quoting. This means that fields may not contain newlines or semicolons. There is no title line.
+
+The outcome file has 6 fields:
+
+* **Platform**: a description of the platform, e.g. `Linux-x86_64` or `Linux-x86_64-gcc7-msan`.
+* **Configuration**: a unique description of the configuration (`mbedtls_config.h`).
+* **Test suite**: `test_suite_xxx`, `ssl-opt` or `compat`.
+* **Test case**: the description of the test case.
+* **Result**: one of `PASS`, `SKIP` or `FAIL`.
+* **Cause**: more information explaining the result.
diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md
new file mode 100644
index 0000000..d6fc19e
--- /dev/null
+++ b/docs/architecture/tls13-support.md
@@ -0,0 +1,435 @@
+TLS 1.3 support
+===============
+
+Overview
+--------
+
+Mbed TLS provides an implementation of the TLS 1.3 protocol. The TLS 1.3 support
+may be enabled using the MBEDTLS_SSL_PROTO_TLS1_3 configuration option.
+
+Support description
+-------------------
+
+- Overview
+
+ - Mbed TLS implements both the client and the server side of the TLS 1.3
+ protocol.
+
+ - Mbed TLS supports ECDHE key establishment.
+
+ - Mbed TLS supports DHE key establishment.
+
+ - Mbed TLS supports pre-shared keys for key establishment, pre-shared keys
+ provisioned externally as well as provisioned via the ticket mechanism.
+
+ - Mbed TLS supports session resumption via the ticket mechanism.
+
+ - Mbed TLS supports sending and receiving early data (0-RTT data).
+
+- Supported cipher suites: depends on the library configuration. Potentially
+ all of them:
+ TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256,
+ TLS_AES_128_CCM_SHA256 and TLS_AES_128_CCM_8_SHA256.
+
+- Supported ClientHello extensions:
+
+ | Extension | Support |
+ | ---------------------------- | ------- |
+ | server_name | YES |
+ | max_fragment_length | no |
+ | status_request | no |
+ | supported_groups | YES |
+ | signature_algorithms | YES |
+ | use_srtp | no |
+ | heartbeat | no |
+ | alpn | YES |
+ | signed_certificate_timestamp | no |
+ | client_certificate_type | no |
+ | server_certificate_type | no |
+ | padding | no |
+ | key_share | YES |
+ | pre_shared_key | YES |
+ | psk_key_exchange_modes | YES |
+ | early_data | YES |
+ | cookie | no |
+ | supported_versions | YES |
+ | certificate_authorities | no |
+ | post_handshake_auth | no |
+ | signature_algorithms_cert | no |
+
+
+- Supported groups: depends on the library configuration.
+ Potentially all ECDHE groups:
+ secp256r1, x25519, secp384r1, x448 and secp521r1.
+
+ Potentially all DHE groups:
+ ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144 and ffdhe8192.
+
+- Supported signature algorithms (both for certificates and CertificateVerify):
+ depends on the library configuration.
+ Potentially:
+ ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha512,
+ rsa_pkcs1_sha256, rsa_pkcs1_sha384, rsa_pkcs1_sha512, rsa_pss_rsae_sha256,
+ rsa_pss_rsae_sha384 and rsa_pss_rsae_sha512.
+
+ Note that in absence of an application profile standard specifying otherwise
+ rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are
+ mandatory (see section 9.1 of the specification).
+
+- Supported versions:
+
+ - TLS 1.2 and TLS 1.3 with version negotiation on client and server side.
+
+ - TLS 1.2 and TLS 1.3 can be enabled in the build independently of each
+ other.
+
+- Compatibility with existing SSL/TLS build options:
+
+ The TLS 1.3 implementation is compatible with nearly all TLS 1.2
+ configuration options in the sense that when enabling TLS 1.3 in the library
+ there is rarely any need to modify the configuration from that used for
+ TLS 1.2. There are two exceptions though: the TLS 1.3 implementation requires
+ MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, so these options
+ must be enabled.
+
+ Most of the Mbed TLS SSL/TLS related options are not supported or not
+ applicable to the TLS 1.3 implementation:
+
+ | Mbed TLS configuration option | Support |
+ | ---------------------------------------- | ------- |
+ | MBEDTLS_SSL_ALL_ALERT_MESSAGES | yes |
+ | MBEDTLS_SSL_ASYNC_PRIVATE | no |
+ | MBEDTLS_SSL_CONTEXT_SERIALIZATION | no |
+ | MBEDTLS_SSL_DEBUG_ALL | no |
+ | MBEDTLS_SSL_ENCRYPT_THEN_MAC | n/a |
+ | MBEDTLS_SSL_EXTENDED_MASTER_SECRET | n/a |
+ | MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | no (1) |
+ | MBEDTLS_SSL_RENEGOTIATION | n/a |
+ | MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no |
+ | | |
+ | MBEDTLS_SSL_SESSION_TICKETS | yes |
+ | MBEDTLS_SSL_SERVER_NAME_INDICATION | yes |
+ | MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH | no |
+ | | |
+ | MBEDTLS_ECP_RESTARTABLE | no |
+ | MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED | no |
+ | | |
+ | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (2) |
+ | MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_RSA_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED | n/a |
+ | MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a |
+ | | |
+ | MBEDTLS_PSA_CRYPTO_C | no (1) |
+ | MBEDTLS_USE_PSA_CRYPTO | yes |
+
+ (1) These options must remain in their default state of enabled.
+ (2) See the TLS 1.3 specific build options section below.
+
+- TLS 1.3 specific build options:
+
+ - MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE enables the support for middlebox
+ compatibility mode as defined in section D.4 of RFC 8446.
+
+ - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED enables the support for
+ the PSK key exchange mode as defined by RFC 8446. If it is the only key
+ exchange mode enabled, the TLS 1.3 implementation does not contain any code
+ related to key exchange protocols, certificates and signatures.
+
+ - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED enables the
+ support for the ephemeral key exchange mode. If it is the only key exchange
+ mode enabled, the TLS 1.3 implementation does not contain any code related
+ to PSK based key exchange. The ephemeral key exchange mode requires at least
+ one of the key exchange protocol allowed by the TLS 1.3 specification, the
+ parsing and validation of x509 certificates and at least one signature
+ algorithm allowed by the TLS 1.3 specification for signature computing and
+ verification.
+
+ - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED enables the
+ support for the PSK ephemeral key exchange mode. If it is the only key
+ exchange mode enabled, the TLS 1.3 implementation does not contain any code
+ related to certificates and signatures. The PSK ephemeral key exchange
+ mode requires at least one of the key exchange protocol allowed by the
+ TLS 1.3 specification.
+
+
+Coding rules checklist for TLS 1.3
+----------------------------------
+
+The following coding rules are aimed to be a checklist for TLS 1.3 upstreaming
+work to reduce review rounds and the number of comments in each round. They
+come along (do NOT replace) the project coding rules
+(https://mbed-tls.readthedocs.io/en/latest/kb/development/mbedtls-coding-standards). They have been
+established and discussed following the review of #4882 that was the
+PR upstreaming the first part of TLS 1.3 ClientHello writing code.
+
+TLS 1.3 specific coding rules:
+
+ - TLS 1.3 specific C modules, headers, static functions names are prefixed
+ with `ssl_tls13_`. The same applies to structures and types that are
+ internal to C modules.
+
+ - TLS 1.3 specific exported functions, structures and types are
+ prefixed with `mbedtls_ssl_tls13_`.
+
+ - Use TLS1_3 in TLS 1.3 specific macros.
+
+ - The names of macros and variables related to a field or structure in the
+ TLS 1.3 specification should contain as far as possible the field name as
+ it is in the specification. If the field name is "too long" and we prefer
+ to introduce some kind of abbreviation of it, use the same abbreviation
+ everywhere in the code.
+
+ Example 1: #define CLIENT_HELLO_RANDOM_LEN 32, macro for the length of the
+ `random` field of the ClientHello message.
+
+ Example 2 (consistent abbreviation): `mbedtls_ssl_tls13_write_sig_alg_ext()`
+ and `MBEDTLS_TLS_EXT_SIG_ALG`, `sig_alg` standing for
+ `signature_algorithms`.
+
+ - Regarding vectors that are represented by a length followed by their value
+ in the data exchanged between servers and clients:
+
+ - Use `<vector name>_len` for the name of a variable used to compute the
+ length in bytes of the vector, where <vector name> is the name of the
+ vector as defined in the TLS 1.3 specification.
+
+ - Use `p_<vector_name>_len` for the name of a variable intended to hold
+ the address of the first byte of the vector length.
+
+ - Use `<vector_name>` for the name of a variable intended to hold the
+ address of the first byte of the vector value.
+
+ - Use `<vector_name>_end` for the name of a variable intended to hold
+ the address of the first byte past the vector value.
+
+ Those idioms should lower the risk of mis-using one of the address in place
+ of another one which could potentially lead to some nasty issues.
+
+ Example: `cipher_suites` vector of ClientHello in
+ `ssl_tls13_write_client_hello_cipher_suites()`
+ ```
+ size_t cipher_suites_len;
+ unsigned char *p_cipher_suites_len;
+ unsigned char *cipher_suites;
+ ```
+
+ - Where applicable, use:
+ - the macros to extract a byte from a multi-byte integer MBEDTLS_BYTE_{0-8}.
+ - the macros to write in memory in big-endian order a multi-byte integer
+ MBEDTLS_PUT_UINT{8|16|32|64}_BE.
+ - the macros to read from memory a multi-byte integer in big-endian order
+ MBEDTLS_GET_UINT{8|16|32|64}_BE.
+ - the macro to check for space when writing into an output buffer
+ `MBEDTLS_SSL_CHK_BUF_PTR`.
+ - the macro to check for data when reading from an input buffer
+ `MBEDTLS_SSL_CHK_BUF_READ_PTR`.
+
+ The three first types, MBEDTLS_BYTE_{0-8}, MBEDTLS_PUT_UINT{8|16|32|64}_BE
+ and MBEDTLS_GET_UINT{8|16|32|64}_BE improve the readability of the code and
+ reduce the risk of writing or reading bytes in the wrong order.
+
+ The two last types, `MBEDTLS_SSL_CHK_BUF_PTR` and
+ `MBEDTLS_SSL_CHK_BUF_READ_PTR`, improve the readability of the code and
+ reduce the risk of error in the non-completely-trivial arithmetic to
+ check that we do not write or read past the end of a data buffer. The
+ usage of those macros combined with the following rule mitigate the risk
+ to read/write past the end of a data buffer.
+
+ Examples:
+ ```
+ hs_hdr[1] = MBEDTLS_BYTE_2( total_hs_len );
+ MBEDTLS_PUT_UINT16_BE( MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS, p, 0 );
+ MBEDTLS_SSL_CHK_BUF_PTR( p, end, 7 );
+ ```
+
+ - To mitigate what happened here
+ (https://github.com/Mbed-TLS/mbedtls/pull/4882#discussion_r701704527) from
+ happening again, use always a local variable named `p` for the reading
+ pointer in functions parsing TLS 1.3 data, and for the writing pointer in
+ functions writing data into an output buffer and only that variable. The
+ name `p` has been chosen as it was already widely used in TLS code.
+
+ - When an TLS 1.3 structure is written or read by a function or as part of
+ a function, provide as documentation the definition of the structure as
+ it is in the TLS 1.3 specification.
+
+General coding rules:
+
+ - We prefer grouping "related statement lines" by not adding blank lines
+ between them.
+
+ Example 1:
+ ```
+ ret = ssl_tls13_write_client_hello_cipher_suites( ssl, buf, end, &output_len );
+ if( ret != 0 )
+ return( ret );
+ buf += output_len;
+ ```
+
+ Example 2:
+ ```
+ MBEDTLS_SSL_CHK_BUF_PTR( cipher_suites_iter, end, 2 );
+ MBEDTLS_PUT_UINT16_BE( cipher_suite, cipher_suites_iter, 0 );
+ cipher_suites_iter += 2;
+ ```
+
+ - Use macros for constants that are used in different functions, different
+ places in the code. When a constant is used only locally in a function
+ (like the length in bytes of the vector lengths in functions reading and
+ writing TLS handshake message) there is no need to define a macro for it.
+
+ Example: `#define CLIENT_HELLO_RANDOM_LEN 32`
+
+ - When declaring a pointer the dereferencing operator should be prepended to
+ the pointer name not appended to the pointer type:
+
+ Example: `mbedtls_ssl_context *ssl;`
+
+ - Maximum line length is 80 characters.
+
+ Exceptions:
+
+ - string literals can extend beyond 80 characters as we do not want to
+ split them to ease their search in the code base.
+
+ - A line can be more than 80 characters by a few characters if just looking
+ at the 80 first characters is enough to fully understand the line. For
+ example it is generally fine if some closure characters like ";" or ")"
+ are beyond the 80 characters limit.
+
+ If a line becomes too long due to a refactoring (for example renaming a
+ function to a longer name, or indenting a block more), avoid rewrapping
+ lines in the same commit: it makes the review harder. Make one commit with
+ the longer lines and another commit with just the rewrapping.
+
+ - When in successive lines, functions and macros parameters should be aligned
+ vertically.
+
+ Example:
+ ```
+ int mbedtls_ssl_start_handshake_msg( mbedtls_ssl_context *ssl,
+ unsigned hs_type,
+ unsigned char **buf,
+ size_t *buf_len );
+ ```
+
+ - When a function's parameters span several lines, group related parameters
+ together if possible.
+
+ For example, prefer:
+
+ ```
+ mbedtls_ssl_start_handshake_msg( ssl, hs_type,
+ buf, buf_len );
+ ```
+ over
+ ```
+ mbedtls_ssl_start_handshake_msg( ssl, hs_type, buf,
+ buf_len );
+ ```
+ even if it fits.
+
+
+Overview of handshake code organization
+---------------------------------------
+
+The TLS 1.3 handshake protocol is implemented as a state machine. The
+functions `mbedtls_ssl_tls13_handshake_{client,server}_step` are the top level
+functions of that implementation. They are implemented as a switch over all the
+possible states of the state machine.
+
+Most of the states are either dedicated to the processing or writing of an
+handshake message.
+
+The implementation does not go systematically through all states as this would
+result in too many checks of whether something needs to be done or not in a
+given state to be duplicated across several state handlers. For example, on
+client side, the states related to certificate parsing and validation are
+bypassed if the handshake is based on a pre-shared key and thus does not
+involve certificates.
+
+On the contrary, the implementation goes systematically though some states
+even if they could be bypassed if it helps in minimizing when and where inbound
+and outbound keys are updated. The `MBEDTLS_SSL_CLIENT_CERTIFICATE` state on
+client side is a example of that.
+
+The names of the handlers processing/writing an handshake message are
+prefixed with `(mbedtls_)ssl_tls13_{process,write}`. To ease the maintenance and
+reduce the risk of bugs, the code of the message processing and writing
+handlers is split into a sequence of stages.
+
+The sending of data to the peer only occurs in `mbedtls_ssl_handshake_step`
+between the calls to the handlers and as a consequence handlers do not have to
+care about the MBEDTLS_ERR_SSL_WANT_WRITE error code. Furthermore, all pending
+data are flushed before to call the next handler. That way, handlers do not
+have to worry about pending data when changing outbound keys.
+
+### Message processing handlers
+For message processing handlers, the stages are:
+
+* coordination stage: check if the state should be bypassed. This stage is
+optional. The check is either purely based on the reading of the value of some
+fields of the SSL context or based on the reading of the type of the next
+message. The latter occurs when it is not known what the next handshake message
+will be, an example of that on client side being if we are going to receive a
+CertificateRequest message or not. The intent is, apart from the next record
+reading to not modify the SSL context as this stage may be repeated if the
+next handshake message has not been received yet.
+
+* fetching stage: at this stage we are sure of the type of the handshake
+message we must receive next and we try to fetch it. If we did not go through
+a coordination stage involving the next record type reading, the next
+handshake message may not have been received yet, the handler returns with
+`MBEDTLS_ERR_SSL_WANT_READ` without changing the current state and it will be
+called again later.
+
+* pre-processing stage: prepare the SSL context for the message parsing. This
+stage is optional. Any processing that must be done before the parsing of the
+message or that can be done to simplify the parsing code. Some simple and
+partial parsing of the handshake message may append at that stage like in the
+ServerHello message pre-processing.
+
+* parsing stage: parse the message and restrict as much as possible any
+update of the SSL context. The idea of the pre-processing/parsing/post-processing
+organization is to concentrate solely on the parsing in the parsing function to
+reduce the size of its code and to simplify it.
+
+* post-processing stage: following the parsing, further update of the SSL
+context to prepare for the next incoming and outgoing messages. This stage is
+optional. For example, secret and key computations occur at this stage, as well
+as handshake messages checksum update.
+
+* state change: the state change is done in the main state handler to ease the
+navigation of the state machine transitions.
+
+
+### Message writing handlers
+For message writing handlers, the stages are:
+
+* coordination stage: check if the state should be bypassed. This stage is
+optional. The check is based on the value of some fields of the SSL context.
+
+* preparation stage: prepare for the message writing. This stage is optional.
+Any processing that must be done before the writing of the message or that can
+be done to simplify the writing code.
+
+* writing stage: write the message and restrict as much as possible any update
+of the SSL context. The idea of the preparation/writing/finalization
+organization is to concentrate solely on the writing in the writing function to
+reduce the size of its code and simplify it.
+
+* finalization stage: following the writing, further update of the SSL
+context to prepare for the next incoming and outgoing messages. This stage is
+optional. For example, handshake secret and key computation occur at that
+stage (ServerHello writing finalization), switching to handshake keys for
+outbound message on server side as well.
+
+* state change: the state change is done in the main state handler to ease
+the navigation of the state machine transitions.
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..41c50c7
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,34 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import glob
+
+project = 'Mbed TLS Versioned'
+copyright = '2023, Mbed TLS Contributors'
+author = 'Mbed TLS Contributors'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['breathe', 'sphinx.ext.graphviz']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+breathe_projects = {
+ 'mbedtls-versioned': '../apidoc/xml'
+}
+breathe_default_project = 'mbedtls-versioned'
+
+primary_domain = 'c'
+highlight_language = 'c'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md
new file mode 100644
index 0000000..4095d8e
--- /dev/null
+++ b/docs/driver-only-builds.md
@@ -0,0 +1,460 @@
+This document explains how to create builds of Mbed TLS where some
+cryptographic mechanisms are provided only by PSA drivers (that is, no
+built-in implementation of those algorithms), from a user's perspective.
+
+This is useful to save code size for people who are using either a hardware
+accelerator, or an alternative software implementation that is more
+aggressively optimized for code size than the default one in Mbed TLS.
+
+General considerations
+----------------------
+
+This document assumes that you already have a working driver.
+Otherwise, please see the [PSA driver example and
+guide](psa-driver-example-and-guide.md) for information on writing a
+driver.
+
+In order to have some mechanism provided only by a driver, you'll want
+the following compile-time configuration options enabled:
+
+- `MBEDTLS_PSA_CRYPTO_C` (enabled by default) - this enables PSA Crypto.
+- `MBEDTLS_USE_PSA_CRYPTO` (disabled by default) - this makes PK, X.509 and
+ TLS use PSA Crypto. You need to enable this if you're using PK, X.509 or TLS
+and want them to have access to the algorithms provided by your driver. (See
+[the dedicated document](use-psa-crypto.md) for details.)
+- `MBEDTLS_PSA_CRYPTO_CONFIG` (disabled by default) - this enables
+ configuration of cryptographic algorithms using `PSA_WANT` macros in
+`include/psa/crypto_config.h`. See [Conditional inclusion of cryptographic
+mechanism through the PSA API in Mbed
+TLS](proposed/psa-conditional-inclusion-c.md) for details.
+
+In addition, for each mechanism you want provided only by your driver:
+
+- Define the corresponding `PSA_WANT` macro in `psa/crypto_config.h` - this
+ means the algorithm will be available in the PSA Crypto API.
+- Define the corresponding `MBEDTLS_PSA_ACCEL` in your build. This could be
+ defined in `psa/crypto_config.h` or your compiler's command line. This
+informs the PSA code that an accelerator is available for this mechanism.
+- Undefine / comment out the corresponding `MBEDTLS_xxx_C` macro in
+ `mbedtls/mbedtls_config.h`. This ensures the built-in implementation is not
+included in the build.
+
+For example, if you want SHA-256 to be provided only by a driver, you'll want
+`PSA_WANT_ALG_SHA_256` and `MBEDTLS_PSA_ACCEL_SHA_256` defined, and
+`MBEDTLS_SHA256_C` undefined.
+
+In addition to these compile-time considerations, at runtime you'll need to
+make sure you call `psa_crypto_init()` before any function that uses the
+driver-only mechanisms. Note that this is already a requirement for any use of
+the PSA Crypto API, as well as for use of the PK, X.509 and TLS modules when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled, so in most cases your application will
+already be doing this.
+
+Mechanisms covered
+------------------
+
+For now, only the following (families of) mechanisms are supported:
+
+- hashes: SHA-3, SHA-2, SHA-1, MD5, etc.
+- elliptic-curve cryptography (ECC): ECDH, ECDSA, EC J-PAKE, ECC key types.
+- finite-field Diffie-Hellman: FFDH algorithm, DH key types.
+- RSA: PKCS#1 v1.5 and v2.1 signature and encryption algorithms, RSA key types
+ (for now, only crypto, no X.509 or TLS support).
+- AEADs:
+ - GCM and CCM with AES, ARIA and Camellia key types
+ - ChachaPoly with ChaCha20 Key type
+- Unauthenticated ciphers:
+ - key types: AES, ARIA, Camellia, DES
+ - modes: ECB, CBC, CTR, CFB, OFB, XTS
+
+For each family listed above, all the mentioned alorithms/key types are also
+all the mechanisms that exist in PSA API.
+
+Supported means that when those are provided only by drivers, everything
+(including PK, X.509 and TLS if `MBEDTLS_USE_PSA_CRYPTO` is enabled) should
+work in the same way as if the mechanisms where built-in, except as documented
+in the "Limitations" sub-sections of the sections dedicated to each family
+below.
+
+Hashes
+------
+
+It is possible to have all hash operations provided only by a driver.
+
+More precisely:
+
+- you can enable `PSA_WANT_ALG_SHA_256` without `MBEDTLS_SHA256_C`, provided
+ you have `MBEDTLS_PSA_ACCEL_ALG_SHA_256` enabled;
+- and similarly for all supported hash algorithms: `MD5`, `RIPEMD160`,
+ `SHA_1`, `SHA_224`, `SHA_256`, `SHA_384`, `SHA_512`, `SHA3_224`, `SHA3_256`,
+`SHA3_384`, `SHA3_512`.
+
+In such a build, all crypto operations (via the PSA Crypto API, or non-PSA
+APIs), as well as X.509 and TLS, will work as usual, except that direct calls
+to low-level hash APIs (`mbedtls_sha256()` etc.) are not possible for the
+modules that are disabled.
+
+You need to call `psa_crypto_init()` before any crypto operation that uses
+a hash algorithm that is provided only by a driver, as mentioned in [General
+considerations](#general-considerations) above.
+
+If you want to check at compile-time whether a certain hash algorithm is
+available in the present build of Mbed TLS, regardless of whether it's
+provided by a driver or built-in, you should use the following macros:
+
+- for code that uses only the PSA Crypto API: `PSA_WANT_ALG_xxx` from
+ `psa/crypto.h`;
+- for code that uses non-PSA crypto APIs: `MBEDTLS_MD_CAN_xxx` from
+ `mbedtls/config_adjust_legacy_crypto.h`.
+
+### HMAC
+
+In addition to accelerated hash operations, it is also possible to accelerate
+HMAC by enabling and accelerating:
+- HMAC algorithm and key type, i.e. `[PSA_WANT|MBEDTLS_PSA_ACCEL]_ALG_HMAC` and
+ `[PSA_WANT|MBEDTLS_PSA_ACCEL]KEY_TYPE_HMAC`.
+- Required hash algorithm(s) as explained in [Hashes](#hashes) section.
+
+In such a build it is possible to disable legacy HMAC support by disabling
+`MBEDTLS_MD_C` and still getting crypto operations, X.509 and TLS to work as
+usual. Exceptions are:
+- As mentioned in [Hashes](#hashes) direct calls to legacy lo-level hash APIs
+ (`mbedtls_sha256()` etc.) will not be possible for the legacy modules that
+ are disabled.
+- Legacy HMAC support (`mbedtls_md_hmac_xxx()`) won't be possible.
+- `MBEDTLS_PKCS[5|7]_C`, `MBEDTLS_HMAC_DRBG_C` and `MBEDTLS_HKDF_C` since they
+ depend on the legacy implementation of HMAC.
+ - disabling HMAC_DRBG_C cause deterministic ECDSA (i.e.
+ `MBEDTLS_DETERMINISTIC_ECDSA` on the legacy side and
+ `PSA_WANT_ALG_DETERMINISTIC_ECDSA` on the PSA one) to be not available.
+
+Elliptic-curve cryptography (ECC)
+---------------------------------
+
+It is possible to have most ECC operations provided only by a driver:
+
+- the ECDH, ECDSA and EC J-PAKE algorithms;
+- key import, export, and random generation.
+
+More precisely, if:
+
+- you have driver support for ECC public and using private keys (that is,
+`MBEDTLS_PSA_ACCEL_KEY_TYPE_ECC_PUBLIC_KEY` and
+`MBEDTLS_PSA_ACCEL_KEY_TYPE_ECC_KEY_PAIR_BASIC` are enabled), and
+- you have driver support for all ECC curves that are enabled (that is, for
+ each `PSA_WANT_ECC_xxx` macro enabled, the corresponding
+`MBEDTLS_PSA_ACCEL_ECC_xxx` macros is enabled as well);
+
+then you can:
+
+- enable `PSA_WANT_ALG_ECDH` without `MBEDTLS_ECDH_C`, provided
+ `MBEDTLS_PSA_ACCEL_ALG_ECDH` is enabled
+- enable `PSA_WANT_ALG_ECDSA` without `MBEDTLS_ECDSA_C`, provided
+ `MBEDTLS_PSA_ACCEL_ALG_ECDSA` is enabled;
+- enable `PSA_WANT_ALG_JPAKE` without `MBEDTLS_ECJPAKE_C`, provided
+ `MBEDTLS_PSA_ACCEL_ALG_JPAKE` is enabled.
+
+In addition, if:
+
+- none of `MBEDTLS_ECDH_C`, `MBEDTLS_ECDSA_C`, `MBEDTLS_ECJPAKE_C` are enabled
+ (see conditions above), and
+- you have driver support for all enabled ECC key pair operations - that is,
+ for each `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_xxx` macro enabled, the
+corresponding `MBEDTLS_PSA_ACCEL_KEY_TYPE_ECC_KEY_PAIR_xxx` macros is also
+enabled,
+
+then you can also disable `MBEDTLS_ECP_C`. However, a small subset of it might
+still be included in the build, see limitations sub-section below.
+
+In addition, if:
+
+- `MBEDTLS_ECP_C` is fully removed (see limitation sub-section below),
+- and support for RSA key types and algorithms is either fully disabled or
+ fully provided by a driver,
+- and support for DH key types and the FFDH algorithm is either disabled or
+ fully provided by a driver,
+
+then you can also disable `MBEDTLS_BIGNUM_C`.
+
+In such builds, all crypto operations via the PSA Crypto API will work as
+usual, as well as the PK, X.509 and TLS modules if `MBEDTLS_USE_PSA_CRYPTO` is
+enabled, with the following exceptions:
+
+- direct calls to APIs from the disabled modules are not possible;
+- PK, X.509 and TLS will not support restartable ECC operations (see
+ limitation sub-section below).
+
+If you want to check at compile-time whether a certain curve is available in
+the present build of Mbed TLS, regardless of whether ECC is provided by a
+driver or built-in, you should use the following macros:
+
+- for code that uses only the PSA Crypto API: `PSA_WANT_ECC_xxx` from
+ `psa/crypto.h`;
+- for code that may also use non-PSA crypto APIs: `MBEDTLS_ECP_HAVE_xxx` from
+ `mbedtls/build_info.h` where xxx can take the same values as for
+`MBEDTLS_ECP_DP_xxx` macros.
+
+Note that for externally-provided drivers, the integrator is responsible for
+ensuring the appropriate `MBEDTLS_PSA_ACCEL_xxx` macros are defined. However,
+for the p256-m driver that's provided with the library, those macros are
+automatically defined when enabling `MBEDTLS_PSA_P256M_DRIVER_ENABLED`.
+
+### Limitations regarding fully removing `ecp.c`
+
+A limited subset of `ecp.c` will still be automatically re-enabled if any of
+the following is enabled:
+
+- `MBEDTLS_PK_PARSE_EC_COMPRESSED` - support for parsing ECC keys where the
+ public part is in compressed format;
+- `MBEDTLS_PK_PARSE_EC_EXTENDED` - support for parsing ECC keys where the
+ curve is identified not by name, but by explicit parameters;
+- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE` - support for deterministic
+ derivation of an ECC keypair with `psa_key_derivation_output_key()`.
+
+Note: when any of the above options is enabled, a subset of `ecp.c` will
+automatically be included in the build in order to support it. Therefore
+you can still disable `MBEDTLS_ECP_C` in `mbedtls_config.h` and this will
+result in some code size savings, but not as much as when none of the
+above features are enabled.
+
+We do have plans to support each of these with `ecp.c` fully removed in the
+future, however there is no established timeline. If you're interested, please
+let us know, so we can take it into consideration in our planning.
+
+### Limitations regarding restartable / interruptible ECC operations
+
+At the moment, there is no driver support for interruptible operations
+(see `psa_sign_hash_start()` + `psa_sign_hash_complete()` etc.) so as a
+consequence these are not supported in builds without `MBEDTLS_ECDSA_C`.
+
+Similarly, there is no PSA support for interruptible ECDH operations so these
+are not supported without `ECDH_C`. See also limitations regarding
+restartable operations with `MBEDTLS_USE_PSA_CRYPTO` in [its
+documentation](use-psa-crypto.md).
+
+Again, we have plans to support this in the future but not with an established
+timeline, please let us know if you're interested.
+
+### Limitations regarding "mixed" builds (driver and built-in)
+
+In order for a build to be driver-only (no built-in implementation), all the
+requested algorithms, key types (key operations) and curves must be
+accelerated (plus a few other restrictions, see "Limitations regarding fully
+removing `ecp.c`" above). However, what if you have an accelerator that only
+supports some algorithms, some key types (key operations), or some curves, but
+want to have more enabled in you build?
+
+It is possible to have acceleration for only a subset of the requested
+algorithms. In this case, the built-in implementation of the accelerated
+algorithms will be disabled, provided all the requested curves and key types
+that can be used with this algorithm are also declared as accelerated.
+
+There is very limited support for having acceleration for only a subset of the
+requested key type operations. The only configuration that's tested is that of
+a driver accelerating `PUBLIC_KEY`, `KEY_PAIR_BASIC`, `KEY_PAIR_IMPORT`,
+`KEY_PAIR_EXPORT` but not `KEY_PAIR_GENERATE`. (Note: currently the driver
+interface does not support `KEY_PAIR_DERIVE`.)
+
+There is limited support for having acceleration for only a subset of the
+requested curves. In such builds, only the PSA API is currently tested and
+working; there are known issues in PK, and X.509 and TLS are untested.
+
+Finite-field Diffie-Hellman
+---------------------------
+
+Support is pretty similar to the "Elliptic-curve cryptography (ECC)" section
+above.
+Key management and usage can be enabled by means of the usual `PSA_WANT` +
+`MBEDTLS_PSA_ACCEL` pairs:
+
+- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_PUBLIC_KEY`;
+- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_BASIC`;
+- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_IMPORT`;
+- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_EXPORT`;
+- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_GENERATE`;
+
+The same holds for the associated algorithm:
+`[PSA_WANT|MBEDTLS_PSA_ACCEL]_ALG_FFDH` allow builds accelerating FFDH and
+removing builtin support (i.e. `MBEDTLS_DHM_C`).
+
+RSA
+---
+
+It is possible for all RSA operations to be provided only by a driver.
+
+More precisely, if:
+
+- all the RSA algorithms that are enabled (`PSA_WANT_ALG_RSA_*`) are also
+ accelerated (`MBEDTLS_PSA_ACCEL_ALG_RSA_*`),
+- and all the RSA key types that are enabled (`PSA_WANT_KEY_TYPE_RSA_*`) are
+ also accelerated (`MBEDTLS_PSA_ACCEL_KEY_TYPE_RSA_*`),
+
+then you can disable `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15` and
+`MBEDTLS_PKCS1_V21`, and RSA will still work in PSA Crypto.
+
+### Limitations on RSA acceleration
+
+Unlike other mechanisms, for now in configurations with driver-only RSA, only
+PSA Crypto works. In particular, PK, X.509 and TLS will _not_ work with
+driver-only RSA even if `MBEDTLS_USE_PSA_CRYPTO` is enabled.
+
+Currently (early 2024) we don't have plans to extend this support. If you're
+interested in wider driver-only support for RSA, please let us know.
+
+Ciphers (unauthenticated and AEAD)
+----------------------------------
+
+It is possible to have all ciphers and AEAD operations provided only by a
+driver. More precisely, for each desired combination of key type and
+algorithm/mode you can:
+
+- Enable desired PSA key type(s):
+ - `PSA_WANT_KEY_TYPE_AES`,
+ - `PSA_WANT_KEY_TYPE_ARIA`,
+ - `PSA_WANT_KEY_TYPE_CAMELLIA`,
+ - `PSA_WANT_KEY_TYPE_CHACHA20`,
+ - `PSA_WANT_KEY_TYPE_DES`.
+- Enable desired PSA algorithm(s):
+ - Unauthenticated ciphers modes:
+ - `PSA_WANT_ALG_CBC_NO_PADDING`,
+ - `PSA_WANT_ALG_CBC_PKCS7`,
+ - `PSA_WANT_ALG_CCM_STAR_NO_TAG`,
+ - `PSA_WANT_ALG_CFB`,
+ - `PSA_WANT_ALG_CTR`,
+ - `PSA_WANT_ALG_ECB_NO_PADDING`,
+ - `PSA_WANT_ALG_OFB`,
+ - `PSA_WANT_ALG_STREAM_CIPHER`.
+ - AEADs:
+ - `PSA_WANT_ALG_CCM`,
+ - `PSA_WANT_ALG_GCM`,
+ - `PSA_WANT_ALG_CHACHA20_POLY1305`.
+- Enable `MBEDTLS_PSA_ACCEL_[KEY_TYPE_xxx|ALG_yyy]` symbol(s) which correspond
+ to the `PSA_WANT_KEY_TYPE_xxx` and `PSA_WANT_ALG_yyy` of the previous steps.
+- Disable builtin support of key types:
+ - `MBEDTLS_AES_C`,
+ - `MBEDTLS_ARIA_C`,
+ - `MBEDTLS_CAMELLIA_C`,
+ - `MBEDTLS_DES_C`,
+ - `MBEDTLS_CHACHA20_C`.
+ and algorithms/modes:
+ - `MBEDTLS_CBC_C`,
+ - `MBEDTLS_CFB_C`,
+ - `MBEDTLS_CTR_C`,
+ - `MBEDTLS_OFB_C`,
+ - `MBEDTLS_XTS_C`,
+ - `MBEDTLS_CCM_C`,
+ - `MBEDTLS_GCM_C`,
+ - `MBEDTLS_CHACHAPOLY_C`,
+ - `MBEDTLS_NULL_CIPHER`.
+
+Once a key type and related algorithm are accelerated, all the PSA Crypto APIs
+will work, as well as X.509 and TLS (with `MBEDTLS_USE_PSA_CRYPTO` enabled) but
+some non-PSA APIs will be absent or have reduced functionality, see
+[Restrictions](#restrictions) for details.
+
+### Restrictions
+
+- If an algorithm other than CCM and GCM (see
+ ["Partial acceleration for CCM/GCM"](#partial-acceleration-for-ccmgcm) below)
+ is enabled but not accelerated, then all key types that can be used with it
+ will need to be built-in.
+- If a key type is enabled but not accelerated, then all algorithms that can be
+ used with it will need to be built-in.
+
+Some legacy modules can't take advantage of PSA drivers yet, and will either
+need to be disabled, or have reduced features when the built-in implementations
+of some ciphers are removed:
+
+- `MBEDTLS_NIST_KW_C` needs built-in AES: it must be disabled when
+ `MBEDTLS_AES_C` is disabled.
+- `MBEDTLS_CMAC_C` needs built-in AES/DES: it must be disabled when
+ `MBEDTLS_AES_C` and `MBEDTLS_DES_C` are both disabled. When only one of them
+ is enabled, then only the corresponding cipher will be available at runtime
+ for use with `mbedtls_cipher_cmac_xxx`. (Note: if there is driver support for
+ CMAC and all compatible key types, then `PSA_WANT_ALG_CMAC` can be enabled
+ without `MBEDTLS_CMAC_C` and CMAC will be usable with `psa_max_xxx` APIs.)
+- `MBEDTLS_CIPHER_C`: the `mbedtls_cipher_xxx()` APIs will only work with
+ ciphers that are built-in - that is, both the underlying cipher
+ (eg `MBEDTLS_AES_C`) and the mode (eg `MBEDTLS_CIPHER_MODE_CBC` or
+ `MBEDTLS_GCM_C`).
+- `MBEDTLS_PKCS5_C`: encryption/decryption (PBES2, PBE) will only work with
+ ciphers that are built-in.
+- PEM decryption will only work with ciphers that are built-in.
+- PK parse will only be able to parse encrypted keys using built-in ciphers.
+
+Note that if you also disable `MBEDTLS_CIPHER_C`, there will be additional
+restrictions, see [Disabling `MBEDTLS_CIPHER_C`](#disabling-mbedtls_cipher_c).
+
+### Legacy <-> PSA matching
+
+Note that the relationship between legacy (i.e. `MBEDTLS_xxx_C`) and PSA
+(i.e. `PSA_WANT_xxx`) symbols is not always 1:1. For example:
+
+- ECB mode is always enabled in the legacy configuration for each key type that
+ allows it (AES, ARIA, Camellia, DES), whereas it must be explicitly enabled
+ in PSA with `PSA_WANT_ALG_ECB_NO_PADDING`.
+- In the legacy API, `MBEDTLS_CHACHA20_C` enables the ChaCha20 stream cipher, and
+ enabling `MBEDTLS_CHACHAPOLY_C` also enables the ChaCha20-Poly1305 AEAD. In the
+ PSA API, you need to enable `PSA_KEY_TYPE_CHACHA20` for both, plus
+ `PSA_ALG_STREAM_CIPHER` or `PSA_ALG_CHACHA20_POLY1305` as desired.
+- The legacy symbol `MBEDTLS_CCM_C` adds support for both cipher and AEAD,
+ whereas in PSA there are 2 different symbols: `PSA_WANT_ALG_CCM_STAR_NO_TAG`
+ and `PSA_WANT_ALG_CCM`, respectively.
+
+### Partial acceleration for CCM/GCM
+
+[This section depends on #8598 so it might be updated while that PR progresses.]
+
+In case legacy CCM/GCM algorithms are enabled, it is still possible to benefit
+from PSA acceleration of the underlying block cipher by enabling support for
+ECB mode (`PSA_WANT_ALG_ECB_NO_PADDING` + `MBEDTLS_PSA_ACCEL_ALG_ECB_NO_PADDING`)
+together with desired key type(s) (`PSA_WANT_KEY_TYPE_[AES|ARIA|CAMELLIA]` +
+`MBEDTLS_PSA_ACCEL_KEY_TYPE_[AES|ARIA|CAMELLIA]`).
+
+In such configurations it is possible to:
+
+- Use CCM and GCM via the PSA Crypto APIs.
+- Use CCM and GCM via legacy functions `mbedtls_[ccm|gcm]_xxx()` (but not the
+ legacy functions `mbedtls_cipher_xxx()`).
+- Disable legacy key types (`MBEDTLS_[AES|ARIA|CAMELLIA]_C`) if there is no
+ other dependency requiring them.
+
+ChaChaPoly has no such feature, so it requires full acceleration (key type +
+algorithm) in order to work with a driver.
+
+### CTR-DRBG
+
+The legacy CTR-DRBG module (enabled by `MBEDTLS_CTR_DRBG_C`) can also benefit
+from PSA acceleration if both of the following conditions are met:
+
+- The legacy AES module (`MBEDTLS_AES_C`) is not enabled and
+- AES is supported on the PSA side together with ECB mode, i.e.
+ `PSA_WANT_KEY_TYPE_AES` + `PSA_WANT_ALG_ECB_NO_PADDING`.
+
+### Disabling `MBEDTLS_CIPHER_C`
+
+It is possible to save code size by disabling MBEDTLS_CIPHER_C when all of the
+following conditions are met:
+
+- The application is not using the `mbedtls_cipher_` API.
+- In PSA, all unauthenticated (that is, non-AEAD) ciphers are either disabled or
+ fully accelerated (that is, all compatible key types are accelerated too).
+- Either TLS is disabled, or `MBEDTLS_USE_PSA_CRYPTO` is enabled.
+- `MBEDTLS_NIST_KW` is disabled.
+- `MBEDTLS_CMAC_C` is disabled. (Note: support for CMAC in PSA can be provided by
+ a driver.)
+
+In such a build, everything will work as usual except for the following:
+
+- Encryption/decryption functions from the PKCS5 and PKCS12 module will not be
+ available (only key derivation functions).
+- Parsing of PKCS5- or PKCS12-encrypted keys in PK parse will fail.
+
+Note: AEAD ciphers (CCM, GCM, ChachaPoly) do not have a dependency on
+MBEDTLS_CIPHER_C even when using the built-in implementations.
+
+If you also have some ciphers fully accelerated and the built-ins removed, see
+[Restrictions](#restrictions) for restrictions related to removing the built-ins.
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..33a9722
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,20 @@
+.. Mbed TLS Versioned documentation master file, created by
+ sphinx-quickstart on Thu Feb 23 18:13:44 2023.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Mbed TLS API documentation
+==========================
+
+.. doxygenpage:: index
+ :project: mbedtls-versioned
+
+.. toctree::
+ :caption: Contents
+ :maxdepth: 1
+
+ Home <self>
+ api/grouplist.rst
+ api/filelist.rst
+ api/structlist.rst
+ api/unionlist.rst
diff --git a/docs/proposed/Makefile b/docs/proposed/Makefile
new file mode 100644
index 0000000..1c31464
--- /dev/null
+++ b/docs/proposed/Makefile
@@ -0,0 +1,25 @@
+PANDOC = pandoc
+
+default: all
+
+all_markdown = \
+ psa-conditional-inclusion-c.md \
+ psa-driver-developer-guide.md \
+ psa-driver-integration-guide.md \
+ psa-driver-interface.md \
+ # This line is intentionally left blank
+
+html: $(all_markdown:.md=.html)
+pdf: $(all_markdown:.md=.pdf)
+all: html pdf
+
+.SUFFIXES:
+.SUFFIXES: .md .html .pdf
+
+.md.html:
+ $(PANDOC) -o $@ $<
+.md.pdf:
+ $(PANDOC) -o $@ $<
+
+clean:
+ rm -f *.html *.pdf
diff --git a/docs/proposed/README b/docs/proposed/README
new file mode 100644
index 0000000..09eae9a
--- /dev/null
+++ b/docs/proposed/README
@@ -0,0 +1,4 @@
+The documents in this directory are proposed specifications for Mbed
+TLS features. They are not implemented yet, or only partially
+implemented. Please follow activity on the `development` branch of
+Mbed TLS if you are interested in these features.
diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md
new file mode 100644
index 0000000..3dd5345
--- /dev/null
+++ b/docs/proposed/psa-conditional-inclusion-c.md
@@ -0,0 +1,253 @@
+Conditional inclusion of cryptographic mechanism through the PSA API in Mbed TLS
+================================================================================
+
+This document is a proposed interface for deciding at build time which cryptographic mechanisms to include in the PSA Cryptography interface.
+
+This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA.
+
+## Introduction
+
+### Purpose of this specification
+
+The [PSA Cryptography API specification](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) specifies the interface between a PSA Cryptography implementation and an application. The interface defines a number of categories of cryptographic algorithms (hashes, MAC, signatures, etc.). In each category, a typical implementation offers many algorithms (e.g. for signatures: RSA-PKCS#1v1.5, RSA-PSS, ECDSA). When building the implementation for a specific use case, it is often desirable to include only a subset of the available cryptographic mechanisms, primarily in order to reduce the code footprint of the compiled system.
+
+The present document proposes a way for an application using the PSA cryptography interface to declare which mechanisms it requires.
+
+### Conditional inclusion of legacy cryptography modules
+
+Mbed TLS offers a way to select which cryptographic mechanisms are included in a build through its configuration file (`mbedtls_config.h`). This mechanism is based on two main sets of symbols: `MBEDTLS_xxx_C` controls the availability of the mechanism to the application, and `MBEDTLS_xxx_ALT` controls the availability of an alternative implementation, so the software implementation is only included if `MBEDTLS_xxx_C` is defined but not `MBEDTLS_xxx_ALT`.
+
+### PSA evolution
+
+In the PSA cryptography interface, the **core** (built-in implementations of cryptographic mechanisms) can be augmented with drivers. **Transparent drivers** replace the built-in implementation of a cryptographic mechanism (or, with **fallback**, the built-in implementation is tried if the driver only has partial support for the mechanism). **Opaque drivers** implement cryptographic mechanisms on keys which are stored in a separate domain such as a secure element, for which the core only does key management and dispatch using wrapped key blobs or key identifiers.
+
+The current model is difficult to adapt to the PSA interface for several reasons. The `MBEDTLS_xxx_ALT` symbols are somewhat inconsistent, and in particular do not work well for asymmetric cryptography. For example, many parts of the ECC code have no `MBEDTLS_xxx_ALT` symbol, so a platform with ECC acceleration that can perform all ECDSA and ECDH operations in the accelerator would still embark the `bignum` module and large parts of the `ecp_curves`, `ecp` and `ecdsa` modules. Also the availability of a transparent driver for a mechanism does not translate directly to `MBEDTLS_xxx` symbols.
+
+### Requirements
+
+[Req.interface] The application can declare which cryptographic mechanisms it needs.
+
+[Req.inclusion] If the application does not require a mechanism, a suitably configured Mbed TLS build must not include it. The granularity of mechanisms must work for typical use cases and has [acceptable limitations](#acceptable-limitations).
+
+[Req.drivers] If a PSA driver is available in the build, a suitably configured Mbed TLS build must not include the corresponding software code (unless a software fallback is needed).
+
+[Req.c] The configuration mechanism consists of C preprocessor definitions, and the build does not require tools other than a C compiler. This is necessary to allow building an application and Mbed TLS in development environments that do not allow third-party tools.
+
+[Req.adaptability] The implementation of the mechanism must be adaptable with future evolution of the PSA cryptography specifications and Mbed TLS. Therefore the interface must remain sufficiently simple and abstract.
+
+### Acceptable limitations
+
+[Limitation.matrix] If a mechanism is defined by a combination of algorithms and key types, for example a block cipher mode (CBC, CTR, CFB, …) and a block permutation (AES, CAMELLIA, ARIA, …), there is no requirement to include only specific combinations.
+
+[Limitation.direction] For mechanisms that have multiple directions (for example encrypt/decrypt, sign/verify), there is no requirement to include only one direction.
+
+[Limitation.size] There is no requirement to include only support for certain key sizes.
+
+[Limitation.multipart] Where there are multiple ways to perform an operation, for example single-part and multi-part, there is no mechanism to select only one or a subset of the possible ways.
+
+## Interface
+
+### PSA Crypto configuration file
+
+The PSA Crypto configuration file `psa/crypto_config.h` defines a series of symbols of the form `PSA_WANT_xxx` where `xxx` describes the feature that the symbol enables. The symbols are documented in the section [“PSA Crypto configuration symbols”](#psa-crypto-configuration-symbols) below.
+
+The symbol `MBEDTLS_PSA_CRYPTO_CONFIG` in `mbedtls/mbedtls_config.h` determines whether `psa/crypto_config.h` is used.
+
+* If `MBEDTLS_PSA_CRYPTO_CONFIG` is unset, which is the default at least in Mbed TLS 2.x versions, things are as they are today: the PSA subsystem includes generic code unconditionally, and includes support for specific mechanisms conditionally based on the existing `MBEDTLS_xxx_` symbols.
+* If `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the necessary software implementations of cryptographic algorithms are included based on both the content of the PSA Crypto configuration file and the Mbed TLS configuration file. For example, the code in `aes.c` is enabled if either `mbedtls/mbedtls_config.h` contains `MBEDTLS_AES_C` or `psa/crypto_config.h` contains `PSA_WANT_KEY_TYPE_AES`.
+
+### PSA Crypto configuration symbols
+
+#### Configuration symbol syntax
+
+A PSA Crypto configuration symbol is a C preprocessor symbol whose name starts with `PSA_WANT_`.
+
+* If the symbol is not defined, the corresponding feature is not included.
+* If the symbol is defined to a preprocessor expression with the value `1`, the corresponding feature is included.
+* If the symbol is defined with a different value, the behavior is currently undefined and reserved for future use.
+
+#### Configuration symbol usage
+
+The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available through the PSA API. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptographic mechanism through the PSA API, including:
+
+* In Mbed TLS test code.
+* In Mbed TLS library code using `MBEDTLS_USE_PSA_CRYPTO`, for example in TLS to determine which cipher suites to enable.
+* In application code that provides additional features based on cryptographic capabilities, for example additional key parsing and formatting functions, or cipher suite availability for network protocols.
+
+#### Configuration symbol semantics
+
+If a feature is not requested for inclusion in the PSA Crypto configuration file, it may still be included in the build, either because the feature has been requested in some other way, or because the library does not support the exclusion of this feature. Mbed TLS should make a best effort to support the exclusion of all features, but in some cases this may be judged too much effort for too little benefit.
+
+#### Configuration symbols for key types
+
+For most constant or constructor macros of the form `PSA_KEY_TYPE_xxx`, the symbol **`PSA_WANT_KEY_TYPE_xxx`** indicates that support for this key type is desired.
+
+As an exception, starting in Mbed TLS 3.5.0, for `KEY_PAIR` types (that is, private keys for asymmetric cryptography), the feature selection is more fine-grained, with an additional suffix:
+* `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_BASIC` enables basic support for the key type, and in particular support for operations with a key of that type for enabled algorithms. This is automatically enabled if any of the other `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_yyy` options is enabled.
+* `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_IMPORT` enables support for `psa_import_key` to import a key of that type.
+* `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_GENERATE` enables support for `psa_generate_key` to randomly generate a key of that type.
+* `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_DERIVE` enables support for `psa_key_derivation_output_key` to deterministically derive a key of that type.
+* `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_EXPORT` enables support for `psa_export_key` to export a key of that type.
+
+For asymmetric cryptography, `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_BASIC` determines whether private-key operations are desired, and `PSA_WANT_KEY_TYPE_xxx_PUBLIC_KEY` determines whether public-key operations are desired. `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_BASIC` implicitly enables `PSA_WANT_KEY_TYPE_xxx_PUBLIC_KEY`, as well as support for `psa_export_public_key` on the private key: there is no way to only include private-key operations (which typically saves little code).
+
+Note: the implementation is always free to include support for more than what was explicitly requested. (For example, as of Mbed TLS 3.5.0, `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_BASIC` implicitly enables import and export support for that key type, but this may not be the case in future versions.) Applications should always request support for all operations they need, rather than rely on them being implicitly enabled by the implementation. The only thing that is documented and guaranteed in the future is as follows: `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_yyy` -> `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_BASIC` -> `PSA_WANT_KEY_TYPE_xxx_PUBLIC_KEY`.
+
+#### Configuration symbols for elliptic curves
+
+For elliptic curve key types, only the specified curves are included. To include a curve, include a symbol of the form **`PSA_WANT_ECC_family_size`**. For example: `PSA_WANT_ECC_SECP_R1_256` for secp256r1, `PSA_WANT_ECC_MONTGOMERY_255` for Curve25519. It is an error to require an ECC key type but no curve, and Mbed TLS will reject this at compile time.
+
+Rationale: this is a deviation of the general principle that `PSA_ECC_FAMILY_xxx` would have a corresponding symbol `PSA_WANT_ECC_FAMILY_xxx`. This deviation is justified by the fact that it is very common to wish to include only certain curves in a family, and that can lead to a significant gain in code size.
+
+#### Configuration symbols for Diffie-Hellman groups
+
+There are no configuration symbols for Diffie-Hellman groups (`PSA_DH_GROUP_xxx`).
+
+Rationale: Finite-field Diffie-Hellman code is usually not specialized for any particular group, so reducing the number of available groups at compile time only saves a little code space. Constrained implementations tend to omit FFDH anyway, so the small code size gain is not important.
+
+#### Configuration symbols for algorithms
+
+For each constant or constructor macro of the form `PSA_ALG_xxx`, the symbol **`PSA_WANT_ALG_xxx`** indicates that support for this algorithm is desired.
+
+For parametrized algorithms, the `PSA_WANT_ALG_xxx` symbol indicates whether the base mechanism is supported. Parameters must themselves be included through their own `PSA_WANT_ALG_xxx` symbols. It is an error to include a base mechanism without at least one possible parameter, and Mbed TLS will reject this at compile time. For example, `PSA_WANT_ALG_ECDSA` requires the inclusion of randomized ECDSA for all hash algorithms whose corresponding symbol `PSA_WANT_ALG_xxx` is enabled.
+
+## Implementation
+
+### Additional non-public symbols
+
+#### Accounting for transparent drivers
+
+In addition to the [configuration symbols](#psa-crypto-configuration-symbols), we need two parallel or mostly parallel sets of symbols:
+
+* **`MBEDTLS_PSA_ACCEL_xxx`** indicates whether a fully-featured, fallback-free transparent driver is available.
+* **`MBEDTLS_PSA_BUILTIN_xxx`** indicates whether the software implementation is needed.
+
+`MBEDTLS_PSA_ACCEL_xxx` is one of the outputs of the transpilation of a driver description, alongside the glue code for calling the drivers.
+
+`MBEDTLS_PSA_BUILTIN_xxx` is enabled when `PSA_WANT_xxx` is enabled and `MBEDTLS_PSA_ACCEL_xxx` is disabled.
+
+These symbols are not part of the public interface of Mbed TLS towards applications or to drivers, regardless of whether the symbols are actually visible.
+
+### Architecture of symbol definitions
+
+#### New-style definition of configuration symbols
+
+When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/mbedtls_config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols.
+
+`mbedtls/config_psa.h` includes `psa/crypto_config.h`, the user-editable file that defines application requirements.
+
+#### Old-style definition of configuration symbols
+
+When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/mbedtls_config.h`. Furthermore, the new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`).
+
+The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that's specific to a given cryptographic mechanism. In Mbed TLS itself, code under `MBEDTLS_USE_PSA_CRYPTO` and conditional compilation guards in tests and sample programs need `PSA_WANT_xxx`.
+
+Since some existing applications use a handwritten `mbedtls/mbedtls_config.h` or an edited copy of `mbedtls/mbedtls_config.h` from an earlier version of Mbed TLS, `mbedtls/config_psa.h` must be included via an already existing header that is not `mbedtls/mbedtls_config.h`, so it is included via `psa/crypto.h` (for example from `psa/crypto_platform.h`).
+
+#### Summary of definitions of configuration symbols
+
+Whether `MBEDTLS_PSA_CRYPTO_CONFIG` is set or not, `mbedtls/config_psa.h` includes `mbedtls/crypto_drivers.h`, a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback.
+
+The following table summarizes where symbols are defined depending on the configuration mode.
+
+* (U) indicates a symbol that is defined by the user (application).
+* (D) indicates a symbol that is deduced from other symbols by code that ships with Mbed TLS.
+* (G) indicates a symbol that is generated from driver descriptions.
+
+| Symbols | With `MBEDTLS_PSA_CRYPTO_CONFIG` | Without `MBEDTLS_PSA_CRYPTO_CONFIG` |
+| ------------------------- | --------------------------------- | ----------------------------------- |
+| `MBEDTLS_xxx_C` | `mbedtls/mbedtls_config.h` (U) or | `mbedtls/mbedtls_config.h` (U) |
+| | `mbedtls/config_psa.h` (D) | |
+| `PSA_WANT_xxx` | `psa/crypto_config.h` (U) | `mbedtls/config_psa.h` (D) |
+| `MBEDTLS_PSA_BUILTIN_xxx` | `mbedtls/config_psa.h` (D) | `mbedtls/config_psa.h` (D) |
+| `MBEDTLS_PSA_ACCEL_xxx` | `mbedtls/crypto_drivers.h` (G) | N/A |
+
+#### Visibility of internal symbols
+
+Ideally, the `MBEDTLS_PSA_ACCEL_xxx` and `MBEDTLS_PSA_BUILTIN_xxx` symbols should not be visible to application code or driver code, since they are not part of the public interface of the library. However these symbols are needed to deduce whether to include library modules (for example `MBEDTLS_AES_C` has to be enabled if `MBEDTLS_PSA_BUILTIN_KEY_TYPE_AES` is enabled), which makes it difficult to keep them private.
+
+#### Compile-time checks
+
+The header file **`library/psa_check_config.h`** applies sanity checks to the configuration, throwing `#error` if something is wrong.
+
+A mechanism similar to `mbedtls/check_config.h` detects errors such as enabling ECDSA but no curve.
+
+Since configuration symbols must be undefined or 1, any other value should trigger an `#error`.
+
+#### Automatic generation of preprocessor symbol manipulations
+
+A lot of the preprocessor symbol manipulation is systematic calculations that analyze the configuration. `mbedtls/config_psa.h` and `library/psa_check_config.h` should be generated automatically, in the same manner as `version_features.c`.
+
+### Structure of PSA Crypto library code
+
+#### Conditional inclusion of library entry points
+
+An entry point can be eliminated entirely if no algorithm requires it.
+
+#### Conditional inclusion of mechanism-specific code
+
+Code that is specific to certain key types or to certain algorithms must be guarded by the applicable symbols: `PSA_WANT_xxx` for code that is independent of the application, and `MBEDTLS_PSA_BUILTIN_xxx` for code that calls an Mbed TLS software implementation.
+
+## PSA standardization
+
+### JSON configuration mechanism
+
+At the time of writing, the preferred configuration mechanism for a PSA service is in JSON syntax. The translation from JSON to build instructions is not specified by PSA.
+
+For PSA Crypto, the preferred configuration mechanism would be similar to capability specifications of transparent drivers. The same JSON properties that are used to mean “this driver can perform that mechanism” in a driver description would be used to mean “the application wants to perform that mechanism” in the application configuration.
+
+### From JSON to C
+
+The JSON capability language allows a more fine-grained selection than the C mechanism proposed here. For example, it allows requesting only single-part mechanisms, only certain key sizes, or only certain combinations of algorithms and key types.
+
+The JSON capability language can be translated approximately to the boolean symbol mechanism proposed here. The approximation considers a feature to be enabled if any part of it is enabled. For example, if there is a capability for AES-CTR and one for CAMELLIA-GCM, the translation to boolean symbols will also include AES-GCM and CAMELLIA-CTR. If there is a capability for AES-128, the translation will also include AES-192 and AES-256.
+
+The boolean symbol mechanism proposed here can be translated to a list of JSON capabilities: for each included algorithm, include a capability with that algorithm, the key types that apply to that algorithm, no size restriction, and all the entry points that apply to that algorithm.
+
+## Open questions
+
+### Open questions about the interface
+
+#### Naming of symbols
+
+The names of [elliptic curve symbols](#configuration-symbols-for-elliptic-curves) are a bit weird: `SECP_R1_256` instead of `SECP256R1`, `MONTGOMERY_255` instead of `CURVE25519`. Should we make them more classical, but less systematic?
+
+#### Impossible combinations
+
+What does it mean to have `PSA_WANT_ALG_ECDSA` enabled but with only Curve25519? Is it a mandatory error?
+
+#### Diffie-Hellman
+
+Way to request only specific groups? Not a priority: constrained devices don't do FFDH. Specify it as may change in future versions.
+
+#### Coexistence with the current Mbed TLS configuration
+
+The two mechanisms have very different designs. Is there serious potential for confusion? Do we understand how the combinations work?
+
+### Open questions about the design
+
+#### Algorithms without a key type or vice versa
+
+Is it realistic to mandate a compile-time error if a key type is required, but no matching algorithm, or vice versa? Is it always the right thing, for example if there is an opaque driver that manipulates this key type?
+
+#### Opaque-only mechanisms
+
+If a mechanism should only be supported in an opaque driver, what does the core need to know about it? Do we have all the information we need?
+
+This is especially relevant to suppress a mechanism completely if there is no matching algorithm. For example, if there is no transparent implementation of RSA or ECDSA, `psa_sign_hash` and `psa_verify_hash` may still be needed if there is an opaque signature driver.
+
+### Open questions about the implementation
+
+#### Testability
+
+Is this proposal decently testable? There are a lot of combinations. What combinations should we test?
+
+<!--
+Local Variables:
+time-stamp-line-limit: 40
+time-stamp-start: "Time-stamp: *\""
+time-stamp-end: "\""
+time-stamp-format: "%04Y/%02m/%02d %02H:%02M:%02S %Z"
+time-stamp-time-zone: "GMT"
+End:
+-->
diff --git a/docs/proposed/psa-driver-developer-guide.md b/docs/proposed/psa-driver-developer-guide.md
new file mode 100644
index 0000000..6b207c8
--- /dev/null
+++ b/docs/proposed/psa-driver-developer-guide.md
@@ -0,0 +1,52 @@
+PSA Cryptoprocessor driver developer's guide
+============================================
+
+**This is a specification of work in progress. The implementation is not yet merged into Mbed TLS.**
+For a description of the current state of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-example-and-guide.html).
+
+This document describes how to write drivers of cryptoprocessors such as accelerators and secure elements for the PSA cryptography subsystem of Mbed TLS.
+
+This document focuses on behavior that is specific to Mbed TLS. For a reference of the interface between Mbed TLS and drivers, refer to the [PSA Cryptoprocessor Driver Interface specification](psa-driver-interface.html).
+
+The interface is not fully implemented in Mbed TLS yet. Please note that the interface may still change: until further notice, we do not guarantee backward compatibility with existing driver code.
+
+## Introduction
+
+### Purpose
+
+The PSA cryptography driver interface provides a way to build Mbed TLS with additional code that implements certain cryptographic primitives. This is primarily intended to support platform-specific hardware.
+
+There are two types of drivers:
+
+* **Transparent** drivers implement cryptographic operations on keys that are provided in cleartext at the beginning of each operation. They are typically used for hardware **accelerators**. When a transparent driver is available for a particular combination of parameters (cryptographic algorithm, key type and size, etc.), it is used instead of the default software implementation. Transparent drivers can also be pure software implementations that are distributed as plug-ins to a PSA Crypto implementation.
+* **Opaque** drivers implement cryptographic operations on keys that can only be used inside a protected environment such as a **secure element**, a hardware security module, a smartcard, a secure enclave, etc. An opaque driver is invoked for the specific key location that the driver is registered for: the dispatch is based on the key's lifetime.
+
+### Deliverables for a driver
+
+To write a driver, you need to implement some functions with C linkage, and to declare these functions in a **driver description file**. The driver description file declares which functions the driver implements and what cryptographic mechanisms they support. Depending on the driver type, you may also need to define some C types and macros in a header file.
+
+The concrete syntax for a driver description file is JSON. The structure of this JSON file is specified in the section [“Driver description syntax”](psa-driver-interface.html#driver-description-syntax) of the PSA cryptography driver interface specification.
+
+A driver therefore consists of:
+
+* A driver description file (in JSON format).
+* C header files defining the types required by the driver description. The names of these header files is declared in the driver description file.
+* An object file compiled for the target platform defining the functions required by the driver description. Implementations may allow drivers to be provided as source files and compiled with the core instead of being pre-compiled.
+
+## Driver C interfaces
+
+Mbed TLS calls driver entry points [as specified in the PSA Cryptography Driver Interface specification](psa-driver-interface.html#driver-entry-points) except as otherwise indicated in this section.
+
+## Mbed TLS extensions
+
+The driver description can include Mbed TLS extensions (marked by the namespace "mbedtls"). Mbed TLS extensions are meant to extend/help integrating the driver into the library's infrastructure.
+* `"mbedtls/h_condition"` (optional, string) can include complex preprocessor definitions to conditionally include header files for a given driver.
+* `"mbedtls/c_condition"` (optional, string) can include complex preprocessor definitions to conditionally enable dispatch capabilities for a driver.
+
+## Building and testing your driver
+
+<!-- TODO -->
+
+## Dependencies on the Mbed TLS configuration
+
+<!-- TODO -->
diff --git a/docs/proposed/psa-driver-integration-guide.md b/docs/proposed/psa-driver-integration-guide.md
new file mode 100644
index 0000000..8b3b404
--- /dev/null
+++ b/docs/proposed/psa-driver-integration-guide.md
@@ -0,0 +1,39 @@
+Building Mbed TLS with PSA cryptoprocessor drivers
+==================================================
+
+**This is a specification of work in progress. The implementation is not yet merged into Mbed TLS.**
+For a description of the current state of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-example-and-guide.html).
+
+This document describes how to build Mbed TLS with additional cryptoprocessor drivers that follow the PSA cryptoprocessor driver interface.
+
+The interface is not fully implemented in Mbed TLS yet. Please note that the interface may still change: until further notice, we do not guarantee backward compatibility with existing driver code.
+
+## Introduction
+
+The PSA cryptography driver interface provides a way to build Mbed TLS with additional code that implements certain cryptographic primitives. This is primarily intended to support platform-specific hardware.
+
+Note that such drivers are only available through the PSA cryptography API (crypto functions beginning with `psa_`, and X.509 and TLS interfaces that reference PSA types).
+
+Concretely speaking, a driver consists of one or more **driver description files** in JSON format and some code to include in the build. The driver code can either be provided in binary form as additional object file to link, or in source form.
+
+## How to build Mbed TLS with drivers
+
+To build Mbed TLS with drivers:
+
+1. Pass the driver description files through the Make variable `PSA_DRIVERS` when building the library.
+
+ ```
+ cd /path/to/mbedtls
+ make PSA_DRIVERS="/path/to/acme/driver.json /path/to/nadir/driver.json" lib
+ ```
+
+2. Link your application with the implementation of the driver functions.
+
+ ```
+ cd /path/to/application
+ ld myapp.o -L/path/to/acme -lacmedriver -L/path/to/nadir -lnadirdriver -L/path/to/mbedtls -lmbedcrypto
+ ```
+
+<!-- TODO: what if the driver is provided as C source code? -->
+
+<!-- TODO: what about additional include files? -->
diff --git a/docs/proposed/psa-driver-interface.md b/docs/proposed/psa-driver-interface.md
new file mode 100644
index 0000000..1aa55b3
--- /dev/null
+++ b/docs/proposed/psa-driver-interface.md
@@ -0,0 +1,1460 @@
+PSA Cryptoprocessor Driver Interface
+====================================
+
+This document describes an interface for cryptoprocessor drivers in the PSA cryptography API. This interface complements the [PSA Cryptography API specification](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface), which describes the interface between a PSA Cryptography implementation and an application.
+
+This specification is work in progress and should be considered to be in a beta stage. There is ongoing work to implement this interface in Mbed TLS, which is the reference implementation of the PSA Cryptography API. At this stage, Arm does not expect major changes, but minor changes are expected based on experience from the first implementation and on external feedback.
+
+For a practical guide, with a description of the current state of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-example-and-guide.html).
+
+## Introduction
+
+### Purpose of the driver interface
+
+The PSA Cryptography API defines an interface that allows applications to perform cryptographic operations in a uniform way regardless of how the operations are performed. Under the hood, different keys may be stored and used in different hardware or in different logical partitions, and different algorithms may involve different hardware or software components.
+
+The driver interface allows implementations of the PSA Cryptography API to be built compositionally. An implementation of the PSA Cryptography API is composed of a **core** and zero or more **drivers**. The core handles key management, enforces key usage policies, and dispatches cryptographic operations either to the applicable driver or to built-in code.
+
+Functions in the PSA Cryptography API invoke functions in the core. Code from the core calls drivers as described in the present document.
+
+### Types of drivers
+
+The PSA Cryptography driver interface supports two types of cryptoprocessors, and accordingly two types of drivers.
+
+* **Transparent** drivers implement cryptographic operations on keys that are provided in cleartext at the beginning of each operation. They are typically used for hardware **accelerators**. When a transparent driver is available for a particular combination of parameters (cryptographic algorithm, key type and size, etc.), it is used instead of the default software implementation. Transparent drivers can also be pure software implementations that are distributed as plug-ins to a PSA Cryptography implementation (for example, an alternative implementation with different performance characteristics, or a certified implementation).
+* **Opaque** drivers implement cryptographic operations on keys that can only be used inside a protected environment such as a **secure element**, a hardware security module, a smartcard, a secure enclave, etc. An opaque driver is invoked for the specific [key location](#lifetimes-and-locations) that the driver is registered for: the dispatch is based on the key's lifetime.
+
+### Requirements
+
+The present specification was designed to fulfill the following high-level requirements.
+
+[Req.plugins] It is possible to combine multiple drivers from different providers into the same implementation, without any prior arrangement other than choosing certain names and values from disjoint namespaces.
+
+[Req.compile] It is possible to compile the code of each driver and of the core separately, and link them together. A small amount of glue code may need to be compiled once the list of drivers is available.
+
+[Req.types] Support drivers for the following types of hardware: accelerators that operate on keys in cleartext; cryptoprocessors that can wrap keys with a built-in keys but not store user keys; and cryptoprocessors that store key material.
+
+[Req.portable] The interface between drivers and the core does not involve any platform-specific consideration. Driver calls are simple C function calls. Interactions with platform-specific hardware happen only inside the driver (and in fact a driver need not involve any hardware at all).
+
+[Req.location] Applications can tell which location values correspond to which secure element drivers.
+
+[Req.fallback] Accelerator drivers can specify that they do not fully support a cryptographic mechanism and that a fallback to core code may be necessary. Conversely, if an accelerator fully supports cryptographic mechanism, the core must be able to omit code for this mechanism.
+
+[Req.mechanisms] Drivers can specify which mechanisms they support. A driver's code will not be invoked for cryptographic mechanisms that it does not support.
+
+## Overview of drivers
+
+### Deliverables for a driver
+
+To write a driver, you need to implement some functions with C linkage, and to declare these functions in a **driver description file**. The driver description file declares which functions the driver implements and what cryptographic mechanisms they support. If the driver description references custom types, macros or constants, you also need to provide C header files defining those elements.
+
+The concrete syntax for a driver description file is JSON. The structure of this JSON file is specified in the section [“Driver description syntax”](#driver-description-syntax).
+
+A driver therefore consists of:
+
+* A driver description file (in JSON format).
+* C header files defining the types required by the driver description. The names of these header files are declared in the driver description file.
+* An object file compiled for the target platform defining the entry point functions specified by the driver description. Implementations may allow drivers to be provided as source files and compiled with the core instead of being pre-compiled.
+
+How to provide the driver description file, the C header files and the object code is implementation-dependent.
+
+### Driver description syntax
+
+The concrete syntax for a driver description file is JSON.
+
+In addition to the properties described here, any JSON object may have a property called `"_comment"` of type string, which will be ignored.
+
+PSA Cryptography core implementations may support additional properties. Such properties must use names consisting of the implementation's name, a slash, and additional characters. For example, the Yoyodyne implementation may use property names such as `"yoyodyne/foo"` and `"yoyodyne/widgets/girth"`.
+
+#### Driver description list
+
+PSA Cryptography core implementations should support multiple drivers. The driver description files are passed to the implementation as an ordered list in an unspecified manner. This may be, for example, a list of file names passed on a command line, or a JSON list whose elements are individual driver descriptions.
+
+#### Driver description top-level element
+
+A driver description is a JSON object containing the following properties:
+
+* `"prefix"` (mandatory, string). This must be a valid, non-empty prefix for a C identifier. All the types and functions provided by the driver have a name that starts with this prefix unless overridden with a `"name"` element in the applicable capability as described below.
+* `"type"` (mandatory, string). One of `"transparent"` or `"opaque"`.
+* `"headers"` (optional, array of strings). A list of header files. These header files must define the types, macros and constants referenced by the driver description. They may declare the entry point functions, but this is not required. They may include other PSA headers and standard headers of the platform. Whether they may include other headers is implementation-specific. If omitted, the list of headers is empty. The header files must be present at the specified location relative to a directory on the compiler's include path when compiling glue code between the core and the drivers.
+* `"capabilities"` (mandatory, array of [capabilities](#driver-description-capability)).
+A list of **capabilities**. Each capability describes a family of functions that the driver implements for a certain class of cryptographic mechanisms.
+* `"key_context"` (not permitted for transparent drivers, mandatory for opaque drivers): information about the [representation of keys](#key-format-for-opaque-drivers).
+* `"persistent_state_size"` (not permitted for transparent drivers, optional for opaque drivers, integer or string). The size in bytes of the [persistent state of the driver](#opaque-driver-persistent-state). This may be either a non-negative integer or a C constant expression of type `size_t`.
+* `"location"` (not permitted for transparent drivers, optional for opaque drivers, integer or string). The [location value](#lifetimes-and-locations) for which this driver is invoked. In other words, this determines the lifetimes for which the driver is invoked. This may be either a non-negative integer or a C constant expression of type `psa_key_location_t`.
+
+### Driver description capability
+
+#### Capability syntax
+
+A capability declares a family of functions that the driver implements for a certain class of cryptographic mechanisms. The capability specifies which key types and algorithms are covered and the names of the types and functions that implement it.
+
+A capability is a JSON object containing the following properties:
+
+* `"entry_points"` (mandatory, list of strings). Each element is the name of a [driver entry point](#driver-entry-points) or driver entry point family. An entry point is a function defined by the driver. If specified, the core will invoke this capability of the driver only when performing one of the specified operations. The driver must implement all the specified entry points, as well as the types if applicable.
+* `"algorithms"` (optional, list of strings). Each element is an [algorithm specification](#algorithm-specifications). If specified, the core will invoke this capability of the driver only when performing one of the specified algorithms. If omitted, the core will invoke this capability for all applicable algorithms.
+* `"key_types"` (optional, list of strings). Each element is a [key type specification](#key-type-specifications). If specified, the core will invoke this capability of the driver only for operations involving a key with one of the specified key types. If omitted, the core will invoke this capability of the driver for all applicable key types.
+* `"key_sizes"` (optional, list of integers). If specified, the core will invoke this capability of the driver only for operations involving a key with one of the specified key sizes. If omitted, the core will invoke this capability of the driver for all applicable key sizes. Key sizes are expressed in bits.
+* `"names"` (optional, object). A mapping from entry point names described by the `"entry_points"` property, to the name of the C function in the driver that implements the corresponding function. If a function is not listed here, name of the driver function that implements it is the driver's prefix followed by an underscore (`_`) followed by the function name. If this property is omitted, it is equivalent to an empty object (so each entry point *suffix* is implemented by a function called *prefix*`_`*suffix*).
+* `"fallback"` (optional for transparent drivers, not permitted for opaque drivers, boolean). If present and true, the driver may return `PSA_ERROR_NOT_SUPPORTED`, in which case the core should call another driver or use built-in code to perform this operation. If absent or false, the driver is expected to fully support the mechanisms described by this capability. See the section “[Fallback](#fallback)” for more information.
+
+#### Capability semantics
+
+When the PSA Cryptography implementation performs a cryptographic mechanism, it invokes available driver entry points as described in the section [“Driver entry points”](#driver-entry-points).
+
+A driver is considered available for a cryptographic mechanism that invokes a given entry point if all of the following conditions are met:
+
+* The driver specification includes a capability whose `"entry_points"` list either includes the entry point or includes an entry point family that includes the entry point.
+* If the mechanism involves an algorithm:
+ * either the capability does not have an `"algorithms"` property;
+ * or the value of the capability's `"algorithms"` property includes an [algorithm specification](#algorithm-specifications) that matches this algorithm.
+* If the mechanism involves a key:
+ * either the key is transparent (its location is `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver is transparent;
+ * or the key is opaque (its location is not `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver is an opaque driver whose location is the key's location.
+* If the mechanism involves a key:
+ * either the capability does not have a `"key_types"` property;
+ * or the value of the capability's `"key_types"` property includes a [key type specification](#key-type-specifications) that matches this algorithm.
+* If the mechanism involves a key:
+ * either the capability does not have a `"key_sizes"` property;
+ * or the value of the capability's `"key_sizes"` property includes the key's size.
+
+If a driver includes multiple applicable capabilities for a given combination of entry point, algorithm, key type and key size, and all the capabilities map the entry point to the same function name, the driver is considered available for this cryptographic mechanism. If a driver includes multiple applicable capabilities for a given combination of entry point, algorithm, key type and key size, and at least two of these capabilities map the entry point to the different function names, the driver specification is invalid.
+
+If multiple transparent drivers have applicable capabilities for a given combination of entry point, algorithm, key type and key size, the first matching driver in the [specification list](#driver-description-list) is invoked. If the capability has [fallback](#fallback) enabled and the first driver returns `PSA_ERROR_NOT_SUPPORTED`, the next matching driver is invoked, and so on.
+
+If multiple opaque drivers have the same location, the list of driver specifications is invalid.
+
+#### Capability examples
+
+Example 1: the following capability declares that the driver can perform deterministic ECDSA signatures (but not signature verification) using any hash algorithm and any curve that the core supports. If the prefix of this driver is `"acme"`, the function that performs the signature is called `acme_sign_hash`.
+```
+{
+ "entry_points": ["sign_hash"],
+ "algorithms": ["PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_ANY_HASH)"],
+}
+```
+
+Example 2: the following capability declares that the driver can perform deterministic ECDSA signatures using SHA-256 or SHA-384 with a SECP256R1 or SECP384R1 private key (with either hash being possible in combination with either curve). If the prefix of this driver is `"acme"`, the function that performs the signature is called `acme_sign_hash`.
+```
+{
+ "entry_points": ["sign_hash"],
+ "algorithms": ["PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)",
+ "PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_384)"],
+ "key_types": ["PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)"],
+ "key_sizes": [256, 384]
+}
+```
+
+### Algorithm and key specifications
+
+#### Algorithm specifications
+
+An algorithm specification is a string consisting of a `PSA_ALG_xxx` macro that specifies a cryptographic algorithm or an algorithm wildcard policy defined by the PSA Cryptography API. If the macro takes arguments, the string must have the syntax of a C macro call and each argument must be an algorithm specification or a decimal or hexadecimal literal with no suffix, depending on the expected type of argument.
+
+Spaces are optional after commas. Whether other whitespace is permitted is implementation-specific.
+
+Valid examples:
+```
+PSA_ALG_SHA_256
+PSA_ALG_HMAC(PSA_ALG_SHA_256)
+PSA_ALG_KEY_AGREEMENT(PSA_ALG_ECDH, PSA_ALG_HKDF(PSA_ALG_SHA_256))
+PSA_ALG_RSA_PSS(PSA_ALG_ANY_HASH)
+```
+
+#### Key type specifications
+
+An algorithm specification is a string consisting of a `PSA_KEY_TYPE_xxx` macro that specifies a key type defined by the PSA Cryptography API. If the macro takes an argument, the string must have the syntax of a C macro call and each argument must be the name of a constant of suitable type (curve or group).
+
+The name `_` may be used instead of a curve or group to indicate that the capability concerns all curves or groups.
+
+Valid examples:
+```
+PSA_KEY_TYPE_AES
+PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)
+PSA_KEY_TYPE_ECC_KEY_PAIR(_)
+```
+
+### Driver entry points
+
+#### Overview of driver entry points
+
+Drivers define functions, each of which implements an aspect of a capability of a driver, such as a cryptographic operation, a part of a cryptographic operation, or a key management action. These functions are called the **entry points** of the driver. Most driver entry points correspond to a particular function in the PSA Cryptography API. For example, if a call to `psa_sign_hash()` is dispatched to a driver, it invokes the driver's `sign_hash` function.
+
+All driver entry points return a status of type `psa_status_t` which should use the status codes documented for PSA services in general and for PSA Cryptography in particular: `PSA_SUCCESS` indicates that the function succeeded, and `PSA_ERROR_xxx` values indicate that an error occurred.
+
+The signature of a driver entry point generally looks like the signature of the PSA Cryptography API that it implements, with some modifications. This section gives an overview of modifications that apply to whole classes of entry points. Refer to the reference section for each entry point or entry point family for details.
+
+* For entry points that operate on an existing key, the `psa_key_id_t` parameter is replaced by a sequence of three parameters that describe the key:
+ 1. `const psa_key_attributes_t *attributes`: the key attributes.
+ 2. `const uint8_t *key_buffer`: a key material or key context buffer.
+ 3. `size_t key_buffer_size`: the size of the key buffer in bytes.
+
+ For transparent drivers, the key buffer contains the key material, in the same format as defined for `psa_export_key()` and `psa_export_public_key()` in the PSA Cryptography API. For opaque drivers, the content of the key buffer is entirely up to the driver.
+
+* For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operation_t`) is replaced by a driver-specific operation state type (*prefix*`_XXX_operation_t`).
+
+* For entry points that are involved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence of parameters that convey the key context:
+ 1. `uint8_t *key_buffer`: a buffer for the key material or key context.
+ 2. `size_t key_buffer_size`: the size of the key buffer in bytes.
+ 2. `size_t *key_buffer_length`: the length of the data written to the key buffer in bytes.
+
+Some entry points are grouped in families that must be implemented as a whole. If a driver supports an entry point family, it must provide all the entry points in the family.
+
+Drivers can also have entry points related to random generation. A transparent driver can provide a [random generation interface](#random-generation-entry-points). Separately, transparent and opaque drivers can have [entropy collection entry points](#entropy-collection-entry-point).
+
+#### General considerations on driver entry point parameters
+
+Buffer parameters for driver entry points obey the following conventions:
+
+* An input buffer has the type `const uint8_t *` and is immediately followed by a parameter of type `size_t` that indicates the buffer size.
+* An output buffer has the type `uint8_t *` and is immediately followed by a parameter of type `size_t` that indicates the buffer size. A third parameter of type `size_t *` is provided to report the actual length of the data written in the buffer if the function succeeds.
+* An in-out buffer has the type `uint8_t *` and is immediately followed by a parameter of type `size_t` that indicates the buffer size. In-out buffers are only used when the input and the output have the same length.
+
+Buffers of size 0 may be represented with either a null pointer or a non-null pointer.
+
+Input buffers and other input-only parameters (`const` pointers) may be in read-only memory. Overlap is possible between input buffers, and between an input buffer and an output buffer, but not between two output buffers or between a non-buffer parameter and another parameter.
+
+#### Driver entry points for single-part cryptographic operations
+
+The following driver entry points perform a cryptographic operation in one shot (single-part operation):
+
+* `"hash_compute"` (transparent drivers only): calculation of a hash. Called by `psa_hash_compute()` and `psa_hash_compare()`. To verify a hash with `psa_hash_compare()`, the core calls the driver's `"hash_compute"` entry point and compares the result with the reference hash value.
+* `"mac_compute"`: calculation of a MAC. Called by `psa_mac_compute()` and possibly `psa_mac_verify()`. To verify a mac with `psa_mac_verify()`, the core calls an applicable driver's `"mac_verify"` entry point if there is one, otherwise the core calls an applicable driver's `"mac_compute"` entry point and compares the result with the reference MAC value.
+* `"mac_verify"`: verification of a MAC. Called by `psa_mac_verify()`. This entry point is mainly useful for drivers of secure elements that verify a MAC without revealing the correct MAC. Although transparent drivers may implement this entry point in addition to `"mac_compute"`, it is generally not useful because the core can call the `"mac_compute"` entry point and compare with the expected MAC value.
+* `"cipher_encrypt"`: unauthenticated symmetric cipher encryption. Called by `psa_cipher_encrypt()`.
+* `"cipher_decrypt"`: unauthenticated symmetric cipher decryption. Called by `psa_cipher_decrypt()`.
+* `"aead_encrypt"`: authenticated encryption with associated data. Called by `psa_aead_encrypt()`.
+* `"aead_decrypt"`: authenticated decryption with associated data. Called by `psa_aead_decrypt()`.
+* `"asymmetric_encrypt"`: asymmetric encryption. Called by `psa_asymmetric_encrypt()`.
+* `"asymmetric_decrypt"`: asymmetric decryption. Called by `psa_asymmetric_decrypt()`.
+* `"sign_hash"`: signature of an already calculated hash. Called by `psa_sign_hash()` and possibly `psa_sign_message()`. To sign a message with `psa_sign_message()`, the core calls an applicable driver's `"sign_message"` entry point if there is one, otherwise the core calls an applicable driver's `"hash_compute"` entry point followed by an applicable driver's `"sign_hash"` entry point.
+* `"verify_hash"`: verification of an already calculated hash. Called by `psa_verify_hash()` and possibly `psa_verify_message()`. To verify a message with `psa_verify_message()`, the core calls an applicable driver's `"verify_message"` entry point if there is one, otherwise the core calls an applicable driver's `"hash_compute"` entry point followed by an applicable driver's `"verify_hash"` entry point.
+* `"sign_message"`: signature of a message. Called by `psa_sign_message()`.
+* `"verify_message"`: verification of a message. Called by `psa_verify_message()`.
+* `"key_agreement"`: key agreement without a subsequent key derivation. Called by `psa_raw_key_agreement()` and possibly `psa_key_derivation_key_agreement()`.
+
+### Driver entry points for multi-part operations
+
+#### General considerations on multi-part operations
+
+The entry points that implement each step of a multi-part operation are grouped into a family. A driver that implements a multi-part operation must define all of the entry points in this family as well as a type that represents the operation context. The lifecycle of a driver operation context is similar to the lifecycle of an API operation context:
+
+1. The core initializes operation context objects to either all-bits-zero or to logical zero (`{0}`), at its discretion.
+1. The core calls the `xxx_setup` entry point for this operation family. If this fails, the core destroys the operation context object without calling any other driver entry point on it.
+1. The core calls other entry points that manipulate the operation context object, respecting the constraints.
+1. If any entry point fails, the core calls the driver's `xxx_abort` entry point for this operation family, then destroys the operation context object without calling any other driver entry point on it.
+1. If a “finish” entry point fails, the core destroys the operation context object without calling any other driver entry point on it. The finish entry points are: *prefix*`_mac_sign_finish`, *prefix*`_mac_verify_finish`, *prefix*`_cipher_finish`, *prefix*`_aead_finish`, *prefix*`_aead_verify`.
+
+If a driver implements a multi-part operation but not the corresponding single-part operation, the core calls the driver's multipart operation entry points to perform the single-part operation.
+
+#### Multi-part operation entry point family `"hash_multipart"`
+
+This family corresponds to the calculation of a hash in multiple steps.
+
+This family applies to transparent drivers only.
+
+This family requires the following type and entry points:
+
+* Type `"hash_operation_t"`: the type of a hash operation context. It must be possible to copy a hash operation context byte by byte, therefore hash operation contexts must not contain any embedded pointers (except pointers to global data that do not change after the setup step).
+* `"hash_setup"`: called by `psa_hash_setup()`.
+* `"hash_update"`: called by `psa_hash_update()`.
+* `"hash_finish"`: called by `psa_hash_finish()` and `psa_hash_verify()`.
+* `"hash_abort"`: called by all multi-part hash functions of the PSA Cryptography API.
+
+To verify a hash with `psa_hash_verify()`, the core calls the driver's *prefix*`_hash_finish` entry point and compares the result with the reference hash value.
+
+For example, a driver with the prefix `"acme"` that implements the `"hash_multipart"` entry point family must define the following type and entry points (assuming that the capability does not use the `"names"` property to declare different type and entry point names):
+
+```
+typedef ... acme_hash_operation_t;
+psa_status_t acme_hash_setup(acme_hash_operation_t *operation,
+ psa_algorithm_t alg);
+psa_status_t acme_hash_update(acme_hash_operation_t *operation,
+ const uint8_t *input,
+ size_t input_length);
+psa_status_t acme_hash_finish(acme_hash_operation_t *operation,
+ uint8_t *hash,
+ size_t hash_size,
+ size_t *hash_length);
+psa_status_t acme_hash_abort(acme_hash_operation_t *operation);
+```
+
+#### Operation family `"mac_multipart"`
+
+TODO
+
+#### Operation family `"mac_verify_multipart"`
+
+TODO
+
+#### Operation family `"cipher_encrypt_multipart"`
+
+TODO
+
+#### Operation family `"cipher_decrypt_multipart"`
+
+TODO
+
+#### Operation family `"aead_encrypt_multipart"`
+
+TODO
+
+#### Operation family `"aead_decrypt_multipart"`
+
+TODO
+
+### Driver entry points for key derivation
+
+Key derivation is more complex than other multipart operations for several reasons:
+
+* There are multiple inputs and outputs.
+* Multiple drivers can be involved. This happens when an operation combines a key agreement and a subsequent symmetric key derivation, each of which can have independent drivers. This also happens when deriving an asymmetric key, where processing the secret input and generating the key output might involve different drivers.
+* When multiple drivers are involved, they are not always independent: if the secret input is managed by an opaque driver, it might not allow the core to retrieve the intermediate output and pass it to another driver.
+* The involvement of an opaque driver cannot be determined as soon as the operation is set up (since `psa_key_derivation_setup()` does not determine the key input).
+
+#### Key derivation driver dispatch logic
+
+The core decides whether to dispatch a key derivation operation to a driver based on the location associated with the input step `PSA_KEY_DERIVATION_INPUT_SECRET`.
+
+1. If this step is passed via `psa_key_derivation_input_key()` for a key in a secure element:
+ * If the driver for this secure element implements the `"key_derivation"` family for the specified algorithm, the core calls that driver's `"key_derivation_setup"` and subsequent entry points.
+ Note that for all currently specified algorithms, the key type for the secret input does not matter.
+ * Otherwise the core calls the secure element driver's [`"export_key"`](#key-management-with-opaque-drivers) entry point.
+2. Otherwise ([or on fallback?](#fallback-for-key-derivation-in-opaque-drivers)), if there is a transparent driver for the specified algorithm, the core calls that driver's `"key_derivation_setup"` and subsequent entry points.
+3. Otherwise, or on fallback, the core uses its built-in implementation.
+
+#### Summary of entry points for the operation family `"key_derivation"`
+
+A key derivation driver has the following entry points:
+
+* `"key_derivation_setup"` (mandatory): always the first entry point to be called. This entry point provides the [initial inputs](#key-derivation-driver-initial-inputs). See [“Key derivation driver setup”](#key-derivation-driver-setup).
+* `"key_derivation_input_step"` (mandatory if the driver supports a key derivation algorithm with long inputs, otherwise ignored): provide an extra input for the key derivation. This entry point is only mandatory in drivers that support algorithms that have extra inputs. See [“Key derivation driver long inputs”](#key-derivation-driver-long-inputs).
+* `"key_derivation_output_bytes"` (mandatory): derive cryptographic material and output it. See [“Key derivation driver outputs”](#key-derivation-driver-outputs).
+* `"key_derivation_output_key"`, `"key_derivation_verify_bytes"`, `"key_derivation_verify_key"` (optional, opaque drivers only): derive key material which remains inside the same secure element. See [“Key derivation driver outputs”](#key-derivation-driver-outputs).
+* `"key_derivation_set_capacity"` (mandatory for opaque drivers that implement `"key_derivation_output_key"` for “cooked”, i.e. non-raw-data key types; ignored for other opaque drivers; not permitted for transparent drivers): update the capacity policy on the operation. See [“Key derivation driver operation capacity”](#key-derivation-driver-operation-capacity).
+* `"key_derivation_abort"` (mandatory): always the last entry point to be called.
+
+For naming purposes, here and in the following subsection, this specification takes the example of a driver with the prefix `"acme"` that implements the `"key_derivation"` entry point family with a capability that does not use the `"names"` property to declare different type and entry point names. Such a driver must implement the following type and functions, as well as the entry points listed above and described in the following subsections:
+```
+typedef ... acme_key_derivation_operation_t;
+psa_status_t acme_key_derivation_abort(acme_key_derivation_operation_t *operation);
+```
+
+#### Key derivation driver initial inputs
+
+The core conveys the initial inputs for a key derivation via an opaque data structure of type `psa_crypto_driver_key_derivation_inputs_t`.
+
+```
+typedef ... psa_crypto_driver_key_derivation_inputs_t; // implementation-specific type
+```
+
+A driver receiving an argument that points to a `psa_crypto_driver_key_derivation_inputs_t` can retrieve its contents by calling one of the type-specific functions below. To determine the correct function, the driver can call `psa_crypto_driver_key_derivation_get_input_type()`.
+
+```
+enum psa_crypto_driver_key_derivation_input_type_t {
+ PSA_KEY_DERIVATION_INPUT_TYPE_INVALID = 0,
+ PSA_KEY_DERIVATION_INPUT_TYPE_OMITTED,
+ PSA_KEY_DERIVATION_INPUT_TYPE_BYTES,
+ PSA_KEY_DERIVATION_INPUT_TYPE_KEY,
+ PSA_KEY_DERIVATION_INPUT_TYPE_INTEGER,
+ // Implementations may add other values, and may freely choose the
+ // numerical values for each identifer except as explicitly specified
+ // above.
+};
+psa_crypto_driver_key_derivation_input_type_t psa_crypto_driver_key_derivation_get_input_type(
+ const psa_crypto_driver_key_derivation_inputs_t *inputs,
+ psa_key_derivation_step_t step);
+```
+
+The function `psa_crypto_driver_key_derivation_get_input_type()` determines whether a given step is present and how to access its value:
+
+* `PSA_KEY_DERIVATION_INPUT_TYPE_INVALID`: the step is invalid for the algorithm of the operation that the inputs are for.
+* `PSA_KEY_DERIVATION_INPUT_TYPE_OMITTED`: the step is optional for the algorithm of the operation that the inputs are for, and has been omitted.
+* `PSA_KEY_DERIVATION_INPUT_TYPE_BYTES`: the step is valid and present and is a transparent byte string. Call `psa_crypto_driver_key_derivation_get_input_size()` to obtain the size of the input data. Call `psa_crypto_driver_key_derivation_get_input_bytes()` to make a copy of the input data (design note: [why a copy?](#key-derivation-inputs-and-buffer-ownership)).
+* `PSA_KEY_DERIVATION_INPUT_TYPE_KEY`: the step is valid and present and is a byte string passed via a key object. Call `psa_crypto_driver_key_derivation_get_input_key()` to obtain a pointer to the key context.
+* `PSA_KEY_DERIVATION_INPUT_TYPE_INTEGER`: the step is valid and present and is an integer. Call `psa_crypto_driver_key_derivation_get_input_integer()` to retrieve the integer value.
+
+```
+psa_status_t psa_crypto_driver_key_derivation_get_input_size(
+ const psa_crypto_driver_key_derivation_inputs_t *inputs,
+ psa_key_derivation_step_t step,
+ size_t *size);
+psa_status_t psa_crypto_driver_key_derivation_get_input_bytes(
+ const psa_crypto_driver_key_derivation_inputs_t *inputs,
+ psa_key_derivation_step_t step,
+ uint8_t *buffer, size_t buffer_size, size_t *buffer_length);
+psa_status_t psa_crypto_driver_key_derivation_get_input_key(
+ const psa_crypto_driver_key_derivation_inputs_t *inputs,
+ psa_key_derivation_step_t step,
+ const psa_key_attributes_t *attributes,
+ uint8_t** p_key_buffer, size_t *key_buffer_size);
+psa_status_t psa_crypto_driver_key_derivation_get_input_integer(
+ const psa_crypto_driver_key_derivation_inputs_t *inputs,
+ psa_key_derivation_step_t step,
+ uint64_t *value);
+```
+
+The get-data functions take the following parameters:
+
+* The first parameter `inputs` must be a pointer passed by the core to a key derivation driver setup entry point which has not returned yet.
+* The `step` parameter indicates the input step whose content the driver wants to retrieve.
+* On a successful invocation of `psa_crypto_driver_key_derivation_get_input_size`, the core sets `*size` to the size of the specified input in bytes.
+* On a successful invocation of `psa_crypto_driver_key_derivation_get_input_bytes`, the core fills the first *N* bytes of `buffer` with the specified input and sets `*buffer_length` to *N*, where *N* is the length of the input in bytes. The value of `buffer_size` must be at least *N*, otherwise this function fails with the status `PSA_ERROR_BUFFER_TOO_SMALL`.
+* On a successful invocation of `psa_crypto_driver_key_derivation_get_input_key`, the core sets `*key_buffer` to a pointer to a buffer containing the key context and `*key_buffer_size` to the size of the key context in bytes. The key context buffer remains valid for the duration of the driver entry point. If the driver needs to access the key context after the current entry point returns, it must make a copy of the key context.
+* On a successful invocation of `psa_crypto_driver_key_derivation_get_input_integer`, the core sets `*value` to the value of the specified input.
+
+These functions can return the following statuses:
+
+* `PSA_SUCCESS`: the call succeeded and the requested value has been copied to the output parameter (`size`, `buffer`, `value` or `p_key_buffer`) and if applicable the size of the value has been written to the applicable parameter (`buffer_length`, `key_buffer_size`).
+* `PSA_ERROR_DOES_NOT_EXIST`: the input step is valid for this particular algorithm, but it is not part of the initial inputs. This is not a fatal error. The driver will receive the input later as a [long input](#key-derivation-driver-long-inputs).
+* `PSA_ERROR_INVALID_ARGUMENT`: the input type is not compatible with this function or was omitted. Call `psa_crypto_driver_key_derivation_get_input_type()` to find out the actual type of this input step. This is not a fatal error and the driver can, for example, subsequently call the appropriate function on the same step.
+* `PSA_ERROR_BUFFER_TOO_SMALL` (`psa_crypto_driver_key_derivation_get_input_bytes` only): the output buffer is too small. This is not a fatal error and the driver can, for example, subsequently call the same function again with a larger buffer. Call `psa_crypto_driver_key_derivation_get_input_size` to obtain the required size.
+* The core may return other errors such as `PSA_ERROR_CORRUPTION_DETECTED` or `PSA_ERROR_COMMUNICATION_FAILURE` to convey implementation-specific error conditions. Portable drivers should treat such conditions as fatal errors.
+
+#### Key derivation driver setup
+
+A key derivation driver must implement the following entry point:
+```
+psa_status_t acme_key_derivation_setup(
+ acme_key_derivation_operation_t *operation,
+ psa_algorithm_t alg,
+ const psa_crypto_driver_key_derivation_inputs_t *inputs);
+```
+
+* `operation` is a zero-initialized operation object.
+* `alg` is the algorithm for the key derivation operation. It does not include a key agreement component.
+* `inputs` is an opaque pointer to the [initial inputs](#key-derivation-driver-initial-inputs) for the key derivation.
+
+#### Key derivation driver long inputs
+
+Some key derivation algorithms take long inputs which it would not be practical to pass in the [initial inputs](#key-derivation-driver-initial-inputs). A driver that implements a key derivation algorithm that takes such inputs must provide a `"key_derivation_input_step"` entry point. The core calls this entry point for all the long inputs after calling `"acme_key_derivation_setup"`. A long input step may be fragmented into multiple calls of `psa_key_derivation_input_bytes()`, and the core may reassemble or refragment those fragments before passing them to the driver. Calls to this entry point for different step values occur in an unspecified order and may be interspersed.
+
+```
+psa_status_t acme_key_derivation_input_step(
+ acme_key_derivation_operation_t *operation,
+ psa_key_derivation_step_t step,
+ const uint8_t *input, size_t input_length);
+```
+
+At the time of writing, no standard key derivation algorithm has long inputs. It is likely that such algorithms will be added in the future.
+
+#### Key derivation driver operation capacity
+
+The core keeps track of an operation's capacity and enforces it. The core guarantees that it will not request output beyond the capacity of the operation, with one exception: opaque drivers that support [`"key_derivation_output_key"`](#key-derivation-driver-outputs), i.e. for key types where the derived key material is not a direct copy of the key derivation's output stream.
+
+Such drivers must enforce the capacity limitation and must return `PSA_ERROR_INSUFFICIENT_CAPACITY` from any output request that exceeds the operation's capacity. Such drivers must provide the following entry point:
+```
+psa_status_t acme_key_derivation_set_capacity(
+ acme_key_derivation_operation_t *operation,
+ size_t capacity);
+```
+`capacity` is guaranteed to be less or equal to any value previously set through this entry point, and is guaranteed not to be `PSA_KEY_DERIVATION_UNLIMITED_CAPACITY`.
+
+If this entry point has not been called, the operation has an unlimited capacity.
+
+#### Key derivation driver outputs
+
+A key derivation driver must provide the following entry point:
+```
+psa_status_t acme_key_derivation_output_bytes(
+ acme_key_derivation_operation_t *operation,
+ uint8_t *output, size_t length);
+```
+
+An opaque key derivation driver may provide the following entry points:
+```
+psa_status_t acme_key_derivation_output_key(
+ const psa_key_attributes_t *attributes,
+ acme_key_derivation_operation_t *operation,
+ uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length);
+psa_status_t acme_key_derivation_verify_bytes(
+ acme_key_derivation_operation_t *operation,
+ const uint8_t *expected output, size_t length);
+psa_status_t acme_key_derivation_verify_key(
+ acme_key_derivation_operation_t *operation,
+ uint8_t *key_buffer, size_t key_buffer_size);
+```
+
+The core calls a key derivation driver's output entry point when the application calls `psa_key_derivation_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()`.
+
+If the key derivation's `PSA_KEY_DERIVATION_INPUT_SECRET` input is in a secure element and the derivation operation is handled by that secure element, the core performs the following steps:
+
+* For a call to `psa_key_derivation_output_key()`:
+
+ 1. If the derived key is in the same secure element, if the driver has an `"key_derivation_output_key"` entry point, call that entry point. If the driver has no such entry point, or if that entry point returns `PSA_ERROR_NOT_SUPPORTED`, continue with the following steps, otherwise stop.
+ 1. If the driver's capabilities indicate that its `"import_key"` entry point does not support the derived key, stop and return `PSA_ERROR_NOT_SUPPORTED`.
+ 1. Otherwise proceed as for `psa_key_derivation_output_bytes()`, then import the resulting key material.
+
+* For a call to `psa_key_derivation_verify_key()`:
+ 1. If the driver has a `"key_derivation_verify_key"` entry point, call it and stop.
+ 1. Call the driver's `"export_key"` entry point on the key object that contains the expected value, then proceed as for `psa_key_derivation_verify_bytes()`.
+
+* For a call to `psa_key_derivation_verify_bytes()`:
+ 1. If the driver has a `"key_derivation_verify_bytes"` entry point, call that entry point on the expected output, then stop.
+ 1. Otherwise, proceed as for `psa_key_derivation_output_bytes()`, and compare the resulting output to the expected output inside the core.
+
+* For a call to `psa_key_derivation_output_bytes()`:
+ 1. Call the `"key_derivation_output_bytes"` entry point. The core may call this entry point multiple times to implement a single call from the application when deriving a cooked (non-raw) key as described below, or if the output size exceeds some implementation limit.
+
+If the key derivation operation is not handled by an opaque driver as described above, the core calls the `"key_derivation_output_bytes"` from the applicable transparent driver (or multiple drivers in succession if fallback applies). In some cases, the core then calls additional entry points in the same or another driver:
+
+* For a call to `psa_key_derivation_output_key()` for some key types, the core calls a transparent driver's `"derive_key"` entry point. See [“Transparent cooked key derivation”](#transparent-cooked-key-derivation).
+* For a call to `psa_key_derivation_output_key()` where the derived key is in a secure element, call that secure element driver's `"import_key"` entry point.
+
+#### Transparent cooked key derivation
+
+Key derivation is said to be *raw* for some key types, where the key material of a derived (8×*n*)-bit key consists of the next *n* bytes of output from the key derivation, and *cooked* otherwise. When deriving a raw key, the core only calls the driver's `"output_bytes"` entry point, except when deriving a key entirely inside a secure element as described in [“Key derivation driver outputs”](#key-derivation-driver-outputs). When deriving a cooked key, the core calls a transparent driver's `"derive_key"` entry point if available.
+
+A capability for cooked key derivation contains the following properties (this is not a subset of [the usual entry point properties](#capability-syntax)):
+
+* `"entry_points"` (mandatory, list of strings). Must be `["derive_key"]`.
+* `"derived_types"` (mandatory, list of strings). Each element is a [key type specification](#key-type-specifications). This capability only applies when deriving a key of the specified type.
+* `"derived_sizes"` (optional, list of integers). Each element is a size for the derived key, in bits. This capability only applies when deriving a key of the specified sizes. If absent, this capability applies to all sizes for the specified types.
+* `"memory"` (optional, boolean). If present and true, the driver must define a type `"derive_key_memory_t"` and the core will allocate an object of that type as specified below.
+* `"names"` (optional, object). A mapping from entry point names to C function and type names, as usual.
+* `"fallback"` (optional, boolean). If present and true, the driver may return `PSA_ERROR_NOT_SUPPORTED` if it only partially supports the specified mechanism, as usual.
+
+A transparent driver with the prefix `"acme"` that implements cooked key derivation must provide the following type and function:
+
+```
+typedef ... acme_derive_key_memory_t; // only if the "memory" property is true
+psa_status_t acme_derive_key(
+ const psa_key_attributes_t *attributes,
+ const uint8_t *input, size_t input_length,
+ acme_derive_key_memory_t *memory, // if the "memory" property is false: void*
+ uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length);
+```
+
+* `attributes` contains the attributes of the specified key. Note that only the key type and the bit-size are guaranteed to be set.
+* `input` is a buffer of `input_length` bytes which contains the raw key stream, i.e. the data that `psa_key_derivation_output_bytes()` would return.
+* If `"memory"` property in the driver capability is true, `memory` is a data structure that the driver may use to store data between successive calls of the `"derive_key"` entry point to derive the same key. If the `"memory"` property is false or absent, the `memory` parameter is a null pointer.
+* `key_buffer` is a buffer for the output material, in the appropriate [export format](#key-format-for-transparent-drivers) for the key type. Its size is `key_buffer_size` bytes.
+* On success, `*key_buffer_length` must contain the number of bytes written to `key_buffer`.
+
+This entry point may return the following statuses:
+
+* `PSA_SUCCESS`: a key was derived successfully. The driver has placed the representation of the key in `key_buffer`.
+* `PSA_ERROR_NOT_SUPPORTED` (for the first call only) (only if fallback is enabled): the driver cannot fulfill this request, but a fallback driver might.
+* `PSA_ERROR_INSUFFICIENT_DATA`: the core must call the `"derive_key"` entry point again with the same `memory` object and with subsequent data from the key stream.
+* Any other error is a fatal error.
+
+The core calls the `"derive_key"` entry point in a loop until it returns a status other than `PSA_ERROR_INSUFFICIENT_DATA`. Each call has a successive fragment of the key stream. The `memory` object is guaranteed to be the same for successive calls, but note that its address may change between calls. Before the first call, `*memory` is initialized to all-bits-zero.
+
+For standard key types, the `"derive_key"` entry point is called with a certain input length as follows:
+
+* `PSA_KEY_TYPE_DES`: the length of the key.
+* `PSA_KEY_TYPE_ECC_KEY_PAIR(…)`, `PSA_KEY_TYPE_DH_KEY_PAIR(…)`: $m$ bytes, where the bit-size of the key $n$ satisfies $8 (m-1) < n \le 8 m$.
+* `PSA_KEY_TYPE_RSA_KEY_PAIR`: an implementation-defined length. A future version of this specification may specify a length.
+* Other key types: not applicable.
+
+See [“Open questions around cooked key derivation”](#open-questions-around-cooked-key-derivation) for some points that may not be fully settled.
+
+#### Key agreement
+
+The core always decouples key agreement from symmetric key derivation.
+
+To implement a call to `psa_key_derivation_key_agreement()` where the private key is in a secure element that has a `"key_agreement_to_key"` entry point which is applicable for the given key type and algorithm, the core calls the secure element driver as follows:
+
+1. Call the `"key_agreement_to_key"` entry point to create a key object containing the shared secret. The key object is volatile and has the type `PSA_KEY_TYPE_DERIVE`.
+2. Call the `"key_derivation_setup"` entry point, passing the resulting key object .
+3. Perform the rest of the key derivation, up to and including the call to the `"key_derivation_abort"` entry point.
+4. Call the `"destroy_key"` entry point to destroy the key containing the key object.
+
+In other cases, the core treats `psa_key_derivation_key_agreement()` as if it was a call to `psa_raw_key_agreement()` followed by a call to `psa_key_derivation_input_bytes()` on the shared secret.
+
+The entry points related to key agreement have the following prototypes for a driver with the prefix `"acme"`:
+```
+psa_status_t acme_key_agreement(psa_algorithm_t alg,
+ const psa_key_attributes_t *our_attributes,
+ const uint8_t *our_key_buffer,
+ size_t our_key_buffer_length,
+ const uint8_t *peer_key,
+ size_t peer_key_length,
+ uint8_t *output,
+ size_t output_size,
+ size_t *output_length);
+psa_status_t acme_key_agreement_to_key(psa_algorithm_t alg,
+ const psa_key_attributes_t *our_attributes,
+ const uint8_t *our_key_buffer,
+ size_t our_key_buffer_length,
+ const uint8_t *peer_key,
+ size_t peer_key_length,
+ const psa_key_attributes_t *shared_secret_attributes,
+ uint8_t *shared_secret_key_buffer,
+ size_t shared_secret_key_buffer_size,
+ size_t *shared_secret_key_buffer_length);
+```
+
+Note that unlike most other key creation entry points, in `"acme_key_agreement_to_key"`, the attributes for the shared secret are not placed near the beginning, but rather grouped with the other parameters related to the shared secret at the end of the parameter list. This is to avoid potential confusion with the attributes of the private key that is passed as an input.
+
+### Driver entry points for PAKE
+
+A PAKE operation is divided into two stages: collecting inputs and computation. Core side is responsible for keeping inputs and core set-data functions do not have driver entry points. Collected inputs are available for drivers via get-data functions for `password`, `role` and `cipher_suite`.
+
+### PAKE driver dispatch logic
+The core decides whether to dispatch a PAKE operation to a driver based on the location of the provided password.
+When all inputs are collected and `"psa_pake_output"` or `"psa_pake_input"` is called for the first time `"pake_setup"` driver entry point is invoked.
+
+1. If the location of the `password` is the local storage
+- if there is a transparent driver for the specified ciphersuite, the core calls that driver's `"pake_setup"` and subsequent entry points.
+- otherwise, or on fallback, the core uses its built-in implementation.
+2. If the location of the `password` is the location of a secure element
+- the core calls the `"pake_setup"` entry point of the secure element driver and subsequent entry points.
+
+### Summary of entry points for PAKE
+
+A PAKE driver has the following entry points:
+* `"pake_setup"` (mandatory): always the first entry point to be called. It is called when all inputs are collected and the computation stage starts.
+* `"pake_output"` (mandatory): derive cryptographic material for the specified step and output it.
+* `"pake_input"` (mandatory): provides cryptographic material in the format appropriate for the specified step.
+* `"pake_get_implicit_key"` (mandatory): returns implicitly confirmed shared secret from a PAKE.
+* `"pake_abort"` (mandatory): always the last entry point to be called.
+
+For naming purposes, here and in the following subsection, this specification takes the example of a driver with the prefix `"acme"` that implements the PAKE entry point family with a capability that does not use the `"names"` property to declare different type and entry point names. Such a driver must implement the following type and functions, as well as the entry points listed above and described in the following subsections:
+```
+typedef ... acme_pake_operation_t;
+psa_status_t acme_pake_abort( acme_pake_operation_t *operation );
+```
+
+#### PAKE driver inputs
+
+The core conveys the initial inputs for a PAKE operation via an opaque data structure of type `psa_crypto_driver_pake_inputs_t`.
+
+```
+typedef ... psa_crypto_driver_pake_inputs_t; // implementation-specific type
+```
+
+A driver receiving an argument that points to a `psa_crypto_driver_pake_inputs_t` can retrieve its contents by calling one of the get-data functions below.
+
+```
+psa_status_t psa_crypto_driver_pake_get_password_len(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ size_t *password_len);
+
+psa_status_t psa_crypto_driver_pake_get_password_bytes(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ uint8_t *buffer, size_t buffer_size, size_t *buffer_length);
+
+psa_status_t psa_crypto_driver_pake_get_password_key(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ uint8_t** p_key_buffer, size_t *key_buffer_size,
+ const psa_key_attributes_t *attributes);
+
+psa_status_t psa_crypto_driver_pake_get_user_len(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ size_t *user_len);
+
+psa_status_t psa_crypto_driver_pake_get_user(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ uint8_t *user_id, size_t user_id_size, size_t *user_id_len);
+
+psa_status_t psa_crypto_driver_pake_get_peer_len(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ size_t *peer_len);
+
+psa_status_t psa_crypto_driver_pake_get_peer(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ uint8_t *peer_id, size_t peer_id_size, size_t *peer_id_length);
+
+psa_status_t psa_crypto_driver_pake_get_cipher_suite(
+ const psa_crypto_driver_pake_inputs_t *inputs,
+ psa_pake_cipher_suite_t *cipher_suite);
+```
+The get-data functions take the following parameters:
+
+The first parameter `inputs` must be a pointer passed by the core to a PAKE driver setup entry point.
+Next parameters are return buffers (must not be null pointers).
+
+These functions can return the following statuses:
+* `PSA_SUCCESS`: value has been successfully obtained
+* `PSA_ERROR_BAD_STATE`: the inputs are not ready
+* `PSA_ERROR_BUFFER_TOO_SMALL` (`psa_crypto_driver_pake_get_password_bytes` and `psa_crypto_driver_pake_get_password_key` only): the output buffer is too small. This is not a fatal error and the driver can, for example, subsequently call the same function again with a larger buffer. Call `psa_crypto_driver_pake_get_password_len` to obtain the required size.
+
+#### PAKE driver setup
+
+```
+psa_status_t acme_pake_setup( acme_pake_operation_t *operation,
+ const psa_crypto_driver_pake_inputs_t *inputs );
+```
+
+* `operation` is a zero-initialized operation object.
+* `inputs` is an opaque pointer to the [inputs](#pake-driver-inputs) for the PAKE operation.
+
+The setup driver function should preserve the inputs using get-data functions.
+
+The pointer output by `psa_crypto_driver_pake_get_password_key` is only valid until the "pake_setup" entry point returns. Opaque drivers must copy all relevant data from the key buffer during the "pake_setup" entry point and must not store the pointer itself.
+
+#### PAKE driver output
+
+```
+psa_status_t acme_pake_output(acme_pake_operation_t *operation,
+ psa_crypto_driver_pake_step_t step,
+ uint8_t *output,
+ size_t output_size,
+ size_t *output_length);
+```
+
+* `operation` is an operation object.
+* `step` computation step based on which driver should perform an action.
+* `output` buffer where the output is to be written.
+* `output_size` size of the output buffer in bytes.
+* `output_length` the number of bytes of the returned output.
+
+For `PSA_ALG_JPAKE` the following steps are available for output operation:
+`step` can be one of the following values:
+* `PSA_JPAKE_X1_STEP_KEY_SHARE` Round 1: output our key share (for ephemeral private key X1)
+* `PSA_JPAKE_X1_STEP_ZK_PUBLIC` Round 1: output Schnorr NIZKP public key for the X1 key
+* `PSA_JPAKE_X1_STEP_ZK_PROOF` Round 1: output Schnorr NIZKP proof for the X1 key
+* `PSA_JPAKE_X2_STEP_KEY_SHARE` Round 1: output our key share (for ephemeral private key X2)
+* `PSA_JPAKE_X2_STEP_ZK_PUBLIC` Round 1: output Schnorr NIZKP public key for the X2 key
+* `PSA_JPAKE_X2_STEP_ZK_PROOF` Round 1: output Schnorr NIZKP proof for the X2 key
+* `PSA_JPAKE_X2S_STEP_KEY_SHARE` Round 2: output our X2S key
+* `PSA_JPAKE_X2S_STEP_ZK_PUBLIC` Round 2: output Schnorr NIZKP public key for the X2S key
+* `PSA_JPAKE_X2S_STEP_ZK_PROOF` Round 2: output Schnorr NIZKP proof for the X2S key
+
+#### PAKE driver input
+```
+psa_status_t acme_pake_input(acme_pake_operation_t *operation,
+ psa_crypto_driver_pake_step_t step,
+ uint8_t *input,
+ size_t input_size);
+```
+
+* `operation` is an operation object.
+* `step` computation step based on which driver should perform an action.
+* `input` buffer containing the input.
+* `input_length` length of the input in bytes.
+
+For `PSA_ALG_JPAKE` the following steps are available for input operation:
+* `PSA_JPAKE_X1_STEP_KEY_SHARE` Round 1: input key share from peer (for ephemeral private key X1)
+* `PSA_JPAKE_X1_STEP_ZK_PUBLIC` Round 1: input Schnorr NIZKP public key for the X1 key
+* `PSA_JPAKE_X1_STEP_ZK_PROOF` Round 1: input Schnorr NIZKP proof for the X1 key
+* `PSA_JPAKE_X2_STEP_KEY_SHARE` Round 1: input key share from peer (for ephemeral private key X2)
+* `PSA_JPAKE_X2_STEP_ZK_PUBLIC` Round 1: input Schnorr NIZKP public key for the X2 key
+* `PSA_JPAKE_X2_STEP_ZK_PROOF` Round 1: input Schnorr NIZKP proof for the X2 key
+* `PSA_JPAKE_X4S_STEP_KEY_SHARE` Round 2: input X4S key from peer
+* `PSA_JPAKE_X4S_STEP_ZK_PUBLIC` Round 2: input Schnorr NIZKP public key for the X4S key
+* `PSA_JPAKE_X4S_STEP_ZK_PROOF` Round 2: input Schnorr NIZKP proof for the X4S key
+
+The core checks that `input_length` is not greater than `PSA_PAKE_INPUT_SIZE(alg, prim, step)` and
+the driver can rely on that.
+
+### PAKE driver get implicit key
+
+```
+psa_status_t acme_pake_get_implicit_key(
+ acme_pake_operation_t *operation,
+ uint8_t *output, size_t output_size,
+ size_t *output_length );
+```
+
+* `operation` The driver PAKE operation object to use.
+* `output` Buffer where the implicit key is to be written.
+* `output_size` Size of the output buffer in bytes.
+* `output_length` On success, the number of bytes of the implicit key.
+
+### Driver entry points for key management
+
+The driver entry points for key management differ significantly between [transparent drivers](#key-management-with-transparent-drivers) and [opaque drivers](#key-management-with-opaque-drivers). This section describes common elements. Refer to the applicable section for each driver type for more information.
+
+The entry points that create or format key data have the following prototypes for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_import_key(const psa_key_attributes_t *attributes,
+ const uint8_t *data,
+ size_t data_length,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length,
+ size_t *bits); // additional parameter, see below
+psa_status_t acme_generate_key(const psa_key_attributes_t *attributes,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length);
+```
+Additionally, opaque drivers can create keys through their [`"key_derivation_output_key"`](#key-derivation-driver-outputs) and [`"key_agreement_key"`](#key-agreement) entry points. Transparent drivers can create key material through their [`"derive_key"`](#transparent-cooked-key-derivation) entry point.
+
+TODO: copy
+
+* The key attributes (`attributes`) have the same semantics as in the PSA Cryptography application interface.
+* For the `"import_key"` entry point, the input in the `data` buffer is either the export format or an implementation-specific format that the core documents as an acceptable input format for `psa_import_key()`.
+* The size of the key data buffer `key_buffer` is sufficient for the internal representation of the key. For a transparent driver, this is the key's [export format](#key-format-for-transparent-drivers). For an opaque driver, this is the size determined from the driver description and the key attributes, as specified in the section [“Key format for opaque drivers”](#key-format-for-opaque-drivers).
+* For an opaque driver with an `"allocate_key"` entry point, the content of the key data buffer on entry is the output of that entry point.
+* The `"import_key"` entry point must determine or validate the key size and set `*bits` as described in the section [“Key size determination on import”](#key-size-determination-on-import) below.
+
+All key creation entry points must ensure that the resulting key is valid as specified in the section [“Key validation”](#key-validation) below. This is primarily important for import entry points since the key data comes from the application.
+
+#### Key size determination on import
+
+The `"import_key"` entry point must determine or validate the key size.
+The PSA Cryptography API exposes the key size as part of the key attributes.
+When importing a key, the key size recorded in the key attributes can be either a size specified by the caller of the API (who may not be trusted), or `0` which indicates that the size must be calculated from the data.
+
+When the core calls the `"import_key"` entry point to process a call to `psa_import_key`, it passes an `attributes` structure such that `psa_get_key_bits(attributes)` is the size passed by the caller of `psa_import_key`. If this size is `0`, the `"import_key"` entry point must set the `bits` input-output parameter to the correct key size. The semantics of `bits` is as follows:
+
+* The core sets `*bits` to `psa_get_key_bits(attributes)` before calling the `"import_key"` entry point.
+* If `*bits == 0`, the driver must determine the key size from the data and set `*bits` to this size. If the key size cannot be determined from the data, the driver must return `PSA_ERROR_INVALID_ARGUMENT` (as of version 1.0 of the PSA Cryptography API specification, it is possible to determine the key size for all standard key types).
+* If `*bits != 0`, the driver must check the value of `*bits` against the data and return `PSA_ERROR_INVALID_ARGUMENT` if it does not match. If the driver entry point changes `*bits` to a different value but returns `PSA_SUCCESS`, the core will consider the key as invalid and the import will fail.
+
+#### Key validation
+
+Key creation entry points must produce valid key data. Key data is _valid_ if operations involving the key are guaranteed to work functionally and not to cause indirect security loss. Operation functions are supposed to receive valid keys, and should not have to check and report invalid keys. For example:
+
+* If a cryptographic mechanism is defined as having keying material of a certain size, or if the keying material involves integers that have to be in a certain range, key creation must ensure that the keying material has an appropriate size and falls within an appropriate range.
+* If a cryptographic operation involves a division by an integer which is provided as part of a key, key creation must ensure that this integer is nonzero.
+* If a cryptographic operation involves two keys A and B (or more), then the creation of A must ensure that using it does not risk compromising B. This applies even if A's policy does not explicitly allow a problematic operation, but A is exportable. In particular, public keys that can potentially be used for key agreement are considered invalid and must not be created if they risk compromising the private key.
+* On the other hand, it is acceptable for import to accept a key that cannot be verified as valid if using this key would at most compromise the key itself and material that is secured with this key. For example, RSA key import does not need to verify that the primes are actually prime. Key import may accept an insecure key if the consequences of the insecurity are no worse than a leak of the key prior to its import.
+
+With opaque drivers, the key context can only be used by code from the same driver, so key validity is primarily intended to report key creation errors at creation time rather than during an operation. With transparent drivers, the key context can potentially be used by code from a different provider, so key validity is critical for interoperability.
+
+This section describes some minimal validity requirements for standard key types.
+
+* For symmetric key types, check that the key size is suitable for the type.
+* For DES (`PSA_KEY_TYPE_DES`), additionally verify the parity bits.
+* For RSA (`PSA_KEY_TYPE_RSA_PUBLIC_KEY`, `PSA_KEY_TYPE_RSA_KEY_PAIR`), check the syntax of the key and make sanity checks on its components. TODO: what sanity checks? Value ranges (e.g. p < n), sanity checks such as parity, minimum and maximum size, what else?
+* For elliptic curve private keys (`PSA_KEY_TYPE_ECC_KEY_PAIR`), check the size and range. TODO: what else?
+* For elliptic curve public keys (`PSA_KEY_TYPE_ECC_PUBLIC_KEY`), check the size and range, and that the point is on the curve. TODO: what else?
+
+### Entropy collection entry point
+
+A driver can declare an entropy source by providing a `"get_entropy"` entry point. This entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_get_entropy(uint32_t flags,
+ size_t *estimate_bits,
+ uint8_t *output,
+ size_t output_size);
+```
+
+The semantics of the parameters is as follows:
+
+* `flags`: a bit-mask of [entropy collection flags](#entropy-collection-flags).
+* `estimate_bits`: on success, an estimate of the amount of entropy that is present in the `output` buffer, in bits. This must be at least `1` on success. The value is ignored on failure. Drivers should return a conservative estimate, even in circumstances where the quality of the entropy source is degraded due to environmental conditions (e.g. undervolting, low temperature, etc.).
+* `output`: on success, this buffer contains non-deterministic data with an estimated entropy of at least `*estimate_bits` bits. When the entropy is coming from a hardware peripheral, this should preferably be raw or lightly conditioned measurements from a physical process, such that statistical tests run over a sufficiently large amount of output can confirm the entropy estimates. But this specification also permits entropy sources that are fully conditioned, for example when the PSA Cryptography system is running as an application in an operating system and `"get_entropy"` returns data from the random generator in the operating system's kernel.
+* `output_size`: the size of the `output` buffer in bytes. This size should be large enough to allow a driver to pass unconditioned data with a low density of entropy; for example a peripheral that returns eight bytes of data with an estimated one bit of entropy cannot provide meaningful output in less than 8 bytes.
+
+Note that there is no output parameter indicating how many bytes the driver wrote to the buffer. Such an output length indication is not necessary because the entropy may be located anywhere in the buffer, so the driver may write less than `output_size` bytes but the core does not need to know this. The output parameter `estimate_bits` contains the amount of entropy, expressed in bits, which may be significantly less than `output_size * 8`.
+
+The entry point may return the following statuses:
+
+* `PSA_SUCCESS`: success. The output buffer contains some entropy.
+* `PSA_ERROR_INSUFFICIENT_ENTROPY`: no entropy is available without blocking. This is only permitted if the `PSA_DRIVER_GET_ENTROPY_BLOCK` flag is clear. The core may call `get_entropy` again later, giving time for entropy to be gathered or for adverse environmental conditions to be rectified.
+* Other error codes indicate a transient or permanent failure of the entropy source.
+
+Unlike most other entry points, if multiple transparent drivers include a `"get_entropy"` point, the core will call all of them (as well as the entry points from opaque drivers). Fallback is not applicable to `"get_entropy"`.
+
+#### Entropy collection flags
+
+* `PSA_DRIVER_GET_ENTROPY_BLOCK`: If this flag is set, the driver should block until it has at least one bit of entropy. If this flag is clear, the driver should avoid blocking if no entropy is readily available.
+* `PSA_DRIVER_GET_ENTROPY_KEEPALIVE`: This flag is intended to help with energy management for entropy-generating peripherals. If this flag is set, the driver should expect another call to `acme_get_entropy` after a short time. If this flag is clear, the core is not expecting to call the `"get_entropy"` entry point again within a short amount of time (but it may do so nonetheless).
+
+#### Entropy collection and blocking
+
+The intent of the `BLOCK` and `KEEPALIVE` [flags](#entropy-collection-flags) is to support drivers for TRNG (True Random Number Generator, i.e. an entropy source peripheral) that have a long ramp-up time, especially on platforms with multiple entropy sources.
+
+Here is a suggested call sequence for entropy collection that leverages these flags:
+
+1. The core makes a first round of calls to `"get_entropy"` on every source with the `BLOCK` flag clear and the `KEEPALIVE` flag set, so that drivers can prepare the TRNG peripheral.
+2. The core makes a second round of calls with the `BLOCK` flag set and the `KEEPALIVE` flag clear to gather needed entropy.
+3. If the second round does not collect enough entropy, the core makes more similar rounds, until the total amount of collected entropy is sufficient.
+
+### Miscellaneous driver entry points
+
+#### Driver initialization
+
+A driver may declare an `"init"` entry point in a capability with no algorithm, key type or key size. If so, the core calls this entry point once during the initialization of the PSA Cryptography subsystem. If the init entry point of any driver fails, the initialization of the PSA Cryptography subsystem fails.
+
+When multiple drivers have an init entry point, the order in which they are called is unspecified. It is also unspecified whether other drivers' `"init"` entry points are called if one or more init entry point fails.
+
+On platforms where the PSA Cryptography implementation is a subsystem of a single application, the initialization of the PSA Cryptography subsystem takes place during the call to `psa_crypto_init()`. On platforms where the PSA Cryptography implementation is separate from the application or applications, the initialization of the PSA Cryptography subsystem takes place before or during the first time an application calls `psa_crypto_init()`.
+
+The init entry point does not take any parameter.
+
+### Combining multiple drivers
+
+To declare a cryptoprocessor can handle both cleartext and wrapped keys, you need to provide two driver descriptions, one for a transparent driver and one for an opaque driver. You can use the mapping in capabilities' `"names"` property to arrange for multiple driver entry points to map to the same C function.
+
+## Transparent drivers
+
+### Key format for transparent drivers
+
+The format of a key for transparent drivers is the same as in applications. Refer to the documentation of [`psa_export_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_key) and [`psa_export_public_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_public_key) in the PSA Cryptography API specification. For custom key types defined by an implementation, refer to the documentation of that implementation.
+
+### Key management with transparent drivers
+
+Transparent drivers may provide the following key management entry points:
+
+* [`"import_key"`](#key-import-with-transparent-drivers): called by `psa_import_key()`, only when importing a key pair or a public key (key such that `PSA_KEY_TYPE_IS_ASYMMETRIC` is true).
+* `"generate_key"`: called by `psa_generate_key()`, only when generating a key pair (key such that `PSA_KEY_TYPE_IS_KEY_PAIR` is true).
+* `"key_derivation_output_key"`: called by `psa_key_derivation_output_key()`, only when deriving a key pair (key such that `PSA_KEY_TYPE_IS_KEY_PAIR` is true).
+* `"export_public_key"`: called by the core to obtain the public key of a key pair. The core may call this function at any time to obtain the public key, which can be for `psa_export_public_key()` but also at other times, including during a cryptographic operation that requires the public key such as a call to `psa_verify_message()` on a key pair object.
+
+Transparent drivers are not involved when exporting, copying or destroying keys, or when importing, generating or deriving symmetric keys.
+
+#### Key import with transparent drivers
+
+As discussed in [the general section about key management entry points](#driver-entry-points-for-key-management), the key import entry points has the following prototype for a driver with the prefix `"acme"`:
+```
+psa_status_t acme_import_key(const psa_key_attributes_t *attributes,
+ const uint8_t *data,
+ size_t data_length,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length,
+ size_t *bits);
+```
+
+This entry point has several roles:
+
+1. Parse the key data in the input buffer `data`. The driver must support the export format for the key types that the entry point is declared for. It may support additional formats as specified in the description of [`psa_import_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_key) in the PSA Cryptography API specification.
+2. Validate the key data. The necessary validation is described in the section [“Key validation”](#key-validation) above.
+3. [Determine the key size](#key-size-determination-on-import) and output it through `*bits`.
+4. Copy the validated key data from `data` to `key_buffer`. The output must be in the canonical format documented for [`psa_export_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_key) or [`psa_export_public_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_public_key), so if the input is not in this format, the entry point must convert it.
+
+### Random generation entry points
+
+A transparent driver may provide an operation family that can be used as a cryptographic random number generator. The random generation mechanism must obey the following requirements:
+
+* The random output must be of cryptographic quality, with a uniform distribution. Therefore, if the random generator includes an entropy source, this entropy source must be fed through a CSPRNG (cryptographically secure pseudo-random number generator).
+* Random generation is expected to be fast. (If a device can provide entropy but is slow at generating random data, declare it as an [entropy driver](#entropy-collection-entry-point) instead.)
+* The random generator should be able to incorporate entropy provided by an outside source. If it isn't, the random generator can only be used if it's the only entropy source on the platform. (A random generator peripheral can be declared as an [entropy source](#entropy-collection-entry-point) instead of a random generator; this way the core will combine it with other entropy sources.)
+* The random generator may either be deterministic (in the sense that it always returns the same data when given the same entropy inputs) or non-deterministic (including its own entropy source). In other words, this interface is suitable both for PRNG (pseudo-random number generator, also known as DRBG (deterministic random bit generator)) and for NRBG (non-deterministic random bit generator).
+
+If no driver implements the random generation entry point family, the core provides an unspecified random generation mechanism.
+
+This operation family requires the following type, entry points and parameters (TODO: where exactly are the parameters in the JSON structure?):
+
+* Type `"random_context_t"`: the type of a random generation context.
+* `"init_random"` (entry point, optional): if this function is present, [the core calls it once](#random-generator-initialization) after allocating a `"random_context_t"` object.
+* `"add_entropy"` (entry point, optional): the core calls this function to [inject entropy](#entropy-injection). This entry point is optional if the driver is for a peripheral that includes an entropy source of its own, however [random generator drivers without entropy injection](#random-generator-drivers-without-entropy-injection) have limited portability since they can only be used on platforms with no other entropy source. This entry point is mandatory if `"initial_entropy_size"` is nonzero.
+* `"get_random"` (entry point, mandatory): the core calls this function whenever it needs to [obtain random data](#the-get_random-entry-point).
+* `"initial_entropy_size"` (integer, mandatory): the minimum number of bytes of entropy that the core must supply before the driver can output random data. This can be `0` if the driver is for a peripheral that includes an entropy source of its own.
+* `"reseed_entropy_size"` (integer, optional): the minimum number of bytes of entropy that the core should supply via [`"add_entropy"`](#entropy-injection) when the driver runs out of entropy. This value is also a hint for the size to supply if the core makes additional calls to `"add_entropy"`, for example to enforce prediction resistance. If omitted, the core should pass an amount of entropy corresponding to the expected security strength of the device (for example, pass 32 bytes of entropy when reseeding to achieve a security strength of 256 bits). If specified, the core should pass the larger of `"reseed_entropy_size"` and the amount corresponding to the security strength.
+
+Random generation is not parametrized by an algorithm. The choice of algorithm is up to the driver.
+
+#### Random generator initialization
+
+The `"init_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_init_random(acme_random_context_t *context);
+```
+
+The core calls this entry point once after allocating a random generation context. Initially, the context object is all-bits-zero.
+
+If a driver does not have an `"init_random"` entry point, the context object passed to the first call to `"add_entropy"` or `"get_random"` will be all-bits-zero.
+
+#### Entropy injection
+
+The `"add_entropy"` entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_add_entropy(acme_random_context_t *context,
+ const uint8_t *entropy,
+ size_t entropy_size);
+```
+
+The semantics of the parameters is as follows:
+
+* `context`: a random generation context. On the first call to `"add_entropy"`, this object has been initialized by a call to the driver's `"init_random"` entry point if one is present, and to all-bits-zero otherwise.
+* `entropy`: a buffer containing full-entropy data to seed the random generator. “Full-entropy” means that the data is uniformly distributed and independent of any other observable quantity.
+* `entropy_size`: the size of the `entropy` buffer in bytes. It is guaranteed to be at least `1`, but it may be smaller than the amount of entropy that the driver needs to deliver random data, in which case the core will call the `"add_entropy"` entry point again to supply more entropy.
+
+The core calls this function to supply entropy to the driver. The driver must mix this entropy into its internal state. The driver must mix the whole supplied entropy, even if there is more than what the driver requires, to ensure that all entropy sources are mixed into the random generator state. The driver may mix additional entropy of its own.
+
+The core may call this function at any time. For example, to enforce prediction resistance, the core can call `"add_entropy"` immediately after each call to `"get_random"`. The core must call this function in two circumstances:
+
+* Before the first call to the `"get_random"` entry point, to supply `"initial_entropy_size"` bytes of entropy.
+* After a call to the `"get_random"` entry point returns less than the required amount of random data, to supply at least `"reseed_entropy_size"` bytes of entropy.
+
+When the driver requires entropy, the core can supply it with one or more successive calls to the `"add_entropy"` entry point. If the required entropy size is zero, the core does not need to call `"add_entropy"`.
+
+#### Combining entropy sources with a random generation driver
+
+This section provides guidance on combining one or more [entropy sources](#entropy-collection-entry-point) (each having a `"get_entropy"` entry point) with a random generation driver (with an `"add_entropy"` entry point).
+
+Note that `"get_entropy"` returns data with an estimated amount of entropy that is in general less than the buffer size. The core must apply a mixing algorithm to the output of `"get_entropy"` to obtain full-entropy data.
+
+For example, the core may use a simple mixing scheme based on a pseudorandom function family $(F_k)$ with an $E$-bit output where $E = 8 \cdot \mathtt{entropy_size}$ and $\mathtt{entropy_size}$ is the desired amount of entropy in bytes (typically the random driver's `"initial_entropy_size"` property for the initial seeding and the `"reseed_entropy_size"` property for subsequent reseeding). The core calls the `"get_entropy"` points of the available entropy drivers, outputting a string $s_i$ and an entropy estimate $e_i$ on the $i$th call. It does so until the total entropy estimate $e_1 + e_2 + \ldots + e_n$ is at least $E$. The core then calculates $F_k(0)$ where $k = s_1 || s_2 || \ldots || s_n$. This value is a string of $\mathtt{entropy_size}$, and since $(F_k)$ is a pseudorandom function family, $F_k(0)$ is uniformly distributed over strings of $\mathtt{entropy_size}$ bytes. Therefore $F_k(0)$ is a suitable value to pass to `"add_entropy"`.
+
+Note that the mechanism above is only given as an example. Implementations may choose a different mechanism, for example involving multiple pools or intermediate compression functions.
+
+#### Random generator drivers without entropy injection
+
+Random generator drivers should have the capability to inject additional entropy through the `"add_entropy"` entry point. This ensures that the random generator depends on all the entropy sources that are available on the platform. A driver where a call to `"add_entropy"` does not affect the state of the random generator is not compliant with this specification.
+
+However, a driver may omit the `"add_entropy"` entry point. This limits the driver's portability: implementations of the PSA Cryptography specification may reject drivers without an `"add_entropy"` entry point, or only accept such drivers in certain configurations. In particular, the `"add_entropy"` entry point is required if:
+
+* the integration of PSA Cryptography includes an entropy source that is outside the driver; or
+* the core saves random data in persistent storage to be preserved across platform resets.
+
+#### The `"get_random"` entry point
+
+The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_get_random(acme_random_context_t *context,
+ uint8_t *output,
+ size_t output_size,
+ size_t *output_length);
+```
+
+The semantics of the parameters is as follows:
+
+* `context`: a random generation context. If the driver's `"initial_entropy_size"` property is nonzero, the core must have called `"add_entropy"` at least once with a total of at least `"initial_entropy_size"` bytes of entropy before it calls `"get_random"`. Alternatively, if the driver's `"initial_entropy_size"` property is zero and the core did not call `"add_entropy"`, or if the driver has no `"add_entropy"` entry point, the core must have called `"init_random"` if present, and otherwise the context is all-bits zero.
+* `output`: on success (including partial success), the first `*output_length` bytes of this buffer contain cryptographic-quality random data. The output is not used on error.
+* `output_size`: the size of the `output` buffer in bytes.
+* `*output_length`: on success (including partial success), the number of bytes of random data that the driver has written to the `output` buffer. This is preferably `output_size`, but the driver is allowed to return less data if it runs out of entropy as described below. The core sets this value to 0 on entry. The value is not used on error.
+
+The driver may return the following status codes:
+
+* `PSA_SUCCESS`: the `output` buffer contains `*output_length` bytes of cryptographic-quality random data. Note that this may be less than `output_size`; in this case the core should call the driver's `"add_entropy"` method to supply at least `"reseed_entropy_size"` bytes of entropy before calling `"get_random"` again.
+* `PSA_ERROR_INSUFFICIENT_ENTROPY`: the core must supply additional entropy by calling the `"add_entropy"` entry point with at least `"reseed_entropy_size"` bytes.
+* `PSA_ERROR_NOT_SUPPORTED`: the random generator is not available. This is only permitted if the driver specification for random generation has the [fallback property](#fallback) enabled.
+* Other error codes such as `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permanent error.
+
+### Fallback
+
+Sometimes cryptographic accelerators only support certain cryptographic mechanisms partially. The capability description language allows specifying some restrictions, including restrictions on key sizes, but it cannot cover all the possibilities that may arise in practice. Furthermore, it may be desirable to deploy the same binary image on different devices, only some of which have a cryptographic accelerators.
+For these purposes, a transparent driver can declare that it only supports a [capability](#driver-description-capability) partially, by setting the capability's `"fallback"` property to true.
+
+If a transparent driver entry point is part of a capability which has a true `"fallback"` property and returns `PSA_ERROR_NOT_SUPPORTED`, the core will call the next transparent driver that supports the mechanism, if there is one. The core considers drivers in the order given by the [driver description list](#driver-description-list).
+
+If all the available drivers have fallback enabled and return `PSA_ERROR_NOT_SUPPORTED`, the core will perform the operation using built-in code.
+As soon as a driver returns any value other than `PSA_ERROR_NOT_SUPPORTED` (`PSA_SUCCESS` or a different error code), this value is returned to the application, without attempting to call any other driver or built-in code.
+
+If a transparent driver entry point is part of a capability where the `"fallback"` property is false or omitted, the core should not include any other code for this capability, whether built in or in another transparent driver.
+
+## Opaque drivers
+
+Opaque drivers allow a PSA Cryptography implementation to delegate cryptographic operations to a separate environment that might not allow exporting key material in cleartext. The opaque driver interface is designed so that the core never inspects the representation of a key. The opaque driver interface is designed to support two subtypes of cryptoprocessors:
+
+* Some cryptoprocessors do not have persistent storage for individual keys. The representation of a key is the key material wrapped with a master key which is located in the cryptoprocessor and never exported from it. The core stores this wrapped key material on behalf of the cryptoprocessor.
+* Some cryptoprocessors have persistent storage for individual keys. The representation of a key is an identifier such as label or slot number. The core stores this identifier.
+
+### Key format for opaque drivers
+
+The format of a key for opaque drivers is an opaque blob. The content of this blob is fully up to the driver. The core merely stores this blob.
+
+Note that since the core stores the key context blob as it is in memory, it must only contain data that is meaningful after a reboot. In particular, it must not contain any pointers or transient handles.
+
+The `"key_context"` property in the [driver description](#driver-description-top-level-element) specifies how to calculate the size of the key context as a function of the key type and size. This is an object with the following properties:
+
+* `"base_size"` (integer or string, optional): this many bytes are included in every key context. If omitted, this value defaults to 0.
+* `"key_pair_size"` (integer or string, optional): this many bytes are included in every key context for a key pair. If omitted, this value defaults to 0.
+* `"public_key_size"` (integer or string, optional): this many bytes are included in every key context for a public key. If omitted, this value defaults to 0.
+* `"symmetric_factor"` (integer or string, optional): every key context for a symmetric key includes this many times the key size. If omitted, this value defaults to 0.
+* `"store_public_key"` (boolean, optional): If specified and true, for a key pair, the key context includes space for the public key. If omitted or false, no additional space is added for the public key.
+* `"size_function"` (string, optional): the name of a function that returns the number of bytes that the driver needs in a key context for a key. This may be a pointer to function. This must be a C identifier; more complex expressions are not permitted. If the core uses this function, it supersedes all the other properties except for `"builtin_key_size"` (where applicable, if present).
+* `"builtin_key_size"` (integer or string, optional): If specified, this overrides all other methods (including the `"size_function"` entry point) to determine the size of the key context for [built-in keys](#built-in-keys). This allows drivers to efficiently represent application keys as wrapped key material, but built-in keys by an internal identifier that takes up less space.
+
+The integer properties must be C language constants. A typical value for `"base_size"` is `sizeof(acme_key_context_t)` where `acme_key_context_t` is a type defined in a driver header file.
+
+#### Size of a dynamically allocated key context
+
+If the core supports dynamic allocation for the key context and chooses to use it, and the driver specification includes the `"size_function"` property, the size of the key context is at least
+```
+size_function(key_type, key_bits)
+```
+where `size_function` is the function named in the `"size_function"` property, `key_type` is the key type and `key_bits` is the key size in bits. The prototype of the size function is
+```
+size_t size_function(psa_key_type_t key_type, size_t key_bits);
+```
+
+#### Size of a statically allocated key context
+
+If the core does not support dynamic allocation for the key context or chooses not to use it, or if the driver specification does not include the `"size_function"` property, the size of the key context for a key of type `key_type` and of size `key_bits` bits is:
+
+* For a key pair (`PSA_KEY_TYPE_IS_KEY_PAIR(key_type)` is true):
+ ```
+ base_size + key_pair_size + public_key_overhead
+ ```
+ where `public_key_overhead = PSA_EXPORT_PUBLIC_KEY_MAX_SIZE(key_type, key_bits)` if the `"store_public_key"` property is true and `public_key_overhead = 0` otherwise.
+
+* For a public key (`PSA_KEY_TYPE_IS_PUBLIC_KEY(key_type)` is true):
+ ```
+ base_size + public_key_size
+ ```
+
+* For a symmetric key (not a key pair or public key):
+ ```
+ base_size + symmetric_factor * key_bytes
+ ```
+ where `key_bytes = ((key_bits + 7) / 8)` is the key size in bytes.
+
+#### Key context size for a secure element with storage
+
+If the key is stored in the secure element and the driver only needs to store a label for the key, use `"base_size"` as the size of the label plus any other metadata that the driver needs to store, and omit the other properties.
+
+If the key is stored in the secure element, but the secure element does not store the public part of a key pair and cannot recompute it on demand, additionally use the `"store_public_key"` property with the value `true`. Note that this only influences the size of the key context: the driver code must copy the public key to the key context and retrieve it on demand in its `export_public_key` entry point.
+
+#### Key context size for a secure element without storage
+
+If the key is stored in wrapped form outside the secure element, and the wrapped form of the key plus any metadata has up to *N* bytes of overhead, use *N* as the value of the `"base_size"` property and set the `"symmetric_factor"` property to 1. Set the `"key_pair_size"` and `"public_key_size"` properties appropriately for the largest supported key pair and the largest supported public key respectively.
+
+### Key management with opaque drivers
+
+Opaque drivers may provide the following key management entry points:
+
+* `"export_key"`: called by `psa_export_key()`, or by `psa_copy_key()` when copying a key from or to a different [location](#lifetimes-and-locations), or [as a fallback for key derivation](#key-derivation-driver-dispatch-logic).
+* `"export_public_key"`: called by the core to obtain the public key of a key pair. The core may call this entry point at any time to obtain the public key, which can be for `psa_export_public_key()` but also at other times, including during a cryptographic operation that requires the public key such as a call to `psa_verify_message()` on a key pair object.
+* `"import_key"`: called by `psa_import_key()`, or by `psa_copy_key()` when copying a key from another location.
+* `"generate_key"`: called by `psa_generate_key()`.
+* `"key_derivation_output_key"`: called by `psa_key_derivation_output_key()`.
+* `"copy_key"`: called by `psa_copy_key()` when copying a key within the same [location](#lifetimes-and-locations).
+* `"get_builtin_key"`: called by functions that access a key to retrieve information about a [built-in key](#built-in-keys).
+
+In addition, secure elements that store the key material internally must provide the following two entry points:
+
+* `"allocate_key"`: called by `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()` or `psa_copy_key()` before creating a key in the location of this driver.
+* `"destroy_key"`: called by `psa_destroy_key()`.
+
+#### Key creation in a secure element without storage
+
+This section describes the key creation process for secure elements that do not store the key material. The driver must obtain a wrapped form of the key material which the core will store. A driver for such a secure element has no `"allocate_key"` or `"destroy_key"` entry point.
+
+When creating a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"` entry point:
+
+1. The core allocates memory for the key context.
+2. The core calls the driver's import, generate, derive or copy entry point.
+3. The core saves the resulting wrapped key material and any other data that the key context may contain.
+
+To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
+
+#### Key management in a secure element with storage
+
+This section describes the key creation and key destruction processes for secure elements that have persistent storage for the key material. A driver for such a secure element has two mandatory entry points:
+
+* `"allocate_key"`: this function obtains an internal identifier for the key. This may be, for example, a unique label or a slot number.
+* `"destroy_key"`: this function invalidates the internal identifier and destroys the associated key material.
+
+These functions have the following prototypes for a driver with the prefix `"acme"`:
+```
+psa_status_t acme_allocate_key(const psa_key_attributes_t *attributes,
+ uint8_t *key_buffer,
+ size_t key_buffer_size);
+psa_status_t acme_destroy_key(const psa_key_attributes_t *attributes,
+ const uint8_t *key_buffer,
+ size_t key_buffer_size);
+```
+
+When creating a persistent key with an opaque driver which has an `"allocate_key"` entry point:
+
+1. The core calls the driver's `"allocate_key"` entry point. This function typically allocates an internal identifier for the key without modifying the state of the secure element and stores the identifier in the key context. This function should not modify the state of the secure element. It may modify the copy of the persistent state of the driver in memory.
+
+1. The core saves the key context to persistent storage.
+
+1. The core calls the driver's key creation entry point.
+
+1. The core saves the updated key context to persistent storage.
+
+If a failure occurs after the `"allocate_key"` step but before the call to the second driver entry point, the core will do one of the following:
+
+* Fail the creation of the key without indicating this to the driver. This can happen, in particular, if the device loses power immediately after the key allocation entry point returns.
+* Call the driver's `"destroy_key"` entry point.
+
+To destroy a key, the core calls the driver's `"destroy_key"` entry point.
+
+Note that the key allocation and destruction entry points must not rely solely on the key identifier in the key attributes to identify a key. Some implementations of the PSA Cryptography API store keys on behalf of multiple clients, and different clients may use the same key identifier to designate different keys. The manner in which the core distinguishes keys that have the same identifier but are part of the key namespace for different clients is implementation-dependent and is not accessible to drivers. Some typical strategies to allocate an internal key identifier are:
+
+* Maintain a set of free slot numbers which is stored either in the secure element or in the driver's persistent storage. To allocate a key slot, find a free slot number, mark it as occupied and store the number in the key context. When the key is destroyed, mark the slot number as free.
+* Maintain a monotonic counter with a practically unbounded range in the secure element or in the driver's persistent storage. To allocate a key slot, increment the counter and store the current value in the key context. Destroying a key does not change the counter.
+
+TODO: explain constraints on how the driver updates its persistent state for resilience
+
+TODO: some of the above doesn't apply to volatile keys
+
+#### Key creation entry points in opaque drivers
+
+The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_import_key(const psa_key_attributes_t *attributes,
+ const uint8_t *data,
+ size_t data_length,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length,
+ size_t *bits);
+psa_status_t acme_generate_key(const psa_key_attributes_t *attributes,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length);
+```
+
+If the driver has an [`"allocate_key"` entry point](#key-management-in-a-secure-element-with-storage), the core calls the `"allocate_key"` entry point with the same attributes on the same key buffer before calling the key creation entry point.
+
+TODO: derivation, copy
+
+#### Key export entry points in opaque drivers
+
+The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_export_key(const psa_key_attributes_t *attributes,
+ const uint8_t *key_buffer,
+ size_t key_buffer_size,
+ uint8_t *data,
+ size_t data_size,
+ size_t *data_length);
+psa_status_t acme_export_public_key(const psa_key_attributes_t *attributes,
+ const uint8_t *key_buffer,
+ size_t key_buffer_size,
+ uint8_t *data,
+ size_t data_size,
+ size_t *data_length);
+```
+
+The core will only call `acme_export_public_key` on a private key. Drivers implementers may choose to store the public key in the key context buffer or to recalculate it on demand. If the key context includes the public key, it needs to have an adequate size; see [“Key format for opaque drivers”](#key-format-for-opaque-drivers).
+
+The core guarantees that the size of the output buffer (`data_size`) is sufficient to export any key with the given attributes. The driver must set `*data_length` to the exact size of the exported key.
+
+### Opaque driver persistent state
+
+The core maintains persistent state on behalf of an opaque driver. This persistent state consists of a single byte array whose size is given by the `"persistent_state_size"` property in the [driver description](#driver-description-top-level-element).
+
+The core loads the persistent state in memory before it calls the driver's [init entry point](#driver-initialization). It is adjusted to match the size declared by the driver, in case a driver upgrade changes the size:
+
+* The first time the driver is loaded on a system, the persistent state is all-bits-zero.
+* If the stored persistent state is smaller than the declared size, the core pads the persistent state with all-bits-zero at the end.
+* If the stored persistent state is larger than the declared size, the core truncates the persistent state to the declared size.
+
+The core provides the following callback functions, which an opaque driver may call while it is processing a call from the driver:
+```
+psa_status_t psa_crypto_driver_get_persistent_state(uint_8_t **persistent_state_ptr);
+psa_status_t psa_crypto_driver_commit_persistent_state(size_t from, size_t length);
+```
+
+`psa_crypto_driver_get_persistent_state` sets `*persistent_state_ptr` to a pointer to the first byte of the persistent state. This pointer remains valid during a call to a driver entry point. Once the entry point returns, the pointer is no longer valid. The core guarantees that calls to `psa_crypto_driver_get_persistent_state` within the same entry point return the same address for the persistent state, but this address may change between calls to an entry point.
+
+`psa_crypto_driver_commit_persistent_state` updates the persistent state in persistent storage. Only the portion at byte offsets `from` inclusive to `from + length` exclusive is guaranteed to be updated; it is unspecified whether changes made to other parts of the state are taken into account. The driver must call this function after updating the persistent state in memory and before returning from the entry point, otherwise it is unspecified whether the persistent state is updated.
+
+The core will not update the persistent state in storage while an entry point is running except when the entry point calls `psa_crypto_driver_commit_persistent_state`. It may update the persistent state in storage after an entry point returns.
+
+In a multithreaded environment, the driver may only call these two functions from the thread that is executing the entry point.
+
+#### Built-in keys
+
+Opaque drivers may declare built-in keys. Built-in keys can be accessed, but not created, through the PSA Cryptography API.
+
+A built-in key is identified by its location and its **slot number**. Drivers that support built-in keys must provide a `"get_builtin_key"` entry point to retrieve the key data and metadata. The core calls this entry point when it needs to access the key, typically because the application requested an operation on the key. The core may keep information about the key in cache, and successive calls to access the same slot number should return the same data. This entry point has the following prototype:
+
+```
+psa_status_t acme_get_builtin_key(psa_drv_slot_number_t slot_number,
+ psa_key_attributes_t *attributes,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length);
+```
+
+If this function returns `PSA_SUCCESS` or `PSA_ERROR_BUFFER_TOO_SMALL`, it must fill `attributes` with the attributes of the key (except for the key identifier). On success, this function must also fill `key_buffer` with the key context.
+
+On entry, `psa_get_key_lifetime(attributes)` is the location at which the driver was declared and a persistence level with which the platform is attempting to register the key. The driver entry point may choose to change the lifetime (`psa_set_key_lifetime(attributes, lifetime)`) of the reported key attributes to one with the same location but a different persistence level, in case the driver has more specific knowledge about the actual persistence level of the key which is being retrieved. For example, if a driver knows it cannot delete a key, it may override the persistence level in the lifetime to `PSA_KEY_PERSISTENCE_READ_ONLY`. The standard attributes other than the key identifier and lifetime have the value conveyed by `PSA_KEY_ATTRIBUTES_INIT`.
+
+The output parameter `key_buffer` points to a writable buffer of `key_buffer_size` bytes. If the driver has a [`"builtin_key_size"` property](#key-format-for-opaque-drivers) property, `key_buffer_size` has this value, otherwise `key_buffer_size` has the value determined from the key type and size.
+
+Typically, for a built-in key, the key context is a reference to key material that is kept inside the secure element, similar to the format returned by [`"allocate_key"`](#key-management-in-a-secure-element-with-storage). A driver may have built-in keys even if it doesn't have an `"allocate_key"` entry point.
+
+This entry point may return the following status values:
+
+* `PSA_SUCCESS`: the requested key exists, and the output parameters `attributes` and `key_buffer` contain the key metadata and key context respectively, and `*key_buffer_length` contains the length of the data written to `key_buffer`.
+* `PSA_ERROR_BUFFER_TOO_SMALL`: `key_buffer_size` is insufficient. In this case, the driver must pass the key's attributes in `*attributes`. In particular, `get_builtin_key(slot_number, &attributes, NULL, 0)` is a way for the core to obtain the key's attributes.
+* `PSA_ERROR_DOES_NOT_EXIST`: the requested key does not exist.
+* Other error codes such as `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permanent error.
+
+The core will pass authorized requests to destroy a built-in key to the [`"destroy_key"`](#key-management-in-a-secure-element-with-storage) entry point if there is one. If built-in keys must not be destroyed, it is up to the driver to reject such requests.
+
+## How to use drivers from an application
+
+### Using transparent drivers
+
+Transparent drivers linked into the library are automatically used for the mechanisms that they implement.
+
+### Using opaque drivers
+
+Each opaque driver is assigned a [location](#lifetimes-and-locations). The driver is invoked for all actions that use a key in that location. A key's location is indicated by its lifetime. The application chooses the key's lifetime when it creates the key.
+
+For example, the following snippet creates an AES-GCM key which is only accessible inside the secure element designated by the location `PSA_KEY_LOCATION_acme`.
+```
+psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
+ PSA_KEY_PERSISTENCE_DEFAULT, PSA_KEY_LOCATION_acme));
+psa_set_key_identifier(&attributes, 42);
+psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
+psa_set_key_size(&attributes, 128);
+psa_set_key_algorithm(&attributes, PSA_ALG_GCM);
+psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT);
+psa_key_id_t key;
+psa_generate_key(&attributes, &key);
+```
+
+## Using opaque drivers from an application
+
+### Lifetimes and locations
+
+The PSA Cryptography API, version 1.0.0, defines [lifetimes](https://armmbed.github.io/mbed-crypto/html/api/keys/attributes.html?highlight=psa_key_lifetime_t#c.psa_key_lifetime_t) as an attribute of a key that indicates where the key is stored and which application and system actions will create and destroy it. The lifetime is expressed as a 32-bit value (`typedef uint32_t psa_key_lifetime_t`). An upcoming version of the PSA Cryptography API defines more structure for lifetime values to separate these two aspects of the lifetime:
+
+* Bits 0–7 are a _persistence level_. This value indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is volatile or persistent.
+* Bits 8–31 are a _location indicator_. This value indicates where the key material is stored and where operations on the key are performed. Location values can be stored in a variable of type `psa_key_location_t`.
+
+An opaque driver is attached to a specific location. Keys in the default location (`PSA_KEY_LOCATION_LOCAL_STORAGE = 0`) are transparent: the core has direct access to the key material. For keys in a location that is managed by an opaque driver, only the secure element has access to the key material and can perform operations on the key, while the core only manipulates a wrapped form of the key or an identifier of the key.
+
+### Creating a key in a secure element
+
+The core defines a compile-time constant for each opaque driver indicating its location called `PSA_KEY_LOCATION_`*prefix* where *prefix* is the value of the `"prefix"` property in the driver description. For convenience, Mbed TLS also declares a compile-time constant for the corresponding lifetime with the default persistence called `PSA_KEY_LIFETIME_`*prefix*. Therefore, to declare an opaque key in the location with the prefix `foo` with the default persistence, call `psa_set_key_lifetime` during the key creation as follows:
+```
+psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_foo);
+```
+
+To declare a volatile key:
+```
+psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
+ PSA_KEY_LOCATION_foo,
+ PSA_KEY_PERSISTENCE_VOLATILE));
+```
+
+Generally speaking, to declare a key with a specified persistence:
+```
+psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
+ PSA_KEY_LOCATION_foo,
+ persistence));
+```
+
+## Open questions
+
+### Value representation
+
+#### Integers
+
+It would be better if there was a uniform requirement on integer values. Do they have to be JSON integers? C preprocessor integers (which could be e.g. a macro defined in some header file)? C compile-time constants (allowing `sizeof`)?
+
+This choice is partly driven by the use of the values, so they might not be uniform. Note that if the value can be zero and it's plausible that the core would want to statically allocate an array of the given size, the core needs to know whether the value is 0 so that it could use code like
+```
+#if ACME_FOO_SIZE != 0
+ uint8_t foo[ACME_FOO_SIZE];
+#endif
+```
+
+### Driver declarations
+
+#### Declaring driver entry points
+
+The core may want to provide declarations for the driver entry points so that it can compile code using them. At the time of writing this paragraph, the driver headers must define types but there is no obligation for them to declare functions. The core knows what the function names and argument types are, so it can generate prototypes.
+
+It should be ok for driver functions to be function-like macros or function pointers.
+
+#### Driver location values
+
+How does a driver author decide which location values to use? It should be possible to combine drivers from different sources. Use the same vendor assignment as for PSA services?
+
+Can the driver assembly process generate distinct location values as needed? This can be convenient, but it's also risky: if you upgrade a device, you need the location values to be the same between builds.
+
+The current plan is for Arm to maintain a registry of vendors and assign a location namespace to each vendor. Parts of the namespace would be reserved for implementations and integrators.
+
+#### Multiple transparent drivers
+
+When multiple transparent drivers implement the same mechanism, which one is called? The first one? The last one? Unspecified? Or is this an error (excluding capabilities with fallback enabled)?
+
+The current choice is that the first one is used, which allows having a preference order on drivers, but may mask integration errors.
+
+### Driver function interfaces
+
+#### Driver function parameter conventions
+
+Should 0-size buffers be guaranteed to have a non-null pointers?
+
+Should drivers really have to cope with overlap?
+
+Should the core guarantee that the output buffer size has the size indicated by the applicable buffer size macro (which may be an overestimation)?
+
+#### Key derivation inputs and buffer ownership
+
+Why is `psa_crypto_driver_key_derivation_get_input_bytes` a copy, rather than giving a pointer?
+
+The main reason is to avoid complex buffer ownership. A driver entry point does not own memory after the entry point return. This is generally necessary because an API function does not own memory after the entry point returns. In the case of key derivation inputs, this could be relaxed because the driver entry point is making callbacks to the core: these functions could return a pointer that is valid until the driver entry point returns, which would allow the driver to process the data immediately (e.g. hash it rather than copy it).
+
+### Partial computations in drivers
+
+#### Substitution points
+
+Earlier drafts of the driver interface had a concept of _substitution points_: places in the calculation where a driver may be called. Some hardware doesn't do the whole calculation, but only the “main” part. This goes both for transparent and opaque drivers. Some common examples:
+
+* A processor that performs the RSA exponentiation, but not the padding. The driver should be able to leverage the padding code in the core.
+* A processor that performs a block cipher operation only for a single block, or only in ECB mode, or only in CTR mode. The core would perform the block mode (CBC, CTR, CCM, ...).
+
+This concept, or some other way to reuse portable code such as specifying inner functions like `psa_rsa_pad` in the core, should be added to the specification.
+
+### Key management
+
+#### Mixing drivers in key derivation
+
+How does `psa_key_derivation_output_key` work when the extraction part and the expansion part use different drivers?
+
+#### Public key calculation
+
+ECC key pairs are represented as the private key value only. The public key needs to be calculated from that. Both transparent drivers and opaque drivers provide a function to calculate the public key (`"export_public_key"`).
+
+The specification doesn't mention when the public key might be calculated. The core may calculate it on creation, on demand, or anything in between. Opaque drivers have a choice of storing the public key in the key context or calculating it on demand and can convey whether the core should store the public key with the `"store_public_key"` property. Is this good enough or should the specification include non-functional requirements?
+
+#### Symmetric key validation with transparent drivers
+
+Should the entry point be called for symmetric keys as well?
+
+#### Support for custom import formats
+
+[“Driver entry points for key management”](#driver-entry-points-for-key-management) states that the input to `"import_key"` can be an implementation-defined format. Is this a good idea? It reduces driver portability, since a core that accepts a custom format would not work with a driver that doesn't accept this format. On the other hand, if a driver accepts a custom format, the core should let it through because the driver presumably handles it more efficiently (in terms of speed and code size) than the core could.
+
+Allowing custom formats also causes a problem with import: the core can't know the size of the key representation until it knows the bit-size of the key, but determining the bit-size of the key is part of the job of the `"import_key"` entry point. For standard key types, this could plausibly be an issue for RSA private keys, where an implementation might accept a custom format that omits the CRT parameters (or that omits *d*).
+
+### Opaque drivers
+
+#### Opaque driver persistent state
+
+The driver is allowed to update the state at any time. Is this ok?
+
+An example use case for updating the persistent state at arbitrary times is to renew a key that is used to encrypt communications between the application processor and the secure element.
+
+`psa_crypto_driver_get_persistent_state` does not identify the calling driver, so the driver needs to remember which driver it's calling. This may require a thread-local variable in a multithreaded core. Is this ok?
+
+#### Open questions around cooked key derivation
+
+`"derive_key"` is not a clear name. Can we use a better one?
+
+For the `"derive_key"` entry point, how does the core choose `input_length`? Doesn't the driver know better? Should there be a driver entry point to determine the length, or should there be a callback that allows the driver to retrieve the input? Note that for some key types, it's impossible to predict the amount of input in advance, because it depends on some complex calculation or even on random data, e.g. if doing a randomized pseudo-primality test. However, for all key types except RSA, the specification mandates how the key is derived, which practically dictates how the pseudorandom key stream is consumed. So it's probably ok.
+
+#### Fallback for key derivation in opaque drivers
+
+Should [dispatch to an opaque driver](#key-derivation-driver-dispatch-logic) allow fallback, so that if `"key_derivation_setup"` returns `PSA_ERROR_NOT_SUPPORTED` then the core exports the key from the secure element instead?
+
+Should the ["`key_derivation_output_key`"](#key-derivation-driver-outputs) capability indicate which key types the driver can derive? How should fallback work? For example, consider a secure element that implements HMAC, HKDF and ECDSA, and that can derive an HMAC key from HKDF without exporting intermediate material but can only import or randomly generate ECC keys. How does this driver convey that it can't derive an ECC key with HKDF, but it can let the core do this and import the resulting key?
+
+### Randomness
+
+#### Input to `"add_entropy"`
+
+Should the input to the [`"add_entropy"` entry point](#entropy-injection) be a full-entropy buffer (with data from all entropy sources already mixed), raw entropy direct from the entropy sources, or give the core a choice?
+
+* Raw data: drivers must implement entropy mixing. `"add_entropy"` needs an extra parameter to indicate the amount of entropy in the data. The core must not do any conditioning.
+* Choice: drivers must implement entropy mixing. `"add_entropy"` needs an extra parameter to indicate the amount of entropy in the data. The core may do conditioning if it wants, but doesn't have to.
+* Full entropy: drivers don't need to do entropy mixing.
+
+#### Flags for `"get_entropy"`
+
+Are the [entropy collection flags](#entropy-collection-flags) well-chosen?
+
+#### Random generator instantiations
+
+May the core instantiate a random generation context more than once? In other words, can there be multiple objects of type `acme_random_context_t`?
+
+Functionally, one RNG is as good as any. If the core wants some parts of the system to use a deterministic generator for reproducibility, it can't use this interface anyway, since the RNG is not necessarily deterministic. However, for performance on multiprocessor systems, a multithreaded core could prefer to use one RNG instance per thread.
+
+<!--
+Local Variables:
+time-stamp-line-limit: 40
+time-stamp-start: "Time-stamp: *\""
+time-stamp-end: "\""
+time-stamp-format: "%04Y/%02m/%02d %02H:%02M:%02S %Z"
+time-stamp-time-zone: "GMT"
+End:
+-->
diff --git a/docs/proposed/psa-driver-wrappers-codegen-migration-guide.md b/docs/proposed/psa-driver-wrappers-codegen-migration-guide.md
new file mode 100644
index 0000000..f9b108d
--- /dev/null
+++ b/docs/proposed/psa-driver-wrappers-codegen-migration-guide.md
@@ -0,0 +1,40 @@
+Migrating to an auto generated psa_crypto_driver_wrappers.h file
+================================================================
+
+This document describes how to migrate to the auto generated psa_crypto_driver_wrappers.h file.
+It is meant to give the library user migration guidelines while the Mbed TLS project tides over multiple minor revs of version 1.0, after which this will be merged into psa-driver-interface.md.
+
+For a practical guide with a description of the current state of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-example-and-guide.md).
+
+## Introduction
+
+The design of the Driver Wrappers code generation is based on the design proposal https://github.com/Mbed-TLS/mbedtls/pull/5067
+During the process of implementation there might be minor variations wrt versioning and broader implementation specific ideas, but the design remains the same.
+
+## Prerequisites
+
+Python3, Jinja2 rev 2.10.1 and jsonschema rev 3.2.0
+
+## Feature Version
+
+1.1
+
+### What's critical for a migrating user
+
+The Driver Wrapper auto generation project is designed to use a python templating library ( Jinja2 ) to render templates based on drivers that are defined using a Driver description JSON file(s).
+
+While that is the larger goal, for version 1.1 here's what's changed
+
+#### What's changed
+
+(1) psa_crypto_driver_wrappers.h will from this point on be auto generated.
+(2) The auto generation is based on the template file at **scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja**.
+(3) The driver JSONS to be used for generating the psa_crypto_driver_wrappers.h file can be found at **scripts/data_files/driver_jsons/** as their default location, this path includes the schemas against which the driver schemas will be validated (driver_opaque_schema.json, driver_transparent_schema.json) and a driverlist.json which specifies the drivers to be considered and the order in which they want to be called into. The default location for driverlist.json and driver JSONS can be overloaded by passing an argument --json-dir while running the script generate_driver_wrappers.py.
+(4) While the complete driver wrapper templating support is yet to come in, if the library user sees a need to patch psa_crypto_driver_wrappers.h file, the user will need to patch into the template file as needed (psa_crypto_driver_wrappers.h.jinja).
+
+#### How to set your driver up
+
+Please refer to psa-driver-interface.md for information on how a driver schema can be written.
+One can also refer to the example test drivers/ JSON schemas under **scripts/data_files/driver_jsons/**.
+
+The JSON file 'driverlist.json' is meant to be edited by the user to reflect the drivers one wants to use on a device. The order in which the drivers are passed is also essential if/when there are multiple transparent drivers on a given system to retain the same order in the templating.
diff --git a/docs/psa-driver-example-and-guide.md b/docs/psa-driver-example-and-guide.md
new file mode 100644
index 0000000..aa825ad
--- /dev/null
+++ b/docs/psa-driver-example-and-guide.md
@@ -0,0 +1,180 @@
+# PSA Cryptoprocessor driver development examples
+
+As of Mbed TLS 3.4.0, the PSA Driver Interface has only been partially implemented. As a result, the deliverables for writing a driver and the method for integrating a driver with Mbed TLS will vary depending on the operation being accelerated. This document describes how to write and integrate cryptoprocessor drivers depending on which operation or driver type is being implemented.
+
+The `docs/proposed/` directory contains three documents which pertain to the proposed, work-in-progress driver system. The [PSA Driver Interface](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-interface.md) describes how drivers will interface with Mbed TLS in the future, as well as driver types, operation types, and entry points. As many key terms and concepts used in the examples in this document are defined in the PSA Driver Interface, it is recommended that developers read it prior to starting work on implementing drivers.
+The PSA Driver [Developer](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-developer-guide.md) Guide describes the deliverables for writing a driver that can be used with Mbed TLS, and the PSA Driver [Integration](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-integration-guide.md) Guide describes how a driver can be built alongside Mbed TLS.
+
+## Contents:
+[Background on how Mbed TLS calls drivers](#background-on-how-mbed-tls-calls-drivers)\
+[Process for Entry Points where auto-generation is implemented](#process-for-entry-points-where-auto-generation-is-implemented) \
+[Process for Entry Points where auto-generation is not implemented](#process-for-entry-points-where-auto-generation-is-not-implemented) \
+[Example: Manually integrating a software accelerator alongside Mbed TLS](#example-manually-integrating-a-software-accelerator-alongside-mbed-tls)
+
+## Background on how Mbed TLS calls drivers
+
+The PSA Driver Interface specification specifies which cryptographic operations can be accelerated by third-party drivers. Operations that are completed within one step (one function call), such as verifying a signature, are called *Single-Part Operations*. On the other hand, operations that consist of multiple steps implemented by different functions called sequentially are called *Multi-Part Operations*. Single-part operations implemented by a driver will have one entry point, while multi-part operations will have multiple: one for each step.
+
+There are two types of drivers: *transparent* or *opaque*. See below an excerpt from the PSA Driver Interface specification defining them:
+* **Transparent** drivers implement cryptographic operations on keys that are provided in cleartext at the beginning of each operation. They are typically used for hardware **accelerators**. When a transparent driver is available for a particular combination of parameters (cryptographic algorithm, key type and size, etc.), it is used instead of the default software implementation. Transparent drivers can also be pure software implementations that are distributed as plug-ins to a PSA Cryptography implementation (for example, an alternative implementation with different performance characteristics, or a certified implementation).
+* **Opaque** drivers implement cryptographic operations on keys that can only be used inside a protected environment such as a **secure element**, a hardware security module, a smartcard, a secure enclave, etc. An opaque driver is invoked for the specific [key location](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-interface.md#lifetimes-and-locations) that the driver is registered for: the dispatch is based on the key's lifetime.
+
+Mbed TLS contains a **driver dispatch layer** (also called a driver wrapper layer). For each cryptographic operation that supports driver acceleration (or sub-part of a multi-part operation), the library calls the corresponding function in the driver wrapper. Using flags set at compile time, the driver wrapper ascertains whether any present drivers support the operation. When no such driver is present, the built-in library implementation is called as a fallback (if allowed). When a compatible driver is present, the driver wrapper calls the driver entry point function provided by the driver author.
+
+The long-term goal is for the driver dispatch layer to be auto-generated using a JSON driver description file provided by the driver author.
+For some cryptographic operations, this auto-generation logic has already been implemented. When accelerating these operations, the instructions in the above documents can be followed. For the remaining operations which do not yet support auto-generation of the driver wrapper, developers will have to manually edit the driver dispatch layer and call their driver's entry point functions from there.
+
+Auto-generation of the driver wrapper is supported for the operation entry points specified in the table below. Certain operations are only permitted for opaque drivers. All other operation entry points do not support auto-generation of the driver wrapper.
+
+| Transparent Driver | Opaque Driver |
+|---------------------|---------------------|
+| `import_key` | `import_key` |
+| `export_public_key` | `export_public_key` |
+| | `export_key` |
+| | `copy_key` |
+| | `get_builtin_key` |
+
+### Process for Entry Points where auto-generation is implemented
+
+If the driver is accelerating operations whose entry points are in the above table, the instructions in the driver [developer](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-developer-guide.md) and [integration](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-integration-guide.md) guides should be followed.
+
+There are three deliverables for creating such a driver. These are:
+ - A driver description file (in JSON format).
+ - C header files defining the types required by the driver description. The names of these header files are declared in the driver description file.
+ - An object file compiled for the target platform defining the functions required by the driver description. Implementations may allow drivers to be provided as source files and compiled with the core instead of being pre-compiled.
+
+The Mbed TLS driver tests for the aforementioned entry points provide examples of how these deliverables can be implemented. For sample driver description JSON files, see [`mbedtls_test_transparent_driver.json`](https://github.com/Mbed-TLS/mbedtls/blob/development/scripts/data_files/driver_jsons/mbedtls_test_transparent_driver.json) or [`mbedtls_test_opaque_driver.json`](https://github.com/Mbed-TLS/mbedtls/blob/development/scripts/data_files/driver_jsons/mbedtls_test_transparent_driver.json). The header file required by the driver description is [`test_driver.h`](https://github.com/Mbed-TLS/mbedtls/blob/development/tests/include/test/drivers/test_driver.h). As Mbed TLS tests are built from source, there is no object file for the test driver. However, the source for the test driver can be found under `tests/src/drivers`.
+
+### Process for Entry Points where auto-generation is not implemented
+
+If the driver is accelerating operations whose entry points are not present in the table, a different process is followed where the developer manually edits the driver dispatch layer. The following steps describe this process. Steps 1, 2, 3, and 7 only need to be done once *per driver*. Steps 4, 5, and 6 must be done *for each single-part operation* or *for each sub-part of a multi-part operation* implemented by the driver.
+
+**1. Choose a driver prefix and a macro name that indicates whether the driver is enabled** \
+A driver prefix is simply a word (often the name of the driver) that all functions/macros associated with the driver should begin with. This is similar to how most functions/macros in Mbed TLS begin with `PSA_XXX/psa_xxx` or `MBEDTLS_XXX/mbedtls_xxx`. The macro name can follow the form `DRIVER_PREFIX_ENABLED` or something similar; it will be used to indicate the driver is available to be called. When building with the driver present, define this macro at compile time.
+
+**2. Include the following in one of the driver header files:**
+```
+#if defined(DRIVER_PREFIX_ENABLED)
+#ifndef PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT
+#define PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT
+#endif
+
+// other definitions here
+
+#endif
+```
+
+**3. Conditionally include header files required by the driver**
+Include any header files required by the driver in `psa_crypto_driver_wrappers.h`, placing the `#include` statements within an `#if defined` block which checks if the driver is available:
+```
+#if defined(DRIVER_PREFIX_ENABLED)
+#include ...
+#endif
+```
+
+
+**4. For each operation being accelerated, locate the function in the driver dispatch layer that corresponds to the entry point of that operation.** \
+The file `psa_crypto_driver_wrappers.h.jinja` and `psa_crypto_driver_wrappers_no_static.c.jinja` contains the driver wrapper functions. For the entry points that have driver wrapper auto-generation implemented, the functions have been replaced with `jinja` templating logic. While the file has a `.jinja` extension, the driver wrapper functions for the remaining entry points are simple C functions. The names of these functions are of the form `psa_driver_wrapper` followed by the entry point name. So, for example, the function `psa_driver_wrapper_sign_hash()` corresponds to the `sign_hash` entry point.
+
+**5. If a driver entry point function has been provided then ensure it has the same signature as the driver wrapper function.** \
+If one has not been provided then write one. Its name should begin with the driver prefix, followed by transparent/opaque (depending on driver type), and end with the entry point name. It should have the same signature as the driver wrapper function. The purpose of the entry point function is to take arguments in PSA format for the implemented operation and return outputs/status codes in PSA format. \
+*Return Codes:*
+* `PSA_SUCCESS`: Successful Execution
+* `PSA_ERROR_NOT_SUPPORTED`: Input arguments are correct, but the driver does not support the operation. If a transparent driver returns this then it allows fallback to another driver or software implementation.
+* `PSA_ERROR_XXX`: Any other PSA error code, see API documentation
+
+**6. Modify the driver wrapper function** \
+Each driver wrapper function contains a `switch` statement which checks the location of the key. If the key is stored in local storage, then operations are performed by a transparent driver. If it is stored elsewhere, then operations are performed by an opaque driver.
+ * **Transparent drivers:** Calls to driver entry points go under `case PSA_KEY_LOCATION_LOCAL_STORAGE`.
+ * **Opaque Drivers** Calls to driver entry points go in a separate `case` block corresponding to the key location.
+
+
+The diagram below shows the layout of a driver wrapper function which can dispatch to two transparent drivers `Foo` and `Bar`, and one opaque driver `Baz`.
+
+ ```
+psa_driver_wrapper_xxx()
+├── switch(location)
+| |
+| ├── case PSA_KEY_LOCATION_LOCAL_STORAGE //transparent driver
+| | ├── #if defined(PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT)
+| | | ├── #if defined(FOO_DRIVER_PREFIX_ENABLED)
+| | | | ├── if(//conditions for foo driver capibilities)
+| | | | ├── foo_driver_transparent_xxx() //call to driver entry point
+| | | | ├── if (status != PSA_ERROR_NOT_SUPPORTED) return status
+| | | ├── #endif
+| | | ├── #if defined(BAR_DRIVER_PREFIX_ENABLED)
+| | | | ├── if(//conditions for bar driver capibilities)
+| | | | ├── bar_driver_transparent_xxx() //call to driver entry point
+| | | | ├── if (status != PSA_ERROR_NOT_SUPPORTED) return status
+| | | ├── #endif
+| | ├── #endif
+| |
+| ├── case SECURE_ELEMENT_LOCATION //opaque driver
+| | ├── #if defined(PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT)
+| | | ├── #if defined(BAZ_DRIVER_PREFIX_ENABLED)
+| | | | ├── if(//conditions for baz driver capibilities)
+| | | | ├── baz_driver_opaque_xxx() //call to driver entry point
+| | | | ├── if (status != PSA_ERROR_NOT_SUPPORTED) return status
+| | | ├── #endif
+| | ├── #endif
+└── return psa_xxx_builtin() // fall back to built in implementation
+ ```
+
+All code related to driver calls within each `case` must be contained between `#if defined(PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT)` and a corresponding `#endif`. Within this block, each individual driver's compatibility checks and call to the entry point must be contained between `#if defined(DRIVER_PREFIX_ENABLED)` and a corresponding `#endif`. Checks that involve accessing key material using PSA macros, such as determining the key type or number of bits, must be done in the driver wrapper.
+
+**7. Build Mbed TLS with the driver**
+This guide assumes you are building Mbed TLS from source alongside your project. If building with a driver present, the chosen driver macro (`DRIVER_PREFIX_ENABLED`) must be defined. This can be done in two ways:
+* *At compile time via flags.* This is the preferred option when your project uses Mbed TLS mostly out-of-the-box without significantly modifying the configuration. This can be done by passing the option via `CFLAGS`.
+ * **Make**:
+ ```
+ make CFLAGS="-DDRIVER_PREFIX_ENABLED"
+ ```
+ * **CMake**: CFLAGS must be passed to CMake when it is invoked. Invoke CMake with
+
+ ```
+ CFLAGS="-DDRIVER_PREFIX_ENABLED" cmake path/to/source
+ ```
+* *Providing a user config file.* This is the preferred option when your project requires a custom configuration that is significantly different to the default. Define the macro for the driver, along with any other custom configurations in a separate header file, then use `config.py`, to set `MBEDTLS_USER_CONFIG_FILE`, providing the path to the defined header file. This will include your custom config file after the default. If you wish to completely replace the default config file, set `MBEDTLS_CONFIG_FILE` instead.
+
+### Example: Manually integrating a software accelerator alongside Mbed TLS
+
+[p256-m](https://github.com/mpg/p256-m) is a minimalistic implementation of ECDH and ECDSA on the NIST P-256 curve, specifically optimized for use in constrained 32-bit environments. It started out as an independent project and has been integrated in Mbed TLS as a PSA transparent driver. The source code of p256-m and the driver entry points is located in the Mbed TLS source tree under `3rdparty/p256-m`. In this section, we will look at how this integration was done.
+
+The Mbed TLS build system includes the instructions needed to build p256-m. To build with and use p256-m, set the macro `MBEDTLS_PSA_P256M_DRIVER_ENABLED` using `config.py`, then build as usual using make/cmake. From the root of the `mbedtls/` directory, run:
+
+ python3 scripts/config.py set MBEDTLS_PSA_CRYPTO_CONFIG
+ python3 scripts/config.py set MBEDTLS_PSA_P256M_DRIVER_ENABLED
+ make
+
+(You need extra steps if you want to disable the built-in implementation of ECC algorithms, which includes more features than p256-m. Refer to the documentation of `MBEDTLS_PSA_P256M_DRIVER_ENABLED` and [`driver-only-builds.md`](driver-only-builds.md) for more information.)
+
+The driver prefix for p256-m is `P256`/`p256`.
+The p256-m driver implements the following entry points: `"import_key"`, `"export_public_key"`, `"generate_key"`, `"key_agreement"`, `"sign_hash"`, `"verify_hash"`.
+There are no entry points for `"sign_message"` and `"verify_message"`, which are not necessary for a sign-and-hash algorithm. The core still implements these functions by doing the hashes and then calling the sign/verify-hash entry points.
+The driver entry point functions can be found in `p256m_driver_entrypoints.[hc]`. These functions act as an interface between Mbed TLS and p256-m; converting between PSA and p256-m argument formats and performing sanity checks. If the driver's status codes differ from PSA's, it is recommended to implement a status code translation function. The function `p256_to_psa_error()` converts error codes returned by p256-m into PSA error codes.
+
+The driver wrapper functions in `psa_crypto_driver_wrappers.h.jinja` for all four entry points have also been modified. The code block below shows the additions made to `psa_driver_wrapper_sign_hash()`. In adherence to the defined process, all code related to the driver call is placed within a check for `MBEDTLS_PSA_P256M_DRIVER_ENABLED`. p256-m only supports non-deterministic ECDSA using keys based on NIST P256; these constraints are enforced through checks (see the `if` statement). Checks that involve accessing key attributes, (e.g. checking key type or bits) **must** be performed in the driver wrapper. This is because this information is marked private and may not be accessed outside the library. Other checks can be performed here or in the entry point function. The status returned by the driver is propagated up the call hierarchy **unless** the driver does not support the operation (i.e. return `PSA_ERROR_NOT_SUPPORTED`). In that case the next available driver/built-in implementation is called.
+
+```
+#if defined (MBEDTLS_PSA_P256M_DRIVER_ENABLED)
+ if( PSA_KEY_TYPE_IS_ECC( psa_get_key_type(attributes) ) &&
+ PSA_ALG_IS_ECDSA(alg) &&
+ !PSA_ALG_ECDSA_IS_DETERMINISTIC( alg ) &&
+ PSA_KEY_TYPE_ECC_GET_FAMILY(psa_get_key_type(attributes)) == PSA_ECC_FAMILY_SECP_R1 &&
+ psa_get_key_bits(attributes) == 256 )
+ {
+ status = p256_transparent_sign_hash( attributes,
+ key_buffer,
+ key_buffer_size,
+ alg,
+ hash,
+ hash_length,
+ signature,
+ signature_size,
+ signature_length );
+ if( status != PSA_ERROR_NOT_SUPPORTED )
+ return( status );
+ }
+#endif /* MBEDTLS_PSA_P256M_DRIVER_ENABLED */
+```
+Following this, p256-m is now ready to use alongside Mbed TLS as a software accelerator. If `MBEDTLS_PSA_P256M_DRIVER_ENABLED` is set in the config, p256-m's implementations of key generation, ECDH, and ECDSA will be used where applicable.
diff --git a/docs/psa-transition.md b/docs/psa-transition.md
new file mode 100644
index 0000000..bbb7da2
--- /dev/null
+++ b/docs/psa-transition.md
@@ -0,0 +1,1322 @@
+# Transitioning to the PSA API
+
+> I have code written for `mbedtls_` cryptography APIs. How do I migrate to `psa_` APIs?
+
+## Introduction
+
+Mbed TLS is gradually moving from legacy `mbedtls_xxx` APIs to newer `psa_xxx` APIs for cryptography. Note that this only concerns cryptography APIs, not X.509 or SSL/TLS APIs.
+
+This guide is intended to help migrate existing applications that use Mbed TLS for cryptography. It aims to cover common use cases, but cannot cover all possible scenarios.
+
+### Suggested reading
+
+This document is long, but you probably don't need to read all of it. You should start with the following sections:
+
+1. [Where can I find documentation?](#where-can-i-find-documentation)
+2. [General considerations](#general-considerations)
+
+Then use the [summary of API modules](#summary-of-api-modules), the table of contents or a text search to locate the sections that interest you, based on what legacy interfaces your code is currently using.
+
+### Where can I find documentation?
+
+**Tutorial**: See the [getting started guide](https://mbed-tls.readthedocs.io/en/latest/getting_started/psa/).
+
+**Reference**: The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/) is available online. Mbed TLS implements a large subset of the specification which is documented in the [`psa/crypto*.h` headers](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto_8h/).
+
+### Additional resources
+
+* [Mbed TLS open issues](https://github.com/Mbed-TLS/mbedtls/issues)
+* [PSA API open issues](https://github.com/ARM-software/psa-api/issues) (not just cryptography APIs)
+* [Mbed TLS mailing list](https://lists.trustedfirmware.org/mailman3/lists/mbed-tls.lists.trustedfirmware.org/)
+
+### Why change the API?
+
+* Mbed TLS APIs are traditionally very transparent: the caller can access internal fields of operations. This is less true in the 3.x major version than before, but still the case to some extent. This offers applications some flexibility, but it removes flexibility from the implementation. For example, it is hard to support hardware acceleration, because the API constrains how the data must be represented. PSA APIs were designed to be more opaque, giving more freedom to the implementation.
+* Mbed TLS legacy APIs require key material to be present in the application memory. The PSA Crypto API natively supports operations on keys stored in an external [location](https://arm-software.github.io/psa-api/crypto/1.1/api/keys/lifetimes.html#c.psa_key_location_t) (secure enclave, secure element, HSM, etc.).
+* PSA APIs have [consistent conventions](https://arm-software.github.io/psa-api/crypto/1.1/overview/conventions.html#parameter-conventions) which many legacy APIs in Mbed TLS do not follow. For example, many legacy cryptography functions require the caller to know how large an output buffer needs to be based on the selected algorithm, whereas in the PSA API, all buffer arguments have a well-defined size and those sizes are checked.
+* Mbed TLS legacy APIs require passing around a random generator argument where needed. This has historically been problematic with functions that were created without an RNG argument but later needed one as part of a security countermeasure. The PSA crypto subsystem maintains a global random generator, resolving this problem.
+
+### Migration timeline
+
+* Mbed TLS 2.15.0 (Nov 2018): first release with a draft implementation of the PSA API.
+* Mbed TLS 2.18.0 (Jun 2019): The PSA API is available in the default build.
+* Mbed TLS 3.1.0 (Dec 2021): TLS 1.3 support is the first major feature that requires the PSA API.
+* Mbed TLS 4.0.0 (2024?): X.509 and TLS require the PSA API. Removal of some legacy crypto APIs.
+* Mbed TLS 5.0.0 (??): Removal of the remaining non-PSA crypto APIs.
+
+## General considerations
+
+### Configuration of the PSA subsystem
+
+To make the PSA API available, make sure that the configuration option [`MBEDTLS_PSA_CRYPTO_C`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#c.MBEDTLS_PSA_CRYPTO_C) is enabled. (It is enabled in the default configuration.)
+
+You should probably enable [`MBEDTLS_USE_PSA_CRYPTO`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1a70fd7b97d5f11170546583f2095942a6) as well (it is disabled by default). This option causes the PK, X.509 and TLS modules to use PSA crypto under the hood.
+
+By default, the PSA crypto API offers a similar set of cryptographic mechanisms as those offered by the legacy API (configured by `MBEDTLS_XXX` macros). The PSA crypto API also has its own configuration mechanism; see “[Cryptographic mechanism availability](#cryptographic-mechanism-availability)”.
+
+### Header files
+
+Applications only need to include a single header file:
+```
+#include <psa/crypto.h>
+```
+
+### General application layout
+
+Before any cryptographic operation, call [`psa_crypto_init`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__initialization/#group__initialization_1ga2de150803fc2f7dc6101d5af7e921dd9) and check that it succeeds. (A failure indicates an abnormal system state from which most applications cannot recover.)
+
+If you wish to free all resources associated with PSA cryptography, call [`mbedtls_psa_crypto_free`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__extra_8h/#_CPPv423mbedtls_psa_crypto_freev).
+
+The PSA subsystem has an internal random generator. As a consequence, you do not need to instantiate one manually (no need to create an `mbedtls_entropy_context` and an `mbedtls_xxx_drbg_context`).
+
+### Error codes
+
+Mbed TLS functions return a status of type `int`: 0 for success (or occasionally a positive value which is the output length), or a negative value `MBEDTLS_ERR_xxx` indicating an error.
+
+PSA functions return a status of type [`psa_status_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__error/#group__error_1ga05676e70ba5c6a7565aff3c36677c1f9): `PSA_SUCCESS == 0` for success, or a negative value [`PSA_ERROR_xxx`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__error/) indicating an error.
+
+### Memory management
+
+Apart from keys, as described in “[Key management](#key-management)” below, APIs that need to preserve state between function calls store this state in a structure allocated by the calling code. For example, multipart operations store state in a multipart operation object.
+
+All PSA operation objects must be zero-initialized (or equivalently, initialized with the provided `PSA_XXX_INIT` macro or `psa_xxx_init()` function) before calling any API function.
+
+Functions that output data require an output buffer of sufficient size. For all PSA crypto API functions that have an output buffer, there is a corresponding macro, generally called `PSA_XXX_OUTPUT_SIZE`, that calculates a sufficient size for the output buffer, given the relevant parameters. In some cases, there may be macros with less precision which can be resolved at compile time. For example, for the size of a buffer containing a hash, you can use `PSA_HASH_LENGTH(hash_alg)` where `hash_alg` is a specific hash algorithm, or `PSA_HASH_MAX_SIZE` for a buffer that is long enough for any supported hash. See the relevant sections of this document and of the reference documentation for more details.
+
+#### Key management
+
+One of the major differences between the legacy API and the PSA API is that in the PSA API, access to keys is indirect. Operations that require a key take a parameter of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv412psa_key_id_t), which is an identifier for the key. This allows the API to be used with keys that are not directly accessible to the application, for example because they are stored in a secure environment that does not allow the key material to be exported.
+
+To use a key:
+
+1. First create a key object with a key creation function. The two most common ones are [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b) if you have the key material available and [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5) to create a random key. The key creation function has the key identifier as an output parameter.
+2. Use the key as desired, passing the key identifier obtained during the key creation.
+3. Finally destroy the key object with [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2).
+
+See “[Cipher key management](#cipher-key-management)”, “[MAC key management](#mac-key-management)”, “[Key lifecycle for asymmetric cryptography](#key-lifecycle-for-asymmetric-cryptography)”, “[Creating keys for asymmetric cryptography](#creating-keys-for-asymmetric-cryptography)” and “[Diffie-Hellman key pair management](#diffie-hellman-key-pair-management)” for more details about key management in specific workflows, including information about choosing the key's attributes.
+
+If you need access to the key material, call [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf). If you need the public key corresponding to a key pair object, call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062).
+
+Note that a key consumes a key store entry, which is distinct from heap memory, until it is destroyed or the application exits. (This is not true for persistent keys, which instead consume disk space. Since persistent keys have no analog in the legacy API, we will not discuss them further in this document.)
+
+## Summary of API modules
+
+| Header | Function prefix | PSA equivalent |
+| ------ | --------------- | -------------- |
+| `aes.h` | `mbedtls_aes_` | [Symmetric encryption](#symmetric-encryption) |
+| `aria.h` | `mbedtls_aria_` | [Symmetric encryption](#symmetric-encryption) |
+| `asn1.h` | `mbedtls_asn1_` | No change ([PK support interface](#pk-format-support-interfaces)) |
+| `asn1write.h` | `mbedtls_asn1_write_` | No change ([PK support interface](#pk-format-support-interfaces)) |
+| `base64.h` | `mbedtls_base64_` | No change ([PK support interface](#pk-format-support-interfaces)) |
+| `bignum.h` | `mbedtls_mpi_` | None (no low-level arithmetic) |
+| `build_info.h` | `MBEDTLS_` | No change (not a crypto API) |
+| `camellia.h` | `mbedtls_camellia_` | [Symmetric encryption](#symmetric-encryption) |
+| `ccm.h` | `mbedtls_ccm_` | [Symmetric encryption](#symmetric-encryption), [Authenticated cipher operations](#authenticated-cipher-operations) |
+| `chacha20.h` | `mbedtls_chacha20_` | [Symmetric encryption](#symmetric-encryption) |
+| `chachapoly.h` | `mbedtls_chachapoly_` | [Symmetric encryption](#symmetric-encryption), [Authenticated cipher operations](#authenticated-cipher-operations) |
+| `check_config.h` | N/A | No public APIs (internal support header) |
+| `cipher.h` | `mbedtls_cipher_` | [Symmetric encryption](#symmetric-encryption) |
+| `cmac.h` | `mbedtls_cipher_cmac_` | [Hashes and MAC](#hashes-and-mac), [MAC calculation](#mac-calculation) |
+| `compat-2.x.h` | various | None (transitional APIs) |
+| `config_psa.h` | N/A | No public APIs (internal support header) |
+| `constant_time.h` | `mbedtls_ct_` | [Constant-time functions](#constant-time-functions) |
+| `ctr_drbg.h` | `mbedtls_ctr_drbg_` | [Random generation interface](#random-generation-interface), [Deterministic pseudorandom generation](#deterministic-pseudorandom-generation) |
+| `debug.h` | `mbedtls_debug_` | No change (not a crypto API) |
+| `des.h` | `mbedtls_des_` | [Symmetric encryption](#symmetric-encryption) |
+| `dhm.h` | `mbedtls_dhm_` | [Asymmetric cryptography](#asymmetric-cryptography) |
+| `ecdh.h` | `mbedtls_ecdh_` | [Asymmetric cryptography](#asymmetric-cryptography) |
+| `ecdsa.h` | `mbedtls_ecdsa_` | [Asymmetric cryptography](#asymmetric-cryptography) |
+| `ecjpake.h` | `mbedtls_ecjpake_` | [EC-JPAKE](#ec-jpake) |
+| `ecp.h` | `mbedtls_ecp_` | [Asymmetric cryptography](#asymmetric-cryptography) |
+| `entropy.h` | `mbedtls_entropy_` | [Random generation interface](#random-generation-interface), [Entropy sources](#entropy-sources) |
+| `error.h` | `mbedtls_*err*` | [Error messages](#error-messages) |
+| `gcm.h` | `mbedtls_gcm_` | [Symmetric encryption](#symmetric-encryption), [Authenticated cipher operations](#authenticated-cipher-operations) |
+| `hkdf.h` | `mbedtls_hkdf_` | [HKDF](#hkdf) |
+| `hmac_drbg.h` | `mbedtls_hmac_drbg_` | [Random generation interface](#random-generation-interface), [Deterministic pseudorandom generation](#deterministic-pseudorandom-generation) |
+| `lms.h` | `mbedtls_lms_` | No change ([LMS signatures](#lms-signatures)) |
+| `mbedtls_config.h` | `MBEDTLS_` | [Compile-time configuration](#compile-time-configuration) |
+| `md.h` | `mbedtls_md_` | [Hashes and MAC](#hashes-and-mac) |
+| `md5.h` | `mbedtls_md5_` | [Hashes and MAC](#hashes-and-mac) |
+| `memory_buffer_alloc.h` | `mbedtls_memory_buffer_alloc_` | No change (not a crypto API) |
+| `net_sockets.h` | `mbedtls_net_` | No change (not a crypto API) |
+| `nist_kw.h` | `mbedtls_nist_kw_` | Migration path not yet defined |
+| `oid.h` | `mbedtls_oid_` | No change ([PK support interface](#pk-format-support-interfaces)) |
+| `pem.h` | `mbedtls_pem_` | No change ([PK support interface](#pk-format-support-interfaces)) |
+| `pk.h` | `mbedtls_pk_` | [Asymmetric cryptography](#asymmetric-cryptography) |
+| `pkcs5.h` | `mbedtls_pkcs5_` | [PKCS#5 module](#pkcs5-module) |
+| `pkcs7.h` | `mbedtls_pkcs7_` | No change (not a crypto API) |
+| `pkcs12.h` | `mbedtls_pkcs12_` | [PKCS#12 module](#pkcs12-module) |
+| `platform.h` | `mbedtls_platform_` | No change (not a crypto API) |
+| `platform_time.h` | `mbedtls_*time*` | No change (not a crypto API) |
+| `platform_util.h` | `mbedtls_platform_` | No change (not a crypto API) |
+| `poly1305.h` | `mbedtls_poly1305_` | None (but there is Chacha20-Poly1305 [AEAD](#symmetric-encryption)) |
+| `private_access.h` | N/A | No public APIs (internal support header) |
+| `psa_util.h` | N/A | No public APIs (internal support header) |
+| `ripemd160.h` | `mbedtls_ripemd160_` | [Hashes and MAC](#hashes-and-mac) |
+| `rsa.h` | `mbedtls_rsa_` | [Asymmetric cryptography](#asymmetric-cryptography) |
+| `sha1.h` | `mbedtls_sha1_` | [Hashes and MAC](#hashes-and-mac) |
+| `sha3.h` | `mbedtls_sha3_` | [Hashes and MAC](#hashes-and-mac) |
+| `sha256.h` | `mbedtls_sha256_` | [Hashes and MAC](#hashes-and-mac) |
+| `sha512.h` | `mbedtls_sha512_` | [Hashes and MAC](#hashes-and-mac) |
+| `ssl.h` | `mbedtls_ssl_` | No change (not a crypto API) |
+| `ssl_cache.h` | `mbedtls_ssl_cache_` | No change (not a crypto API) |
+| `ssl_ciphersuites.h` | `mbedtls_ssl_ciphersuite_` | No change (not a crypto API) |
+| `ssl_cookie.h` | `mbedtls_ssl_cookie_` | No change (not a crypto API) |
+| `ssl_ticket.h` | `mbedtls_ssl_ticket_` | No change (not a crypto API) |
+| `threading.h` | `mbedtls_threading_` | No change (not a crypto API) |
+| `timing.h` | `mbedtls_timing_` | No change (not a crypto API) |
+| `version.h` | `mbedtls_version_` | No change (not a crypto API) |
+| `x509.h` | `mbedtls_x509` | No change (not a crypto API) |
+| `x509_crl.h` | `mbedtls_x509` | No change (not a crypto API) |
+| `x509_crt.h` | `mbedtls_x509` | No change (not a crypto API) |
+| `x509_csr.h` | `mbedtls_x509` | No change (not a crypto API) |
+
+## Compile-time configuration
+
+### Cryptographic mechanism availability
+
+**This section only applies if `MBEDTLS_PSA_CRYPTO_CONFIG` is enabled.** This option is disabled in the default configuration.
+
+When the configuration option [`MBEDTLS_PSA_CRYPTO_CONFIG`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1a5aca5ddcffb586acad82f9aef26db056) is enabled, the cryptographic mechanisms available through the PSA API are determined by the contents of the header file `"psa/crypto_config.h"`. You can override the file location with the macro [`MBEDTLS_PSA_CRYPTO_CONFIG_FILE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1a25f7e358caa101570cb9519705c2b873), and you can set [`MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1abd1870cc0d2681183a3018a7247cb137) to the path of an additional file (similar to `MBEDTLS_CONFIG_FILE` and `MBEDTLS_USER_CONFIG_FILE` for legacy configuration symbols).
+
+The availability of cryptographic mechanisms in the PSA API is based on a systematic pattern:
+
+* To make `PSA_ALG_aaa` available, enable `PSA_WANT_ALG_aaa`.
+ For parametrized algorithms, there is a `PSA_WANT_` symbol both for the main macro and for each argument. For example, to make `PSA_ALG_HMAC(PSA_ALG_SHA_256)` available, enable both `PSA_WANT_ALG_HMAC` and `PSA_WANT_ALG_SHA_256`.
+
+* To make `PSA_KEY_TYPE_ttt` available, enable `PSA_WANT_KEY_TYPE_ttt`.
+
+ As an exception, starting in Mbed TLS 3.5.0, for key pair types, the feature selection is more fine-grained, with an additional suffix:
+ * `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_BASIC` enables basic support for the key type, and in particular support for operations with a key of that type for enabled algorithms. This is automatically enabled if any of the other `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_yyy` options are enabled.
+ * `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_IMPORT` enables support for `psa_import_key` to import a key of that type.
+ * `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_GENERATE` enables support for `psa_generate_key` to randomly generate a key of that type.
+ * `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_DERIVE` enables support for `psa_key_derivation_output_key` to deterministically derive a key of that type.
+ * `PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_EXPORT` enables support for `psa_export_key` to export a key of that type.
+
+ Enabling any support for a key pair type automatically enables support for the corresponding public key type, as well as support for `psa_export_public_key` on the private key.
+
+* To make `PSA_ECC_FAMILY_fff` available for size sss, enable `PSA_WANT_ECC_fff_sss`.
+
+Note that all `PSA_WANT_xxx` symbols must be set to a non-zero value. In particular, setting `PSA_WANT_xxx` to an empty value may not be handled consistently.
+
+For example, the following configuration enables hashing with SHA-256, AEAD with AES-GCM, signature with deterministic ECDSA using SHA-256 on the curve secp256r1 using a randomly generated key as well as the corresponding verification, and ECDH key exchange on secp256r1 and Curve25519.
+
+```
+#define PSA_WANT_ALG_SHA_256 1
+
+#define PSA_WANT_KEY_TYPE_AES 1
+#define PSA_WANT_ALG_GCM 1
+
+#define PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE 1
+// ^^ In Mbed TLS <= 3.4, enable PSA_WANT_KEY_TYPE_ECC_KEY_PAIR instead
+// ^^ implicitly enables PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_BASIC, PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY
+#define PSA_WANT_ECC_SECP_R1_256 1 // secp256r1 (suitable for ECDSA and ECDH)
+#define PSA_WANT_ECC_MONTGOMERY_255 1 // Curve25519 (suitable for ECDH)
+#define PSA_WANT_ALG_DETERMINISTIC_ECDSA 1
+#define PSA_WANT_ALG_ECDH
+```
+
+If a mechanism is not enabled by `PSA_WANT_xxx`, Mbed TLS will normally not include it. This allows builds that use few features to have a small code size. However, this is not guaranteed: a mechanism that is not explicitly requested can be enabled because it is a dependency of another configuration option, because it is used internally, or because the granularity is not fine enough to distinguish between it and another mechanism that is requested.
+
+Under the hood, `PSA_WANT_xxx` enables the necessary legacy modules. Note that if a mechanism has a PSA accelerator driver, the corresponding legacy module is typically not needed. Thus applications that use a cryptographic mechanism both through the legacy API and through the PSA API need to explicitly enable both the `PSA_WANT_xxx` symbols and the `MBEDTLS_xxx` symbols.
+
+### Optimization options
+
+When PSA Crypto mechanisms are implemented by the built-in code from Mbed TLS, the legacy optimization options (e.g. `MBEDTLS_SHA256_SMALLER`, `MBEDTLS_ECP_WINDOW_SIZE`, etc.) apply to the PSA implementation as well (they invoke the same code under the hood).
+
+The PSA Crypto API may use accelerator drivers. In this case any options controlling the driver behavior are driver-specific.
+
+### Alternative implementations (`MBEDTLS_xxx_ALT` options)
+
+In the Mbed TLS legacy interface, you can replace some cryptographic primitives and modes by an alternative implementation, by enabling configuration options of the form `MBEDTLS_xxx_ALT` and linking with your own implementation of the affected function or module. Alternative implementations remain supported in Mbed TLS 3.x even if the application code uses the PSA API. However, they will be removed from the next version of the library.
+
+The corresponding PSA feature is accelerator drivers. To implement an accelerator driver, see the [PSA cryptoprocessor driver example and guide](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/psa-driver-example-and-guide.md). In an application that uses both the legacy interface and the PSA interface for the same mechanism, only some algorithms support calling a PSA driver from the legacy interface. See the [Guide to driver-only builds](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/driver-only-builds.md) for more information.
+
+### Self-tests
+
+There is currently [no PSA equivalent to the self-tests](https://github.com/Mbed-TLS/mbedtls/issues/7781) enabled by `MBEDTLS_SELF_TEST`.
+
+## Miscellaneous support modules
+
+### Error messages
+
+At the time of writing, there is no equivalent to the error messages provided by `mbedtls_strerror`. However, you can use the companion program `programs/psa/psa_constant_names` to convert various numbers (`psa_status_t`, `psa_algorithm_t`, `psa_key_type_t`, `psa_ecc_family_t`, `psa_dh_family_t`, `psa_key_usage_t`) to a programmer-friendly representation. The conversion doesn't depend on the library configuration or the target platform, so you can use a native build of this program even if you cross-compile your application.
+
+```
+$ programs/psa/psa_constant_names error -138
+PSA_ERROR_BUFFER_TOO_SMALL
+$ programs/psa/psa_constant_names type 0x7112
+PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)
+$ programs/psa/psa_constant_names alg 0x06000609
+PSA_ALG_ECDSA(PSA_ALG_SHA_256)
+```
+
+The other functions in `error.h` are specific to the construction of Mbed TLS error code and are not relevant to the PSA API. PSA error codes are never the combination of multiple codes.
+
+### Constant-time functions
+
+The PSA API does not have an equivalent to the timing-side-channel-resistance utility functions in `constant_time.h`. Continue using `constant_time.h` as needed.
+
+Note that the PSA API does include features that reduce the need for `mbedtls_ct_memcmp`:
+
+* To compare a MAC with a reference value, use `psa_mac_verify` rather than `psa_mac_compute` followed by `mbedtls_ct_memcmp`, or use `psa_mac_verify_setup` and `psa_mac_verify_finish` in the multi-part case. See “[MAC calculation](#mac-calculation)”.
+* The AEAD decryption functions take care of verifying the tag. See “[Authenticated cipher operations](#authenticated-cipher-operations)”.
+
+## Symmetric encryption
+
+All PSA APIs have algorithm agility, where the functions depend only on the nature of the operation and the choice of a specific algorithm comes from an argument. There is no special API for a particular block cipher (`aes.h`, `aria.h`, `camellia.h`, `des.h`), a particular block cipher mode (`ccm.h`, `gcm.h`) or a particular stream cipher (`chacha20.h`, `chachapoly.h`). To migrate code using those low-level modules, please follow the recommendations in the following sections, using the same principles as the corresponding `cipher.h` API.
+
+### Cipher mechanism selection
+
+Instead of `mbedtls_cipher_id_t` (`MBEDTLS_CIPHER_ID_xxx` constants), `mbedtls_cipher_type_t` (`MBEDTLS_CIPHER_base_size_mode` constants), `mbedtls_cipher_mode_t` (`MBEDTLS_CIPHER_MODE_xxx` constants) and `mbedtls_cipher_padding_t` (`MBEDTLS_CIPHER_PADDING_xxx` constants), use the [`PSA_KEY_TYPE_xxx` and `PSA_ALG_xxx` constants](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/).
+
+For modes that are based on a block cipher, the key type encodes the choice of block cipher:
+[`PSA_KEY_TYPE_AES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga6ee54579dcf278c677eda4bb1a29575e),
+[`PSA_KEY_TYPE_ARIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#c.PSA_KEY_TYPE_ARIA),
+[`PSA_KEY_TYPE_CAMELLIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gad8e5da742343fd5519f9d8a630c2ed81),
+[`PSA_KEY_TYPE_DES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga577562bfbbc691c820d55ec308333138).
+The algorithm encodes the mode and if relevant the padding type:
+
+* Unauthenticated cipher modes:
+ [`PSA_ALG_CTR`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gad318309706a769cffdc64e4c7e06b2e9),
+ [`PSA_ALG_CFB`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga0088c933e01d671f263a9a1f177cb5bc),
+ [`PSA_ALG_OFB`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gae96bb421fa634c6fa8f571f0112f1ddb),
+ [`PSA_ALG_XTS`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gaa722c0e426a797fd6d99623f59748125),
+ [`PSA_ALG_ECB_NO_PADDING`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gab8f0609cd0f12cccc9c950fd5a81a0e3),
+ [`PSA_ALG_CBC_NO_PADDING`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gacb332d72716958880ee7f97d8365ae66),
+ [`PSA_ALG_CBC_PKCS7`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gaef50d2e9716eb6d476046608e4e0c78c),
+ [`PSA_ALG_CCM_STAR_NO_TAG`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga89627bb27ec3ce642853ab8554a88572).
+* Other padding modes, which are obsolete, are not available in the PSA API. If you need them, handle the padding in your application code and use the `NO_PADDING` algorithm.
+* AEAD modes:
+ [`PSA_ALG_CCM`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac2c0e7d21f1b2df5e76bcb4a8f84273c),
+ [`PSA_ALG_GCM`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga0d7d02b15aaae490d38277d99f1c637c).
+* KW/KWP modes are not available in the PSA API at the time of writing.
+
+For the ChaCha20 unauthenticated cipher, use [`PSA_KEY_TYPE_CHACHA20`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga901548883b3bce56cc21c3a22cf8d93c) with [`PSA_ALG_STREAM_CIPHER`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gad98c105198f7428f7d1dffcb2cd398cd).
+For the Chacha20+Poly1305 AEAD, use [`PSA_KEY_TYPE_CHACHA20`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga901548883b3bce56cc21c3a22cf8d93c) with [`PSA_ALG_CHACHA20_POLY1305`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga1fec55093541640a71bdd022d4adfb9c)
+
+### Cipher mechanism availability
+
+For each key type value `PSA_KEY_TYPE_xxx`, the symbol `PSA_WANT_KEY_TYPE_xxx` is defined with a non-zero value if the library is built with support for that key type. For each algorithm value `PSA_ALG_yyy`, the symbol `PSA_WANT_ALG_yyy` is defined with a non-zero value if the library is built with support for that algorithm. Note that for a mechanism to be supported, both the key type and the algorithm must be supported.
+
+For example, to test if AES-CBC-PKCS7 is supported, in the legacy API, you could write:
+```
+#if defined(MBEDTLS_AES_C) && \
+ defined(MBEDTLS_CIPHER_MODE_CBC) && defined(MBEDTLS_CIPHER_PADDING_PKCS7)
+```
+The equivalent in the PSA API is
+```
+#if PSA_WANT_KEY_TYPE_AES && PSA_WANT_ALG_CBC_PKCS7
+```
+
+### Cipher metadata
+
+Both APIs express key sizes in bits. Note however that in the PSA API, the size of a _buffer_ is always expressed in bytes, even if that buffer contains a key.
+
+The following table lists corresponding PSA macros for maximum-size macros that take all supported algorithms into account.
+
+| Legacy macro | PSA macro |
+| ------------ | --------- |
+| `MBEDTLS_MAX_IV_LENGTH` | [`PSA_CIPHER_IV_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_IV_MAX_SIZE), [`PSA_AEAD_NONCE_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#crypto__sizes_8h_1ac2a332765ba4ccfc24935d6f7f48fcc7) |
+| `MBEDTLS_MAX_BLOCK_LENGTH` | [`PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE) |
+| `MBEDTLS_MAX_KEY_LENGTH` | no equivalent|
+
+There is no equivalent to the type `mbedtls_cipher_info_t` and the functions `mbedtls_cipher_info_from_type` and `mbedtls_cipher_info_from_values` in the PSA API because it is unnecessary. All macros and functions operate directly on key type values (`psa_key_type_t`, `PSA_KEY_TYPE_xxx` constants) and algorithm values (`psa_algorithm_t`, `PSA_ALG_xxx` constants).
+
+| Legacy function | PSA macro |
+| --------------- | --------- |
+| `mbedtls_cipher_info_get_iv_size` | [`PSA_CIPHER_IV_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_IV_LENGTH), [`PSA_AEAD_NONCE_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_NONCE_LENGTH) |
+| `mbedtls_cipher_info_get_block_size` | not available (use specific macros for the IV, nonce or tag length) |
+
+The following features have no PSA equivalent:
+
+* `mbedtls_cipher_list`: the PSA API does not currently have a discovery mechanism for cryptographic mechanisms, but one may be added in the future.
+* `mbedtls_cipher_info_has_variable_key_bitlen`, `mbedtls_cipher_info_has_variable_iv_size`: the PSA API does not currently have such mechanism for high-level metadata information.
+* `mbedtls_cipher_info_from_string`: there is no equivalent of Mbed TLS's lookup based on a (nonstandard) name.
+
+### Cipher key management
+
+The legacy API and the PSA API have a different organization of operations in several respects:
+
+* In the legacy API, each operation object contains the necessary key material. In the PSA API, an operation object contains a reference to a key object. To perform a cryptographic operation, you must create a key object first. However, for a one-shot operation, you do not need an operation object, just a single function call.
+* The legacy API uses the same interface for authenticated and non-authenticated ciphers, while the PSA API has separate functions.
+* The legacy API uses the same functions for encryption and decryption, while the PSA API has separate functions where applicable.
+
+Here is an overview of the lifecycle of a key object.
+
+1. First define the attributes of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga0ec645e1fdafe59d591104451ebf5680). You need to set the following parameters:
+ * Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga6857ef0ecb3fa844d4536939d9c64025) to set the key type to the desired `PSA_KEY_TYPE_xxx` value (see “[Cipher mechanism selection](#cipher-mechanism-selection)”).
+ * Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaf61683ac87f87687a40262b5afbfa018) to set the key's size in bits. This is optional with `psa_import_key`, which determines the key size from the length of the key material.
+ * Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaeb8341ca52baa0279475ea3fd3bcdc98) to set the algorithm to the desired `PSA_ALG_xxx` value (see “[Cipher mechanism selection](#cipher-mechanism-selection)”). By design, the same key cannot be used with multiple algorithms.
+ * Call [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de) to enable at least [`PSA_KEY_USAGE_ENCRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#c.PSA_KEY_USAGE_ENCRYPT) or [`PSA_KEY_USAGE_DECRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#c.PSA_KEY_USAGE_DECRYPT), depending on which direction you want to use the key in. To allow both directions, use the flag mask `PSA_KEY_USAGE_DECRYPT | PSA_KEY_USAGE_ENCRYPT`. The same policy flags cover authenticated and non-authenticated encryption/decryption.
+2. Call one of the key creation functions, passing the attributes defined in the previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv412psa_key_id_t) to the key object.
+ * Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b) to directly import key material.
+ * If the key is randomly generated, use [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5).
+ * If the key is derived from other material (for example from a key exchange), use the [key derivation interface](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the key with [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gada7a6e17222ea9e7a6be6864a00316e1).
+3. Call the functions in the following sections to perform operations on the key. The same key object can be used in multiple operations.
+4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) after all operations with that key are finished.
+
+### Unauthenticated cipher operations
+
+Recall the workflow of an unauthenticated cipher operation in the legacy Mbed TLS cipher API:
+
+1. Create a cipher context of type `mbedtls_cipher_context_t` and initialize it with `mbedtls_cipher_init`.
+2. Establish the operation parameters (algorithm, key, mode) with `mbedtls_cipher_setup`, `mbedtls_cipher_setkey` (or `mbedtls_cipher_setup_psa`), `mbedtls_cipher_set_padding_mode` if applicable.
+3. Set the IV with `mbedtls_cipher_set_iv` (except for ECB which does not use an IV).
+4. For a one-shot operation, call `mbedtls_cipher_crypt`. To pass the input in multiple parts, call `mbedtls_cipher_update` as many times as necessary followed by `mbedtls_cipher_finish`.
+5. Finally free the resources associated with the operation object by calling `mbedtls_cipher_free`.
+
+For a one-shot operation (where the whole plaintext or ciphertext is passed as a single input), the equivalent workflow with the PSA API is to call a single function:
+
+* [`psa_cipher_encrypt`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga61f02fbfa681c2659546eca52277dbf1) to perform encryption with a random IV of the default size (indicated by [`PSA_CIPHER_IV_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_IV_LENGTH)). (To encrypt with a specified IV, use the multi-part API described below.) You can use the macro [`PSA_CIPHER_ENCRYPT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE) or [`PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+* [`psa_cipher_decrypt`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gab3593f5f14d8c0431dd306d80929215e) to perform decryption with a specified IV. You can use the macro [`PSA_CIPHER_DECRYPT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE) or [`PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+
+For a multi-part operation, the equivalent workflow with the PSA API is as follows:
+
+1. Create an operation object of type [`psa_cipher_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga1399de29db657e3737bb09927aae51fa) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Select the key and algorithm with [`psa_cipher_encrypt_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga587374c0eb8137a572f8e2fc409bb2b4) or [`psa_cipher_decrypt_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gaa4ba3a167066eaef2ea49abc5dcd1d4b) depending on the desired direction.
+3. When encrypting with a random IV, use [`psa_cipher_generate_iv`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga29fd7d32a5729226a2f73e7b6487bd8a). When encrypting with a chosen IV, or when decrypting, set the IV with [`psa_cipher_set_iv`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga9caddac1a429a5032d6d4a907fb70ba1). Skip this step with ECB since it does not use an IV.
+4. Call [`psa_cipher_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gac3ca27ac6682917c48247d01fd96cd0f) as many times as needed. You can use [`PSA_CIPHER_UPDATE_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE) or [`PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#crypto__sizes_8h_1ab1f6598efd6a7dc56e7ad7e34719eb32) to determine a sufficient size for the output buffer.
+5. Call [`psa_cipher_finish`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga1dcb58b8befe23f8a4d7a1d49c99249b) to obtain the last part of the output. You can use [`PSA_CIPHER_FINISH_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_FINISH_OUTPUT_SIZE) or [`PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+
+If you need to interrupt the operation after calling the setup function without calling the finish function, call [`psa_cipher_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gaad482cdca2098bca0620596aaa02eaa4).
+
+### Authenticated cipher operations
+
+Recall the workflow of an authenticated cipher operation in the legacy Mbed TLS cipher API (or similar workflows in the `chachapoly`, `ccm` and `gcm` modules):
+
+1. Create a cipher context of type `mbedtls_cipher_context_t` and initialize it with `mbedtls_cipher_init`.
+2. Establish the operation parameters (algorithm, key, mode) with `mbedtls_cipher_setup`, `mbedtls_cipher_setkey` (or `mbedtls_cipher_setup_psa`), `mbedtls_cipher_set_padding_mode` if applicable.
+3. Set the nonce with `mbedtls_cipher_set_iv` (or the `starts` function for low-level modules). For CCM, which requires direct use of the `ccm` module, also call `mbedtls_ccm_set_lengths` to set the length of the additional data and of the plaintext.
+4. Call `mbedtls_cipher_update_ad` to pass the unencrypted additional data.
+5. Call `mbedtls_cipher_update` as many times as necessary to pass the input plaintext or ciphertext.
+6. Call `mbedtls_cipher_finish` to obtain the last part of the output. Then call `mbedtls_cipher_write_tag` (when encrypting) or `mbedtls_cipher_check_tag` (when decrypting) to process the authentication tag.
+7. Finally free the resources associated with the operation object by calling `mbedtls_cipher_free`.
+
+Steps 3–6 can be replaced by a single call to `mbedtls_cipher_auth_encrypt_ext` or `mbedtls_cipher_auth_decrypt_ext` for a one-shot operation (where the whole plaintext or ciphertext is passed as a single input).
+
+For a one-shot operation, the PSA API allows you to call a single function:
+
+* [`psa_aead_encrypt`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae72e1eb3c2da3ebd843bb9c8db8df509) to perform authenticated encryption with a random nonce of the default size (indicated by [`PSA_AEAD_NONCE_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_NONCE_LENGTH)), with the authentication tag written at the end of the output. (To encrypt with a specified nonce, or to separate the tag from the rest of the ciphertext, use the multi-part API described below.) You can use the macro [`PSA_AEAD_ENCRYPT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE) or [`PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+* [`psa_aead_decrypt`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae799f6196a22d50c216c947e0320d3ba) to perform authenticated decryption of a ciphertext with the authentication tag at the end. (If the tag is separate, use the multi-part API described below.) You can use the macro [`PSA_AEAD_DECRYPT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE) or [`PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+
+For a multi-part operation, the equivalent workflow with the PSA API is as follows:
+
+1. Create an operation object of type [`psa_aead_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga14f6a01afbaa8c5b3d8c5d345cbaa3ed) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Select the key and algorithm with [`psa_aead_encrypt_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga2732c40ce8f3619d41359a329e9b46c4) or [`psa_aead_decrypt_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gaaa5c5018e67a7a6514b7e76b9a14de26) depending on the desired direction.
+3. When encrypting with a random nonce, use [`psa_aead_generate_nonce`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga5799df1c555efd35970b65be51cb07d1). When encrypting with a chosen nonce, or when decrypting, set the nonce with [`psa_aead_set_nonce`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga59132751a6f843d038924cb217b5e13b). If the algorithm is CCM, you must also call [`psa_aead_set_lengths`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gad3431e28d05002c2a7b0760610176050) before or after setting the nonce (for other algorithms, this is permitted but not needed).
+4. Call [`psa_aead_update_ad`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga6d0eed03f832e5c9c91cb8adf2882569) as many times as needed.
+5. Call [`psa_aead_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gaf6d49864951ca42136b4a9b71ea26e5c) as many times as needed. You can use [`PSA_AEAD_UPDATE_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_UPDATE_OUTPUT_SIZE) or [`PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+6. Finally:
+ * When encrypting, call [`psa_aead_finish`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga759791bbe1763b377c3b5447641f1fc8) to obtain the last part of the ciphertext and the authentication tag. You can use [`PSA_AEAD_FINISH_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_FINISH_OUTPUT_SIZE) or [`PSA_AEAD_FINISH_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+ * When decrypting, call [`psa_aead_verify`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae0280e2e61a185b893c36d858453f0d0) to obtain the last part of the plaintext and check the authentication tag. You can use [`PSA_AEAD_VERIFY_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_VERIFY_OUTPUT_SIZE) or [`PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+
+If you need to interrupt the operation after calling the setup function without calling the finish or verify function, call [`psa_aead_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae8a5f93d92318c8f592ee9fbb9d36ba0).
+
+### Miscellaneous cipher operation management
+
+The equivalent of `mbedtls_cipher_reset` is to call [`psa_cipher_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gaad482cdca2098bca0620596aaa02eaa4) or [`psa_aead_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae8a5f93d92318c8f592ee9fbb9d36ba0). Note that you must set the key again with a setup function: the PSA API does not have a special way to reuse an operation object with the same key.
+
+There is no equivalent for the `mbedtls_cipher_get_xxx` functions to extract information from an ongoing PSA cipher or AEAD operation. Applications that need this information will need to save it from the key and operation parameters.
+
+## Hashes and MAC
+
+The PSA API groups functions by purpose rather than by underlying primitive: there is a MAC API (equivalent to `md.h` for HMAC, and `cmac.h` for CMAC) and a hash API (equivalent to `md.h` for hashing). There is no special API for a particular hash algorithm (`md5.h`, `sha1.h`, `sha256.h`, `sha512.h`, `sha3.h`). To migrate code using those low-level modules, please follow the recommendations in the following section, using the same principles as the corresponding `md.h` API.
+
+The PSA API does not have a direct interface for the AES-CMAC-PRF-128 algorithm from RFC 4615 calculated by `mbedtls_aes_cmac_prf_128` at the time of writing. You can implement it using the MAC interface with an AES key and the CMAC algorithm.
+
+### Hash mechanism selection
+
+The equivalent to `mbedtls_md_type_t` and `MBEDTLS_MD_XXX` constants is the type `psa_algorithm_t` and `PSA_ALG_xxx` constants (the type encompasses all categories of cryptographic algorithms, not just hashes). PSA offers a similar selection of algorithms, but note that SHA-1 and SHA-2 are spelled slightly differently.
+
+| Mbed TLS constant | PSA constant |
+| ---------------------- | ------------------- |
+| `MBEDTLS_MD_MD5` | `PSA_ALG_MD5` |
+| `MBEDTLS_MD_SHA1` | `PSA_ALG_SHA_1` |
+| `MBEDTLS_MD_SHA224` | `PSA_ALG_SHA_224` |
+| `MBEDTLS_MD_SHA256` | `PSA_ALG_SHA_256` |
+| `MBEDTLS_MD_SHA384` | `PSA_ALG_SHA_384` |
+| `MBEDTLS_MD_SHA512` | `PSA_ALG_SHA_512` |
+| `MBEDTLS_MD_RIPEMD160` | `PSA_ALG_RIPEMD160` |
+| `MBEDTLS_MD_SHA3_224` | `PSA_ALG_SHA3_224` |
+| `MBEDTLS_MD_SHA3_256` | `PSA_ALG_SHA3_256` |
+| `MBEDTLS_MD_SHA3_384` | `PSA_ALG_SHA3_384` |
+| `MBEDTLS_MD_SHA3_512` | `PSA_ALG_SHA3_512` |
+
+The following helper functions can be used to convert between the 2 types:
+- `mbedtls_md_psa_alg_from_type()` converts from legacy `mbedtls_md_type_t` to PSA's `psa_algorithm_t`.
+- `mbedtls_md_type_from_psa_alg()` converts from PSA's `psa_algorithm_t` to legacy `mbedtls_md_type_t`.
+
+### MAC mechanism selection
+
+PSA Crypto has a generic API with the same functions for all MAC mechanisms. The mechanism is determined by a combination of an algorithm value of type [`psa_algorithm_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac2e4d47f1300d73c2f829a6d99252d69) and a key type value of type [`psa_key_type_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga63fce6880ca5933b5d6baa257febf1f6).
+
+* For HMAC, the algorithm is [`PSA_ALG_HMAC`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga70f397425684b3efcde1e0e34c28261f)`(hash)` where `hash` is the underlying hash algorithm (see “[Hash mechanism selection](#hash-mechanism-selection)”),
+ for example `PSA_ALG_HMAC(PSA_ALG_SHA_256)` for HMAC-SHA-256.
+ The key type is [`PSA_KEY_TYPE_HMAC`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__values_8h/#c.PSA_KEY_TYPE_HMAC) regardless of the hash algorithm.
+* For CMAC, the algorithm is [`PSA_ALG_CMAC`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__values_8h/#c.PSA_ALG_CMAC) regardless of the underlying block cipher. The key type determines the block cipher:
+ [`PSA_KEY_TYPE_AES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga6ee54579dcf278c677eda4bb1a29575e),
+ [`PSA_KEY_TYPE_ARIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#c.PSA_KEY_TYPE_ARIA),
+ [`PSA_KEY_TYPE_CAMELLIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gad8e5da742343fd5519f9d8a630c2ed81) or
+ [`PSA_KEY_TYPE_DES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga577562bfbbc691c820d55ec308333138).
+
+### Hash and MAC mechanism availability
+
+For each key type value `PSA_KEY_TYPE_xxx`, the symbol `PSA_WANT_KEY_TYPE_xxx` is defined with a non-zero value if the library is built with support for that key type. For each algorithm value `PSA_ALG_yyy`, the symbol `PSA_WANT_ALG_yyy` is defined with a non-zero value if the library is built with support for that algorithm. For a compound mechanism, all parts must be supported. In particular, for HMAC, all three of `PSA_WANT_KEY_TYPE_HMAC`, `PSA_WANT_ALG_HMAC` and the underlying hash must be enabled. (A configuration with only one of `PSA_WANT_KEY_TYPE_HMAC` and `PSA_WANT_ALG_HMAC` is technically possible but not useful.)
+
+For example, to test if HMAC-SHA-256 is supported, in the legacy API, you could write:
+```
+#if defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA256_C)
+```
+The equivalent in the PSA API is
+```
+#if PSA_WANT_KEY_TYPE_HMAC && PSA_WANT_ALG_HMAC && PSA_WANT_ALG_SHA_256
+```
+
+To test if AES-CMAC is supported, in the legacy API, you could write:
+```
+if defined(MBEDTLS_AES_C) && defined(MBEDTLS_CMAC_C)
+```
+The equivalent in the PSA API is
+```
+#if PSA_WANT_KEY_TYPE_AES && PSA_WANT_ALG_CMAC
+```
+
+### Hash algorithm metadata
+
+There is no equivalent to the type `mbedtls_md_info_t` and the functions `mbedtls_md_info_from_type` and `mbedtls_md_get_type` in the PSA API because it is unnecessary. All macros and functions operate directly on algorithm (`psa_algorithm_t`, `PSA_ALG_xxx` constants).
+
+| Legacy macro | PSA macro |
+| ------------ | --------- |
+| `MBEDTLS_MD_MAX_SIZE` | [`PSA_HASH_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_HASH_MAX_SIZE) |
+| `MBEDTLS_MD_MAX_BLOCK_SIZE` | [`PSA_HMAC_MAX_HASH_BLOCK_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_HMAC_MAX_HASH_BLOCK_SIZE) |
+| `mbedtls_md_get_size` | [`PSA_HASH_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_HASH_LENGTH) |
+| `mbedtls_md_get_size_from_type` | [`PSA_HASH_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_HASH_LENGTH) |
+
+The following features have no PSA equivalent:
+
+* `mbedtls_md_list`: the PSA API does not currently have a discovery mechanism for cryptographic mechanisms, but one may be added in the future.
+* `mbedtls_md_info_from_ctx`
+* `mbedtls_cipher_info_from_string`, `mbedtls_md_get_name`: there is no equivalent of Mbed TLS's lookup based on a (nonstandard) name.
+
+### Hash calculation
+
+The equivalent of `mbedtls_md` for a one-shot hash calculation is [`psa_hash_compute`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1gac69f7f19d96a56c28cf3799d11b12156). In addition, to compare the hash of a message with an expected value, you can call [`psa_hash_compare`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga0c08f4797bec96b886c8c8d7acc2a553) instead of `mbedtls_md` followed by `memcmp` or a constant-time equivalent.
+
+For a multi-part hash calculation, the legacy process is as follows:
+
+1. Create a digest context of type `mbedtls_md_context_t` and initialize it with `mbedtls_md_init`.
+2. Call `mbedtls_md_setup` to select the hash algorithm, with `hmac=0`. Then call `mbedtls_md_starts` to start the hash operation.
+3. Call `mbedtls_md_update` as many times as necessary.
+4. Call `mbedtls_md_finish`. If verifying the hash against an expected value, compare the result with the expected value.
+5. Finally free the resources associated with the operation object by calling `mbedtls_md_free`.
+
+The equivalent process in the PSA API is as follows:
+
+1. Create an operation object of type [`psa_hash_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga3c4205d2ce66c4095fc5c78c25273fab) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_hash_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga8d72896cf70fc4d514c5c6b978912515) to specify the algorithm.
+3. Call [`psa_hash_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga65b16ef97d7f650899b7db4b7d1112ff) as many times as necessary.
+4. To obtain the hash, call [`psa_hash_finish`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga4795fd06a0067b0adcd92e9627b8c97e). Alternatively, to verify the hash against an expected value, call [`psa_hash_verify`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga7be923c5700c9c70ef77ee9b76d1a5c0).
+
+If you need to interrupt the operation after calling the setup function without calling the finish or verify function, call [`psa_hash_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1gab0b4d5f9912a615559497a467b532928).
+
+There is no equivalent to `mbedtls_md_file` in the PSA API. Load the file data and calculate its hash.
+
+### MAC key management
+
+The legacy API and the PSA API have a different organization of operations in several respects:
+
+* In the legacy API, each operation object contains the necessary key material. In the PSA API, an operation object contains a reference to a key object. To perform a cryptographic operation, you must create a key object first. However, for a one-shot operation, you do not need an operation object, just a single function call.
+* The legacy API uses the same interface for authenticated and non-authenticated ciphers, while the PSA API has separate functions.
+* The legacy API uses the same functions for encryption and decryption, while the PSA API has separate functions where applicable.
+
+Here is an overview of the lifecycle of a key object.
+
+1. First define the attributes of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga0ec645e1fdafe59d591104451ebf5680). You need to set the following parameters:
+ * Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga6857ef0ecb3fa844d4536939d9c64025) to set the key type to the desired `PSA_KEY_TYPE_xxx` value (see “[Cipher mechanism selection](#cipher-mechanism-selection)”).
+ * Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaf61683ac87f87687a40262b5afbfa018) to set the key's size in bits. This is optional with `psa_import_key`, which determines the key size from the length of the key material.
+ * Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaeb8341ca52baa0279475ea3fd3bcdc98) to set the algorithm to the desired `PSA_ALG_xxx` value (see “[Cipher mechanism selection](#cipher-mechanism-selection)”). By design, the same key cannot be used with multiple algorithms.
+ * Call [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de) to enable at least [`PSA_KEY_USAGE_SIGN_MESSAGE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#c.PSA_KEY_USAGE_SIGN_MESSAGE) to calculate a MAC or [`PSA_KEY_USAGE_VERIFY_MESSAGE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#c.PSA_KEY_USAGE_VERIFY_MESSAGE) to verify the MAC of a message. To allow both directions, use the flag mask `PSA_KEY_USAGE_SIGN_MESSAGE | PSA_KEY_USAGE_VERIFY_MESSAGE`.
+2. Call one of the key creation functions, passing the attributes defined in the previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv412psa_key_id_t) to the key object.
+ * Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b) to directly import key material.
+ * If the key is randomly generated, use [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5).
+ * If the key is derived from other material (for example from a key exchange), use the [key derivation interface](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the key with [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gada7a6e17222ea9e7a6be6864a00316e1).
+3. Call the functions in the following sections to perform operations on the key. The same key object can be used in multiple operations.
+4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) after all operations with that key are finished.
+
+### MAC calculation
+
+The process for a HMAC operation in the legacy API is as follows:
+
+1. Create a digest context of type `mbedtls_md_context_t` and initialize it with `mbedtls_md_init`.
+2. Call `mbedtls_md_setup` to select the hash algorithm, with `hmac=1`. Then call `mbedtls_md_hmac_starts` to set the key.
+3. Call `mbedtls_md_hmac_update` as many times as necessary.
+4. Call `mbedtls_md_hmac_finish`. If verifying the MAC against an expected value, compare the result with the expected value. Note that this comparison should be in constant time to avoid a side channel vulnerability, for example using `mbedtls_ct_memcmp`.
+5. Finally free the resources associated with the operation object by calling `mbedtls_md_free`.
+
+The process for a CMAC operation in the legacy API is as follows:
+
+1. Create a cipher context of type `mbedtls_cipher_context_t` and initialize it with `mbedtls_cipher_init`.
+2. Call `mbedtls_cipher_setup` to select the block cipher. Then call `mbedtls_md_cmac_starts` to set the key.
+3. Call `mbedtls_cipher_cmac_update` as many times as necessary.
+4. Call `mbedtls_cipher_cmac_finish`. If verifying the MAC against an expected value, compare the result with the expected value. Note that this comparison should be in constant time to avoid a side channel vulnerability, for example using `mbedtls_ct_memcmp`.
+5. Finally free the resources associated with the operation object by calling `mbedtls_cipher_free`.
+
+The process in the PSA API to calculate a MAC is as follows:
+
+1. Create an operation object of type [`psa_mac_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1ga78f0838b0c4e3db28b26355624d4bd37) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_mac_sign_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1ga03bc3e3c0b7e55b20d2a238e418d46cd) to specify the algorithm and the key. See “[MAC key management](#mac-key-management)” for how to obtain a key identifier.
+3. Call [`psa_mac_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1ga5560af371497babefe03c9da4e8a1c05) as many times as necessary.
+4. To obtain the MAC, call [`psa_mac_sign_finish`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1gac22bc0125580c96724a09226cfbc97f2).
+
+To verify a MAC against an expected value, use the following process instead:
+
+1. Create an operation object of type [`psa_mac_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1ga78f0838b0c4e3db28b26355624d4bd37) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_mac_verify_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1ga08ae327fcbc5f8e201172fe11e536984) to specify the algorithm and the key. See “[MAC key management](#mac-key-management)” for how to obtain a key identifier.
+3. Call [`psa_mac_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1ga5560af371497babefe03c9da4e8a1c05) as many times as necessary.
+4. To verify the MAC against an expected value, call [`psa_mac_verify_finish`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1gac92b2930d6728e1be4d011c05d485822).
+
+If you need to interrupt the operation after calling the setup function without calling the finish function, call [`psa_mac_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1gacd8dd54855ba1bc0a03f104f252884fd).
+
+The PSA API also offers functions for a one-shot MAC calculation, similar to `mbedtls_cipher_cmac` and `mbedtls_md_hmac`:
+
+* [`psa_mac_compute`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1gabf02ebd3595ea15436967092b5d52878) to calculate the MAC of a buffer in memory.
+* [`psa_mac_verify`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1gaf6988545df5d5e2466c34d753443b15a) to verify the MAC of a buffer in memory against an expected value.
+
+In both cases, see “[MAC key management](#mac-key-management)” for how to obtain a key identifier.
+
+### Miscellaneous hash or MAC operation management
+
+The equivalent of `mbedtls_md_reset`, `mbedtls_md_hmac_reset` or `mbedtls_cmac_reset` is to call [`psa_hash_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1gab0b4d5f9912a615559497a467b532928) or [`psa_mac_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___m_a_c/#group___m_a_c_1gacd8dd54855ba1bc0a03f104f252884fd). Note that you must call a setup function to specify the algorithm and the key (for MAC) again, and they can be different ones.
+
+The equivalent of `mbedtls_md_clone` to clone a hash operation is [`psa_hash_clone`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga39673348f3302b4646bd780034a5aeda). A PSA MAC operation cannot be cloned.
+
+## Key derivation
+
+### HKDF
+
+PSA Crypto provides access to HKDF, HKDF-Extract and HKDF-Expand via its [key derivation interface](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/). This is a generic interface using an operation object with one function call for each input and one function call for each output.
+
+1. Create an operation object of type [`psa_key_derivation_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga5f099b63799a0959c3d46718c86c2609) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_key_derivation_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gac0b6a76e45cceb1862752bf041701859) to select the algorithm, which is a value of type [`psa_algorithm_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac2e4d47f1300d73c2f829a6d99252d69). For HKDF and variants, use one of the macros [`PSA_ALG_HKDF`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__values_8h/#c.PSA_ALG_HKDF), [`PSA_ALG_HKDF_EXTRACT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__values_8h/#c.PSA_ALG_HKDF_EXTRACT) or [`PSA_ALG_HKDF_EXPAND`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__values_8h/#c.PSA_ALG_HKDF_EXPAND) with the [hash algorithm](#hash-mechanism-selection) passed as an argument. For example `PSA_ALG_HKDF(PSA_ALG_SHA_256)` selects HKDF-SHA-256.
+3. Call [`psa_key_derivation_input_bytes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga8fd934dfb0ca45cbf89542ef2a5494c2) on each of the inputs in the order listed below. (Use [`psa_key_derivation_input_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gab2d7ce8705dd8e4a093f4b8a21a0c15a) instead for an input that is a PSA key object.) The input step value for each step is as follows:
+ 1. [`PSA_KEY_DERIVATION_INPUT_SALT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__derivation/#group__derivation_1gab62757fb125243562c3947a752470d4a) for the salt used during the extraction step. Omit this step for HKDF-Expand. For HKDF, you may omit this step if the salt is empty.
+ 2. [`PSA_KEY_DERIVATION_INPUT_SECRET`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__derivation/#group__derivation_1ga0ddfbe764baba995c402b1b0ef59392e) for the secret input.
+ 3. [`PSA_KEY_DERIVATION_INPUT_INFO`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__derivation/#group__derivation_1gacef8df989e09c769233f4b779acb5b7d) for the info string used during the expansion step. Omit this step for HKDF-Extract.
+4. Call [`psa_key_derivation_output_bytes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga06b7eb34a2fa88965f68e3d023fa12b9) to obtain the output of the derivation. You may call this function more than once to retrieve the output in successive chunks. Use [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gada7a6e17222ea9e7a6be6864a00316e1) instead if you want to use a chunk as a PSA key.
+5. Call [`psa_key_derivation_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga90fdd2716124d0bd258826184824675f) to free the resources associated with the key derivation object.
+
+### PKCS#5 module
+
+Applications currently using `mbedtls_pkcs5_pbkdf2_hmac` or `mbedtls_pkcs5_pbkdf2_hmac_ext` can switch to the PSA key derivation API for PBKDF2. This is a generic interface using an operation object with one function call for each input and one function call for each output.
+
+1. Create an operation object of type [`psa_key_derivation_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga5f099b63799a0959c3d46718c86c2609) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_key_derivation_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gac0b6a76e45cceb1862752bf041701859) to select the algorithm, which is a value of type [`psa_algorithm_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac2e4d47f1300d73c2f829a6d99252d69). For PBKDF2-HMAC, select `PSA_ALG_PBKDF2_HMAC(hash)` where `hash` is the underlying hash algorithm (see “[Hash mechanism selection](#hash-mechanism-selection)”).
+3. Call `psa_key_derivation_input_cost` with the step `PSA_KEY_DERIVATION_INPUT_COST` to select the iteration count.
+4. Call [`psa_key_derivation_input_bytes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga8fd934dfb0ca45cbf89542ef2a5494c2) on each of the inputs in the order listed below. (Use [`psa_key_derivation_input_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gab2d7ce8705dd8e4a093f4b8a21a0c15a) instead for an input that is a PSA key object.) The input step value for each step is as follows:
+ 1. [`PSA_KEY_DERIVATION_INPUT_SALT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__derivation/#group__derivation_1gab62757fb125243562c3947a752470d4a) for the salt used during the extraction step. You may repeat this step to pass the salt in pieces (for example a salt and a pepper).
+ 2. [`PSA_KEY_DERIVATION_INPUT_SECRET`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__derivation/#group__derivation_1ga0ddfbe764baba995c402b1b0ef59392e) for the password.
+5. Call [`psa_key_derivation_output_bytes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga06b7eb34a2fa88965f68e3d023fa12b9) to obtain the output of the derivation. You may call this function more than once to retrieve the output in successive chunks.
+ Use [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gada7a6e17222ea9e7a6be6864a00316e1) instead if you want to use a chunk as a PSA key.
+ If you want to verify the output against an expected value (for authentication, rather than to derive key material), call [`psa_key_derivation_verify_bytes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gaf01520beb7ba932143ffe733b0795b08) or [`psa_key_derivation_verify_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gac041714e34a94742e8ee006ac7dfea5a) instead of `psa_key_derivation_output_bytes`. (Note that the `verify` functions are not yet present in the 3.5 release of Mbed TLS. They are expected to be released in version 3.6.0.)
+6. Call [`psa_key_derivation_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga90fdd2716124d0bd258826184824675f) to free the resources associated with the key derivation object.
+
+The function `mbedtls_pkcs5_pbes2` is only intended as a support function to parse encrypted private keys in the PK module. It has no PSA equivalent.
+
+### PKCS#12 module
+
+The functions `mbedtls_pkcs12_derivation` and `mbedtls_pkcs12_pbe` are only intended as support functions to parse encrypted private keys in the PK module. They have no PSA equivalent.
+
+## Random generation
+
+### Random generation interface
+
+The PSA subsystem has an internal random generator. As a consequence, you do not need to instantiate one manually, so most applications using PSA crypto do not need the interfaces from `entropy.h`, `ctr_drbg.h` and `hmac_drbg.h`. See the next sections for remaining use cases for [entropy](#entropy-sources) and [DRBG](#deterministic-pseudorandom-generation).
+
+The PSA API uses its internal random generator to generate keys (`psa_generate_key`), nonces for encryption (`psa_cipher_generate_iv`, `psa_cipher_encrypt`, `psa_aead_generate_nonce`, `psa_aead_encrypt`, `psa_asymmetric_encrypt`), and other random material as needed. If you need random data for some other purposes, call [`psa_generate_random`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5).
+
+If your application mixes uses of the PSA crypto API and the mbedtls API and you need to pass an RNG argument to a legacy or X.509/TLS function, include the header file `<mbedtls/psa_util.h>` and use:
+
+* [`mbedtls_psa_get_random`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/psa__util_8h/#_CPPv422mbedtls_psa_get_randomPvPh6size_t) as the `f_rng` argument;
+* [`MBEDTLS_PSA_RANDOM_STATE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/psa__util_8h/#c.MBEDTLS_PSA_RANDOM_STATE) as the `p_rng` argument.
+
+You can remove the Mbed TLS RNG boilerplate (`mbedtls_entropy_init`, `mbedtls_ctr_drbg_init`, `mbedtls_ctr_drbg_seed`, `mbedtls_ctr_drbg_random`, `mbedtls_ctr_drbg_free`, `mbedtls_entropy_free` — or `hmac_drbg` equivalents of the `ctr_drbg` functions) once you have finished replacing the references to `mbedtls_ctr_drbg_random` (or `mbedtls_hmac_drbg_random`) by `mbedtls_psa_get_random`.
+
+### Entropy sources
+
+Unless explicitly configured otherwise, the PSA random generator uses the default entropy sources configured through the legacy interface (`MBEDTLS_ENTROPY_xxx` symbols). Its set of sources is equivalent to an entropy object configured with `mbedtls_entropy_init`.
+
+A future version of Mbed TLS will include a PSA interface for configuring entropy sources. This is likely to replace the legacy interface in Mbed TLS 4.0.
+
+### Deterministic pseudorandom generation
+
+The PSA API does not have a dedicated interface for pseudorandom generation. The [key derivation interface](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) can serve a similar purpose in some applications, but it does not offer CTR\_DRBG or HMAC\_DRBG. If you need these algorithms, keep using `ctr_drbg.h` and `hmac_drbg.h`, but note that they may be removed from the public API in Mbed TLS 4.0.
+
+## Asymmetric cryptography
+
+The PSA API supports RSA (see “[RSA mechanism selection](#rsa-mechanism-selection)”), elliptic curve cryptography (see “[ECC mechanism selection](#elliptic-curve-mechanism-selection)” and “[EC-JPAKE](#ec-jpake)”) and finite-field Diffie-Hellman (see “[Diffie-Hellman mechanism selection](#diffie-hellman-mechanism-selection)”).
+
+### Key lifecycle for asymmetric cryptography
+
+In the PSA API, keys are referenced by an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv412psa_key_id_t).
+(Some documentation references [`mbedtls_svc_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv420mbedtls_svc_key_id_t); the two types are identical except when the library is configured for use in a multi-client cryptography service.)
+The PSA key identifier tends to play the same role as an `mbedtls_pk_context`, `mbedtls_rsa_context` or `mbedtls_ecp_keypair` structure in the legacy API. However, there are major differences in the way the two APIs can be used to create keys or to obtain information about a key.
+
+Here is an overview of the lifecycle of a PSA key object.
+
+1. First define the attributes of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga0ec645e1fdafe59d591104451ebf5680). You need to set the following parameters:
+ * Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga6857ef0ecb3fa844d4536939d9c64025) to set the key type to the desired `PSA_KEY_TYPE_xxx` value (see “[RSA mechanism selection](#rsa-mechanism-selection)”, “[Elliptic curve mechanism selection](#elliptic-curve-mechanism-selection)” and “[Diffie-Hellman mechanism selection](#diffie-hellman-mechanism-selection)”).
+ * Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaf61683ac87f87687a40262b5afbfa018) to set the key's conceptual size in bits. This is optional with `psa_import_key`, which determines the key size from the length of the key material.
+ * Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaeb8341ca52baa0279475ea3fd3bcdc98) to set the permitted algorithm to the desired `PSA_ALG_xxx` value (see “[RSA mechanism selection](#rsa-mechanism-selection)”, “[Elliptic curve mechanism selection](#elliptic-curve-mechanism-selection)” and “[Diffie-Hellman mechanism selection](#diffie-hellman-mechanism-selection)” as well as “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+ * Call [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de) to enable the desired usage types (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+2. Call one of the key creation functions, passing the attributes defined in the previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv412psa_key_id_t) to the key object.
+ * Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b) to directly import key material.
+ * If the key is randomly generated, use [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5).
+ * If the key is derived from other material (for example from a key exchange), use the [key derivation interface](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the key with [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gada7a6e17222ea9e7a6be6864a00316e1).
+3. Call the functions in the following sections to perform operations on the key. The same key object can be used in multiple operations.
+4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) after all operations with that key are finished.
+
+### Public-key cryptography policies
+
+A key's policy indicates what algorithm(s) it can be used with (usage algorithm policy) and what operations are permitted (usage flags).
+
+The following table lists the relevant usage flags for asymmetric cryptography. You can pass those flags (combined with bitwise-or) to [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de).
+
+| Usage | Flag |
+| ----- | ---- |
+| export public key | 0 (always permitted) |
+| export private key | [`PSA_KEY_USAGE_EXPORT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga7dddccdd1303176e87a4d20c87b589ed) |
+| Sign a message directly | [`PSA_KEY_USAGE_SIGN_MESSAGE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga552117ac92b79500cae87d4e65a85c54) |
+| Sign an already-calculated hash | at least one of [`PSA_KEY_USAGE_SIGN_MESSAGE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga552117ac92b79500cae87d4e65a85c54) or [`PSA_KEY_USAGE_SIGN_HASH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga552117ac92b79500cae87d4e65a85c54) |
+| Verify a message directly | [`PSA_KEY_USAGE_VERIFY_MESSAGE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1gabea7ec4173f4f943110329ac2953b2b1) |
+| Verify an already-calculated hash | at least one of [`PSA_KEY_USAGE_VERIFY_MESSAGE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1gabea7ec4173f4f943110329ac2953b2b1) or [`PSA_KEY_USAGE_VERIFY_HASH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1gafadf131ef2182045e3483d03aadaa1bd) |
+| Encryption | [`PSA_KEY_USAGE_ENCRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga75153b296d045d529d97203a6a995dad) |
+| Decryption | [`PSA_KEY_USAGE_DECRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1gac3f2d2e5983db1edde9f142ca9bf8e6a) |
+| Key agreement | [`PSA_KEY_USAGE_DERIVE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1gaf19022acc5ef23cf12477f632b48a0b2) |
+
+The sections “[RSA mechanism selection](#rsa-mechanism-selection)”, “[Elliptic curve mechanism selection](#elliptic-curve-mechanism-selection)” and “[Diffie-Hellman mechanism selection](#diffie-hellman-mechanism-selection)” cover the available algorithm values for each key type. Normally, a key can only be used with a single algorithm, following standard good practice. However, there are two ways to relax this requirement.
+
+* Many signature algorithms encode a hash algorithm. Sometimes the same key may need to be used to sign messages with multiple different hashes. In an algorithm policy, you can use [`PSA_ALG_ANY_HASH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__values_8h/#c.PSA_ALG_ANY_HASH) instead of a hash algorithm value to allow the key to be used with any hash. For example, `psa_set_key_algorithm(&attributes, PSA_ALG_RSA_PSS(PSA_ALG_ANY_HASH))` allows the key to be used with RSASSA-PSS, with different hash algorithms in each operation.
+* In addition to the algorithm (or wildcard) selected with [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaeb8341ca52baa0279475ea3fd3bcdc98), you can use [`psa_set_key_enrollment_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaffa134b74aa52aa3ed9397fcab4005aa) to permit a second algorithm (or wildcard). This is intended for scenarios where a key is normally used with a single algorithm, but needs to be used with a different algorithm for enrollment (such as an ECDH key for which an ECDSA proof-of-possession is also required).
+
+### Asymmetric cryptographic mechanisms
+
+#### RSA mechanism selection
+
+The PK types `MBEDTLS_PK_RSA`, `MBEDTLS_PK_RSASSA_PSS` and `MBEDTLS_PK_RSA_ALT` correspond to RSA key types in the PSA API. In the PSA API, key pairs and public keys are separate object types.
+See “[RSA-ALT interface](#rsa-alt-interface)” for more information about `MBEDTLS_PK_RSA_ALT`.
+
+The PSA API uses policies and algorithm parameters rather than key types to distinguish between RSA-based mechanisms. The PSA algorithm selection corresponds to the `mbedtls_pk_type_t` value passed to `mbedtls_pk_{sign,verify}_ext`. It also replaces the use of `mbedtls_rsa_set_padding` on an `mbedtls_rsa_context` object. See the list of algorithms below and the signature and encryption sections for more information.
+
+An RSA public key has the type [`PSA_KEY_TYPE_RSA_PUBLIC_KEY`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga9ba0878f56c8bcd1995ac017a74f513b).
+
+An RSA key pair has the type [`PSA_KEY_TYPE_RSA_KEY_PAIR`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga11745b110166e927e2abeabc7d532051). A key with this type can be used both for private-key and public-key operations (there is no separate key type for a private key without the corresponding public key).
+You can always use a private key for operations on the corresponding public key (as long as the policy permits it).
+
+The following cryptographic algorithms work with RSA keys:
+
+* PKCS#1v1.5 RSA signature: [`PSA_ALG_RSA_PKCS1V15_SIGN`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga702ff75385a6ae7d4247033f479439af), [`PSA_ALG_RSA_PKCS1V15_SIGN_RAW`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga4215e2a78dcf834e9a625927faa2a817).
+* PKCS#1v1.5 RSA encryption: [`PSA_ALG_RSA_PKCS1V15_CRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga4c540d3abe43fb9abcb94f2bc51acef9).
+* PKCS#1 RSASSA-PSS signature: [`PSA_ALG_RSA_PSS`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga62152bf4cb4bf6aace5e1be8f143564d), [`PSA_ALG_RSA_PSS_ANY_SALT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga9b7355a2cd6bde88177634d539127f2b).
+* PKCS#1 RSAES-OAEP encryption: [`PSA_ALG_RSA_OAEP`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gaa1235dc3fdd9839c6c1b1a9857344c76).
+
+#### Elliptic curve mechanism selection
+
+The PK types `MBEDTLS_PK_ECKEY`, `MBEDTLS_PK_ECKEY_DH` and `MBEDTLS_PK_ECDSA` correspond to elliptic-curve key types in the PSA API. In the PSA API, key pairs and public keys are separate object types. The PSA API uses policies and algorithm parameters rather than key types to distinguish between the PK EC types.
+
+An ECC public key has the type [`PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gad54c03d3b47020e571a72cd01d978cf2) where `curve` is a curve family identifier.
+
+An ECC key pair has the type [`PSA_KEY_TYPE_ECC_KEY_PAIR(curve)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga0b6f5d4d5037c54ffa850d8059c32df0) where `curve` is a curve family identifier. A key with this type can be used both for private-key and public-key operations (there is no separate key type for a private key without the corresponding public key).
+You can always use a private key for operations on the corresponding public key (as long as the policy permits it).
+
+A curve is fully determined by a curve family identifier and the private key size in bits. You can use the following functions to convert between the PSA and legacy elliptic curve designations:
+- [`mbedtls_ecc_group_to_psa()`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__psa__tls__helpers/#group__psa__tls__helpers_1ga9c83c095adfec7da99401cf81e164f99) converts from the legacy curve type identifier to PSA curve family and bit-size.
+- [`mbedtls_ecc_group_from_psa()`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__psa__tls__helpers/#group__psa__tls__helpers_1ga6243eb619d5b2f5fe4667811adeb8a12) converts from PSA curve family and bit-size to the legacy identifier.
+
+The following table gives the correspondence between legacy and PSA elliptic curve designations.
+
+| Mbed TLS legacy curve identifier | PSA curve family | Curve bit-size |
+| -------------------------------- | ---------------- | -------------- |
+| `MBEDTLS_ECP_DP_SECP192R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 192 |
+| `MBEDTLS_ECP_DP_SECP224R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 224 |
+| `MBEDTLS_ECP_DP_SECP256R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 256 |
+| `MBEDTLS_ECP_DP_SECP384R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 384 |
+| `MBEDTLS_ECP_DP_SECP521R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 521 |
+| `MBEDTLS_ECP_DP_BP256R1` | [`PSA_ECC_FAMILY_BRAINPOOL_P_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac1643f1baf38b30d07c20a6eac697f15) | 256 |
+| `MBEDTLS_ECP_DP_BP384R1` | [`PSA_ECC_FAMILY_BRAINPOOL_P_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac1643f1baf38b30d07c20a6eac697f15) | 384 |
+| `MBEDTLS_ECP_DP_BP512R1` | [`PSA_ECC_FAMILY_BRAINPOOL_P_R1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gac1643f1baf38b30d07c20a6eac697f15) | 512 |
+| `MBEDTLS_ECP_DP_CURVE25519` | [`PSA_ECC_FAMILY_MONTGOMERY`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga1f624c5cdaf25b21287af33024e1aff8) | 255 |
+| `MBEDTLS_ECP_DP_SECP192K1` | [`PSA_ECC_FAMILY_SECP_K1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 192 |
+| `MBEDTLS_ECP_DP_SECP224K1` | not supported | N/A |
+| `MBEDTLS_ECP_DP_SECP256K1` | [`PSA_ECC_FAMILY_SECP_K1`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga48bb340b5544ba617b0f5b89542665a7) | 256 |
+| `MBEDTLS_ECP_DP_CURVE448` | [`PSA_ECC_FAMILY_MONTGOMERY`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga1f624c5cdaf25b21287af33024e1aff8) | 448 |
+
+The following cryptographic algorithms work with ECC keys:
+
+* ECDH key agreement (including X25519 and X448): [`PSA_ALG_ECDH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gab2dbcf71b63785e7dd7b54a100edee43).
+* ECDSA: [`PSA_ALG_ECDSA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7e3ce9f514a227d5ba5d8318870452e3), [`PSA_ALG_ECDSA_ANY`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga51d6b6044a62e33cae0cf64bfc3b22a4), [`PSA_ALG_DETERMINISTIC_ECDSA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga11da566bcd341661c8de921e2ca5ed03).
+* EC-JPAKE (see “[EC-JPAKE](#ec-jpake)”.
+
+#### Diffie-Hellman mechanism selection
+
+A finite-field Diffie-Hellman key pair has the type [`PSA_KEY_TYPE_DH_KEY_PAIR(group)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gab4f857c4cd56f5fe65ded421e61bcc8c) where `group` is a group family as explained below.
+
+A finite-field Diffie-Hellman public key has the type [`PSA_KEY_TYPE_DH_PUBLIC_KEY(group)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gaa22f0f2ea89b929f2fadc19890cc5d5c) where `group` is a group family as explained below. Due to the design of the API, there is rarely a need to use Diffie-Hellman public key objects.
+
+The PSA API only supports Diffie-Hellman with predefined groups. A group is fully determined by a group family identifier and the public key size in bits.
+
+| Mbed TLS DH group P value | PSA DH group family | Bit-size |
+| ------------------------- | ------------------- | -------- |
+| `MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7be917e67fe4a567fb36864035822ff7) | 2048 |
+| `MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7be917e67fe4a567fb36864035822ff7) | 3072 |
+| `MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7be917e67fe4a567fb36864035822ff7) | 4096 |
+| `MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7be917e67fe4a567fb36864035822ff7) | 6144 |
+| `MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7be917e67fe4a567fb36864035822ff7) | 8192 |
+
+A finite-field Diffie-Hellman key can be used for key agreement with the algorithm [`PSA_ALG_FFDH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga0ebbb6f93a05b6511e6f108ffd2d1eb4).
+
+### Creating keys for asymmetric cryptography
+
+The easiest way to create a key pair object is by randomly generating it with [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5). Compared with the low-level functions from the legacy API (`mbedtls_rsa_gen_key`, `mbedtls_ecp_gen_privkey`, `mbedtls_ecp_gen_keypair`, `mbedtls_ecp_gen_keypair_base`, `mbedtls_ecdsa_genkey`), this directly creates an object that can be used with high-level APIs, but removes some of the flexibility. Note that if you want to export the generated private key, you must pass the flag [`PSA_KEY_USAGE_EXPORT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga7dddccdd1303176e87a4d20c87b589ed) to [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de); exporting the public key with [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) is always permitted.
+
+For RSA keys, `psa_generate_key` uses 65537 as the public exponent. You can use [`psa_generate_key_ext`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga6776360ae8046a4456a5f990f997da58) to select a different public exponent. As of Mbed TLS 3.6.0, selecting a different public exponent is only supported with the built-in RSA implementation, not with PSA drivers.
+
+To create a key object from existing material, use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b). This function has the same basic goal as the PK parse functions (`mbedtls_pk_parse_key`, `mbedtls_pk_parse_public_key`, `mbedtls_pk_parse_subpubkey`), but only supports a single format that just contains the number(s) that make up the key, with very little metadata. The table below summarizes the PSA import/export format for key pairs and public keys; see the documentation of [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf) and [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) for more details.
+
+| Key type | PSA import/export format |
+| -------- | ------------------------ |
+| RSA key pair | PKCS#1 RSAPrivateKey DER encoding (including both private exponent and CRT parameters) |
+| RSA public key | PKCS#1 RSAPublicKey DER encoding |
+| ECC key pair | Fixed-length private value (not containing the public key) |
+| ECC public key (Weierstrass curve) | Fixed-length uncompressed point |
+| ECC public key (Montgomery curve) | Fixed-length public value |
+| FFDH key pair | Fixed-length private value (not containing the public key) |
+| FFDH public key | Fixed-length public value |
+
+There is no equivalent of `mbedtls_pk_parse_keyfile` and `mbedtls_pk_parse_public_keyfile`. Either call the legacy function or load the file data manually.
+
+A future extension of the PSA API will support other import formats. Until those are implemented, see the following subsection for how to use the PK module for key parsing and construct a PSA key object from the PK object.
+
+### Creating a PSA key via PK
+
+You can use the PK module as an intermediate step to create an RSA or ECC key for use with PSA. This is useful for use cases that the PSA API does not currently cover, such as:
+
+* Parsing a key in a format with metadata without knowing its type ahead of time.
+* Parsing a key in a format that the PK module supports, but `psa_import_key` doesn't.
+* Importing a key which you have in the form of a list of numbers, rather than the binary encoding required by `psa_import_key`.
+* Importing a key with less information than what the PSA API needs, for example an ECC public key in a compressed format, an RSA private key without the private exponent, or an RSA private key without the CRT parameters.
+
+For such use cases:
+
+1. First create a PK object with the desired key material.
+2. Call [`mbedtls_pk_get_psa_attributes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a7aa7b33cffb6981d95d1632631de9244) to fill PSA attributes corresponding to the PK key. Pass one of the following values as the `usage` parameter:
+ * `PSA_KEY_USAGE_SIGN_HASH` or `PSA_KEY_USAGE_SIGN_MESSAGE` for a key pair used for signing.
+ * `PSA_KEY_USAGE_DECRYPT` for a key pair used for decryption.
+ * `PSA_KEY_USAGE_DERIVE` for a key pair used for key agreement.
+ * `PSA_KEY_USAGE_VERIFY_HASH` or `PSA_KEY_USAGE_VERIFY_MESSAGE` for a public key pair used for signature verification.
+ * `PSA_KEY_USAGE_ENCRYPT` for a key pair used for encryption.
+3. Optionally, tweak the attributes (this is rarely necessary). For example:
+ * Call [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de), [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaeb8341ca52baa0279475ea3fd3bcdc98) and/or [`psa_set_key_enrollment_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__extra_8h/#group__attributes_1gaffa134b74aa52aa3ed9397fcab4005aa) to change the key's policy (by default, it allows what can be done through the PK module).
+ · Call [`psa_set_key_id`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae48fcfdc72a23e7499957d7f54ff5a64) and perhaps [`psa_set_key_lifetime`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gac03ccf09ca6d36cc3d5b43f8303db6f7) to create a PSA persistent key.
+4. Call [`mbedtls_pk_import_into_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1ad59835d14832daf0f4b4bd0a4555abb9) to import the key into the PSA key store.
+5. You can now free the PK object with `mbedtls_pk_free`.
+
+Here is some sample code illustrating the above process, with error checking omitted.
+
+```
+mbedtls_pk_context pk;
+mbedtls_pk_init(&pk);
+mbedtls_pk_parse_key(&pk, key_buffer, key_buffer_length, NULL, 0,
+ mbedtls_psa_get_random, MBEDTLS_PSA_RANDOM_STATE);
+psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+mbedtls_pk_get_psa_attributes(&pk, PSA_KEY_USAGE_SIGN_HASH, &attributes);
+psa_key_id_t key_id;
+mbedtls_pk_import_into_psa(&pk, &attributes, &key_id);
+mbedtls_pk_free(&pk);
+psa_sign_hash(key_id, ...);
+```
+
+#### Importing an elliptic curve key from ECP
+
+This section explains how to use the `ecp.h` API to create an elliptic curve key in a format suitable for `psa_import_key`.
+
+You can use this, for example, to import an ECC key in the form of a compressed point by calling `mbedtls_ecp_point_read_binary` then following the process below.
+
+The following code snippet illustrates how to import a private key which is initially in an `mbedtls_ecp_keypair` object. (This includes `mbedtls_ecdsa_keypair` objects since that is just a type alias.) Error checks are omitted for simplicity. A future version of Mbed TLS [will provide a function to calculate the curve family](https://github.com/Mbed-TLS/mbedtls/issues/7764).
+
+```
+mbedtls_ecp_keypair ec;
+mbedtls_ecp_keypair_init(&ec);
+// Omitted: fill ec with key material
+// (the public key will not be used and does not need to be set)
+unsigned char buf[PSA_BITS_TO_BYTES(PSA_VENDOR_ECC_MAX_CURVE_BITS)];
+size_t length;
+mbedtls_ecp_write_key_ext(&ec, &length, buf, sizeof(buf));
+psa_ecc_curve_t curve = ...; // need to determine the curve family manually
+psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+psa_set_key_attributes(&attributes, PSA_KEY_TYPE_ECC_KEY_PAIR(curve));
+psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_... | ...);
+psa_set_key_algorithm(&attributes, PSA_ALGORITHM_...);
+psa_key_id_t key_id = 0;
+psa_import_key(&attributes, buf, length, &key_id);
+mbedtls_ecp_keypair_free(&ec);
+```
+The following code snippet illustrates how to import a private key which is initially in an `mbedtls_ecp_keypair` object. Error checks are omitted for simplicity.
+
+```
+mbedtls_ecp_group grp;
+mbedtls_ecp_group_init(&grp);
+mbedtls_ecp_group_load(&grp, MBEDTLS_ECP_DP_...);
+mbedtls_ecp_point pt;
+mbedtls_ecp_point_init(&pt);
+// Omitted: fill pt with key material
+unsigned char buf[PSA_BITS_TO_BYTES(PSA_VENDOR_ECC_PUBLIC_KEY_MAX_SIZE)];
+size_t length;
+mbedtls_ecp_point_write_binary(&grp, &pt, &length, buf, sizeof(buf));
+psa_ecc_curve_t curve = ...; // need to determine the curve family manually
+psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+psa_set_key_attributes(&attributes, PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve));
+psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_... | ...);
+psa_set_key_algorithm(&attributes, PSA_ALGORITHM_...);
+psa_key_id_t key_id = 0;
+psa_import_key(&attributes, buf, length, &key_id);
+mbedtls_ecp_point_free(&pt);
+mbedtls_ecp_group_free(&grp);
+```
+
+### Key pair and public key metadata
+
+There is no equivalent to the type `mbedtls_pk_info_t` and the functions `mbedtls_pk_info_from_type` in the PSA API because it is unnecessary. All macros and functions operate directly on key type values (`psa_key_type_t`, `PSA_KEY_TYPE_xxx` constants) and algorithm values (`psa_algorithm_t`, `PSA_ALG_xxx` constants).
+
+You can call [`psa_get_key_attributes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gacbbf5c11eac6cd70c87ffb936e1b9be2) to populate a structure with the attributes of a key, then functions such as [`psa_get_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae4fb812af4f57aa1ad85e335a865b918) and [`psa_get_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga5bee85c2164ad3d4c0d42501241eeb06) to obtain a key's type (`PSA_KEY_TYPE_xxx` value) and size (nominal size in bits).
+
+The bit-size from `psa_get_key_bits` is the same as the one from `mbedtls_pk_get_bitlen`. To convert to bytes as `mbedtls_pk_get_len` or `mbedtls_rsa_get_len` do, you can use the macro `PSA_BITS_TO_BYTES`. However, note that the PSA API has generic macros for each related buffer size (export, signature size, etc.), so you should generally use those instead. The present document lists those macros where it explains the usage of the corresponding function.
+
+Most code that calls `mbedtls_pk_get_type` or `mbedtls_pk_can_do` only requires the key's type as reported by [`psa_get_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae4fb812af4f57aa1ad85e335a865b918). For code that uses both `mbedtls_pk_context` objects and PSA metadata encoding, [`mbedtls_pk_can_do_ext`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a256d3e8d4323a45aafa7d2b6c59a36f6) checks the compatibility between a key object and a mechanism. If needed, you can also access a key's policy from its attributes with [`psa_get_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaa1af20f142ca722222c6d98678a0c448), [`psa_get_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gac255da850a00bbed925390044f016b34) and [`psa_get_key_enrollment_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga39803b62a97198cf630854db9b53c588). The algorithm policy also conveys the padding and hash information provided by `mbedtls_rsa_get_padding_mode` and `mbedtls_rsa_get_md_alg`.
+
+### Exporting a public key or a key pair
+
+To export a PSA key pair or public key, call [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf). If the key is a key pair, its policy must allow `PSA_KEY_USAGE_EXPORT` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+
+To export a PSA public key or to export the public key of a PSA key pair object, call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062). This is always permitted regardless of the key's policy.
+
+The export format is the same format used for `psa_import_key`, described in “[Creating keys for asymmetric cryptography](#creating-keys-for-asymmetric-cryptography)” above.
+
+A future extension of the PSA API will support other export formats. Until those are implemented, see “[Exposing a PSA key via PK](#exposing-a-psa-key-via-pk)” for ways to use the PK module to format a PSA key.
+
+#### Exposing a PSA key via PK
+
+This section discusses how to use a PSA key in a context that requires a PK object, such as PK formatting functions (`mbedtls_pk_write_key_der`, `mbedtls_pk_write_pubkey_der`, `mbedtls_pk_write_pubkey_pem`, `mbedtls_pk_write_key_pem` or `mbedtls_pk_write_pubkey`), Mbed TLS X.509 functions, Mbed TLS SSL functions, or another API that involves `mbedtls_pk_context` objects. The PSA key must be an RSA or ECC key since the PK module does not support DH keys. Three functions from `pk.h` help with that:
+
+* [`mbedtls_pk_copy_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1ab8e88836fd9ee344ffe630c40447bd08) copies a PSA key into a PK object. The PSA key must be exportable. The PK object remains valid even if the PSA key is destroyed.
+* [`mbedtls_pk_copy_public_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a2a50247a528889c12ea0ddddb8b15a4e) copies the public part of a PSA key into a PK object. The PK object remains valid even if the PSA key is destroyed.
+* [`mbedtls_pk_setup_opaque`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a4c04ac22ab9c1ae09cc29438c308bf05) sets up a PK object that wraps the PSA key. This functionality is only available when `MBEDTLS_USE_PSA_CRYPTO` is enabled. The PK object has the type `MBEDTLS_PK_OPAQUE` regardless of whether the key is an RSA or ECC key. The PK object can only be used as permitted by the PSA key's policy. The PK object contains a reference to the PSA key identifier, therefore PSA key must not be destroyed as long as the PK object remains alive.
+
+Here is some sample code illustrating how to use the PK module to format a PSA public key or the public key of a PSA key pair.
+```
+int write_psa_pubkey(psa_key_id_t key_id,
+ unsigned char *buf, size_t size, size_t *len) {
+ mbedtls_pk_context pk;
+ mbedtls_pk_init(&pk);
+ int ret = mbedtls_pk_copy_public_from_psa(key_id, &pk);
+ if (ret != 0) goto exit;
+ ret = mbedtls_pk_write_pubkey_der(&pk, buf, size);
+ if (ret < 0) goto exit;
+ *len = ret;
+ memmove(buf, buf + size - ret, ret);
+ ret = 0;
+exit:
+ mbedtls_pk_free(&pk);
+}
+```
+
+### Signature operations
+
+The equivalent of `mbedtls_pk_sign` or `mbedtls_pk_sign_ext` to sign an already calculated hash is [`psa_sign_hash`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1ga785e746a31a7b2a35ae5175c5ace3c5c).
+The key must be a key pair allowing the usage `PSA_KEY_USAGE_SIGN_HASH` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+Use [`PSA_SIGN_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_SIGN_OUTPUT_SIZE) or [`PSA_SIGNATURE_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_SIGNATURE_MAX_SIZE) (similar to `MBEDTLS_PK_SIGNATURE_MAX_SIZE`) to determine a sufficient size for the output buffer.
+This is also the equivalent of the type-specific functions `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_ecdsa_sign`, `mbedtls_ecdsa_sign_det_ext` and `mbedtls_ecdsa_write_signature`. Note that the PSA API uses the raw format for ECDSA signatures, not the ASN.1 format; see “[ECDSA signature](#ecdsa-signature)” for more details.
+
+The equivalent of `mbedtls_pk_verify` or `mbedtls_pk_verify_ext` to verify an already calculated hash is [`psa_verify_hash`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1gae2ffbf01e5266391aff22b101a49f5f5).
+The key must be a public key (or a key pair) allowing the usage `PSA_KEY_USAGE_VERIFY_HASH` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+This is also the equivalent of the type-specific functions `mbedtls_rsa_pkcs1_verify`, `mbedtls_rsa_rsassa_pkcs1_v15_verify`, `mbedtls_rsa_rsassa_pss_verify`, `mbedtls_rsa_rsassa_pss_verify_ext`, `mbedtls_ecdsa_verify` amd `mbedtls_ecdsa_read_signature`. Note that the PSA API uses the raw format for ECDSA signatures, not the ASN.1 format; see “[ECDSA signature](#ecdsa-signature)” for more details.
+
+Generally, `psa_sign_hash` and `psa_verify_hash` require the input to have the correct length for the hash (this has historically not always been enforced in the corresponding legacy APIs).
+
+See also “[Restartable ECDSA signature](#restartable-ecdsa-signature)” for a restartable variant of this API.
+
+The PSA API also has functions [`psa_sign_message`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1ga963ecadae9c38c85826f9a13cf1529b9) and [`psa_verify_message`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1ga01c11f480b185a4268bebd013df7c14c). These functions combine the hash calculation with the signature calculation or verification.
+For `psa_sign_message`, either the usage flag `PSA_KEY_USAGE_SIGN_MESSAGE` or `PSA_KEY_USAGE_SIGN_HASH` is sufficient.
+For `psa_verify_message`, either the usage flag `PSA_KEY_USAGE_VERIFY_MESSAGE` or `PSA_KEY_USAGE_VERIFY_HASH` is sufficient.
+
+Most signature algorithms involve a hash algorithm. See “[Hash mechanism selection](#hash-mechanism-selection)”.
+
+The following subsections describe the PSA signature mechanisms that correspond to legacy Mbed TLS mechanisms.
+
+#### ECDSA signature
+
+**Note: in the PSA API, the format of an ECDSA signature is the raw fixed-size format. This is different from the legacy API** which uses the ASN.1 DER format for ECDSA signatures. To convert between the two formats, use [`mbedtls_ecdsa_raw_to_der`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/psa__util_8h/#group__psa__tls__helpers_1ga9295799b5437bdff8ce8abd524c5ef2e) or [`mbedtls_ecdsa_der_to_raw`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/psa__util_8h/#group__psa__tls__helpers_1ga33b3cf65d5992ccc724b7ee00186ae61).
+
+<!-- The following are specific to the DER format and therefore have no PSA equivalent: MBEDTLS_ECDSA_MAX_SIG_LEN, MBEDTLS_ECDSA_MAX_LEN -->
+
+ECDSA is the mechanism provided by `mbedtls_pk_sign` and `mbedtls_pk_verify` for ECDSA keys, as well as by `mbedtls_ecdsa_sign`, `mbedtls_ecdsa_sign_det_ext`, `mbedtls_ecdsa_write_signature`, `mbedtls_ecdsa_verify` and `mbedtls_ecdsa_read_signature`.
+
+The PSA API offers three algorithm constructors for ECDSA. They differ only for signature, and have exactly the same behavior for verification.
+
+* [`PSA_ALG_ECDSA(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga7e3ce9f514a227d5ba5d8318870452e3) is a randomized ECDSA signature of a hash calculated with the algorithm `hash`.
+* [`PSA_ALG_ECDSA_ANY`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga51d6b6044a62e33cae0cf64bfc3b22a4) is equivalent to `PSA_ALG_ECDSA`, but does not require specifying a hash as part of the algorithm. It can only be used with `psa_sign_hash` and `psa_verify_hash`, with no constraint on the length of the hash.
+* [`PSA_ALG_DETERMINISTIC_ECDSA(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga11da566bcd341661c8de921e2ca5ed03) is a deterministic ECDSA signature of a hash calculated with the algorithm `hash`. This is the same as the functionality offered by `MBEDTLS_ECDSA_DETERMINISTIC` in the legacy API.
+ * For `psa_sign_message` with `PSA_ALG_DETERMINISTIC_ECDSA`, the same hash algorithm is used to hash the message and to parametrize the deterministic signature generation.
+
+Unlike the legacy API, where `mbedtls_pk_sign` and `mbedtls_ecdsa_write_signature` automatically select deterministic ECDSA if both are available, the PSA API requires the application to select the preferred variant. ECDSA verification cannot distinguish between randomized and deterministic ECDSA (except in so far as if the same message is signed twice and the signatures are different, then at least one of the signatures is not the determinstic variant), so in most cases switching between the two is a compatible change.
+
+#### Restartable ECDSA signature
+
+The legacy API includes an API for “restartable” ECC operations: the operation returns after doing partial computation, and can be resumed. This is intended for highly constrained devices where long cryptographic calculations need to be broken up to poll some inputs, where interrupt-based scheduling is not desired. The legacy API consists of the functions `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable`, `mbedtls_ecdsa_sign_restartable`, `mbedtls_ecdsa_verify_restartable`, `mbedtls_ecdsa_write_signature_restartable`, `mbedtls_ecdsa_read_signature_restartable`, as well as several configuration and data manipulation functions.
+
+The PSA API offers similar functionality via “interruptible” public-key operations. As of Mbed TLS 3.5, it is only implemented for ECDSA, for the same curves as the legacy API. This will likely be extended to ECDH in the short term. At the time of writing, no extension is planned to other curves or other algorithms.
+
+The flow of operations for an interruptible signature operation is as follows:
+
+1. Create an operation object of type [`psa_sign_hash_interruptible_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga6948d4653175b1b530a265540066a7e7) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_sign_hash_start`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga441988da830205182b3e791352537fac) with the private key object and the hash to verify.
+3. Call [`psa_sign_hash_complete`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga79849aaa7004a85d2ffbc4b658a333dd) repeatedly until it returns a status other than `PSA_OPERATION_INCOMPLETE`.
+
+The flow of operations for an interruptible signature verification operation is as follows:
+
+1. Create an operation object of type [`psa_verify_hash_interruptible_operation_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga537054cf4909ad1426331ae4ce7148bb) and zero-initialize it (or use the corresponding `INIT` macro).
+2. Call [`psa_verify_hash_start`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga912eb51fb94056858f451f276ee289cb) with the private key object and the hash and signature to verify.
+3. Call [`psa_verify_hash_complete`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga67fe82352bc2f8c0343e231a70a5bc7d) repeatedly until it returns a status other than `PSA_OPERATION_INCOMPLETE`.
+
+If you need to cancel the operation after calling the start function without waiting for the loop calling the complete function to finish, call [`psa_sign_hash_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1gae893a4813aa8e03bd201fe4f1bbbb403) or [`psa_verify_hash_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga18dc9c0cc27d590c5e3b186094d90f88).
+
+Call [`psa_interruptible_set_max_ops`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga6d86790b31657c13705214f373af869e) to set the number of basic operations per call. This is the same unit as `mbedtls_ecp_set_max_ops`. You can retrieve the current value with [`psa_interruptible_get_max_ops`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interruptible__hash_1ga73e66a6d93f2690b626fcea20ada62b2). The value is [`PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible/#group__interruptible_1gad19c1da7f6b7d59d5873d5b68eb943d4) if operations are not restartable, which corresponds to `mbedtls_ecp_restart_is_enabled()` being false.
+
+#### PKCS#1 v1.5 RSA signature
+
+This mechanism corresponds to `mbedtls_pk_sign`, `mbedtls_pk_verify`, `mbedtls_rsa_pkcs1_sign` and `mbedtls_rsa_pkcs1_verify` for an RSA key, unless PSS has been selected with `mbedtls_rsa_set_padding` on the underlying RSA key context. This mechanism also corresponds to `mbedtls_rsa_rsassa_pkcs1_v15_sign` and `mbedtls_rsa_rsassa_pkcs1_v15_verify`.
+
+The PSA API has two algorithm constructors:
+
+* [`PSA_ALG_RSA_PKCS1V15_SIGN(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga702ff75385a6ae7d4247033f479439af) formats the hash as specified in PKCS#1. The hash algorithm corresponds to the `md_alg` parameter of the legacy functions.
+* [`PSA_ALG_RSA_PKCS1V15_SIGN_RAW`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga4215e2a78dcf834e9a625927faa2a817) uses the “hash” input in lieu of a DigestInfo structure. This is the same as calling the legacy functions with `md_alg=MBEDTLS_MD_NONE`.
+
+#### PKCS#1 RSASSA-PSS signature
+
+This mechanism corresponds to `mbedtls_pk_sign_ext` and `mbedtls_pk_verify_ext` for an RSA key, as well as `mbedtls_pk_sign`, `mbedtls_pk_verify`, `mbedtls_rsa_pkcs1_sign` and `mbedtls_rsa_pkcs1_verify` if PSS has been selected on the underlying RSA context with `mbedlts_rsa_set_padding`.
+It also corresponds to `mbedtls_rsa_rsassa_pss_sign` and `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify` and `mbedtls_rsa_rsassa_pss_verify_ext`.
+
+The PSA API has two algorithm constructors: [`PSA_ALG_RSA_PSS(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga62152bf4cb4bf6aace5e1be8f143564d) and [`PSA_ALG_RSA_PSS_ANY_SALT(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga9b7355a2cd6bde88177634d539127f2b). They differ only for verification, and have exactly the same behavior for signature. The hash algorithm `hash` corresponds to the `md_alg` parameter passed to the legacy API. It is used to hash the message, to create the salted hash, and for the mask generation with MGF1. The PSA API does not support using different hash algorithms for these different purposes.
+
+With respect to the salt length:
+
+* When signing, the salt is random, and the salt length is the largest possible salt length up to the hash length. This is the same as passing `MBEDTLS_RSA_SALT_LEN_ANY` as the salt length to `xxx_ext` legacy functions or using a legacy function that does not have a `saltlen` argument.
+* When verifying, `PSA_ALG_RSA_PSS` requires the the salt length to the largest possible salt length up to the hash length (i.e. the same that would be used for signing).
+* When verifying, `PSA_ALG_RSA_PSS_ANY_SALT` accepts any salt length. This is the same as passing `MBEDTLS_RSA_SALT_LEN_ANY` as the salt length to `xxx_ext` legacy functions or using a legacy function that does not have a `saltlen` argument.
+
+### Asymmetric encryption and decryption
+
+The equivalent of `mbedtls_pk_encrypt`, `mbedtls_rsa_pkcs1_encrypt`, `mbedtls_rsa_rsaes_pkcs1_v15_encrypt` or `mbedtls_rsa_rsaes_oaep_encrypt` to encrypt a short message (typically a symmetric key) is [`psa_asymmetric_encrypt`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1gaa17f61e4ddafd1823d2c834b3706c290).
+The key must be a public key (or a key pair) allowing the usage `PSA_KEY_USAGE_ENCRYPT` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+Use the macro [`PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#crypto__sizes_8h_1a66ba3bd93e5ec52870ccc3848778bad8) or [`PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE) to determine the output buffer size.
+
+The equivalent of `mbedtls_pk_decrypt`, `mbedtls_rsa_pkcs1_decrypt`, `mbedtls_rsa_rsaes_pkcs1_v15_decrypt` or `mbedtls_rsa_rsaes_oaep_decrypt` to decrypt a short message (typically a symmetric key) is [`psa_asymmetric_decrypt`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1ga4f968756f6b22aab362b598b202d83d7).
+The key must be a key pair allowing the usage `PSA_KEY_USAGE_DECRYPT` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+Use the macro [`PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#crypto__sizes_8h_1a61a246f3eac41989821d982e56fea6c1) or [`PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE) to determine the output buffer size.
+
+The following subsections describe the PSA asymmetric encryption mechanisms that correspond to legacy Mbed TLS mechanisms.
+
+#### RSA PKCS#1v1.5 encryption
+
+This is the mechanism used by the PK functions and by `mbedtls_rsa_pkcs1_{encrypt,decrypt}` unless `mbedtls_rsa_set_padding` has been called on the underlying RSA key context.
+This is also the mechanism used by `mbedtls_rsa_rsaes_pkcs1_v15_{encrypt,decrypt}`.
+
+The PSA algorithm is [`PSA_ALG_RSA_PKCS1V15_CRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga4c540d3abe43fb9abcb94f2bc51acef9).
+
+Beware that PKCS#1v1.5 decryption is subject to padding oracle attacks. Revealing when `psa_asymmetric_decrypt` returns `PSA_ERROR_INVALID_PADDING` may allow an adversary to decrypt arbitrary ciphertexts.
+
+#### RSA RSAES-OAEP
+
+This is the mechanism used by `mbedtls_rsa_rsaes_oaep_{encrypt,decrypt}`.
+
+The PSA algorithm is [`PSA_ALG_RSA_OAEP(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gaa1235dc3fdd9839c6c1b1a9857344c76) where `hash` is a hash algorithm value (`PSA_ALG_xxx`, see “[Hash mechanism selection](#hash-mechanism-selection)”).
+
+As with the PK API, the mask generation is MGF1, the label is empty, and the same hash algorithm is used for MGF1 and to hash the label. The PSA API does not offer a way to choose a different label or a different hash algorithm for the label.
+
+### Private-public key consistency
+
+There is no direct equivalent of the functions `mbedtls_rsa_check_privkey`, `mbedtls_rsa_check_pubkey`,`mbedtls_ecp_check_privkey`, `mbedtls_ecp_check_pubkey`. The PSA API performs some basic checks when it imports a key, and may perform additional checks before performing an operation if needed, so it will never perform an operation on a key that does not satisfy these checks, but the details of when the check is performed may change between versions of the library.
+
+The legacy API provides functions `mbedtls_pk_check_pair`, `mbedtls_rsa_check_pub_priv` and `mbedtls_ecp_check_pub_priv`, which can be used to check the consistency between a private key and a public key. To perform such a check with the PSA API, you can export the public keys; this works because the PSA representation of public keys is canonical.
+
+* Prepare a key object containing the private key, for example with [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b).
+* Prepare a key object containing the public key, for example with [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b).
+* Export both public keys with [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) (this is possible regardless of the usage policies on the keys) and compare the output.
+ ```
+ // Error checking omitted
+ unsigned char pub1[PSA_EXPORT_PUBLIC_KEY_MAX_SIZE];
+ unsigned char pub2[PSA_EXPORT_PUBLIC_KEY_MAX_SIZE];
+ size_t length1, length2;
+ psa_export_public_key(key1, pub1, sizeof(pub1), &length1);
+ psa_export_public_key(key2, pub2, sizeof(pub2), &length2);
+ if (length1 == length2 && !memcmp(pub1, pub2, length1))
+ puts("The keys match");
+ else
+ puts("The keys do not match");
+ ```
+
+### PK functionality with no PSA equivalent
+
+There is no PSA equivalent of the debug functionality provided by `mbedtls_pk_debug`. Use `psa_export_key` to export the key if desired.
+
+There is no PSA equivalent to Mbed TLS's custom key type names exposed by `mbedtls_pk_get_name`.
+
+### Key agreement
+
+The PSA API has a generic interface for key agreement, covering the main use of both `ecdh.h` and `dhm.h`.
+
+<!-- TODO: static FFDH/ECDH (including `mbedtls_ecdh_get_params`)
+ https://github.com/Mbed-TLS/mbedtls/pull/7766#discussion_r1410568541
+ -->
+
+#### Diffie-Hellman key pair management
+
+The PSA API manipulates keys as such, rather than via an operation context. Thus, to use Diffie-Hellman, you need to create a key object, then perform the key exchange, then destroy the key. There is no equivalent to the types `mbedtls_ecdh_context` and `mbedtls_dhm_context`.
+
+Here is an overview of the lifecycle of a key object.
+
+1. First define the attributes of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga0ec645e1fdafe59d591104451ebf5680). You need to set the following parameters:
+ * Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga6857ef0ecb3fa844d4536939d9c64025) to set the key type to the desired `PSA_KEY_TYPE_xxx` value:
+ * [`PSA_KEY_TYPE_DH_KEY_PAIR(group)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gab4f857c4cd56f5fe65ded421e61bcc8c) for finite-field Diffie-Hellman (see “[Diffie-Hellman mechanism selection](#diffie-hellman-mechanism-selection)”).
+ * [`PSA_KEY_TYPE_ECC_KEY_PAIR(curve)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga0b6f5d4d5037c54ffa850d8059c32df0) for elliptic-curve Diffie-Hellman (see “[Elliptic curve mechanism selection](#elliptic-curve-mechanism-selection)”).
+ * Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaf61683ac87f87687a40262b5afbfa018) to set the private key size in bits. This is optional with `psa_import_key`, which determines the key size from the length of the key material.
+ * Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gaeb8341ca52baa0279475ea3fd3bcdc98) to select the appropriate algorithm:
+ * [`PSA_ALG_ECDH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1gab2dbcf71b63785e7dd7b54a100edee43) or [`PSA_ALG_FFDH`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga0ebbb6f93a05b6511e6f108ffd2d1eb4) for a raw key agreement.
+ * [`PSA_ALG_KEY_AGREEMENT(ka, kdf)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__types_1ga78bb81cffb87a635c247725eeb2a2682) if the key will be used as part of a key derivation, where:
+ * `ka` is either `PSA_ALG_ECDH` or `PSA_ALG_FFDH`.
+ * `kdf` is a key derivation algorithm.
+ * Call [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de) to enable at least [`PSA_KEY_USAGE_DERIVE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#c.PSA_KEY_USAGE_DERIVE). See “[Public-key cryptography policies](#public-key-cryptography-policies)” for more information.
+2. Call one of the key creation functions, passing the attributes defined in the previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__types_8h/#_CPPv412psa_key_id_t) to the key object.
+ * Use [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5) to generate a random key. This is normally the case for a Diffie-Hellman key.
+ * Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b) to directly import key material.
+ * If the key is derived deterministically from other material, use the [key derivation interface](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the key with [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1gada7a6e17222ea9e7a6be6864a00316e1).
+3. Call the functions in the following sections to perform operations on the key. The same key object can be used in multiple operations.
+4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) after all operations with that key are finished.
+
+#### Performing a key agreement
+
+Call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) to obtain the public key that needs to be sent to the other party.
+Use the macros [`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE) or [`PSA_EXPORT_PUBLIC_KEY_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE) to determine a sufficient size for the output buffer.
+
+Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga90fdd2716124d0bd258826184824675f) to calculate the shared secret from your private key and the other party's public key.
+Use the macros [`PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE) or [`PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE) to determine a sufficient size for the output buffer.
+
+Call [`psa_key_derivation_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga2cd5a8ac906747d3204ec442db78745f) instead of `psa_raw_key_agreement` to use the resulting shared secret as the secret input to a key derivation. See “[HKDF](#hkdf)” for an example of the key derivation interface.
+
+#### Translating a legacy key agreement contextless workflow
+
+A typical workflow for ECDH using the legacy API without a context object is:
+
+1. Initialize objects:
+ * `mbedtls_ecp_group grp` for the curve;
+ * `mbedtls_mpi our_priv` for our private key;
+ * `mbedtls_ecp_point our_pub` for our public key;
+ * `mbedtls_ecp_point their_pub` for their public key (this may be the same variable as `our_pub` if the application does not need to hold both at the same time);
+ * `mbedtls_mpi z` for the shared secret (this may be the same variable as `our_priv` when doing ephemeral ECDH).
+2. Call `mbedtls_ecp_group_load` on `grp` to select the curve.
+3. Call `mbedtls_ecdh_gen_public` on `grp`, `our_priv` (output) and `our_pub` (output) to generate a key pair and retrieve the corresponding public key.
+4. Send `our_pub` to the peer. Retrieve the peer's public key and import it into `their_pub`. These two actions may be performed in either order.
+5. Call `mbedtls_ecdh_compute_shared` on `grp`, `z` (output), `their_pub` and `our_priv`. Use the raw shared secret `z`, typically, to construct a shared key.
+6. Free `grp`, `our_priv`, `our_pub`, `their_pub` and `z`.
+
+The corresponding workflow with the PSA API is as follows:
+
+1. Initialize objects:
+ * `psa_key_id_t our_key`: a handle to our key pair;
+ * `psa_key_attributes_t attributes`: key attributes used in steps 2–3;;
+ * `our_pub`: a buffer of size [`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, bits)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE) (where `key_type` is the value passed to `psa_set_key_size` in step 2) or [`PSA_EXPORT_PUBLIC_KEY_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE) to hold our key.
+ * `their_pub`: a buffer of the same size, to hold the peer's key. This can be the same as `our_pub` if the application does not need to hold both at the same time;
+ * `shared_secret`: a buffer of size [`PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, bits)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE) or [`PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE) (if not using a key derivation operation).
+2. Prepare an attribute structure as described in “[Diffie-Hellman key pair management](#diffie-hellman-key-pair-management)”, in particular selecting the curve with `psa_set_key_type`.
+3. Call [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5) on `attributes` and `our_key` (output) to generate a key pair, then [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) on `our_key` and `our_pub` (output) to obtain our public key.
+4. Send `our_pub` to the peer. Retrieve the peer's public key and import it into `their_pub`. These two actions may be performed in either order.
+5. Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga90fdd2716124d0bd258826184824675f) on `our_key`, `their_pub` and `shared_secret` (output).
+ Alternatively, call `psa_key_derivation_key_agreement` to use the shared secret directly in a key derivation operation (see “[Performing a key agreement](#performing-a-key-agreement)”).
+6. Call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) on `key_id`, and free the memory buffers.
+
+Steps 4–6 are only performed once for a "true" ephemeral Diffie-Hellman. They may be repeated multiple times for a "fake ephemeral" Diffie-Hellman where the same private key is used for multiple key exchanges, but it not saved.
+
+#### Translating a legacy ephemeral key agreement TLS server workflow
+
+The legacy API offers the following workflow for an ephemeral Diffie-Hellman key agreement in a TLS 1.2 server. The PSA version of this workflow can also be used with other protocols, on the side of the party that selects the curve or group and sends its public key first.
+
+1. Setup phase:
+ 1. Initialize a context of type `mbedtls_ecdh_context` or `mbedtls_dhm_context` with `mbedtls_ecdh_init` or `mbedtls_dhm_init`.
+ 2. Call `mbedtls_ecdh_setup` or `mbedtls_dhm_set_group` to select the curve or group.
+ 3. Call `mbedtls_ecdh_make_params` or `mbedtls_dhm_make_params` to generate our key pair and obtain a TLS ServerKeyExchange message encoding the selected curve/group and our public key.
+2. Send the ServerKeyExchange message to the peer.
+3. Retrieve the peer's public key.
+4. Call `mbedtls_ecdh_read_public` or `mbedtls_dhm_read_public` on the peer's public key, then call `mbedtls_ecdh_calc_secret` or `mbedtls_dhm_calc_secret` to calculate the shared secret.
+5. Free the context with `mbedtls_ecdh_free` or `mbedtls_dhm_free`.
+
+The corresponding workflow with the PSA API is as follows:
+
+1. Setup phase:
+ 1. Generate an ECDH or DHM key pair with `psa_generate_key` as described in “[Diffie-Hellman key pair management](#diffie-hellman-key-pair-management)”.
+ 2. Call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) to obtain our public key.
+ 3. Format a ServerKeyExchange message containing the curve/group selection and our public key.
+2. Send the ServerKeyExchange message to the peer.
+3. Retrieve the peer's public key.
+4. Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga90fdd2716124d0bd258826184824675f) on `our_key`, `their_pub` and `shared_secret` (output).
+ Alternatively, call `psa_key_derivation_key_agreement` to use the shared secret directly in a key derivation operation (see “[Performing a key agreement](#performing-a-key-agreement)”).
+5. Call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) to free the resources associated with our key pair.
+
+#### Translating a legacy ephemeral key agreement TLS client workflow
+
+The legacy API offers the following workflow for an ephemeral Diffie-Hellman key agreement in a TLS 1.2 client. The PSA version of this workflow can also be used with other protocols, on the side of the party that receives a message indicating both the choice of curve or group, and the peer's public key.
+
+1. Upon reception of a TLS ServerKeyExchange message received from the peer, which encodes the selected curve/group and the peer's public key:
+ 1. Initialize a context of type `mbedtls_ecdh_context` or `mbedtls_dhm_context` with `mbedtls_ecdh_init` or `mbedtls_dhm_init`.
+ 2. Call `mbedtls_ecdh_read_params` or `mbedtls_dhm_read_params` to input the data from the ServerKeyExchange message.
+2. Call `mbedtls_ecdh_make_public` or `mbedtls_dh_make_public` to generate our private key and export our public key.
+3. Send our public key to the peer.
+4. Call `mbedtls_ecdh_calc_secret` or `mbedtls_dhm_calc_secret` to calculate the shared secret.
+5. Free the context with `mbedtls_ecdh_free` or `mbedtls_dhm_free`.
+
+The corresponding workflow with the PSA API is as follows:
+
+1. Upon reception of a TLS ServerKeyExchange message received from the peer, which encodes the selected curve/group and the peer's public key:
+ 1. Decode the selected curve/group and use this to determine a PSA key type (`PSA_KEY_TYPE_ECC_KEY_PAIR(curve)` or `PSA_KEY_TYPE_DH_KEY_PAIR(group)`), a key size and an algorithm.
+2. Generate an ECDH or DHM key pair with `psa_generate_key` as described in “[Diffie-Hellman key pair management](#diffie-hellman-key-pair-management)”.
+ Call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) to obtain our public key.
+3. Send our public key to the peer.
+4. Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__derivation_1ga90fdd2716124d0bd258826184824675f) on `our_key`, `their_pub` and `shared_secret` (output).
+ Alternatively, call `psa_key_derivation_key_agreement` to use the shared secret directly in a key derivation operation (see “[Performing a key agreement](#performing-a-key-agreement)”).
+5. Call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__key__management/#group__key__management_1ga5f52644312291335682fbc0292c43cd2) to free the resources associated with our key pair.
+
+#### ECDH and DHM metadata functions
+
+You can obtain data and metadata from an ECDH key agreement through the PSA API as follows:
+
+* With either side, accessing the group: call [`psa_get_key_attributes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gacbbf5c11eac6cd70c87ffb936e1b9be2) on the key identifier, then [`psa_get_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae4fb812af4f57aa1ad85e335a865b918) and [`psa_get_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga5bee85c2164ad3d4c0d42501241eeb06) to obtain metadata about the key.
+* Accessing our public key: call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) on the PSA key identifier.
+* Accessing our private key: call [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf) on the key identifier. Note that the key policy must allow `PSA_KEY_USAGE_EXPORT` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+* Accessing the peer's public key: there is no PSA equivalent since the PSA API only uses the peer's public key to immediately calculate the shared secret. If your application needs the peer's public key for some other purpose, store it separately.
+
+The functions `mbedtls_dhm_get_bitlen`, `mbedtls_dhm_get_len` and `mbedtls_dhm_get_value` allow the caller to obtain metadata about the keys used for the key exchange. The PSA equivalents access the key identifier:
+
+* `mbedtls_dhm_get_bitlen`, `mbedtls_dhm_get_len`: call [`psa_get_key_attributes`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gacbbf5c11eac6cd70c87ffb936e1b9be2) on the PSA key identifier, then [`psa_get_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga5bee85c2164ad3d4c0d42501241eeb06).
+* `mbedtls_dhm_get_value` for `MBEDTLS_DHM_PARAM_X` (our private key): call [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf) on the key identifier. Note that the key policy must allow `PSA_KEY_USAGE_EXPORT` (see “[Public-key cryptography policies](#public-key-cryptography-policies)”).
+* `mbedtls_dhm_get_value` for `MBEDTLS_DHM_PARAM_GX` (our public key): call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) on the PSA key identifier.
+* `mbedtls_dhm_get_value` for `MBEDTLS_DHM_PARAM_GY` (peer's public key): the there is no PSA equivalent since the PSA API only uses the peer's public key to immediately calculate the shared secret. If your application needs the peer's public key for some other purpose, store it separately.
+* `mbedtls_dhm_get_value` for `MBEDTLS_DHM_PARAM_K` (shared secret): this is the value calculated by `psa_raw_key_agreement` or `psa_key_derivation_key_agreement`. If you need to use it multiple times (for example to derive multiple values independently), call `psa_raw_key_agreement` and make a copy.
+* `mbedtls_dhm_get_value` for `MBEDTLS_DHM_PARAM_P` or `MBEDTLS_DHM_PARAM_G` (group parameters): [there is no PSA API to retrieve these values](https://github.com/Mbed-TLS/mbedtls/issues/7780).
+
+The PSA API for finite-field Diffie-Hellman only supports predefined groups. Therefore there is no equivalent to `mbedtls_dhm_parse_dhm`, `mbedtls_dhm_parse_dhmfile`, and the `MBEDTLS_DHM_xxx_BIN` macros.
+
+#### Restartable key agreement
+
+Restartable key agreement (enabled by `mbedtls_ecdh_enable_restart`) is not yet available through the PSA API. It will be added under the name “interruptible key agreement” in a future version of the library, with an interface that's similar to the interruptible signature interface described in “[Restartable ECDSA signature](#restartable-ecdsa-signature)”.
+
+### Additional information about Elliptic-curve cryptography
+
+#### Information about a curve
+
+The legacy API identifies a curve by an `MBEDTLS_ECP_DP_xxx` value of type `mbedtls_ecp_group_id`. The PSA API identifies a curve by a `PSA_ECC_FAMILY_xxx` value and the private value's bit-size. See “[Elliptic curve mechanism selection](#elliptic-curve-mechanism-selection)” for the correspondence between the two sets of values.
+
+There is no PSA equivalent of the `mbedtls_ecp_group` data structure (and so no equivalent to `mbedtls_ecp_group_init`, `mbedtls_ecp_group_load`, `mbedtls_ecp_group_copy` and `mbedtls_ecp_group_free`) or of the `mbedtls_ecp_curve_info` data structure (and so no equivalent to `mbedtls_ecp_curve_info_from_grp_id`) because they are not needed. All API elements identify the curve directly by its family and size.
+
+The bit-size used by the PSA API is the size of the private key. For most curves, the PSA bit-size, the `bit_size` field in `mbedtls_ecp_curve_info`, the `nbits` field in `mbedtls_ecp_group` and the `pbits` field in `mbedtls_ecp_group` are the same. The following table lists curves for which they are different.
+
+| Curve | `grp->nbits` | `grp->pbits` | `curve_info->bit_size` | PSA bit-size |
+| ----- | ------------ | ------------ | ---------------------- | ------------ |
+| secp224k1 | 225 | 224 | 224 | not supported |
+| Curve25519 | 253 | 255 | 256 | 255 |
+| Curve448 | 446 | 448 | 448 | 448 |
+
+There is no exact PSA equivalent of the type `mbedtls_ecp_curve_type` and the function `mbedtls_ecp_get_type`, but the curve family encodes the same information. `PSA_ECC_FAMILY_MONTGOMERY` is the only Montgomery family. All other families supported in Mbed TLS 3.4.0 are short Weierstrass families.
+
+There is no PSA equivalent for the following functionality:
+
+* The `name` field of `mbedtls_ecp_curve_info`, and the function `mbedtls_ecp_curve_info_from_name`. There is no equivalent of Mbed TLS's lookup based on the name used for the curve in TLS specifications.
+* The `tls_id` field of `mbedtls_ecp_curve_info`, the constant `MBEDTLS_ECP_TLS_NAMED_CURVE`, and the functions `mbedtls_ecp_curve_info_from_tls_id`, `mbedtls_ecp_tls_read_group`, `mbedtls_ecp_tls_read_group_id` and `mbedtls_ecp_tls_write_group`. The PSA crypto API does not have this dedicated support for the TLS protocol.
+* Retrieving the parameters of a curve from the fields of an `mbedtls_ecp_group` structure.
+
+#### Information about supported curves
+
+The PSA API does not currently have a discovery mechanism for cryptographic mechanisms (although one may be added in the future). Thus there is no equivalent for `MBEDTLS_ECP_DP_MAX` and the functions `mbedtls_ecp_curve_list` and `mbedtls_ecp_grp_id_list`.
+
+The API provides macros that give the maximum supported sizes for various kinds of objects. The following table lists equivalents for `MBEDTLS_ECP_MAX_xxx` macros.
+
+| Legacy macro | PSA equivalent |
+| ------------ | -------------- |
+| `MBEDTLS_ECP_MAX_BITS` | [`PSA_VENDOR_ECC_MAX_CURVE_BITS`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_VENDOR_ECC_MAX_CURVE_BITS) |
+| `MBEDTLS_ECP_MAX_BYTES` | `PSA_BITS_TO_BYTES(PSA_VENDOR_ECC_MAX_CURVE_BITS)` |
+| `MBEDTLS_ECP_MAX_PT_LEN` | [`PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE) |
+
+#### Restartable ECC
+
+The PSA API supports the equivalent of restartable operations, but only for signatures at the time of writing. See “[Restartable ECDSA signature](#restartable-ecdsa-signature)”.
+
+There is no PSA API for elliptic curve arithmetic as such, and therefore no equivalent of `mbedtls_ecp_restart_ctx` and functions that operate on it.
+
+There is PSA no equivalent of the `MBEDTLS_ECP_OPS_xxx` constants.
+
+#### ECC functionality with no PSA equivalent
+
+There is no PSA equivalent of `mbedtls_ecdsa_can_do` and `mbedtls_ecdh_can_do` to query the capabilities of a curve at runtime. Check the documentation of each curve family to see what algorithms it supports.
+
+There is no PSA equivalent to the types `mbedtls_ecdsa_context` and `mbedtls_ecdsa_restart_ctx`, and to basic ECDSA context manipulation functions including `mbedtls_ecdsa_from_keypair`, because they are not needed: the PSA API does not have ECDSA-specific context types.
+
+#### No curve arithmetic
+
+The PSA API is a cryptography API, not an arithmetic API. As a consequence, there is no PSA equivalent for the ECC arithmetic functionality exposed by `ecp.h`:
+
+* Manipulation of point objects and input-output: the type `mbedtls_ecp_point` and functions operating on it (`mbedtls_ecp_point_xxx`, `mbedtls_ecp_copy`, `mbedtls_ecp_{set,is}_zero`, `mbedtls_ecp_tls_{read,write}_point`). Note that the PSA export format for public keys corresponds to the uncompressed point format (`MBEDTLS_ECP_PF_UNCOMPRESSED`), so [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b), [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf) and [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) are equivalent to `mbedtls_ecp_point_read_binary` and `mbedtls_ecp_point_write_binary` for uncompressed points. The PSA API does not currently support compressed points, but it is likely that such support will be added in the future.
+* Manipulation of key pairs as such, with a bridge to bignum arithmetic (`mbedtls_ecp_keypair` type, `mbedtls_ecp_export`). However, the PSA export format for ECC private keys used by [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b), [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf) is the same as the format used by `mbedtls_ecp_read_key` and `mbedtls_ecp_write_key_ext`.
+* Elliptic curve arithmetic (`mbedtls_ecp_mul`, `mbedtls_ecp_muladd` and their restartable variants).
+
+### Additional information about RSA
+
+#### RSA-ALT interface
+
+Implementers of the RSA-ALT interface (`MBEDTLS_PK_RSA_ALT` pk type, `mbedtls_pk_setup_rsa_alt` setup function) should migrate to the [PSA cryptoprocessor driver interface](https://github.com/Mbed-TLS/mbedtls/blob/development/docs/psa-driver-example-and-guide.md).
+
+* If the purpose of the ALT interface is acceleration only: use the accelerator driver interface. This is fully transparent to application code.
+* If the purpose of the ALT interface is to isolate the private key in a high-security environment: use the opaque driver interface. This is mostly transparent to user code. Code that uses a key via its key identifier does not need to know whether the key is transparent (equivalent of `MBEDTLS_PK_RSA`) or opaque (equivalent of `MBEDTLS_PK_RSA_ALT`). When creating a key, it will be transparent by default; to create an opaque key, call [`psa_set_key_lifetime`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gac03ccf09ca6d36cc3d5b43f8303db6f7) to set the key's location to the chosen location value for the driver, e.g.
+ ```
+ psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
+ PSA_KEY_PERSISTENCE_VOLATILE, MY_RSA_DRIVER_LOCATION));
+ ```
+
+The PSA subsystem uses its internal random generator both for randomized algorithms and to generate blinding values. As a consequence, none of the API functions take an RNG parameter.
+
+#### RSA functionality with no PSA equivalent
+
+The PSA API does not provide direct access to the exponentiation primitive as with `mbedtls_rsa_public` and `mbedtls_rsa_private`. If you need an RSA-based mechanism that is not supported by the PSA API, please [submit an issue on GitHub](https://github.com/ARM-software/psa-api/issues) so that we can extend the API to support it.
+
+The PSA API does not support constructing RSA keys progressively from numbers with `mbedtls_rsa_import` or `mbedtls_rsa_import_raw` followed by `mbedtls_rsa_complete`. See “[Importing a PK key by wrapping](#importing-a-pk-key-by-wrapping)”.
+
+There is no direct equivalent of `mbedtls_rsa_export`, `mbedtls_rsa_export_raw` and `mbedtls_rsa_export_crt` to export some of the numbers in a key. You can export the whole key with `psa_export_key`, or with `psa_export_public_key` to export the public key from a key pair object. See also “[Exporting a public key or a key pair](#exporting-a-public-key-or-a-key-pair)”.
+
+A PSA key object is immutable, so there is no need for an equivalent of `mbedtls_rsa_copy`. (There is a function `psa_copy_key`, but it is only useful to make a copy of a key with a different policy of ownership; both concepts are out of scope of this document since they have no equivalent in the legacy API.)
+
+### LMS signatures
+
+A future version of Mbed TLS will support LMS keys and signatures through the PSA API (`psa_generate_key`, `psa_export_public_key`, `psa_import_key`, `psa_sign_hash`, `psa_verify_hash`, etc.). However, this is likely to happen after Mbed TLS 4.0, therefore the next major version of Mbed TLS will likely keep the existing `lms.h` interface.
+
+### PK format support interfaces
+
+The interfaces in `base64.h`, `asn1.h`, `asn1write.h`, `oid.h` and `pem.h` are intended to support X.509 and key file formats. They have no PSA equivalent since they are not directly about cryptography.
+
+In Mbed TLS 4.0, we are planning to keep the ASN.1 interfaces mostly unchanged. The evolution of Base64, OID and PEM as separate interfaces is still undecided at the time of writing.
+
+## EC-JPAKE
+
+The PSA API exposes EC-JPAKE via the algorithm [`PSA_ALG_JPAKE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__extra_8h/#c.PSA_ALG_JPAKE) and the PAKE API functions. At the time of writing, the PAKE API is still experimental, but it should offer the same functionality as the legacy `ecjpake.h`. Please consult the documentation of your version of Mbed TLS for more information.
+
+Please note a few differences between the two APIs: the legacy API is geared towards the use of EC-JPAKE in TLS 1.2, whereas the PSA API is protocol-agnostic.
+
+* The PSA API is finer-grained and offers more flexibility in message ordering. Where the legacy API makes a single function call, the PSA API may require multiple calls.
+* The legacy API uses the TLS 1.2 wire format in the input or output format of several functions. In particular, one of the messages embeds the curve identifier in the TLS protocol. The PSA API uses protocol-agnostic formats.
+* The legacy API always applies the key derivation specified by TLS 1.2 to the shared secret. With the PSA API, use a key derivation with `PSA_ALG_TLS12_ECJPAKE_TO_PMS` for the same calculation.
diff --git a/docs/redirects.yaml b/docs/redirects.yaml
new file mode 100644
index 0000000..969ffe4
--- /dev/null
+++ b/docs/redirects.yaml
@@ -0,0 +1,11 @@
+# Readthedocs redirects
+# See https://docs.readthedocs.io/en/stable/user-defined-redirects.html
+#
+# Changes to this file do not take effect until they are merged into the
+# 'development' branch. This is because the API token (RTD_TOKEN) is not
+# made available in PR jobs - preventing bad actors from crafting PRs to
+# expose it.
+
+- type: exact
+ from_url: /projects/api/en/latest/*
+ to_url: /projects/api/en/development/:splat
diff --git a/docs/requirements.in b/docs/requirements.in
new file mode 100644
index 0000000..14d618c
--- /dev/null
+++ b/docs/requirements.in
@@ -0,0 +1,3 @@
+breathe
+readthedocs-cli
+sphinx-rtd-theme
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..a1bfd82
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,82 @@
+#
+# This file is autogenerated by pip-compile with Python 3.9
+# by the following command:
+#
+# pip-compile requirements.in
+#
+alabaster==0.7.13
+ # via sphinx
+babel==2.12.1
+ # via sphinx
+breathe==4.35.0
+ # via -r requirements.in
+certifi==2022.12.7
+ # via requests
+charset-normalizer==3.1.0
+ # via requests
+click==8.1.3
+ # via readthedocs-cli
+docutils==0.17.1
+ # via
+ # breathe
+ # sphinx
+ # sphinx-rtd-theme
+idna==3.4
+ # via requests
+imagesize==1.4.1
+ # via sphinx
+importlib-metadata==6.0.0
+ # via sphinx
+jinja2==3.1.2
+ # via sphinx
+markdown-it-py==2.2.0
+ # via rich
+markupsafe==2.1.2
+ # via jinja2
+mdurl==0.1.2
+ # via markdown-it-py
+packaging==23.0
+ # via sphinx
+pygments==2.14.0
+ # via
+ # rich
+ # sphinx
+pyyaml==6.0
+ # via readthedocs-cli
+readthedocs-cli==4
+ # via -r requirements.in
+requests==2.28.2
+ # via
+ # readthedocs-cli
+ # sphinx
+rich==13.3.5
+ # via readthedocs-cli
+snowballstemmer==2.2.0
+ # via sphinx
+sphinx==4.5.0
+ # via
+ # breathe
+ # sphinx-rtd-theme
+sphinx-rtd-theme==1.2.0
+ # via -r requirements.in
+sphinxcontrib-applehelp==1.0.4
+ # via sphinx
+sphinxcontrib-devhelp==1.0.2
+ # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+ # via sphinx
+sphinxcontrib-jquery==2.0.0
+ # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+ # via sphinx
+sphinxcontrib-qthelp==1.0.3
+ # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+ # via sphinx
+urllib3==1.26.15
+ # via requests
+zipp==3.15.0
+ # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools
diff --git a/docs/tls13-early-data.md b/docs/tls13-early-data.md
new file mode 100644
index 0000000..4b6f5d3
--- /dev/null
+++ b/docs/tls13-early-data.md
@@ -0,0 +1,192 @@
+
+Writing early data
+------------------
+
+An application function to write and send a buffer of data to a server through
+TLS may plausibly look like:
+
+```
+int write_data(mbedtls_ssl_context *ssl,
+ const unsigned char *data_to_write,
+ size_t data_to_write_len,
+ size_t *data_written)
+{
+ int ret;
+ *data_written = 0;
+
+ while (*data_written < data_to_write_len) {
+ ret = mbedtls_ssl_write(ssl, data_to_write + *data_written,
+ data_to_write_len - *data_written);
+
+ if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_WANT_READ &&
+ ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+ return ret;
+ }
+
+ *data_written += ret;
+ }
+
+ return 0;
+}
+```
+where ssl is the SSL context to use, data_to_write the address of the data
+buffer and data_to_write_len the number of data bytes. The handshake may
+not be completed, not even started for the SSL context ssl when the function is
+called and in that case the mbedtls_ssl_write() API takes care transparently of
+completing the handshake before to write and send data to the server. The
+mbedtls_ssl_write() may not be able to write and send all data in one go thus
+the need for a loop calling it as long as there are still data to write and
+send.
+
+An application function to write and send early data and only early data,
+data sent during the first flight of client messages while the handshake is in
+its initial phase, would look completely similar but the call to
+mbedtls_ssl_write_early_data() instead of mbedtls_ssl_write().
+```
+int write_early_data(mbedtls_ssl_context *ssl,
+ const unsigned char *data_to_write,
+ size_t data_to_write_len,
+ size_t *data_written)
+{
+ int ret;
+ *data_written = 0;
+
+ while (*data_written < data_to_write_len) {
+ ret = mbedtls_ssl_write_early_data(ssl, data_to_write + *data_written,
+ data_to_write_len - *data_written);
+
+ if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_WANT_READ &&
+ ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+ return ret;
+ }
+
+ *data_written += ret;
+ }
+
+ return 0;
+}
+```
+Note that compared to write_data(), write_early_data() can also return
+MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA and that should be handled
+specifically by the user of write_early_data(). A fresh SSL context (typically
+just after a call to mbedtls_ssl_setup() or mbedtls_ssl_session_reset()) would
+be expected when calling `write_early_data`.
+
+All together, code to write and send a buffer of data as long as possible as
+early data and then as standard post-handshake application data could
+plausibly look like:
+
+```
+ret = write_early_data(ssl,
+ data_to_write,
+ data_to_write_len,
+ &early_data_written);
+if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA) {
+ goto error;
+}
+
+ret = write_data(ssl,
+ data_to_write + early_data_written,
+ data_to_write_len - early_data_written,
+ &data_written);
+if (ret < 0) {
+ goto error;
+}
+
+data_written += early_data_written;
+```
+
+Finally, taking into account that the server may reject early data, application
+code to write and send a buffer of data could plausibly look like:
+```
+ret = write_early_data(ssl,
+ data_to_write,
+ data_to_write_len,
+ &early_data_written);
+if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA) {
+ goto error;
+}
+
+/*
+ * Make sure the handshake is completed as it is a requisite of
+ * mbedtls_ssl_get_early_data_status().
+ */
+while (!mbedtls_ssl_is_handshake_over(ssl)) {
+ ret = mbedtls_ssl_handshake(ssl);
+ if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_WANT_READ &&
+ ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+ goto error;
+ }
+}
+
+ret = mbedtls_ssl_get_early_data_status(ssl);
+if (ret < 0) {
+ goto error;
+}
+
+if (ret == MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED) {
+ early_data_written = 0;
+}
+
+ret = write_data(ssl,
+ data_to_write + early_data_written,
+ data_to_write_len - early_data_written,
+ &data_written);
+if (ret < 0) {
+ goto error;
+}
+
+data_written += early_data_written;
+```
+
+Reading early data
+------------------
+Mbed TLS provides the mbedtls_ssl_read_early_data() API to read the early data
+that a TLS 1.3 server might receive during the TLS 1.3 handshake.
+
+While establishing a TLS 1.3 connection with a client using a combination
+of the mbedtls_ssl_handshake(), mbedtls_ssl_read() and mbedtls_ssl_write() APIs,
+the reception of early data is signaled by an API returning the
+MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA error code. Early data can then be read
+with the mbedtls_ssl_read_early_data() API.
+
+For example, a typical code to establish a TLS connection, where ssl is the SSL
+context to use:
+```
+while ((int ret = mbedtls_ssl_handshake(&ssl)) != 0) {
+
+ if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_WANT_READ &&
+ ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+ break;
+ }
+}
+```
+could be adapted to handle early data in the following way:
+```
+size_t data_read_len = 0;
+while ((ret = mbedtls_ssl_handshake(&ssl)) != 0) {
+
+ if (ret == MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA) {
+ ret = mbedtls_ssl_read_early_data(&ssl,
+ buffer + data_read_len,
+ sizeof(buffer) - data_read_len);
+ if (ret < 0) {
+ break;
+ }
+ data_read_len += ret;
+ continue;
+ }
+
+ if (ret < 0 &&
+ ret != MBEDTLS_ERR_SSL_WANT_READ &&
+ ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
+ break;
+ }
+}
+```
diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md
new file mode 100644
index 0000000..92d0985
--- /dev/null
+++ b/docs/use-psa-crypto.md
@@ -0,0 +1,174 @@
+This document describes the compile-time configuration option
+`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.
+
+This option:
+- makes the X.509 and TLS libraries use PSA for cryptographic operations as
+ much as possible, see "Internal changes" below;
+- enables new APIs for using keys handled by PSA Crypto, such as
+ `mbedtls_pk_setup_opaque()` and `mbedtls_ssl_conf_psk_opaque()`, see
+"New APIs / API extensions" below.
+
+General considerations
+----------------------
+
+**Application code:** when this option is enabled, you need to call
+`psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK
+modules, except for the various mbedtls_xxx_init() functions which can be called
+at any time.
+
+**Why enable this option:** to fully take advantage of PSA drivers in PK,
+X.509 and TLS. For example, enabling this option is what allows use of drivers
+for ECDSA, ECDH and EC J-PAKE in those modules. However, note that even with
+this option disabled, some code in PK, X.509, TLS or the crypto library might
+still use PSA drivers, if it can determine it's safe to do so; currently
+that's the case for hashes.
+
+**Relationship with other options:** This option depends on
+`MBEDTLS_PSA_CRYPTO_C`. These two options differ in the following way:
+- `MBEDTLS_PSA_CRYPTO_C` enables the implementation of the PSA Crypto API.
+ When it is enabled, `psa_xxx()` APIs are available and you must call
+`psa_crypto_init()` before you call any other `psa_xxx()` function. Other
+modules in the library (non-PSA crypto APIs, X.509, TLS) may or may not use
+PSA Crypto but you're not required to call `psa_crypto_init()` before calling
+non-PSA functions, unless explicitly documented (TLS 1.3).
+- `MBEDTLS_USE_PSA_CRYPTO` means that X.509 and TLS will use PSA Crypto as
+ much as possible (that is, everywhere except for features that are not
+supported by PSA Crypto, see "Internal Changes" below for a complete list of
+exceptions). When it is enabled, you need to call `psa_crypto_init()` before
+calling any function from PK, X.509 or TLS; however it doesn't change anything
+for the rest of the library.
+
+**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on modules other than PK,
+X.509 and TLS. It also has no effect on most of the TLS 1.3 code, which always
+uses PSA crypto. The parts of the TLS 1.3 code that will use PSA Crypto or not
+depending on this option being set or not are:
+- record protection;
+- running handshake hash;
+- asymmetric signature verification & generation;
+- X.509 certificate chain verification.
+You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you want TLS 1.3 to use PSA
+everywhere.
+
+**Historical note:** This option was introduced at a time when PSA Crypto was
+still beta and not ready for production, so we made its use in X.509 and TLS
+opt-in: by default, these modules would keep using the stable,
+production-ready legacy (pre-PSA) crypto APIs. So, the scope of was X.509 and
+TLS, as well as some of PK for technical reasons. Nowadays PSA Crypto is no
+longer beta, and production quality, so there's no longer any reason to make
+its use in other modules opt-in. However, PSA Crypto functions require that
+`psa_crypto_init()` has been called before their use, and for backwards
+compatibility reasons we can't impose this requirement on non-PSA functions
+that didn't have such a requirement before. So, nowadays the main meaning of
+`MBEDTLS_USE_PSA_CRYPTO` is that the user promises to call `psa_crypto_init()`
+before calling any PK, X.509 or TLS functions. For the same compatibility
+reasons, we can't extend its scope. However, new modules in the library, such
+as TLS 1.3, can be introduced with a requirement to call `psa_crypto_init()`.
+
+New APIs / API extensions
+-------------------------
+
+### PSA-held (opaque) keys in the PK layer
+
+**New API function:** `mbedtls_pk_setup_opaque()` - can be used to
+wrap a PSA key pair into a PK context. The key can be used for private-key
+operations and its public part can be exported.
+
+**Benefits:** isolation of long-term secrets, use of PSA Crypto drivers.
+
+**Limitations:** can only wrap a key pair, can only use it for private key
+operations. (That is, signature generation, and for RSA decryption too.)
+Note: for ECDSA, currently this uses randomized ECDSA while Mbed TLS uses
+deterministic ECDSA by default. The following operations are not supported
+with a context set this way, while they would be available with a normal
+context: `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key
+operations.
+
+**Use in X.509 and TLS:** opt-in. The application needs to construct the PK context
+using the new API in order to get the benefits; it can then pass the
+resulting context to the following existing APIs:
+
+- `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the
+ key together with a certificate for certificate-based key exchanges;
+- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
+ request);
+- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.
+
+### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
+
+**New API functions:** `mbedtls_ssl_conf_psk_opaque()` and
+`mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to
+register a PSA key for use with a PSK key exchange.
+
+**Benefits:** isolation of long-term secrets.
+
+**Limitations:** none.
+
+**Use in TLS:** opt-in. The application needs to register the key using one of
+the new APIs to get the benefits.
+
+### PSA-held (opaque) keys for TLS 1.2 EC J-PAKE key exchange
+
+**New API function:** `mbedtls_ssl_set_hs_ecjpake_password_opaque()`.
+Call this function from an application to register a PSA key for use with the
+TLS 1.2 EC J-PAKE key exchange.
+
+**Benefits:** isolation of long-term secrets.
+
+**Limitations:** none.
+
+**Use in TLS:** opt-in. The application needs to register the key using one of
+the new APIs to get the benefits.
+
+### PSA-based operations in the Cipher layer
+
+There is a new API function `mbedtls_cipher_setup_psa()` to set up a context
+that will call PSA to store the key and perform the operations.
+
+This function only worked for a small number of ciphers. It is now deprecated
+and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions
+directly instead.
+
+**Warning:** This function will be removed in a future version of Mbed TLS. If
+you are using it and would like us to keep it, please let us know about your
+use case.
+
+Internal changes
+----------------
+
+All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
+is enabled, no change required on the application side.
+
+### TLS: most crypto operations based on PSA
+
+Current exceptions:
+
+- Finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA,
+ DHE-PSK).
+- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
+ the documentation of that option).
+
+Other than the above exceptions, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
+
+### X.509: most crypto operations based on PSA
+
+Current exceptions:
+
+- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
+ the documentation of that option).
+
+Other than the above exception, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
+
+### PK layer: most crypto operations based on PSA
+
+Current exceptions:
+
+- Verification of RSA-PSS signatures with an MGF hash that's different from
+ the message hash.
+- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
+ the documentation of that option).
+
+Other than the above exceptions, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
+
