Lines Matching refs:API
1 # Transitioning to the PSA API
18 Then use the [summary of API modules](#summary-of-api-modules), the table of contents or a text sea…
24 **Reference**: The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/) i…
29 * [PSA API open issues](https://github.com/ARM-software/psa-api/issues) (not just cryptography APIs)
32 ### Why change the API?
34 …ion. For example, it is hard to support hardware acceleration, because the API constrains how the …
35 …quire key material to be present in the application memory. The PSA Crypto API natively supports o…
36 …put buffer needs to be based on the selected algorithm, whereas in the PSA API, all buffer argumen…
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.
51 To make the PSA API available, make sure that the configuration option [`MBEDTLS_PSA_CRYPTO_C`](htt…
55 …pto API offers a similar set of cryptographic mechanisms as those offered by the legacy API (confi…
82 …th the provided `PSA_XXX_INIT` macro or `psa_xxx_init()` function) before calling any API function.
84 Functions that output data require an output buffer of sufficient size. For all PSA crypto API func…
88 …API and the PSA API is that in the PSA API, access to keys is indirect. Operations that require a …
100 …ead consume disk space. Since persistent keys have no analog in the legacy API, we will not discus…
102 ## Summary of API modules
112 | `build_info.h` | `MBEDTLS_` | No change (not a crypto API) |
124 | `debug.h` | `mbedtls_debug_` | No change (not a crypto API) |
140 | `memory_buffer_alloc.h` | `mbedtls_memory_buffer_alloc_` | No change (not a crypto API) |
141 | `net_sockets.h` | `mbedtls_net_` | No change (not a crypto API) |
147 | `pkcs7.h` | `mbedtls_pkcs7_` | No change (not a crypto API) |
149 | `platform.h` | `mbedtls_platform_` | No change (not a crypto API) |
150 | `platform_time.h` | `mbedtls_*time*` | No change (not a crypto API) |
151 | `platform_util.h` | `mbedtls_platform_` | No change (not a crypto API) |
161 | `ssl.h` | `mbedtls_ssl_` | No change (not a crypto API) |
162 | `ssl_cache.h` | `mbedtls_ssl_cache_` | No change (not a crypto API) |
163 | `ssl_ciphersuites.h` | `mbedtls_ssl_ciphersuite_` | No change (not a crypto API) |
164 | `ssl_cookie.h` | `mbedtls_ssl_cookie_` | No change (not a crypto API) |
165 | `ssl_ticket.h` | `mbedtls_ssl_ticket_` | No change (not a crypto API) |
166 | `threading.h` | `mbedtls_threading_` | No change (not a crypto API) |
167 | `timing.h` | `mbedtls_timing_` | No change (not a crypto API) |
168 | `version.h` | `mbedtls_version_` | No change (not a crypto API) |
169 | `x509.h` | `mbedtls_x509` | No change (not a crypto API) |
170 | `x509_crl.h` | `mbedtls_x509` | No change (not a crypto API) |
171 | `x509_crt.h` | `mbedtls_x509` | No change (not a crypto API) |
172 | `x509_csr.h` | `mbedtls_x509` | No change (not a crypto API) |
180 …6db056) is enabled, the cryptographic mechanisms available through the PSA API are determined by t…
182 The availability of cryptographic mechanisms in the PSA API is based on a systematic pattern:
221 …ons that use a cryptographic mechanism both through the legacy API and through the PSA API need to…
227 The PSA Crypto API may use accelerator drivers. In this case any options controlling the driver beh…
231 …remain supported in Mbed TLS 3.x even if the application code uses the PSA API. However, they will…
254 …to the construction of Mbed TLS error code and are not relevant to the PSA API. PSA error codes ar…
258 The PSA API does not have an equivalent to the timing-side-channel-resistance utility functions in …
260 Note that the PSA API does include features that reduce the need for `mbedtls_ct_memcmp`:
267 …API for a particular block cipher (`aes.h`, `aria.h`, `camellia.h`, `des.h`), a particular block c…
289 * Other padding modes, which are obsolete, are not available in the PSA API. If you need them, hand…
293 * KW/KWP modes are not available in the PSA API at the time of writing.
302 For example, to test if AES-CBC-PKCS7 is supported, in the legacy API, you could write:
307 The equivalent in the PSA API is
314 Both APIs express key sizes in bits. Note however that in the PSA API, the size of a _buffer_ is al…
324 …ls_cipher_info_from_type` and `mbedtls_cipher_info_from_values` in the PSA API because it is unnec…
333 * `mbedtls_cipher_list`: the PSA API does not currently have a discovery mechanism for cryptographi…
334 …_variable_key_bitlen`, `mbedtls_cipher_info_has_variable_iv_size`: the PSA API does not currently …
339 The legacy API and the PSA API have a different organization of operations in several respects:
341 * In the legacy API, each operation object contains the necessary key material. In the PSA API, an …
342 * The legacy API uses the same interface for authenticated and non-authenticated ciphers, while the…
343 * The legacy API uses the same functions for encryption and decryption, while the PSA API has separ…
361 Recall the workflow of an unauthenticated cipher operation in the legacy Mbed TLS cipher API:
369 …hertext is passed as a single input), the equivalent workflow with the PSA API is to call a single…
371 …SA_CIPHER_IV_LENGTH)). (To encrypt with a specified IV, use the multi-part API described below.) Y…
374 For a multi-part operation, the equivalent workflow with the PSA API is as follows:
386 Recall the workflow of an authenticated cipher operation in the legacy Mbed TLS cipher API (or simi…
398 For a one-shot operation, the PSA API allows you to call a single function:
400 …or to separate the tag from the rest of the ciphertext, use the multi-part API described below.) …
401 …authentication tag at the end. (If the tag is separate, use the multi-part API described below.) Y…
403 For a multi-part operation, the equivalent workflow with the PSA API is as follows:
418 …6ba0). Note that you must set the key again with a setup function: the PSA API does not have a spe…
424 …API groups functions by purpose rather than by underlying primitive: there is a MAC API (equivalen…
426 The PSA API does not have a direct interface for the AES-CMAC-PRF-128 algorithm from RFC 4615 calcu…
452 PSA Crypto has a generic API with the same functions for all MAC mechanisms. The mechanism is deter…
467 For example, to test if HMAC-SHA-256 is supported, in the legacy API, you could write:
471 The equivalent in the PSA API is
476 To test if AES-CMAC is supported, in the legacy API, you could write:
480 The equivalent in the PSA API is
487 …functions `mbedtls_md_info_from_type` and `mbedtls_md_get_type` in the PSA API because it is unnec…
498 * `mbedtls_md_list`: the PSA API does not currently have a discovery mechanism for cryptographic me…
514 The equivalent process in the PSA API is as follows:
523 There is no equivalent to `mbedtls_md_file` in the PSA API. Load the file data and calculate its ha…
527 The legacy API and the PSA API have a different organization of operations in several respects:
529 * In the legacy API, each operation object contains the necessary key material. In the PSA API, an …
530 * The legacy API uses the same interface for authenticated and non-authenticated ciphers, while the…
531 * The legacy API uses the same functions for encryption and decryption, while the PSA API has separ…
549 The process for a HMAC operation in the legacy API is as follows:
557 The process for a CMAC operation in the legacy API is as follows:
565 The process in the PSA API to calculate a MAC is as follows:
581 The PSA API also offers functions for a one-shot MAC calculation, similar to `mbedtls_cipher_cmac` …
611 …c` or `mbedtls_pkcs5_pbkdf2_hmac_ext` can switch to the PSA key derivation API for PBKDF2. This is…
636 The PSA API uses its internal random generator to generate keys (`psa_generate_key`), nonces for en…
638 If your application mixes uses of the PSA crypto API and the mbedtls API and you need to pass an RN…
653 …API does not have a dedicated interface for pseudorandom generation. The [key derivation interface…
657 The PSA API supports RSA (see “[RSA mechanism selection](#rsa-mechanism-selection)”), elliptic curv…
661 In the PSA API, keys are referenced by an identifier of type [`psa_key_id_t`](https://mbed-tls.read…
663 …t`, `mbedtls_rsa_context` or `mbedtls_ecp_keypair` structure in the legacy API. However, there are…
706 …S` and `MBEDTLS_PK_RSA_ALT` correspond to RSA key types in the PSA API. In the PSA API, key pairs …
709 The PSA API uses policies and algorithm parameters rather than key types to distinguish between RSA…
725 …liptic-curve key types in the PSA API. In the PSA API, key pairs and public keys are separate obje…
764 …ere `group` is a group family as explained below. Due to the design of the API, there is rarely a …
766 The PSA API only supports Diffie-Hellman with predefined groups. A group is fully determined by a g…
780 …cedf50d5fff54ea8c5). Compared with the low-level functions from the legacy API (`mbedtls_rsa_gen_k…
798 A future extension of the PSA API will support other import formats. Until those are implemented, s…
802 …RSA or ECC key for use with PSA. This is useful for use cases that the PSA API does not currently …
807 * Importing a key with less information than what the PSA API needs, for example an ECC public key …
841 This section explains how to use the `ecp.h` API to create an elliptic curve key in a format suitab…
889 …bedtls_pk_info_t` and the functions `mbedtls_pk_info_from_type` in the PSA API because it is unnec…
893 … do, you can use the macro `PSA_BITS_TO_BYTES`. However, note that the PSA API has generic macros …
905 A future extension of the PSA API will support other export formats. Until those are implemented, s…
909 …ite_pubkey`), Mbed TLS X.509 functions, Mbed TLS SSL functions, or another API that involves `mbed…
938 …ecdsa_sign_det_ext` and `mbedtls_ecdsa_write_signature`. Note that the PSA API uses the raw format…
942 …bedtls_ecdsa_verify` amd `mbedtls_ecdsa_read_signature`. Note that the PSA API uses the raw format…
946 …[Restartable ECDSA signature](#restartable-ecdsa-signature)” for a restartable variant of this API.
948 The PSA API also has functions [`psa_sign_message`](https://mbed-tls.readthedocs.io/projects/api/en…
958 **Note: in the PSA API, the format of an ECDSA signature is the raw fixed-size format. This is diff…
964 The PSA API offers three algorithm constructors for ECDSA. They differ only for signature, and have…
968 …. This is the same as the functionality offered by `MBEDTLS_ECDSA_DETERMINISTIC` in the legacy API.
971 …egacy API, where `mbedtls_pk_sign` and `mbedtls_ecdsa_write_signature` automatically select determ…
975 …API includes an API for “restartable” ECC operations: the operation returns after doing partial co…
977 …API offers similar functionality via “interruptible” public-key operations. As of Mbed TLS 3.5, it…
999 The PSA API has two algorithm constructors:
1009 …API has two algorithm constructors: [`PSA_ALG_RSA_PSS(hash)`](https://mbed-tls.readthedocs.io/proj…
1044 …th the PK API, the mask generation is MGF1, the label is empty, and the same hash algorithm is use…
1048 …k_pubkey`,`mbedtls_ecp_check_privkey`, `mbedtls_ecp_check_pubkey`. The PSA API performs some basic…
1050 …API provides functions `mbedtls_pk_check_pair`, `mbedtls_rsa_check_pub_priv` and `mbedtls_ecp_chec…
1076 The PSA API has a generic interface for key agreement, covering the main use of both `ecdh.h` and `…
1084 The PSA API manipulates keys as such, rather than via an operation context. Thus, to use Diffie-Hel…
1118 A typical workflow for ECDH using the legacy API without a context object is:
1132 The corresponding workflow with the PSA API is as follows:
1151 The legacy API offers the following workflow for an ephemeral Diffie-Hellman key agreement in a TLS…
1162 The corresponding workflow with the PSA API is as follows:
1176 The legacy API offers the following workflow for an ephemeral Diffie-Hellman key agreement in a TLS…
1186 The corresponding workflow with the PSA API is as follows:
1199 You can obtain data and metadata from an ECDH key agreement through the PSA API as follows:
1204 * Accessing the peer's public key: there is no PSA equivalent since the PSA API only uses the peer'…
1211 …ARAM_GY` (peer's public key): the there is no PSA equivalent since the PSA API only uses the peer'…
1213 …DHM_PARAM_P` or `MBEDTLS_DHM_PARAM_G` (group parameters): [there is no PSA API to retrieve these v…
1215 The PSA API for finite-field Diffie-Hellman only supports predefined groups. Therefore there is no …
1219 …led by `mbedtls_ecdh_enable_restart`) is not yet available through the PSA API. It will be added u…
1225 The legacy API identifies a curve by an `MBEDTLS_ECP_DP_xxx` value of type `mbedtls_ecp_group_id`. …
1227 … to `mbedtls_ecp_curve_info_from_grp_id`) because they are not needed. All API elements identify t…
1229 The bit-size used by the PSA API is the size of the private key. For most curves, the PSA bit-size,…
1242 …s_ecp_tls_read_group_id` and `mbedtls_ecp_tls_write_group`. The PSA crypto API does not have this …
1247 The PSA API does not currently have a discovery mechanism for cryptographic mechanisms (although on…
1249 The API provides macros that give the maximum supported sizes for various kinds of objects. The fol…
1259 The PSA API supports the equivalent of restartable operations, but only for signatures at the time …
1261 There is no PSA API for elliptic curve arithmetic as such, and therefore no equivalent of `mbedtls_…
1269 …cluding `mbedtls_ecdsa_from_keypair`, because they are not needed: the PSA API does not have ECDSA…
1273 The PSA API is a cryptography API, not an arithmetic API. As a consequence, there is no PSA equival…
1275 …ary` and `mbedtls_ecp_point_write_binary` for uncompressed points. The PSA API does not currently …
1292 … algorithms and to generate blinding values. As a consequence, none of the API functions take an R…
1296 …API does not provide direct access to the exponentiation primitive as with `mbedtls_rsa_public` an…
1298 The PSA API does not support constructing RSA keys progressively from numbers with `mbedtls_rsa_imp…
1302 …; both concepts are out of scope of this document since they have no equivalent in the legacy API.)
1306 A future version of Mbed TLS will support LMS keys and signatures through the PSA API (`psa_generat…
1316 …API exposes EC-JPAKE via the algorithm [`PSA_ALG_JPAKE`](https://mbed-tls.readthedocs.io/projects/…
1318 …rences between the two APIs: the legacy API is geared towards the use of EC-JPAKE in TLS 1.2, wher…
1320 * The PSA API is finer-grained and offers more flexibility in message ordering. Where the legacy AP…
1321 …API uses the TLS 1.2 wire format in the input or output format of several functions. In particular…
1322 * The legacy API always applies the key derivation specified by TLS 1.2 to the shared secret. With …