Lines Matching full:the

4 …the PSA cryptography API. This interface complements the [PSA Cryptography API specification](http…
6 …the reference implementation of the PSA Cryptography API. At this stage, Arm does not expect major…
8 For a practical guide, with a description of the current state of drivers Mbed TLS, see our [PSA Cr…
12 ### Purpose of the driver interface
14 The PSA Cryptography API defines an interface that allows applications to perform cryptographic ope…
16 The driver interface allows implementations of the PSA Cryptography API to be built compositionally…
18 Functions in the PSA Cryptography API invoke functions in the core. Code from the core calls driver…
22 The PSA Cryptography driver interface supports two types of cryptoprocessors, and accordingly two t…
24 …the beginning of each operation. They are typically used for hardware **accelerators**. When a tra…
25 …er is invoked for the specific [key location](#lifetimes-and-locations) that the driver is registe…
29 The present specification was designed to fulfill the following high-level requirements.
31 [Req.plugins] It is possible to combine multiple drivers from different providers into the same imp…
33 …compile the code of each driver and of the core separately, and link them together. A small amount…
35 [Req.types] Support drivers for the following types of hardware: accelerators that operate on keys …
37 …The interface between drivers and the core does not involve any platform-specific consideration. D…
41 …ary. Conversely, if an accelerator fully supports cryptographic mechanism, the core must be able t…
49 …ion file**. The driver description file declares which functions the driver implements and what cr…
51 The concrete syntax for a driver description file is JSON. The structure of this JSON file is speci…
56 * C header files defining the types required by the driver description. The names of these header f…
57 …the target platform defining the entry point functions specified by the driver description. Implem…
59 How to provide the driver description file, the C header files and the object code is implementatio…
63 The concrete syntax for a driver description file is JSON.
65 In addition to the properties described here, any JSON object may have a property called `"_comment…
67 …perties must use names consisting of the implementation's name, a slash, and additional characters…
71 …ore implementations should support multiple drivers. The driver description files are passed to th…
75 A driver description is a JSON object containing the following properties:
77 …er. All the types and functions provided by the driver have a name that starts with this prefix un…
79 …the types, macros and constants referenced by the driver description. They may declare the entry p…
81 A list of **capabilities**. Each capability describes a family of functions that the driver impleme…
82 … for transparent drivers, mandatory for opaque drivers): information about the [representation of …
83 …s, optional for opaque drivers, integer or string). The size in bytes of the [persistent state of …
84 …ing). The [location value](#lifetimes-and-locations) for which this driver is invoked. In other wo…
90 …the driver implements for a certain class of cryptographic mechanisms. The capability specifies wh…
92 A capability is a JSON object containing the following properties:
94 …the name of a [driver entry point](#driver-entry-points) or driver entry point family. An entry po…
95 …. If specified, the core will invoke this capability of the driver only when performing one of the…
96 …the core will invoke this capability of the driver only for operations involving a key with one of…
97 …the core will invoke this capability of the driver only for operations involving a key with one of…
98 …the `"entry_points"` property, to the name of the C function in the driver that implements the cor…
99 …the driver may return `PSA_ERROR_NOT_SUPPORTED`, in which case the core should call another driver…
103 When the PSA Cryptography implementation performs a cryptographic mechanism, it invokes available d…
105 …e for a cryptographic mechanism that invokes a given entry point if all of the following condition…
107 …The driver specification includes a capability whose `"entry_points"` list either includes the ent…
108 * If the mechanism involves an algorithm:
109     * either the capability does not have an `"algorithms"` property;
110 …* or the value of the capability's `"algorithms"` property includes an [algorithm specification](#…
111 * If the mechanism involves a key:
112 …* either the key is transparent (its location is `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver …
113 …* or the key is opaque (its location is not `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver is an…
114 * If the mechanism involves a key:
115     * either the capability does not have a `"key_types"` property;
116 …* or the value of the capability's `"key_types"` property includes a [key type specification](#key…
117 * If the mechanism involves a key:
118     * either the capability does not have a `"key_sizes"` property;
119     * or the value of the capability's `"key_sizes"` property includes the key's size.
121 …the capabilities map the entry point to the same function name, the driver is considered available…
123 …the first matching driver in the [specification list](#driver-description-list) is invoked. If the…
125 If multiple opaque drivers have the same location, the list of driver specifications is invalid.
129 …the following capability declares that the driver can perform deterministic ECDSA signatures (but …
137 …the following capability declares that the driver can perform deterministic ECDSA signatures using…
152 …the PSA Cryptography API. If the macro takes arguments, the string must have the syntax of a C mac…
166 …ined by the PSA Cryptography API. If the macro takes an argument, the string must have the syntax …
168 The name `_` may be used instead of a curve or group to indicate that the capability concerns all c…
181 …the **entry points** of the driver. Most driver entry points correspond to a particular function i…
183 … should use the status codes documented for PSA services in general and for PSA Cryptography in pa…
185 The signature of a driver entry point generally looks like the signature of the PSA Cryptography AP…
187 …t operate on an existing key, the `psa_key_id_t` parameter is replaced by a sequence of three para…
188     1. `const psa_key_attributes_t *attributes`: the key attributes.
190     3. `size_t key_buffer_size`: the size of the key buffer in bytes.
192 …the key buffer contains the key material, in the same format as defined for `psa_export_key()` and…
194 * For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operatio…
196 …are involved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence of p…
197     1. `uint8_t *key_buffer`: a buffer for the key material or key context.
198     2. `size_t key_buffer_size`: the size of the key buffer in bytes.
199     2. `size_t *key_buffer_length`: the length of the data written to the key buffer in bytes.
201 …le. If a driver supports an entry point family, it must provide all the entry points in the family.
207 Buffer parameters for driver entry points obey the following conventions:
209 * An input buffer has the type `const uint8_t *` and is immediately followed by a parameter of type…
210 …the type `uint8_t *` and is immediately followed by a parameter of type `size_t` that indicates th…
211 …the type `uint8_t *` and is immediately followed by a parameter of type `size_t` that indicates th…
219 The following driver entry points perform a cryptographic operation in one shot (single-part operat…
221 …hash with `psa_hash_compare()`, the core calls the driver's `"hash_compute"` entry point and compa…
222 …the core calls an applicable driver's `"mac_verify"` entry point if there is one, otherwise the co…
223 …the correct MAC. Although transparent drivers may implement this entry point in addition to `"mac_…
230 … with `psa_sign_message()`, the core calls an applicable driver's `"sign_message"` entry point if …
231 …th `psa_verify_message()`, the core calls an applicable driver's `"verify_message"` entry point if…
240 The entry points that implement each step of a multi-part operation are grouped into a family. A dr…
242 1. The core initializes operation context objects to either all-bits-zero or to logical zero (`{0}`…
243 1. The core calls the `xxx_setup` entry point for this operation family. If this fails, the core de…
244 1. The core calls other entry points that manipulate the operation context object, respecting the c…
245 …. If any entry point fails, the core calls the driver's `xxx_abort` entry point for this operation…
246 …nish” entry point fails, the core destroys the operation context object without calling any other …
248 …operation but not the corresponding single-part operation, the core calls the driver's multipart o…
252 This family corresponds to the calculation of a hash in multiple steps.
256 This family requires the following type and entry points:
258 …the type of a hash operation context. It must be possible to copy a hash operation context byte by…
262 * `"hash_abort"`: called by all multi-part hash functions of the PSA Cryptography API.
264 …sh with `psa_hash_verify()`, the core calls the driver's *prefix*`_hash_finish` entry point and co…
266 …the prefix `"acme"` that implements the `"hash_multipart"` entry point family must define the foll…
311 … happens when deriving an asymmetric key, where processing the secret input and generating the key…
312 …re not always independent: if the secret input is managed by an opaque driver, it might not allow …
313 … The involvement of an opaque driver cannot be determined as soon as the operation is set up (sinc…
317 The core decides whether to dispatch a key derivation operation to a driver based on the location a…
320 …* If the driver for this secure element implements the `"key_derivation"` family for the specified…
321 …Note that for all currently specified algorithms, the key type for the secret input does not matte…
322 …* Otherwise the core calls the secure element driver's [`"export_key"`](#key-management-with-opaqu…
323 …ion-in-opaque-drivers)), if there is a transparent driver for the specified algorithm, the core ca…
324 3. Otherwise, or on fallback, the core uses its built-in implementation.
326 #### Summary of entry points for the operation family `"key_derivation"`
328 A key derivation driver has the following entry points:
330 …"key_derivation_setup"` (mandatory): always the first entry point to be called. This entry point p…
331 …ep"` (mandatory if the driver supports a key derivation algorithm with long inputs, otherwise igno…
333 … (optional, opaque drivers only): derive key material which remains inside the same secure element…
334 …opaque drivers; not permitted for transparent drivers): update the capacity policy on the operatio…
335 * `"key_derivation_abort"` (mandatory): always the last entry point to be called.
337 …the following subsection, this specification takes the example of a driver with the prefix `"acme"…
345 The core conveys the initial inputs for a key derivation via an opaque data structure of type `psa_…
351 …retrieve its contents by calling one of the type-specific functions below. To determine the correc…
360     // Implementations may add other values, and may freely choose the
369 The function `psa_crypto_driver_key_derivation_get_input_type()` determines whether a given step is…
371 * `PSA_KEY_DERIVATION_INPUT_TYPE_INVALID`: the step is invalid for the algorithm of the operation t…
372 * `PSA_KEY_DERIVATION_INPUT_TYPE_OMITTED`: the step is optional for the algorithm of the operation …
373 …the step is valid and present and is a transparent byte string. Call `psa_crypto_driver_key_deriva…
374 …the step is valid and present and is a byte string passed via a key object. Call `psa_crypto_drive…
375 …YPE_INTEGER`: the step is valid and present and is an integer. Call `psa_crypto_driver_key_derivat…
397 The get-data functions take the following parameters:
399 * The first parameter `inputs` must be a pointer passed by the core to a key derivation driver setu…
400 * The `step` parameter indicates the input step whose content the driver wants to retrieve.
401 …n of `psa_crypto_driver_key_derivation_get_input_size`, the core sets `*size` to the size of the s…
402 …the core fills the first *N* bytes of `buffer` with the specified input and sets `*buffer_length` …
403 …the core sets `*key_buffer` to a pointer to a buffer containing the key context and `*key_buffer_s…
404 … `psa_crypto_driver_key_derivation_get_input_integer`, the core sets `*value` to the value of the …
406 These functions can return the following statuses:
408 …the call succeeded and the requested value has been copied to the output parameter (`size`, `buffe…
409 … the input step is valid for this particular algorithm, but it is not part of the initial inputs. …
410 …the input type is not compatible with this function or was omitted. Call `psa_crypto_driver_key_de…
411 …the output buffer is too small. This is not a fatal error and the driver can, for example, subsequ…
412 * The core may return other errors such as `PSA_ERROR_CORRUPTION_DETECTED` or `PSA_ERROR_COMMUNICAT…
416 A key derivation driver must implement the following entry point:
425 * `alg` is the algorithm for the key derivation operation. It does not include a key agreement comp…
426 * `inputs` is an opaque pointer to the [initial inputs](#key-derivation-driver-initial-inputs) for …
430 …the [initial inputs](#key-derivation-driver-initial-inputs). A driver that implements a key deriva…
439 At the time of writing, no standard key derivation algorithm has long inputs. It is likely that suc…
443 The core keeps track of an operation's capacity and enforces it. The core guarantees that it will n…
445 …the capacity limitation and must return `PSA_ERROR_INSUFFICIENT_CAPACITY` from any output request …
453 If this entry point has not been called, the operation has an unlimited capacity.
457 A key derivation driver must provide the following entry point:
464 An opaque key derivation driver may provide the following entry points:
478 The core calls a key derivation driver's output entry point when the application calls `psa_key_der…
480 …the key derivation's `PSA_KEY_DERIVATION_INPUT_SECRET` input is in a secure element and the deriva…
484 …the derived key is in the same secure element, if the driver has an `"key_derivation_output_key"` …
485 …1. If the driver's capabilities indicate that its `"import_key"` entry point does not support the …
486 …1. Otherwise proceed as for `psa_key_derivation_output_bytes()`, then import the resulting key mat…
489     1. If the driver has a `"key_derivation_verify_key"` entry point, call it and stop.
490 …1. Call the driver's `"export_key"` entry point on the key object that contains the expected value…
493 …1. If the driver has a `"key_derivation_verify_bytes"` entry point, call that entry point on the e…
494 …`psa_key_derivation_output_bytes()`, and compare the resulting output to the expected output insid…
497 …the `"key_derivation_output_bytes"` entry point. The core may call this entry point multiple times…
499 …the key derivation operation is not handled by an opaque driver as described above, the core calls…
501 * For a call to `psa_key_derivation_output_key()` for some key types, the core calls a transparent …
502 * For a call to `psa_key_derivation_output_key()` where the derived key is in a secure element, cal…
506 …the key material of a derived (8×*n*)-bit key consists of the next *n* bytes of output from the ke…
508 A capability for cooked key derivation contains the following properties (this is not a subset of […
511 …(#key-type-specifications). This capability only applies when deriving a key of the specified type.
512 …the derived key, in bits. This capability only applies when deriving a key of the specified sizes.…
513 …y"` (optional, boolean). If present and true, the driver must define a type `"derive_key_memory_t"…
515 …nal, boolean). If present and true, the driver may return `PSA_ERROR_NOT_SUPPORTED` if it only par…
517 A transparent driver with the prefix `"acme"` that implements cooked key derivation must provide th…
520 typedef ... acme_derive_key_memory_t; // only if the "memory" property is true
524     acme_derive_key_memory_t *memory, // if the "memory" property is false: void*
528 * `attributes` contains the attributes of the specified key. Note that only the key type and the bi…
529 * `input` is a buffer of `input_length` bytes which contains the raw key stream, i.e. the data that…
530 …the driver capability is true, `memory` is a data structure that the driver may use to store data …
531 …y_buffer` is a buffer for the output material, in the appropriate [export format](#key-format-for-…
532 * On success, `*key_buffer_length` must contain the number of bytes written to `key_buffer`.
534 This entry point may return the following statuses:
536 * `PSA_SUCCESS`: a key was derived successfully. The driver has placed the representation of the ke…
537 * `PSA_ERROR_NOT_SUPPORTED` (for the first call only) (only if fallback is enabled): the driver can…
538 …UFFICIENT_DATA`: the core must call the `"derive_key"` entry point again with the same `memory` ob…
541 The core calls the `"derive_key"` entry point in a loop until it returns a status other than `PSA_E…
543 For standard key types, the `"derive_key"` entry point is called with a certain input length as fol…
545 * `PSA_KEY_TYPE_DES`: the length of the key.
546 …_ECC_KEY_PAIR(…)`, `PSA_KEY_TYPE_DH_KEY_PAIR(…)`: $m$ bytes, where the bit-size of the key $n$ sat…
554 The core always decouples key agreement from symmetric key derivation.
556 …the private key is in a secure element that has a `"key_agreement_to_key"` entry point which is ap…
558 1. Call the `"key_agreement_to_key"` entry point to create a key object containing the shared secre…
559 2. Call the `"key_derivation_setup"` entry point, passing the resulting key object .
560 3. Perform the rest of the key derivation, up to and including the call to the `"key_derivation_abo…
561 4. Call the `"destroy_key"` entry point to destroy the key containing the key object.
563 …the core treats `psa_key_derivation_key_agreement()` as if it was a call to `psa_raw_key_agreement…
565 The entry points related to key agreement have the following prototypes for a driver with the prefi…
588 …the attributes for the shared secret are not placed near the beginning, but rather grouped with th…
595 The core decides whether to dispatch a PAKE operation to a driver based on the location of the prov…
596 When all inputs are collected and `"psa_pake_output"` or `"psa_pake_input"` is called for the first…
598 1. If the location of the `password` is the local storage
599 - if there is a transparent driver for the specified ciphersuite, the core calls that driver's `"pa…
600 - otherwise, or on fallback, the core uses its built-in implementation.
601 2. If the location of the `password` is the location of a secure element
602 - the core calls the `"pake_setup"` entry point of the secure element driver and subsequent entry p…
606 A PAKE driver has the following entry points:
607 …pake_setup"` (mandatory): always the first entry point to be called. It is called when all inputs …
608 * `"pake_output"` (mandatory): derive cryptographic material for the specified step and output it.
609 * `"pake_input"` (mandatory): provides cryptographic material in the format appropriate for the spe…
611 * `"pake_abort"` (mandatory): always the last entry point to be called.
613 …the following subsection, this specification takes the example of a driver with the prefix `"acme"…
621 The core conveys the initial inputs for a PAKE operation via an opaque data structure of type `psa_…
627 …a_crypto_driver_pake_inputs_t` can retrieve its contents by calling one of the get-data functions …
663 The get-data functions take the following parameters:
665 The first parameter `inputs` must be a pointer passed by the core to a PAKE driver setup entry poin…
668 These functions can return the following statuses:
670 * `PSA_ERROR_BAD_STATE`: the inputs are not ready
671 …the output buffer is too small. This is not a fatal error and the driver can, for example, subsequ…
681 * `inputs` is an opaque pointer to the [inputs](#pake-driver-inputs) for the PAKE operation.
683 The setup driver function should preserve the inputs using get-data functions.
685 The pointer output by `psa_crypto_driver_pake_get_password_key` is only valid until the "pake_setup…
699 * `output` buffer where the output is to be written.
700 * `output_size` size of the output buffer in bytes.
701 * `output_length` the number of bytes of the returned output.
703 For `PSA_ALG_JPAKE` the following steps are available for output operation:
704 `step` can be one of the following values:
706 * `PSA_JPAKE_X1_STEP_ZK_PUBLIC`     Round 1: output Schnorr NIZKP public key for the X1 key
707 * `PSA_JPAKE_X1_STEP_ZK_PROOF`      Round 1: output Schnorr NIZKP proof for the X1 key
709 * `PSA_JPAKE_X2_STEP_ZK_PUBLIC`     Round 1: output Schnorr NIZKP public key for the X2 key
710 * `PSA_JPAKE_X2_STEP_ZK_PROOF`      Round 1: output Schnorr NIZKP proof for the X2 key
712 * `PSA_JPAKE_X2S_STEP_ZK_PUBLIC`    Round 2: output Schnorr NIZKP public key for the X2S key 
713 * `PSA_JPAKE_X2S_STEP_ZK_PROOF`     Round 2: output Schnorr NIZKP proof for the X2S key
725 * `input` buffer containing the input.
726 * `input_length` length of the input in bytes.
728 For `PSA_ALG_JPAKE` the following steps are available for input operation:
730 * `PSA_JPAKE_X1_STEP_ZK_PUBLIC`     Round 1: input Schnorr NIZKP public key for the X1 key
731 * `PSA_JPAKE_X1_STEP_ZK_PROOF`      Round 1: input Schnorr NIZKP proof for the X1 key
733 * `PSA_JPAKE_X2_STEP_ZK_PUBLIC`     Round 1: input Schnorr NIZKP public key for the X2 key
734 * `PSA_JPAKE_X2_STEP_ZK_PROOF`      Round 1: input Schnorr NIZKP proof for the X2 key
736 * `PSA_JPAKE_X4S_STEP_ZK_PUBLIC`    Round 2: input Schnorr NIZKP public key for the X4S key
737 * `PSA_JPAKE_X4S_STEP_ZK_PROOF`     Round 2: input Schnorr NIZKP proof for the X4S key
739 The core checks that `input_length` is not greater than `PSA_PAKE_INPUT_SIZE(alg, prim, step)` and
740 the driver can rely on that.
751 * `operation` The driver PAKE operation object to use.
752 * `output` Buffer where the implicit key is to be written.
753 * `output_size` Size of the output buffer in bytes.
754 * `output_length` On success, the number of bytes of the implicit key.
758 The driver entry points for key management differ significantly between [transparent drivers](#key-…
760 The entry points that create or format key data have the following prototypes for a driver with the…
779 * The key attributes (`attributes`) have the same semantics as in the PSA Cryptography application …
780 * For the `"import_key"` entry point, the input in the `data` buffer is either the export format or…
781 …The size of the key data buffer `key_buffer` is sufficient for the internal representation of the …
782 …paque driver with an `"allocate_key"` entry point, the content of the key data buffer on entry is …
783 * The `"import_key"` entry point must determine or validate the key size and set `*bits` as describ…
785 …the resulting key is valid as specified in the section [“Key validation”](#key-validation) below. …
789 The `"import_key"` entry point must determine or validate the key size.
790 The PSA Cryptography API exposes the key size as part of the key attributes.
791 …the key size recorded in the key attributes can be either a size specified by the caller of the AP…
793 …the core calls the `"import_key"` entry point to process a call to `psa_import_key`, it passes an …
795 * The core sets `*bits` to `psa_get_key_bits(attributes)` before calling the `"import_key"` entry p…
796 …the driver must determine the key size from the data and set `*bits` to this size. If the key size…
797 …the driver must check the value of `*bits` against the data and return `PSA_ERROR_INVALID_ARGUMENT…
801 …s must produce valid key data. Key data is _valid_ if operations involving the key are guaranteed …
803 … a certain size, or if the keying material involves integers that have to be in a certain range, k…
805 …the creation of A must ensure that using it does not risk compromising B. This applies even if A's…
806 …the other hand, it is acceptable for import to accept a key that cannot be verified as valid if us…
808 …the key context can only be used by code from the same driver, so key validity is primarily intend…
812 * For symmetric key types, check that the key size is suitable for the type.
813 * For DES (`PSA_KEY_TYPE_DES`), additionally verify the parity bits.
814 * For RSA (`PSA_KEY_TYPE_RSA_PUBLIC_KEY`, `PSA_KEY_TYPE_RSA_KEY_PAIR`), check the syntax of the key…
815 * For elliptic curve private keys (`PSA_KEY_TYPE_ECC_KEY_PAIR`), check the size and range. TODO: wh…
816 … public keys (`PSA_KEY_TYPE_ECC_PUBLIC_KEY`), check the size and range, and that the point is on t…
820 …g a `"get_entropy"` entry point. This entry point has the following prototype for a driver with th…
829 The semantics of the parameters is as follows:
832 …the amount of entropy that is present in the `output` buffer, in bits. This must be at least `1` o…
833 …the entropy is coming from a hardware peripheral, this should preferably be raw or lightly conditi…
834 * `output_size`: the size of the `output` buffer in bytes. This size should be large enough to allo…
836 …the driver wrote to the buffer. Such an output length indication is not necessary because the entr…
838 The entry point may return the following statuses:
840 * `PSA_SUCCESS`: success. The output buffer contains some entropy.
841 …lable without blocking. This is only permitted if the `PSA_DRIVER_GET_ENTROPY_BLOCK` flag is clear…
842 * Other error codes indicate a transient or permanent failure of the entropy source.
844 …transparent drivers include a `"get_entropy"` point, the core will call all of them (as well as th…
848 …_BLOCK`: If this flag is set, the driver should block until it has at least one bit of entropy. If…
849 … set, the driver should expect another call to `acme_get_entropy` after a short time. If this flag…
853 The intent of the `BLOCK` and `KEEPALIVE` [flags](#entropy-collection-flags) is to support drivers …
857 …The core makes a first round of calls to `"get_entropy"` on every source with the `BLOCK` flag cle…
858 2. The core makes a second round of calls with the `BLOCK` flag set and the `KEEPALIVE` flag clear …
859 3. If the second round does not collect enough entropy, the core makes more similar rounds, until t…
865 …the core calls this entry point once during the initialization of the PSA Cryptography subsystem. …
867 When multiple drivers have an init entry point, the order in which they are called is unspecified. …
869 …the PSA Cryptography implementation is a subsystem of a single application, the initialization of …
871 The init entry point does not take any parameter.
875 …que driver. You can use the mapping in capabilities' `"names"` property to arrange for multiple dr…
881 The format of a key for transparent drivers is the same as in applications. Refer to the documentat…
885 Transparent drivers may provide the following key management entry points:
890 …the core to obtain the public key of a key pair. The core may call this function at any time to ob…
896 …the general section about key management entry points](#driver-entry-points-for-key-management), t…
909 …the key data in the input buffer `data`. The driver must support the export format for the key typ…
910 2. Validate the key data. The necessary validation is described in the section [“Key validation”](#…
911 3. [Determine the key size](#key-size-determination-on-import) and output it through `*bits`.
912 …the validated key data from `data` to `key_buffer`. The output must be in the canonical format doc…
916 …n be used as a cryptographic random number generator. The random generation mechanism must obey th…
918 * The random output must be of cryptographic quality, with a uniform distribution. Therefore, if th…
920 …The random generator should be able to incorporate entropy provided by an outside source. If it is…
921 * The random generator may either be deterministic (in the sense that it always returns the same da…
923 If no driver implements the random generation entry point family, the core provides an unspecified …
925 …is operation family requires the following type, entry points and parameters (TODO: where exactly …
927 * Type `"random_context_t"`: the type of a random generation context.
928 * `"init_random"` (entry point, optional): if this function is present, [the core calls it once](#r…
929 …entry point, optional): the core calls this function to [inject entropy](#entropy-injection). This…
930 …get_random"` (entry point, mandatory): the core calls this function whenever it needs to [obtain r…
931 …mandatory): the minimum number of bytes of entropy that the core must supply before the driver can…
932 …the minimum number of bytes of entropy that the core should supply via [`"add_entropy"`](#entropy-…
934 Random generation is not parametrized by an algorithm. The choice of algorithm is up to the driver.
938 The `"init_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
944 The core calls this entry point once after allocating a random generation context. Initially, the c…
946 If a driver does not have an `"init_random"` entry point, the context object passed to the first ca…
950 The `"add_entropy"` entry point has the following prototype for a driver with the prefix `"acme"`:
958 The semantics of the parameters is as follows:
960 …: a random generation context. On the first call to `"add_entropy"`, this object has been initiali…
961 …py`: a buffer containing full-entropy data to seed the random generator. “Full-entropy” means that…
962 …the size of the `entropy` buffer in bytes. It is guaranteed to be at least `1`, but it may be smal…
964 The core calls this function to supply entropy to the driver. The driver must mix this entropy into…
966 The core may call this function at any time. For example, to enforce prediction resistance, the cor…
968 * Before the first call to the `"get_random"` entry point, to supply `"initial_entropy_size"` bytes…
969 * After a call to the `"get_random"` entry point returns less than the required amount of random da…
971 …the driver requires entropy, the core can supply it with one or more successive calls to the `"add…
977 …ount of entropy that is in general less than the buffer size. The core must apply a mixing algorit…
979 …the core may use a simple mixing scheme based on a pseudorandom function family $(F_k)$ with an $E…
981 Note that the mechanism above is only given as an example. Implementations may choose a different m…
985 …the capability to inject additional entropy through the `"add_entropy"` entry point. This ensures …
987 …the `"add_entropy"` entry point. This limits the driver's portability: implementations of the PSA …
989 * the integration of PSA Cryptography includes an entropy source that is outside the driver; or
990 * the core saves random data in persistent storage to be preserved across platform resets.
992 #### The `"get_random"` entry point
994 The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
1003 The semantics of the parameters is as follows:
1005 …the driver's `"initial_entropy_size"` property is nonzero, the core must have called `"add_entropy…
1006 …(including partial success), the first `*output_length` bytes of this buffer contain cryptographic…
1007 * `output_size`: the size of the `output` buffer in bytes.
1008 …the number of bytes of random data that the driver has written to the `output` buffer. This is pre…
1010 The driver may return the following status codes:
1012 …the `output` buffer contains `*output_length` bytes of cryptographic-quality random data. Note tha…
1013 * `PSA_ERROR_INSUFFICIENT_ENTROPY`: the core must supply additional entropy by calling the `"add_en…
1014 …_NOT_SUPPORTED`: the random generator is not available. This is only permitted if the driver speci…
1019 …The capability description language allows specifying some restrictions, including restrictions on…
1020 …ports a [capability](#driver-description-capability) partially, by setting the capability's `"fall…
1022 …D`, the core will call the next transparent driver that supports the mechanism, if there is one. T…
1024 If all the available drivers have fallback enabled and return `PSA_ERROR_NOT_SUPPORTED`, the core w…
1025 …RTED` (`PSA_SUCCESS` or a different error code), this value is returned to the application, withou…
1027 …t driver entry point is part of a capability where the `"fallback"` property is false or omitted, …
1031 … material in cleartext. The opaque driver interface is designed so that the core never inspects th…
1033 …The representation of a key is the key material wrapped with a master key which is located in the …
1034 …sistent storage for individual keys. The representation of a key is an identifier such as label or…
1038 The format of a key for opaque drivers is an opaque blob. The content of this blob is fully up to t…
1040 Note that since the core stores the key context blob as it is in memory, it must only contain data …
1042 The `"key_context"` property in the [driver description](#driver-description-top-level-element) spe…
1047 … optional): every key context for a symmetric key includes this many times the key size. If omitte…
1048 …true, for a key pair, the key context includes space for the public key. If omitted or false, no a…
1049 …the name of a function that returns the number of bytes that the driver needs in a key context for…
1050 … this overrides all other methods (including the `"size_function"` entry point) to determine the s…
1052 The integer properties must be C language constants. A typical value for `"base_size"` is `sizeof(a…
1056 …the core supports dynamic allocation for the key context and chooses to use it, and the driver spe…
1060 …n` is the function named in the `"size_function"` property, `key_type` is the key type and `key_bi…
1067 …the core does not support dynamic allocation for the key context or chooses not to use it, or if t…
1073 …where `public_key_overhead = PSA_EXPORT_PUBLIC_KEY_MAX_SIZE(key_type, key_bits)` if the `"store_pu…
1084     where `key_bytes = ((key_bits + 7) / 8)` is the key size in bytes.
1088 …the key is stored in the secure element and the driver only needs to store a label for the key, us…
1090 …the key is stored in the secure element, but the secure element does not store the public part of …
1094 …the key is stored in wrapped form outside the secure element, and the wrapped form of the key plus…
1098 Opaque drivers may provide the following key management entry points:
1101 …the core to obtain the public key of a key pair. The core may call this entry point at any time to…
1105 * `"copy_key"`: called by `psa_copy_key()` when copying a key within the same [location](#lifetimes…
1108 In addition, secure elements that store the key material internally must provide the following two …
1110 …_key_derivation_output_key()` or `psa_copy_key()` before creating a key in the location of this dr…
1115 …s the key creation process for secure elements that do not store the key material. The driver must…
1119 1. The core allocates memory for the key context.
1120 2. The core calls the driver's import, generate, derive or copy entry point.
1121 3. The core saves the resulting wrapped key material and any other data that the key context may co…
1123 To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
1127 This section describes the key creation and key destruction processes for secure elements that have…
1129 * `"allocate_key"`: this function obtains an internal identifier for the key. This may be, for exam…
1130 * `"destroy_key"`: this function invalidates the internal identifier and destroys the associated ke…
1132 These functions have the following prototypes for a driver with the prefix `"acme"`:
1144 …The core calls the driver's `"allocate_key"` entry point. This function typically allocates an int…
1146 1. The core saves the key context to persistent storage.
1148 1. The core calls the driver's key creation entry point.
1150 1. The core saves the updated key context to persistent storage.
1152 …a failure occurs after the `"allocate_key"` step but before the call to the second driver entry po…
1154 …Fail the creation of the key without indicating this to the driver. This can happen, in particular…
1155 * Call the driver's `"destroy_key"` entry point.
1157 To destroy a key, the core calls the driver's `"destroy_key"` entry point.
1159 …the key allocation and destruction entry points must not rely solely on the key identifier in the …
1161 …the secure element or in the driver's persistent storage. To allocate a key slot, find a free slot…
1162 …the secure element or in the driver's persistent storage. To allocate a key slot, increment the co…
1164 TODO: explain constraints on how the driver updates its persistent state for resilience
1166 TODO: some of the above doesn't apply to volatile keys
1170 The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
1186 …the driver has an [`"allocate_key"` entry point](#key-management-in-a-secure-element-with-storage)…
1192 The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
1209 The core will only call `acme_export_public_key` on a private key. Drivers implementers may choose …
1211 The core guarantees that the size of the output buffer (`data_size`) is sufficient to export any ke…
1215 The core maintains persistent state on behalf of an opaque driver. This persistent state consists o…
1217 The core loads the persistent state in memory before it calls the driver's [init entry point](#driv…
1219 * The first time the driver is loaded on a system, the persistent state is all-bits-zero.
1220 * If the stored persistent state is smaller than the declared size, the core pads the persistent st…
1221 * If the stored persistent state is larger than the declared size, the core truncates the persisten…
1223 The core provides the following callback functions, which an opaque driver may call while it is pro…
1229 …the first byte of the persistent state. This pointer remains valid during a call to a driver entry…
1231 …the persistent state in persistent storage. Only the portion at byte offsets `from` inclusive to `…
1233 The core will not update the persistent state in storage while an entry point is running except whe…
1235 In a multithreaded environment, the driver may only call these two functions from the thread that i…
1239 …are built-in keys. Built-in keys can be accessed, but not created, through the PSA Cryptography AP…
1241 …the key data and metadata. The core calls this entry point when it needs to access the key, typica…
1251 …ttributes` with the attributes of the key (except for the key identifier). On success, this functi…
1253 …the location at which the driver was declared and a persistence level with which the platform is a…
1255 The output parameter `key_buffer` points to a writable buffer of `key_buffer_size` bytes. If the dr…
1257 …ally, for a built-in key, the key context is a reference to key material that is kept inside the s…
1259 This entry point may return the following status values:
1261 …the requested key exists, and the output parameters `attributes` and `key_buffer` contain the key …
1262 …the driver must pass the key's attributes in `*attributes`. In particular, `get_builtin_key(slot_n…
1263 * `PSA_ERROR_DOES_NOT_EXIST`: the requested key does not exist.
1266 The core will pass authorized requests to destroy a built-in key to the [`"destroy_key"`](#key-mana…
1272 Transparent drivers linked into the library are automatically used for the mechanisms that they imp…
1276 …The driver is invoked for all actions that use a key in that location. A key's location is indicat…
1278 For example, the following snippet creates an AES-GCM key which is only accessible inside the secur…
1296 The PSA Cryptography API, version 1.0.0, defines [lifetimes](https://armmbed.github.io/mbed-crypto/…
1298 … actions can cause it to be destroyed. In particular, it indicates whether the key is volatile or …
1299 …_location indicator_. This value indicates where the key material is stored and where operations o…
1301 …the default location (`PSA_KEY_LOCATION_LOCAL_STORAGE = 0`) are transparent: the core has direct a…
1305 The core defines a compile-time constant for each opaque driver indicating its location called `PSA…
1332 …the use of the values, so they might not be uniform. Note that if the value can be zero and it's p…
1343 The core may want to provide declarations for the driver entry points so that it can compile code u…
1349 … use? It should be possible to combine drivers from different sources. Use the same vendor assignm…
1351 …the driver assembly process generate distinct location values as needed? This can be convenient, b…
1353 The current plan is for Arm to maintain a registry of vendors and assign a location namespace to ea…
1357 When multiple transparent drivers implement the same mechanism, which one is called? The first one?…
1359 The current choice is that the first one is used, which allows having a preference order on drivers…
1369 Should the core guarantee that the output buffer size has the size indicated by the applicable buff…
1375 The main reason is to avoid complex buffer ownership. A driver entry point does not own memory afte…
1381 …the driver interface had a concept of _substitution points_: places in the calculation where a dri…
1383 …rocessor that performs the RSA exponentiation, but not the padding. The driver should be able to l…
1384 … for a single block, or only in ECB mode, or only in CTR mode. The core would perform the block mo…
1386 …de such as specifying inner functions like `psa_rsa_pad` in the core, should be added to the speci…
1392 How does `psa_key_derivation_output_key` work when the extraction part and the expansion part use d…
1396 …the private key value only. The public key needs to be calculated from that. Both transparent driv…
1398 The specification doesn't mention when the public key might be calculated. The core may calculate i…
1402 Should the entry point be called for symmetric keys as well?
1406 …the input to `"import_key"` can be an implementation-defined format. Is this a good idea? It reduc…
1408 …the core can't know the size of the key representation until it knows the bit-size of the key, but…
1414 The driver is allowed to update the state at any time. Is this ok?
1416 …dating the persistent state at arbitrary times is to renew a key that is used to encrypt communica…
1418 `psa_crypto_driver_get_persistent_state` does not identify the calling driver, so the driver needs …
1424 …the `"derive_key"` entry point, how does the core choose `input_length`? Doesn't the driver know b…
1428 …y_derivation_setup"` returns `PSA_ERROR_NOT_SUPPORTED` then the core exports the key from the secu…
1430 …the ["`key_derivation_output_key`"](#key-derivation-driver-outputs) capability indicate which key …
1436 …the input to the [`"add_entropy"` entry point](#entropy-injection) be a full-entropy buffer (with …
1438 …ng. `"add_entropy"` needs an extra parameter to indicate the amount of entropy in the data. The co…
1439 …ng. `"add_entropy"` needs an extra parameter to indicate the amount of entropy in the data. The co…
1444 Are the [entropy collection flags](#entropy-collection-flags) well-chosen?
1448 May the core instantiate a random generation context more than once? In other words, can there be m…
1450 …ny. If the core wants some parts of the system to use a deterministic generator for reproducibilit…