psa-transition.md - OpenGrok cross reference for /third_party/mbedtls/docs/psa-transition.md

Lines Matching full:tls
7 …TLS is gradually moving from legacy `mbedtls_xxx` APIs to newer `psa_xxx` APIs for cryptography. N…
9 This guide is intended to help migrate existing applications that use Mbed TLS for cryptography. It…
22 **Tutorial**: See the [getting started guide](https://mbed-tls.readthedocs.io/en/latest/getting_sta…
24 …le online. Mbed TLS implements a large subset of the specification which is documented in the [`ps…
28 * [Mbed TLS open issues](https://github.com/Mbed-TLS/mbedtls/issues)
30 * [Mbed TLS mailing list](https://lists.trustedfirmware.org/mailman3/lists/mbed-tls.lists.trustedfi…
34 * Mbed TLS APIs are traditionally very transparent: the caller can access internal fields of operat…
35 * Mbed TLS legacy APIs require key material to be present in the application memory. The PSA Crypto…
36 …iew/conventions.html#parameter-conventions) which many legacy APIs in Mbed TLS do not follow. For …
37 * Mbed TLS legacy APIs require passing around a random generator argument where needed. This has hi…
41 * Mbed TLS 2.15.0 (Nov 2018): first release with a draft implementation of the PSA API.
42 * Mbed TLS 2.18.0 (Jun 2019): The PSA API is available in the default build.
43 * Mbed TLS 3.1.0 (Dec 2021): TLS 1.3 support is the first major feature that requires the PSA API.
44 * Mbed TLS 4.0.0 (2024?): X.509 and TLS require the PSA API. Removal of some legacy crypto APIs.
45 * Mbed TLS 5.0.0 (??): Removal of the remaining non-PSA crypto APIs.
51 …e sure that the configuration option [`MBEDTLS_PSA_CRYPTO_C`](https://mbed-tls.readthedocs.io/proj…
53 …tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1a7…
66 Before any cryptographic operation, call [`psa_crypto_init`](https://mbed-tls.readthedocs.io/projec…
68 …iated with PSA cryptography, call [`mbedtls_psa_crypto_free`](https://mbed-tls.readthedocs.io/proj…
74 Mbed TLS functions return a status of type `int`: 0 for success (or occasionally a positive value w…
76 …tls.readthedocs.io/projects/api/en/development/api/group/group__error/#group__error_1ga05676e70ba5…
88 … that require a key take a parameter of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/proj…
92 …tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__exp…
94 3. Finally destroy the key object with [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects…
98 …tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__exp…
180 …tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1a5…
189 …As an exception, starting in Mbed TLS 3.5.0, for key pair types, the feature selection is more fin…
211 // ^^ In Mbed TLS <= 3.4, enable PSA_WANT_KEY_TYPE_ECC_KEY_PAIR instead
219 If a mechanism is not enabled by `PSA_WANT_xxx`, Mbed TLS will normally not include it. This allows…
225 When PSA Crypto mechanisms are implemented by the built-in code from Mbed TLS, the legacy optimizat…
231 …TLS legacy interface, you can replace some cryptographic primitives and modes by an alternative im…
233 …TLS/mbedtls/blob/development/docs/psa-driver-example-and-guide.md). In an application that uses bo…
237 There is currently [no PSA equivalent to the self-tests](https://github.com/Mbed-TLS/mbedtls/issues…
254 The other functions in `error.h` are specific to the construction of Mbed TLS error code and are no…
271 …ts), use the [`PSA_KEY_TYPE_xxx` and `PSA_ALG_xxx` constants](https://mbed-tls.readthedocs.io/proj…
274 [`PSA_KEY_TYPE_AES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__c…
275 [`PSA_KEY_TYPE_ARIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__…
276 [`PSA_KEY_TYPE_CAMELLIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gro…
277 [`PSA_KEY_TYPE_DES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__c…
281 …[`PSA_ALG_CTR`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypt…
282 …[`PSA_ALG_CFB`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypt…
283 …[`PSA_ALG_OFB`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypt…
284 …[`PSA_ALG_XTS`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypt…
285 …[`PSA_ALG_ECB_NO_PADDING`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
286 …[`PSA_ALG_CBC_NO_PADDING`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
287 …[`PSA_ALG_CBC_PKCS7`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group_…
288 …[`PSA_ALG_CCM_STAR_NO_TAG`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
291 …[`PSA_ALG_CCM`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypt…
292 …[`PSA_ALG_GCM`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__crypt…
295 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
296 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
320 …bed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_IV_MAX_…
321 | `MBEDTLS_MAX_BLOCK_LENGTH` | [`PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE`](https://mbed-tls.readthedocs.io/…
328 …/mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_CIPHER_IV_LE…
335 * `mbedtls_cipher_info_from_string`: there is no equivalent of Mbed TLS's lookup based on a (nonsta…
347 …es of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/proj…
348 …* Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
349 …* Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
350 …* Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
351 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga4…
352 … previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/proj…
353 …* Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gro…
354 …* If the key is randomly generated, use [`psa_generate_key`](https://mbed-tls.readthedocs.io/proje…
355 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the k…
357 4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthed…
361 Recall the workflow of an unauthenticated cipher operation in the legacy Mbed TLS cipher API:
371 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga61f02fbfa…
372 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gab3593f5f1…
376 1. Create an operation object of type [`psa_cipher_operation_t`](https://mbed-tls.readthedocs.io/pr…
377 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga587374c0e…
378 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga29fd7d32a…
379 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gac3ca27ac6…
380 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1ga1dcb58b8b…
382 …ithout calling the finish function, call [`psa_cipher_abort`](https://mbed-tls.readthedocs.io/proj…
386 Recall the workflow of an authenticated cipher operation in the legacy Mbed TLS cipher API (or simi…
400 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae72e1eb3c2da3…
401 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae799f6196a22d…
405 1. Create an operation object of type [`psa_aead_operation_t`](https://mbed-tls.readthedocs.io/proj…
406 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga2732c40ce8f36…
407 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga5799df1c555ef…
408 4. Call [`psa_aead_update_ad`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/grou…
409 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gaf6d49864951ca…
411 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1ga759791bbe1763…
412 …tls.readthedocs.io/projects/api/en/development/api/group/group__aead/#group__aead_1gae0280e2e61a18…
414 …alling the finish or verify function, call [`psa_aead_abort`](https://mbed-tls.readthedocs.io/proj…
418 …tls.readthedocs.io/projects/api/en/development/api/group/group__cipher/#group__cipher_1gaad482cdca…
432 | Mbed TLS constant      | PSA constant        |
452 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
454 * For HMAC, the algorithm is [`PSA_ALG_HMAC`](https://mbed-tls.readthedocs.io/projects/api/en/devel…
456 …The key type is [`PSA_KEY_TYPE_HMAC`](https://mbed-tls.readthedocs.io/projects/api/en/development/…
457 * For CMAC, the algorithm is [`PSA_ALG_CMAC`](https://mbed-tls.readthedocs.io/projects/api/en/devel…
458 …[`PSA_KEY_TYPE_AES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__…
459 …[`PSA_KEY_TYPE_ARIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group_…
460 …[`PSA_KEY_TYPE_CAMELLIA`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gr…
461 …[`PSA_KEY_TYPE_DES`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__…
491 | `MBEDTLS_MD_MAX_SIZE` | [`PSA_HASH_MAX_SIZE`](https://mbed-tls.readthedocs.io/projects/api/en/dev…
492 | `MBEDTLS_MD_MAX_BLOCK_SIZE` | [`PSA_HMAC_MAX_HASH_BLOCK_SIZE`](https://mbed-tls.readthedocs.io/pr…
493 | `mbedtls_md_get_size` | [`PSA_HASH_LENGTH`](https://mbed-tls.readthedocs.io/projects/api/en/devel…
494 | `mbedtls_md_get_size_from_type` | [`PSA_HASH_LENGTH`](https://mbed-tls.readthedocs.io/projects/ap…
500 * `mbedtls_cipher_info_from_string`, `mbedtls_md_get_name`: there is no equivalent of Mbed TLS's lo…
504 …tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1gac69f7f19d96a5…
516 1. Create an operation object of type [`psa_hash_operation_t`](https://mbed-tls.readthedocs.io/proj…
517 2. Call [`psa_hash_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gr…
518 3. Call [`psa_hash_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
519 …tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1ga4795fd06a0067…
521 …alling the finish or verify function, call [`psa_hash_abort`](https://mbed-tls.readthedocs.io/proj…
535 …es of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/proj…
536 …* Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
537 …* Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
538 …* Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
539 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga4…
540 … previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/proj…
541 …* Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gro…
542 …* If the key is randomly generated, use [`psa_generate_key`](https://mbed-tls.readthedocs.io/proje…
543 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the k…
545 4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthed…
567 1. Create an operation object of type [`psa_mac_operation_t`](https://mbed-tls.readthedocs.io/proje…
568 2. Call [`psa_mac_sign_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/grou…
569 3. Call [`psa_mac_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gr…
570 4. To obtain the MAC, call [`psa_mac_sign_finish`](https://mbed-tls.readthedocs.io/projects/api/en/…
574 1. Create an operation object of type [`psa_mac_operation_t`](https://mbed-tls.readthedocs.io/proje…
575 2. Call [`psa_mac_verify_setup`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/gr…
576 3. Call [`psa_mac_update`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gr…
577 4. To verify the MAC against an expected value, call [`psa_mac_verify_finish`](https://mbed-tls.rea…
579 …n without calling the finish function, call [`psa_mac_abort`](https://mbed-tls.readthedocs.io/proj…
583 * [`psa_mac_compute`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__…
584 * [`psa_mac_verify`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group___…
590 …tls.readthedocs.io/projects/api/en/development/api/group/group__hash/#group__hash_1gab0b4d5f9912a6…
592 …tls_md_clone` to clone a hash operation is [`psa_hash_clone`](https://mbed-tls.readthedocs.io/proj…
598 …DF-Extract and HKDF-Expand via its [key derivation interface](https://mbed-tls.readthedocs.io/proj…
600 1. Create an operation object of type [`psa_key_derivation_operation_t`](https://mbed-tls.readthedo…
601 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__deriv…
602 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__deriv…
603 …1. [`PSA_KEY_DERIVATION_INPUT_SALT`](https://mbed-tls.readthedocs.io/projects/api/en/development/a…
604 …2. [`PSA_KEY_DERIVATION_INPUT_SECRET`](https://mbed-tls.readthedocs.io/projects/api/en/development…
605 …3. [`PSA_KEY_DERIVATION_INPUT_INFO`](https://mbed-tls.readthedocs.io/projects/api/en/development/a…
606 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__deriv…
607 5. Call [`psa_key_derivation_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/ap…
613 1. Create an operation object of type [`psa_key_derivation_operation_t`](https://mbed-tls.readthedo…
614 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__deriv…
616 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__deriv…
617 …1. [`PSA_KEY_DERIVATION_INPUT_SALT`](https://mbed-tls.readthedocs.io/projects/api/en/development/a…
618 …2. [`PSA_KEY_DERIVATION_INPUT_SECRET`](https://mbed-tls.readthedocs.io/projects/api/en/development…
619 5. Call [`psa_key_derivation_output_bytes`](https://mbed-tls.readthedocs.io/projects/api/en/develop…
620 …Use [`psa_key_derivation_output_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/…
621 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/#group__key__deriv…
622 6. Call [`psa_key_derivation_abort`](https://mbed-tls.readthedocs.io/projects/api/en/development/ap…
636 …om data for some other purposes, call [`psa_generate_random`](https://mbed-tls.readthedocs.io/proj…
638 … the mbedtls API and you need to pass an RNG argument to a legacy or X.509/TLS function, include t…
640 * [`mbedtls_psa_get_random`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/p…
641 * [`MBEDTLS_PSA_RANDOM_STATE`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file…
643 You can remove the Mbed TLS RNG boilerplate (`mbedtls_entropy_init`, `mbedtls_ctr_drbg_init`, `mbed…
649 …rsion of Mbed TLS will include a PSA interface for configuring entropy sources. This is likely to …
653 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) can serve a simi…
661 In the PSA API, keys are referenced by an identifier of type [`psa_key_id_t`](https://mbed-tls.read…
662 (Some documentation references [`mbedtls_svc_key_id_t`](https://mbed-tls.readthedocs.io/projects/ap…
667 …es of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/proj…
668 …* Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
669 …* Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
670 …* Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
671 …* Call [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api…
672 … previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/proj…
673 …* Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gro…
674 …* If the key is randomly generated, use [`psa_generate_key`](https://mbed-tls.readthedocs.io/proje…
675 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the k…
677 4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthed…
683 …ags (combined with bitwise-or) to [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/proj…
688 | export private key | [`PSA_KEY_USAGE_EXPORT`](https://mbed-tls.readthedocs.io/projects/api/en/dev…
689 | Sign a message directly | [`PSA_KEY_USAGE_SIGN_MESSAGE`](https://mbed-tls.readthedocs.io/projects…
690 …tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga552117ac9…
691 | Verify a message directly | [`PSA_KEY_USAGE_VERIFY_MESSAGE`](https://mbed-tls.readthedocs.io/proj…
692 …tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1gabea7ec417…
693 | Encryption | [`PSA_KEY_USAGE_ENCRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/developmen…
694 | Decryption | [`PSA_KEY_USAGE_DECRYPT`](https://mbed-tls.readthedocs.io/projects/api/en/developmen…
695 | Key agreement | [`PSA_KEY_USAGE_DERIVE`](https://mbed-tls.readthedocs.io/projects/api/en/developm…
699 …hes. In an algorithm policy, you can use [`PSA_ALG_ANY_HASH`](https://mbed-tls.readthedocs.io/proj…
700 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae…
711 An RSA public key has the type [`PSA_KEY_TYPE_RSA_PUBLIC_KEY`](https://mbed-tls.readthedocs.io/proj…
713 An RSA key pair has the type [`PSA_KEY_TYPE_RSA_KEY_PAIR`](https://mbed-tls.readthedocs.io/projects…
718 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
719 * PKCS#1v1.5 RSA encryption: [`PSA_ALG_RSA_PKCS1V15_CRYPT`](https://mbed-tls.readthedocs.io/project…
720 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
721 * PKCS#1 RSAES-OAEP encryption: [`PSA_ALG_RSA_OAEP`](https://mbed-tls.readthedocs.io/projects/api/e…
727 An ECC public key has the type [`PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve)`](https://mbed-tls.readthedocs.…
729 An ECC key pair has the type [`PSA_KEY_TYPE_ECC_KEY_PAIR(curve)`](https://mbed-tls.readthedocs.io/p…
733 - [`mbedtls_ecc_group_to_psa()`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/gr…
734 - [`mbedtls_ecc_group_from_psa()`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/…
738 | Mbed TLS legacy curve identifier | PSA curve family | Curve bit-size |
740 | `MBEDTLS_ECP_DP_SECP192R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/…
741 | `MBEDTLS_ECP_DP_SECP224R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/…
742 | `MBEDTLS_ECP_DP_SECP256R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/…
743 | `MBEDTLS_ECP_DP_SECP384R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/…
744 | `MBEDTLS_ECP_DP_SECP521R1` | [`PSA_ECC_FAMILY_SECP_R1`](https://mbed-tls.readthedocs.io/projects/…
745 | `MBEDTLS_ECP_DP_BP256R1` | [`PSA_ECC_FAMILY_BRAINPOOL_P_R1`](https://mbed-tls.readthedocs.io/proj…
746 | `MBEDTLS_ECP_DP_BP384R1` | [`PSA_ECC_FAMILY_BRAINPOOL_P_R1`](https://mbed-tls.readthedocs.io/proj…
747 | `MBEDTLS_ECP_DP_BP512R1` | [`PSA_ECC_FAMILY_BRAINPOOL_P_R1`](https://mbed-tls.readthedocs.io/proj…
748 | `MBEDTLS_ECP_DP_CURVE25519` | [`PSA_ECC_FAMILY_MONTGOMERY`](https://mbed-tls.readthedocs.io/proje…
749 | `MBEDTLS_ECP_DP_SECP192K1` | [`PSA_ECC_FAMILY_SECP_K1`](https://mbed-tls.readthedocs.io/projects/…
751 | `MBEDTLS_ECP_DP_SECP256K1` | [`PSA_ECC_FAMILY_SECP_K1`](https://mbed-tls.readthedocs.io/projects/…
752 | `MBEDTLS_ECP_DP_CURVE448` | [`PSA_ECC_FAMILY_MONTGOMERY`](https://mbed-tls.readthedocs.io/project…
756 * ECDH key agreement (including X25519 and X448): [`PSA_ALG_ECDH`](https://mbed-tls.readthedocs.io/…
757 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
762 …man key pair has the type [`PSA_KEY_TYPE_DH_KEY_PAIR(group)`](https://mbed-tls.readthedocs.io/proj…
764 …public key has the type [`PSA_KEY_TYPE_DH_PUBLIC_KEY(group)`](https://mbed-tls.readthedocs.io/proj…
768 | Mbed TLS DH group P value | PSA DH group family | Bit-size |
770 | `MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io…
771 | `MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io…
772 | `MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io…
773 | `MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io…
774 | `MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN` | [`PSA_DH_FAMILY_RFC7919`](https://mbed-tls.readthedocs.io…
776 …be used for key agreement with the algorithm [`PSA_ALG_FFDH`](https://mbed-tls.readthedocs.io/proj…
780 …tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae41…
782 …tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga6776360ae…
784 …tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__exp…
812 2. Call [`mbedtls_pk_get_psa_attributes`](https://mbed-tls.readthedocs.io/projects/api/en/developme…
819 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga4…
820 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae…
821 4. Call [`mbedtls_pk_import_into_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/…
845 …licity. A future version of Mbed TLS [will provide a function to calculate the curve family](https…
891 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gac…
895 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gae…
899 To export a PSA key pair or public key, call [`psa_export_key`](https://mbed-tls.readthedocs.io/pro…
901 … key of a PSA key pair object, call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/proj…
909 …mbedtls_pk_write_key_pem` or `mbedtls_pk_write_pubkey`), Mbed TLS X.509 functions, Mbed TLS SSL fu…
911 * [`mbedtls_pk_copy_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file…
912 * [`mbedtls_pk_copy_public_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/a…
913 * [`mbedtls_pk_setup_opaque`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/…
935 …_ext` to sign an already calculated hash is [`psa_sign_hash`](https://mbed-tls.readthedocs.io/proj…
937 …bed-tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_SIGN_OUTPUT_SI…
940 …` to verify an already calculated hash is [`psa_verify_hash`](https://mbed-tls.readthedocs.io/proj…
948 …tls.readthedocs.io/projects/api/en/development/api/group/group__asymmetric/#group__asymmetric_1ga9…
954 The following subsections describe the PSA signature mechanisms that correspond to legacy Mbed TLS …
958 …tls.readthedocs.io/projects/api/en/development/api/file/psa__util_8h/#group__psa__tls__helpers_1ga…
966 * [`PSA_ALG_ECDSA(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gro…
967 * [`PSA_ALG_ECDSA_ANY`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group…
968 * [`PSA_ALG_DETERMINISTIC_ECDSA(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development…
977 The PSA API offers similar functionality via “interruptible” public-key operations. As of Mbed TLS …
981 1. Create an operation object of type [`psa_sign_hash_interruptible_operation_t`](https://mbed-tls.…
982 2. Call [`psa_sign_hash_start`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/gro…
983 3. Call [`psa_sign_hash_complete`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/…
987 … object of type [`psa_verify_hash_interruptible_operation_t`](https://mbed-tls.readthedocs.io/proj…
988 2. Call [`psa_verify_hash_start`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
989 3. Call [`psa_verify_hash_complete`](https://mbed-tls.readthedocs.io/projects/api/en/development/ap…
991 …tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interr…
993 …tls.readthedocs.io/projects/api/en/development/api/group/group__interruptible__hash/#group__interr…
1001 * [`PSA_ALG_RSA_PKCS1V15_SIGN(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/development/a…
1002 * [`PSA_ALG_RSA_PKCS1V15_SIGN_RAW`](https://mbed-tls.readthedocs.io/projects/api/en/development/api…
1009 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
1019 …age (typically a symmetric key) is [`psa_asymmetric_encrypt`](https://mbed-tls.readthedocs.io/proj…
1021 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#crypto__sizes_8h_1a66ba3…
1023 …age (typically a symmetric key) is [`psa_asymmetric_decrypt`](https://mbed-tls.readthedocs.io/proj…
1025 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#crypto__sizes_8h_1a61a24…
1027 …ns describe the PSA asymmetric encryption mechanisms that correspond to legacy Mbed TLS mechanisms.
1034 The PSA algorithm is [`PSA_ALG_RSA_PKCS1V15_CRYPT`](https://mbed-tls.readthedocs.io/projects/api/en…
1042 The PSA algorithm is [`PSA_ALG_RSA_OAEP(hash)`](https://mbed-tls.readthedocs.io/projects/api/en/dev…
1052 …ntaining the private key, for example with [`psa_import_key`](https://mbed-tls.readthedocs.io/proj…
1053 …ontaining the public key, for example with [`psa_import_key`](https://mbed-tls.readthedocs.io/proj…
1054 * Export both public keys with [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/a…
1072 There is no PSA equivalent to Mbed TLS's custom key type names exposed by `mbedtls_pk_get_name`.
1079  https://github.com/Mbed-TLS/mbedtls/pull/7766#discussion_r1410568541
1088 …es of the key by filling a [`psa_key_attributes_t` structure](https://mbed-tls.readthedocs.io/proj…
1089 …* Call [`psa_set_key_type`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
1090 …* [`PSA_KEY_TYPE_DH_KEY_PAIR(group)`](https://mbed-tls.readthedocs.io/projects/api/en/development/…
1091 …* [`PSA_KEY_TYPE_ECC_KEY_PAIR(curve)`](https://mbed-tls.readthedocs.io/projects/api/en/development…
1092 …* Call [`psa_set_key_bits`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/…
1093 …* Call [`psa_set_key_algorithm`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
1094 …tls.readthedocs.io/projects/api/en/development/api/group/group__crypto__types/#group__crypto__type…
1095 …* [`PSA_ALG_KEY_AGREEMENT(ka, kdf)`](https://mbed-tls.readthedocs.io/projects/api/en/development/a…
1098 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga4…
1099 … previous step, to get an identifier of type [`psa_key_id_t`](https://mbed-tls.readthedocs.io/proj…
1100 …* Use [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
1101 …* Use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/gro…
1102 …tls.readthedocs.io/projects/api/en/development/api/group/group__key__derivation/) and create the k…
1104 4. To free the resources used by the key object, call [`psa_destroy_key`](https://mbed-tls.readthed…
1108 Call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/grou…
1109 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_EXPORT_PUBLIC_KEY_…
1111 Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/grou…
1112 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_RAW_KEY_AGREEMENT_…
1114 Call [`psa_key_derivation_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/developme…
1137 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_EXPORT_PUBLIC_KEY_…
1139 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__sizes_8h/#c.PSA_RAW_KEY_AGREEMENT_…
1141 …tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae41…
1143 5. Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
1145 6. Call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
1149 #### Translating a legacy ephemeral key agreement TLS server workflow
1151 The legacy API offers the following workflow for an ephemeral Diffie-Hellman key agreement in a TLS…
1156 …params` or `mbedtls_dhm_make_params` to generate our key pair and obtain a TLS ServerKeyExchange m…
1166 …2. Call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/…
1170 4. Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
1172 5. Call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
1174 #### Translating a legacy ephemeral key agreement TLS client workflow
1176 The legacy API offers the following workflow for an ephemeral Diffie-Hellman key agreement in a TLS…
1178 1. Upon reception of a TLS ServerKeyExchange message received from the peer, which encodes the sele…
1188 1. Upon reception of a TLS ServerKeyExchange message received from the peer, which encodes the sele…
1191 …Call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/gro…
1193 4. Call [`psa_raw_key_agreement`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/g…
1195 5. Call [`psa_destroy_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/g…
1201 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gac…
1202 * Accessing our public key: call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects…
1203 * Accessing our private key: call [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/e…
1208 …tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1gac…
1209 …EDTLS_DHM_PARAM_X` (our private key): call [`psa_export_key`](https://mbed-tls.readthedocs.io/proj…
1210 …HM_PARAM_GX` (our public key): call [`psa_export_public_key`](https://mbed-tls.readthedocs.io/proj…
1213 …s): [there is no PSA API to retrieve these values](https://github.com/Mbed-TLS/mbedtls/issues/7780…
1237 …OMERY` is the only Montgomery family. All other families supported in Mbed TLS 3.4.0 are short Wei…
1241 …info_from_name`. There is no equivalent of Mbed TLS's lookup based on the name used for the curve …
1242 …ecp_tls_write_group`. The PSA crypto API does not have this dedicated support for the TLS protocol.
1253 | `MBEDTLS_ECP_MAX_BITS` | [`PSA_VENDOR_ECC_MAX_CURVE_BITS`](https://mbed-tls.readthedocs.io/projec…
1255 …PORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)`](https://mbed-tls.readthedocs.io/proj…
1275 …tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__exp…
1276 …tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__exp…
1283 …rate to the [PSA cryptoprocessor driver interface](https://github.com/Mbed-TLS/mbedtls/blob/develo…
1286 …fault; to create an opaque key, call [`psa_set_key_lifetime`](https://mbed-tls.readthedocs.io/proj…
1306 …TLS will support LMS keys and signatures through the PSA API (`psa_generate_key`, `psa_export_publ…
1312 In Mbed TLS 4.0, we are planning to keep the ASN.1 interfaces mostly unchanged. The evolution of Ba…
1316 …tls.readthedocs.io/projects/api/en/development/api/file/crypto__extra_8h/#c.PSA_ALG_JPAKE) and the…
1318 …ween the two APIs: the legacy API is geared towards the use of EC-JPAKE in TLS 1.2, whereas the PS…
1321 …the TLS 1.2 wire format in the input or output format of several functions. In particular, one of …
1322 * The legacy API always applies the key derivation specified by TLS 1.2 to the shared secret. With …