Lines Matching refs:entry
57 * An object file compiled for the target platform defining the entry point functions specified by t…
79 … and constants referenced by the driver description. They may declare the entry point functions, b…
94 …entry point](#driver-entry-points) or driver entry point family. An entry point is a function defi…
98 …entry point names described by the `"entry_points"` property, to the name of the C function in the…
103 …chanism, it invokes available driver entry points as described in the section [“Driver entry point…
105 A driver is considered available for a cryptographic mechanism that invokes a given entry point if …
107 …`"entry_points"` list either includes the entry point or includes an entry point family that inclu…
121 …entry point, algorithm, key type and key size, and all the capabilities map the entry point to the…
123 If multiple transparent drivers have applicable capabilities for a given combination of entry point…
177 ### Driver entry points
179 #### Overview of driver entry points
181 … management action. These functions are called the **entry points** of the driver. Most driver ent…
183 All driver entry points return a status of type `psa_status_t` which should use the status codes do…
185 …entry point generally looks like the signature of the PSA Cryptography API that it implements, wit…
187 * For entry points that operate on an existing key, the `psa_key_id_t` parameter is replaced by a s…
194 * For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operatio…
196 * For entry points that are involved in key creation, the `psa_key_id_t *` output parameter is repl…
201 …me entry points are grouped in families that must be implemented as a whole. If a driver supports …
203 …entry points related to random generation. A transparent driver can provide a [random generation i…
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 …h with `psa_hash_compare()`, the core calls the driver's `"hash_compute"` entry point and compares…
222 …le driver's `"mac_verify"` entry point if there is one, otherwise the core calls an applicable dri…
223 …entry point is mainly useful for drivers of secure elements that verify a MAC without revealing th…
230 …entry point if there is one, otherwise the core calls an applicable driver's `"hash_compute"` entr…
231 …entry point if there is one, otherwise the core calls an applicable driver's `"hash_compute"` entr…
236 ### Driver entry points for multi-part operations
240 …entry points that implement each step of a multi-part operation are grouped into a family. A drive…
243 …setup` entry point for this operation family. If this fails, the core destroys the operation conte…
244 1. The core calls other entry points that manipulate the operation context object, respecting the c…
245 …entry point fails, the core calls the driver's `xxx_abort` entry point for this operation family, …
246 …“finish” entry point fails, the core destroys the operation context object without calling any oth…
248 …ng single-part operation, the core calls the driver's multipart operation entry points to perform …
250 #### Multi-part operation entry point family `"hash_multipart"`
256 This family requires the following type and entry points:
264 To verify a hash with `psa_hash_verify()`, the core calls the driver's *prefix*`_hash_finish` entry…
266 …entry point family must define the following type and entry points (assuming that the capability d…
306 ### Driver entry points for key derivation
320 …ified algorithm, the core calls that driver's `"key_derivation_setup"` and subsequent entry points.
322 …alls the secure element driver's [`"export_key"`](#key-management-with-opaque-drivers) entry point.
323 …ified algorithm, the core calls that driver's `"key_derivation_setup"` and subsequent entry points.
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…
331 …, otherwise ignored): provide an extra input for the key derivation. This entry point is only mand…
335 * `"key_derivation_abort"` (mandatory): always the last entry point to be called.
337 …entry point family with a capability that does not use the `"names"` property to declare different…
399 …ts` must be a pointer passed by the core to a key derivation driver setup entry point which has no…
403 …lid for the duration of the driver entry point. If the driver needs to access the key context afte…
416 A key derivation driver must implement the following entry point:
430 …entry point. The core calls this entry point for all the long inputs after calling `"acme_key_deri…
445 …request that exceeds the operation's capacity. Such drivers must provide the following entry point:
451 `capacity` is guaranteed to be less or equal to any value previously set through this entry point, …
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…
484 … `"key_derivation_output_key"` entry point, call that entry point. If the driver has no such entry…
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…
497 …1. Call the `"key_derivation_output_bytes"` entry point. The core may call this entry point multip…
499 …ssion if fallback applies). In some cases, the core then calls additional entry points in the same…
501 … for some key types, the core calls a transparent driver's `"derive_key"` entry point. See [“Trans…
502 …e derived key is in a secure element, call that secure element driver's `"import_key"` entry point.
506 …entry point, except when deriving a key entirely inside a secure element as described in [“Key der…
508 …ion contains the following properties (this is not a subset of [the usual entry point properties](…
514 * `"names"` (optional, object). A mapping from entry point names to C function and type names, as u…
530 …iver may use to store data between successive calls of the `"derive_key"` entry point to derive th…
534 This entry point may return the following statuses:
538 * `PSA_ERROR_INSUFFICIENT_DATA`: the core must call the `"derive_key"` entry point again with the s…
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…
556 …he private key is in a secure element that has a `"key_agreement_to_key"` entry point which is app…
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 …st of the key derivation, up to and including the call to the `"key_derivation_abort"` entry point.
561 4. Call the `"destroy_key"` entry point to destroy the key containing the key object.
565 The entry points related to key agreement have the following prototypes for a driver with the prefi…
588 Note that unlike most other key creation entry points, in `"acme_key_agreement_to_key"`, the attrib…
590 ### Driver entry points for PAKE
592 …onsible for keeping inputs and core set-data functions do not have driver entry points. Collected …
596 …"` or `"psa_pake_input"` is called for the first time `"pake_setup"` driver entry point is invoked.
599 …the specified ciphersuite, the core calls that driver's `"pake_setup"` and subsequent entry points.
602 - the core calls the `"pake_setup"` entry point of the secure element driver and subsequent entry p…
604 ### Summary of entry points for PAKE
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 inpu…
611 * `"pake_abort"` (mandatory): always the last entry point to be called.
613 …entry point family with a capability that does not use the `"names"` property to declare different…
665 The first parameter `inputs` must be a pointer passed by the core to a PAKE driver setup entry poin…
685 …il the "pake_setup" entry point returns. Opaque drivers must copy all relevant data from the key b…
756 ### Driver entry points for key management
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…
775 …agreement) entry points. Transparent drivers can create key material through their [`"derive_key"`…
780 * For the `"import_key"` entry point, the input in the `data` buffer is either the export format or…
782 …e driver with an `"allocate_key"` entry point, the content of the key data buffer on entry is the …
783 * The `"import_key"` entry point must determine or validate the key size and set `*bits` as describ…
785 …entry points must ensure that the resulting key is valid as specified in the section [“Key validat…
789 The `"import_key"` entry point must determine or validate the key size.
793 …entry point to process a call to `psa_import_key`, it passes an `attributes` structure such that `…
795 * The core sets `*bits` to `psa_get_key_bits(attributes)` before calling the `"import_key"` entry p…
797 …d return `PSA_ERROR_INVALID_ARGUMENT` if it does not match. If the driver entry point changes `*bi…
801 Key creation entry points must produce valid key data. Key data is _valid_ if operations involving …
818 ### Entropy collection entry point
820 A driver can declare an entropy source by providing a `"get_entropy"` entry point. This entry point…
838 The entry point may return the following statuses:
844 …most other entry points, if multiple transparent drivers include a `"get_entropy"` point, the core…
849 …this flag is clear, the core is not expecting to call the `"get_entropy"` entry point again within…
861 ### Miscellaneous driver entry points
865 …entry point in a capability with no algorithm, key type or key size. If so, the core calls this en…
867 …entry point, the order in which they are called is unspecified. It is also unspecified whether oth…
871 The init entry point does not take any parameter.
875 …apping in capabilities' `"names"` property to arrange for multiple driver entry points to map to t…
885 Transparent drivers may provide the following key management entry points:
896 … general section about key management entry points](#driver-entry-points-for-key-management), the …
907 This entry point has several roles:
909 …ta`. The driver must support the export format for the key types that the entry point is declared …
912 …html#c.psa_export_public_key), so if the input is not in this format, the entry point must convert…
914 ### Random generation entry points
919 …enerating random data, declare it as an [entropy driver](#entropy-collection-entry-point) instead.)
920 …tor peripheral can be declared as an [entropy source](#entropy-collection-entry-point) instead of …
923 If no driver implements the random generation entry point family, the core provides an unspecified …
925 This operation family requires the following type, entry points and parameters (TODO: where exactly…
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 [obtai…
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"`:
960 …his object has been initialized by a call to the driver's `"init_random"` entry point if one is pr…
962 …deliver random data, in which case the core will call the `"add_entropy"` entry point again to sup…
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 …re can supply it with one or more successive calls to the `"add_entropy"` entry point. If the requ…
975 …tropy-collection-entry-point) (each having a `"get_entropy"` entry point) with a random generation…
985 …e the capability to inject additional entropy through the `"add_entropy"` entry point. This ensure…
987 …entry point. This limits the driver's portability: implementations of the PSA Cryptography specifi…
992 #### The `"get_random"` entry point
994 The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
1005 …ore did not call `"add_entropy"`, or if the driver has no `"add_entropy"` entry point, the core mu…
1008 … runs out of entropy as described below. The core sets this value to 0 on entry. The value is not …
1013 …`: the core must supply additional entropy by calling the `"add_entropy"` entry point with at leas…
1022 If a transparent driver entry point is part of a capability which has a true `"fallback"` property …
1027 If a transparent driver entry point is part of a capability where the `"fallback"` property is fals…
1050 …cified, this overrides all other methods (including the `"size_function"` entry point) to determin…
1090 …the public key to the key context and retrieve it on demand in its `export_public_key` entry point.
1098 Opaque drivers may provide the following key management entry points:
1101 …y the core to obtain the public key of a key pair. The core may call this entry point at any time …
1108 …secure elements that store the key material internally must provide the following two entry points:
1115 …l store. A driver for such a secure element has no `"allocate_key"` or `"destroy_key"` entry point.
1117 …a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"` entry point:
1120 2. The core calls the driver's import, generate, derive or copy entry point.
1127 …nt storage for the key material. A driver for such a secure element has two mandatory entry points:
1142 When creating a persistent key with an opaque driver which has an `"allocate_key"` entry point:
1144 1. The core calls the driver's `"allocate_key"` entry point. This function typically allocates an i…
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 … in particular, if the device loses power immediately after the key allocation entry point returns.
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 Note that the key allocation and destruction entry points must not rely solely on the key identifie…
1168 #### Key creation entry points in opaque drivers
1170 The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
1186 …entry point](#key-management-in-a-secure-element-with-storage), the core calls the `"allocate_key"…
1190 #### Key export entry points in opaque drivers
1192 The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
1217 The core loads the persistent state in memory before it calls the driver's [init entry point](#driv…
1229 …entry point. Once the entry point returns, the pointer is no longer valid. The core guarantees tha…
1231 …ter updating the persistent state in memory and before returning from the entry point, otherwise i…
1233 …entry point is running except when the entry point calls `psa_crypto_driver_commit_persistent_stat…
1235 …nt, the driver may only call these two functions from the thread that is executing the entry point.
1241 …entry point to retrieve the key data and metadata. The core calls this entry point when it needs t…
1253 …entry, `psa_get_key_lifetime(attributes)` is the location at which the driver was declared and a p…
1257 …-storage). A driver may have built-in keys even if it doesn't have an `"allocate_key"` entry point.
1259 This entry point may return the following status values:
1266 …o the [`"destroy_key"`](#key-management-in-a-secure-element-with-storage) entry point if there is …
1341 #### Declaring driver entry points
1343 The core may want to provide declarations for the driver entry points so that it can compile code u…
1375 …entry point does not own memory after the entry point return. This is generally necessary because …
1402 Should the entry point be called for symmetric keys as well?
1406 [“Driver entry points for key management”](#driver-entry-points-for-key-management) states that the…
1408 …ermining the bit-size of the key is part of the job of the `"import_key"` entry point. For standar…
1424 …he `"derive_key"` entry point, how does the core choose `input_length`? Doesn't the driver know be…
1436 Should the input to the [`"add_entropy"` entry point](#entropy-injection) be a full-entropy buffer …