Lines Matching full:driver

1 PSA Cryptoprocessor Driver Interface
8 …tate of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-…
12 ### Purpose of the driver interface
16 …driver interface allows implementations of the PSA Cryptography API to be built compositionally. A…
22 The PSA Cryptography driver interface supports two types of cryptoprocessors, and accordingly two t…
24 …hey are typically used for hardware **accelerators**. When a transparent driver is available for a…
25 …secure enclave, etc. An opaque driver is invoked for the specific [key location](#lifetimes-and-lo…
33 [Req.compile] It is possible to compile the code of each driver and of the core separately, and lin…
37 …ation. Driver calls are simple C function calls. Interactions with platform-specific hardware happ…
43 [Req.mechanisms] Drivers can specify which mechanisms they support. A driver's code will not be inv…
47 ### Deliverables for a driver
49 …driver, you need to implement some functions with C linkage, and to declare these functions in a *…
51 …ntax for a driver description file is JSON. The structure of this JSON file is specified in the se…
53 A driver therefore consists of:
55 * A driver description file (in JSON format).
56 …s defining the types required by the driver description. The names of these header files are decla…
57 … the target platform defining the entry point functions specified by the driver description. Imple…
59 How to provide the driver description file, the C header files and the object code is implementatio…
61 ### Driver description syntax
63 The concrete syntax for a driver description file is JSON.
69 #### Driver description list
71 …driver description files are passed to the implementation as an ordered list in an unspecified man…
73 #### Driver description top-level element
75 A driver description is a JSON object containing the following properties:
77 …y prefix for a C identifier. All the types and functions provided by the driver have a name that s…
79 …ader files must define the types, macros and constants referenced by the driver description. They …
80 * `"capabilities"` (mandatory, array of [capabilities](#driver-description-capability)).
81 A list of **capabilities**. Each capability describes a family of functions that the driver impleme…
83 …er or string). The size in bytes of the [persistent state of the driver](#opaque-driver-persistent…
84 …mes-and-locations) for which this driver is invoked. In other words, this determines the lifetimes…
86 ### Driver description capability
90 A capability declares a family of functions that the driver implements for a certain class of crypt…
94 …driver entry point](#driver-entry-points) or driver entry point family. An entry point is a functi…
95 …ecifications). If specified, the core will invoke this capability of the driver only when performi…
96 … the driver only for operations involving a key with one of the specified key types. If omitted, t…
97 … the driver only for operations involving a key with one of the specified key sizes. If omitted, t…
98 …the driver that implements the corresponding function. If a function is not listed here, name of t…
99 …driver may return `PSA_ERROR_NOT_SUPPORTED`, in which case the core should call another driver or …
103 …phic mechanism, it invokes available driver entry points as described in the section [“Driver entr…
105 A driver is considered available for a cryptographic mechanism that invokes a given entry point if …
107 * The driver specification includes a capability whose `"entry_points"` list either includes the en…
112 …ey is transparent (its location is `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver is transparent;
113 …(its location is not `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver is an opaque driver whose lo…
121 …driver includes multiple applicable capabilities for a given combination of entry point, algorithm…
123 …driver in the [specification list](#driver-description-list) is invoked. If the capability has [fa…
125 If multiple opaque drivers have the same location, the list of driver specifications is invalid.
129 …driver can perform deterministic ECDSA signatures (but not signature verification) using any hash …
137 …driver can perform deterministic ECDSA signatures using SHA-256 or SHA-384 with a SECP256R1 or SEC…
177 ### Driver entry points
179 #### Overview of driver entry points
181 …driver, such as a cryptographic operation, a part of a cryptographic operation, or a key managemen…
183 All driver entry points return a status of type `psa_status_t` which should use the status codes do…
185 The signature of a driver entry point generally looks like the signature of the PSA Cryptography AP…
192 …A Cryptography API. For opaque drivers, the content of the key buffer is entirely up to the driver.
194 …ation, the operation state type (`psa_XXX_operation_t`) is replaced by a driver-specific operation…
201 Some entry points are grouped in families that must be implemented as a whole. If a driver supports…
203 Drivers can also have entry points related to random generation. A transparent driver can provide a…
205 #### General considerations on driver entry point parameters
207 Buffer parameters for driver entry points obey the following conventions:
217 #### Driver entry points for single-part cryptographic operations
219 The following driver entry points perform a cryptographic operation in one shot (single-part operat…
221 …mpare()`. To verify a hash with `psa_hash_compare()`, the core calls the driver's `"hash_compute"`…
222 …e core calls an applicable driver's `"mac_verify"` entry point if there is one, otherwise the core…
230 …driver's `"sign_message"` entry point if there is one, otherwise the core calls an applicable driv…
231 …driver's `"verify_message"` entry point if there is one, otherwise the core calls an applicable dr…
236 ### Driver entry points for multi-part operations
240 …driver that implements a multi-part operation must define all of the entry points in this family a…
243 … the core destroys the operation context object without calling any other driver entry point on it.
245 …alls the driver's `xxx_abort` entry point for this operation family, then destroys the operation c…
246 …the core destroys the operation context object without calling any other driver entry point on it.…
248 If a driver implements a multi-part operation but not the corresponding single-part operation, the …
264 To verify a hash with `psa_hash_verify()`, the core calls the driver's *prefix*`_hash_finish` entry…
266 For example, a driver with the prefix `"acme"` that implements the `"hash_multipart"` entry point f…
306 ### Driver entry points for key derivation
312 …t is managed by an opaque driver, it might not allow the core to retrieve the intermediate output …
313 * The involvement of an opaque driver cannot be determined as soon as the operation is set up (sinc…
315 #### Key derivation driver dispatch logic
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…
322 …* Otherwise the core calls the secure element driver's [`"export_key"`](#key-management-with-opaqu…
323 …-opaque-drivers)), if there is a transparent driver for the specified algorithm, the core calls th…
328 A key derivation driver has the following entry points:
330 …e [initial inputs](#key-derivation-driver-initial-inputs). See [“Key derivation driver setup”](#ke…
331 …driver supports a key derivation algorithm with long inputs, otherwise ignored): provide an extra …
332 …yptographic material and output it. See [“Key derivation driver outputs”](#key-derivation-driver-o…
333 …ins inside the same secure element. See [“Key derivation driver outputs”](#key-derivation-driver-o…
334 …city policy on the operation. See [“Key derivation driver operation capacity”](#key-derivation-dri…
337 …driver with the prefix `"acme"` that implements the `"key_derivation"` entry point family with a c…
343 #### Key derivation driver initial inputs
351 …driver receiving an argument that points to a `psa_crypto_driver_key_derivation_inputs_t` can retr…
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.
403 …he key context buffer remains valid for the duration of the driver entry point. If the driver need…
409 …nputs. This is not a fatal error. The driver will receive the input later as a [long input](#key-d…
410 …ut the actual type of this input step. This is not a fatal error and the driver can, for example, …
411 …only): the output buffer is too small. This is not a fatal error and the driver can, for example, …
414 #### Key derivation driver setup
416 A key derivation driver must implement the following entry point:
426 * `inputs` is an opaque pointer to the [initial inputs](#key-derivation-driver-initial-inputs) for …
428 #### Key derivation driver long inputs
430 …driver-initial-inputs). A driver that implements a key derivation algorithm that takes such inputs…
441 #### Key derivation driver operation capacity
443 …que drivers that support [`"key_derivation_output_key"`](#key-derivation-driver-outputs), i.e. for…
455 #### Key derivation driver outputs
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…
484 …e same secure element, if the driver has an `"key_derivation_output_key"` entry point, call that e…
485 …1. If the driver's capabilities indicate that its `"import_key"` entry point does not support the …
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…
499 …driver as described above, the core calls the `"key_derivation_output_bytes"` from the applicable …
501 …erivation_output_key()` for some key types, the core calls a transparent driver's `"derive_key"` e…
502 …` where the derived key is in a secure element, call that secure element driver's `"import_key"` e…
506 …driver's `"output_bytes"` entry point, except when deriving a key entirely inside a secure element…
513 * `"memory"` (optional, boolean). If present and true, the driver must define a type `"derive_key_m…
515 * `"fallback"` (optional, boolean). If present and true, the driver may return `PSA_ERROR_NOT_SUPPO…
517 A transparent driver with the prefix `"acme"` that implements cooked key derivation must provide th…
530 * If `"memory"` property in the driver capability is true, `memory` is a data structure that the dr…
536 * `PSA_SUCCESS`: a key was derived successfully. The driver has placed the representation of the ke…
537 …t call only) (only if fallback is enabled): the driver cannot fulfill this request, but a fallback…
556 …plicable for the given key type and algorithm, the core calls the secure element driver as follows:
565 The entry points related to key agreement have the following prototypes for a driver with the prefi…
590 ### Driver entry points for PAKE
592 …s responsible for keeping inputs and core set-data functions do not have driver entry points. Coll…
594 ### PAKE driver dispatch logic
595 The core decides whether to dispatch a PAKE operation to a driver based on the location of the prov…
596 …tput"` or `"psa_pake_input"` is called for the first time `"pake_setup"` driver entry point is inv…
599 - if there is a transparent driver for the specified ciphersuite, the core calls that driver's `"pa…
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:
613 …driver with the prefix `"acme"` that implements the PAKE entry point family with a capability that…
619 #### PAKE driver inputs
627 A driver receiving an argument that points to a `psa_crypto_driver_pake_inputs_t` can retrieve its …
665 The first parameter `inputs` must be a pointer passed by the core to a PAKE driver setup entry poin…
671 …only): the output buffer is too small. This is not a fatal error and the driver can, for example, …
673 #### PAKE driver setup
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.
687 #### PAKE driver output
698 * `step` computation step based on which driver should perform an action.
715 #### PAKE driver input
724 * `step` computation step based on which driver should perform an action.
740 the driver can rely on that.
742 ### PAKE driver get implicit key
751 * `operation` The driver PAKE operation object to use.
756 ### Driver entry points for key management
758 …driver entry points for key management differ significantly between [transparent drivers](#key-man…
760 The entry points that create or format key data have the following prototypes for a driver with the…
775 …reate keys through their [`"key_derivation_output_key"`](#key-derivation-driver-outputs) and [`"ke…
781 …ent driver, this is the key's [export format](#key-format-for-transparent-drivers). For an opaque …
782 * For an opaque driver with an `"allocate_key"` entry point, the content of the key data buffer on …
796 …, the driver must determine the key size from the data and set `*bits` to this size. If the key si…
797 …!= 0`, the driver must check the value of `*bits` against the data and return `PSA_ERROR_INVALID_A…
808 With opaque drivers, the key context can only be used by code from the same driver, so key validity…
820 A driver can declare an entropy source by providing a `"get_entropy"` entry point. This entry point…
834 …he `output` buffer in bytes. This size should be large enough to allow a driver to pass unconditio…
836 … driver wrote to the buffer. Such an output length indication is not necessary because the entropy…
848 …K`: If this flag is set, the driver should block until it has at least one bit of entropy. If this…
849 … management for entropy-generating peripherals. If this flag is set, the driver should expect anot…
861 ### Miscellaneous driver entry points
863 #### Driver initialization
865 …driver may declare an `"init"` entry point in a capability with no algorithm, key type or key size…
875 …driver descriptions, one for a transparent driver and one for an opaque driver. You can use the ma…
896 …gement entry points](#driver-entry-points-for-key-management), the key import entry points has the…
909 1. Parse the key data in the input buffer `data`. The driver must support the export format for the…
916 A transparent driver may provide an operation family that can be used as a cryptographic random num…
919 …entropy but is slow at generating random data, declare it as an [entropy driver](#entropy-collecti…
923 If no driver implements the random generation entry point family, the core provides an unspecified …
929 …inject entropy](#entropy-injection). This entry point is optional if the driver is for a periphera…
931 … entropy that the core must supply before the driver can output random data. This can be `0` if th…
932 …he core should supply via [`"add_entropy"`](#entropy-injection) when the driver runs out of entrop…
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"`:
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"`:
960 …ll to `"add_entropy"`, this object has been initialized by a call to the driver's `"init_random"` …
962 … at least `1`, but it may be smaller than the amount of entropy that the driver needs to deliver r…
964 …driver. The driver must mix this entropy into its internal state. The driver must mix the whole su…
971 When the driver requires entropy, the core can supply it with one or more successive calls to the `…
973 #### Combining entropy sources with a random generation driver
975 …nt) (each having a `"get_entropy"` entry point) with a random generation driver (with an `"add_ent…
979 …y_size}$ is the desired amount of entropy in bytes (typically the random driver's `"initial_entrop…
985 …depends on all the entropy sources that are available on the platform. A driver where a call to `"…
987 However, a driver may omit the `"add_entropy"` entry point. This limits the driver's portability: i…
989 * the integration of PSA Cryptography includes an entropy source that is outside the driver; or
994 The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
1005 …driver's `"initial_entropy_size"` property is nonzero, the core must have called `"add_entropy"` a…
1008 … bytes of random data that the driver has written to the `output` buffer. This is preferably `outp…
1010 The driver may return the following status codes:
1012 …is may be less than `output_size`; in this case the core should call the driver's `"add_entropy"` …
1014 …D`: the random generator is not available. This is only permitted if the driver specification for …
1020 For these purposes, a transparent driver can declare that it only supports a [capability](#driver-d…
1022 …driver entry point is part of a capability which has a true `"fallback"` property and returns `PSA…
1025 …driver returns any value other than `PSA_ERROR_NOT_SUPPORTED` (`PSA_SUCCESS` or a different error …
1027 …driver entry point is part of a capability where the `"fallback"` property is false or omitted, th…
1031 … cleartext. The opaque driver interface is designed so that the core never inspects the representa…
1038 …e drivers is an opaque blob. The content of this blob is fully up to the driver. The core merely s…
1042 The `"key_context"` property in the [driver description](#driver-description-top-level-element) spe…
1049 …ional): the name of a function that returns the number of bytes that the driver needs in a key con…
1052 … `sizeof(acme_key_context_t)` where `acme_key_context_t` is a type defined in a driver header file.
1056 If the core supports dynamic allocation for the key context and chooses to use it, and the driver s…
1067 …namic allocation for the key context or chooses not to use it, or if the driver specification does…
1088 …nt and the driver only needs to store a label for the key, use `"base_size"` as the size of the la…
1090 … `true`. Note that this only influences the size of the key context: the driver code must copy the…
1100 …times-and-locations), or [as a fallback for key derivation](#key-derivation-driver-dispatch-logic).
1110 …_derivation_output_key()` or `psa_copy_key()` before creating a key in the location of this driver.
1115 …not store the key material. The driver must obtain a wrapped form of the key material which the co…
1117 When creating a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"…
1120 2. The core calls the driver's import, generate, derive or copy entry point.
1123 To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
1127 …for secure elements that have persistent storage for the key material. A driver for such a secure …
1132 These functions have the following prototypes for a driver with the prefix `"acme"`:
1142 When creating a persistent key with an opaque driver which has an `"allocate_key"` entry point:
1144 …driver's `"allocate_key"` entry point. This function typically allocates an internal identifier fo…
1148 1. The core calls the driver's key creation entry point.
1152 If a failure occurs after the `"allocate_key"` step but before the call to the second driver entry …
1154 * Fail the creation of the key without indicating this to the driver. This can happen, in particula…
1155 * Call the driver's `"destroy_key"` entry point.
1157 To destroy a key, the core calls the driver's `"destroy_key"` entry point.
1161 * Maintain a set of free slot numbers which is stored either in the secure element or in the driver…
1162 …unter with a practically unbounded range in the secure element or in the driver's persistent stora…
1164 TODO: explain constraints on how the driver updates its persistent state for resilience
1170 The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
1186 If the driver has an [`"allocate_key"` entry point](#key-management-in-a-secure-element-with-storag…
1192 The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
1211 …ta_size`) is sufficient to export any key with the given attributes. The driver must set `*data_le…
1213 ### Opaque driver persistent state
1215 …driver. This persistent state consists of a single byte array whose size is given by the `"persist…
1217 …it calls the driver's [init entry point](#driver-initialization). It is adjusted to match the size…
1219 * The first time the driver is loaded on a system, the persistent state is all-bits-zero.
1223 …following callback functions, which an opaque driver may call while it is processing a call from t…
1229 …e of the persistent state. This pointer remains valid during a call to a driver entry point. Once …
1231 …her changes made to other parts of the state are taken into account. The driver must call this fun…
1235 In a multithreaded environment, the driver may only call these two functions from the thread that i…
1253 …driver was declared and a persistence level with which the platform is attempting to register the …
1255 …y_buffer` points to a writable buffer of `key_buffer_size` bytes. If the driver has a [`"builtin_k…
1257 … [`"allocate_key"`](#key-management-in-a-secure-element-with-storage). A driver may have built-in …
1262 * `PSA_ERROR_BUFFER_TOO_SMALL`: `key_buffer_size` is insufficient. In this case, the driver must pa…
1266 …if there is one. If built-in keys must not be destroyed, it is up to the driver to reject such req…
1276 Each opaque driver is assigned a [location](#lifetimes-and-locations). The driver is invoked for al…
1301 …driver is attached to a specific location. Keys in the default location (`PSA_KEY_LOCATION_LOCAL_S…
1305 …h opaque driver indicating its location called `PSA_KEY_LOCATION_`*prefix* where *prefix* is the v…
1339 ### Driver declarations
1341 #### Declaring driver entry points
1343 … declarations for the driver entry points so that it can compile code using them. At the time of w…
1345 It should be ok for driver functions to be function-like macros or function pointers.
1347 #### Driver location values
1349 How does a driver author decide which location values to use? It should be possible to combine driv…
1351 Can the driver assembly process generate distinct location values as needed? This can be convenient…
1361 ### Driver function interfaces
1363 #### Driver function parameter conventions
1375 …driver entry point does not own memory after the entry point return. This is generally necessary b…
1381 Earlier drafts of the driver interface had a concept of _substitution points_: places in the calcul…
1383 * A processor that performs the RSA exponentiation, but not the padding. The driver should be able …
1406 …Driver entry points for key management”](#driver-entry-points-for-key-management) states that the …
1412 #### Opaque driver persistent state
1414 The driver is allowed to update the state at any time. Is this ok?
1418 …t_persistent_state` does not identify the calling driver, so the driver needs to remember which dr…
1424 …sn't the driver know better? Should there be a driver entry point to determine the length, or shou…
1428 Should [dispatch to an opaque driver](#key-derivation-driver-dispatch-logic) allow fallback, so tha…
1430 …driver-outputs) capability indicate which key types the driver can derive? How should fallback wor…