Lines Matching refs:a
4 …/#application-programming-interface), which describes the interface between a PSA Cryptography imp…
6 This specification is work in progress and should be considered to be in a beta stage. There is ong…
12 …n interface that allows applications to perform cryptographic operations in a uniform way regardle…
14 …mpositionally. An implementation of the PSA Cryptography API is composed of a **core** and zero or…
22 …a transparent driver is available for a particular combination of parameters (cryptographic algori…
23 …hat can only be used inside a protected environment such as a **secure element**, a hardware secur…
33 …that operate on keys in cleartext; cryptoprocessors that can wrap keys with a built-in keys but no…
35 … with platform-specific hardware happen only inside the driver (and in fact a driver need not invo…
39 …erator drivers can specify that they do not fully support a cryptographic mechanism and that a fal…
45 ### Deliverables for a driver
47 To write a driver, you need to implement some functions with C linkage, and to declare these functi…
49 The concrete syntax for a driver description file is JSON. The structure of this JSON file is speci…
61 The concrete syntax for a driver description file is JSON.
65 …n an unspecified manner. This may be, for example, a list of file names passed on a command line, …
69 A driver description is a JSON object containing the following properties:
71 … a valid prefix for a C identifier. All the types and functions provided by the driver have a name…
73 …pty. The header files must be present at the specified location relative to a directory on the com…
75 …t of **capabilities**. Each capability describes a family of functions that the driver implements …
77 …e driver](#opaque-driver-persistent-state). This may be either a non-negative integer or a C const…
78 … lifetimes for which the driver is invoked. This may be either a non-negative integer or a C const…
84 A capability declares a family of functions that the driver implements for a certain class of crypt…
86 A capability is a JSON object containing the following properties:
88 … Each element is the name of a [driver entry point](#driver-entry-points) or driver entry point fa…
90 … a [key type specification](#key-type-specifications). If specified, the core will invoke this cap…
91 …ore will invoke this capability of the driver only for operations involving a key with one of the …
92 …a function is not listed here, name of the driver function that implements it is the driver's pref…
97 When the PSA Cryptography implementation performs a cryptographic mechanism, it invokes available d…
99 A driver is considered available for a cryptographic mechanism that invokes a given entry point if …
101 * The driver specification includes a capability whose `"entry_points"` list either includes the en…
105 * If the mechanism involves a key:
108 * If the mechanism involves a key:
109 * either the capability does not have a `"key_types"` property;
110 …* or the value of the capability's `"key_types"` property includes a [key type specification](#key…
111 * If the mechanism involves a key:
112 * either the capability does not have a `"key_sizes"` property;
115 …a driver includes multiple applicable capabilities for a given combination of entry point, algorit…
117 If multiple transparent drivers have applicable capabilities for a given combination of entry point…
131 …er can perform deterministic ECDSA signatures using SHA-256 or SHA-384 with a SECP256R1 or SECP384…
146 …a string consisting of a `PSA_ALG_xxx` macro that specifies a cryptographic algorithm or an algori…
160 …a string consisting of a `PSA_KEY_TYPE_xxx` macro that specifies a key type defined by the PSA Cry…
162 The name `_` may be used instead of a curve or group to indicate that the capability concerns all c…
175 …a capability of a driver, such as a cryptographic operation, a part of a cryptographic operation, …
177 All driver entry points return a status of type `psa_status_t` which should use the status codes do…
179 The signature of a driver entry point generally looks like the signature of the PSA Cryptography AP…
181 * For entry points that operate on an existing key, the `psa_key_id_t` parameter is replaced by a s…
183 2. `const uint8_t *key_buffer`: a key material or key context buffer.
188 * For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operatio…
190 …olved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence of paramete…
191 1. `uint8_t *key_buffer`: a buffer for the key material or key context.
195 Some entry points are grouped in families that must be implemented as a whole. If a driver supports…
197 Drivers can also have entry points related to random generation. A transparent driver can provide a…
203 * An input buffer has the type `const uint8_t *` and is immediately followed by a parameter of type…
204 * An output buffer has the type `uint8_t *` and is immediately followed by a parameter of type `siz…
205 * An in-out buffer has the type `uint8_t *` and is immediately followed by a parameter of type `siz…
207 Buffers of size 0 may be represented with either a null pointer or a non-null pointer.
209 … buffer and an output buffer, but not between two output buffers or between a non-buffer parameter…
213 The following driver entry points perform a cryptographic operation in one shot (single-part operat…
215 …sparent drivers only): calculation of a hash. Called by `psa_hash_compute()` and `psa_hash_compare…
216 * `"mac_compute"`: calculation of a MAC. Called by `psa_mac_compute()` and possibly `psa_mac_verify…
217 …`: verification of a MAC. Called by `psa_mac_verify()`. This entry point is mainly useful for driv…
224 …ash. Called by `psa_sign_hash()` and possibly `psa_sign_message()`. To sign a message with `psa_si…
225 …alled by `psa_verify_hash()` and possibly `psa_verify_message()`. To verify a message with `psa_ve…
226 * `"sign_message"`: signature of a message. Called by `psa_sign_message()`.
227 * `"verify_message"`: verification of a message. Called by `psa_verify_message()`.
228 * `"key_agreement"`: key agreement without a subsequent key derivation. Called by `psa_raw_key_agre…
234 …a multi-part operation are grouped into a family. A driver that implements a multi-part operation …
240 1. If a “finish” entry point fails, the core destroys the operation context object without calling …
242 If a driver implements a multi-part operation but not the corresponding single-part operation, the …
246 This family corresponds to the calculation of a hash in multiple steps.
252 * Type `"hash_operation_t"`: the type of a hash operation context. It must be possible to copy a ha…
258 To verify a hash with `psa_hash_verify()`, the core calls the driver's *prefix*`_hash_finish` entry…
260 For example, a driver with the prefix `"acme"` that implements the `"hash_multipart"` entry point f…
304 * Type `"key_derivation_operation_t"`: the type of a key derivation operation context.
307 … `psa_key_derivation_input_key()`. For transparent drivers, when processing a call to `psa_key_der…
324 The entry points that create or format key data have the following prototypes for a driver with the…
344 … `key_buffer` is sufficient for the internal representation of the key. For a transparent driver, …
354 When importing a key, the key size recorded in the key attributes can be either a size specified by…
356 When the core calls the `"import_key"` entry point to process a call to `psa_import_key`, it passes…
360 …RGUMENT` if it does not match. If the driver entry point changes `*bits` to a different value but …
366 …If a cryptographic mechanism is defined as having keying material of a certain size, or if the key…
367 * If a cryptographic operation involves a division by an integer which is provided as part of a key…
368 …a cryptographic operation involves two keys A and B (or more), then the creation of A must ensure …
369 …a key that cannot be verified as valid if using this key would at most compromise the key itself a…
371 …h transparent drivers, the key context can potentially be used by code from a different provider, …
383 …lare an entropy source by providing a `"get_entropy"` entry point. This entry point has the follow…
394 * `flags`: a bit-mask of [entropy collection flags](#entropy-collection-flags).
395 …east `1` on success. The value is ignored on failure. Drivers should return a conservative estimat…
396 …a hardware peripheral, this should preferably be raw or lightly conditioned measurements from a ph…
397 …ize should be large enough to allow a driver to pass unconditioned data with a low density of entr…
405 * Other error codes indicate a transient or permanent failure of the entropy source.
407 Unlike most other entry points, if multiple transparent drivers include a `"get_entropy"` point, th…
412 …et_entropy` after a short time. If this flag is clear, the core is not expecting to call the `"get…
416 …(True Random Number Generator, i.e. an entropy source peripheral) that have a long ramp-up time, e…
418 Here is a suggested call sequence for entropy collection that leverages these flags:
420 1. The core makes a first round of calls to `"get_entropy"` on every source with the `BLOCK` flag c…
421 2. The core makes a second round of calls with the `BLOCK` flag set and the `KEEPALIVE` flag clear …
428 A driver may declare an `"init"` entry point in a capability with no algorithm, key type or key siz…
432 On platforms where the PSA Cryptography implementation is a subsystem of a single application, the …
438 To declare a cryptoprocessor can handle both cleartext and wrapped keys, you need to provide two dr…
444 The format of a key for transparent drivers is the same as in applications. Refer to the documentat…
450 …nsparent-drivers): called by `psa_import_key()`, only when importing a key pair or a public key (k…
451 * `"generate_key"`: called by `psa_generate_key()`, only when generating a key pair (key such that …
452 * `"key_derivation_output_key"`: called by `psa_key_derivation_output_key()`, only when deriving a …
453 …a key pair. The core may call this function at any time to obtain the public key, which can be for…
459 …ey-management), the key import entry points has the following prototype for a driver with the pref…
479 A transparent driver may provide an operation family that can be used as a cryptographic random num…
481 …ality, with a uniform distribution. Therefore, if the random generator includes an entropy source,…
482 * Random generation is expected to be fast. (If a device can provide entropy but is slow at generat…
483 …declared as an [entropy source](#entropy-collection-entry-point) instead of a random generator; th…
490 * Type `"random_context_t"`: the type of a random generation context.
491 …[the core calls it once](#random-generator-initialization) after allocating a `"random_context_t"`…
492 …opy](#entropy-injection). This entry point is optional if the driver is for a peripheral that incl…
494 …ore the driver can output random data. This can be `0` if the driver is for a peripheral that incl…
495 …a hint for the size to supply if the core makes additional calls to `"add_entropy"`, for example t…
501 The `"init_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
507 The core calls this entry point once after allocating a random generation context. Initially, the c…
509 If a driver does not have an `"init_random"` entry point, the context object passed to the first ca…
513 The `"add_entropy"` entry point has the following prototype for a driver with the prefix `"acme"`:
523 * `context`: a random generation context. On the first call to `"add_entropy"`, this object has bee…
524 * `entropy`: a buffer containing full-entropy data to seed the random generator. “Full-entropy” mea…
532 * After a call to the `"get_random"` entry point returns less than the required amount of random da…
536 #### Combining entropy sources with a random generation driver
538 …py sources](#entropy-collection-entry-point) (each having a `"get_entropy"` entry point) with a ra…
540 …f entropy that is in general less than the buffer size. The core must apply a mixing algorithm to …
542 …a simple mixing scheme based on a pseudorandom function family $(F_k)$ with an $E$-bit output wher…
544 Note that the mechanism above is only given as an example. Implementations may choose a different m…
548 … all the entropy sources that are available on the platform. A driver where a call to `"add_entrop…
550 However, a driver may omit the `"add_entropy"` entry point. This limits the driver's portability: i…
557 The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
568 …a random generation context. If the driver's `"initial_entropy_size"` property is nonzero, the cor…
578 … `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permane…
582 … deploy the same binary image on different devices, only some of which have a cryptographic accele…
583 For these purposes, a transparent driver can declare that it only supports a [capability](#driver-d…
585 If a transparent driver entry point is part of a capability which has a true `"fallback"` property …
588 As soon as a driver returns any value other than `PSA_ERROR_NOT_SUPPORTED` (`PSA_SUCCESS` or a diff…
590 If a transparent driver entry point is part of a capability where the `"fallback"` property is fals…
594 …a PSA Cryptography implementation to delegate cryptographic operations to a separate environment t…
596 …tent storage for individual keys. The representation of a key is the key material wrapped with a m…
597 * Some cryptoprocessors have persistent storage for individual keys. The representation of a key is…
601 The format of a key for opaque drivers is an opaque blob. The content of this blob is fully up to t…
603 …blob as it is in memory, it must only contain data that is meaningful after a reboot. In particula…
605 …op-level-element) specifies how to calculate the size of the key context as a function of the key …
608 …or string, optional): this many bytes are included in every key context for a key pair. If omitted…
609 …or string, optional): this many bytes are included in every key context for a public key. If omitt…
610 * `"symmetric_factor"` (integer or string, optional): every key context for a symmetric key include…
611 * `"store_public_key"` (boolean, optional): If specified and true, for a key pair, the key context …
612 …e of a function that returns the number of bytes that the driver needs in a key context for a key.…
615 …ze"` is `sizeof(acme_key_context_t)` where `acme_key_context_t` is a type defined in a driver head…
617 #### Size of a dynamically allocated key context
628 #### Size of a statically allocated key context
630 …not include the `"size_function"` property, the size of the key context for a key of type `key_typ…
632 * For a key pair (`PSA_KEY_TYPE_IS_KEY_PAIR(key_type)` is true):
638 * For a public key (`PSA_KEY_TYPE_IS_PUBLIC_KEY(key_type)` is true):
643 * For a symmetric key (not a key pair or public key):
649 #### Key context size for a secure element with storage
651 If the key is stored in the secure element and the driver only needs to store a label for the key, …
653 …he secure element, but the secure element does not store the public part of a key pair and cannot …
655 #### Key context size for a secure element without storage
663 … called by `psa_export_key()`, or by `psa_copy_key()` when copying a key from or to a different [l…
664 …a key pair. The core may call this entry point at any time to obtain the public key, which can be …
665 * `"import_key"`: called by `psa_import_key()`, or by `psa_copy_key()` when copying a key from anot…
668 * `"copy_key"`: called by `psa_copy_key()` when copying a key within the same [location](#lifetimes…
669 * `"get_builtin_key"`: called by functions that access a key to retrieve information about a [built…
673 …y()`, `psa_key_derivation_output_key()` or `psa_copy_key()` before creating a key in the location …
676 #### Key creation in a secure element without storage
678 …ey material. The driver must obtain a wrapped form of the key material which the core will store. …
680 When creating a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"…
686 To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
688 #### Key management in a secure element with storage
690 …ements that have persistent storage for the key material. A driver for such a secure element has t…
692 …ains an internal identifier for the key. This may be, for example, a unique label or a slot number.
695 These functions have the following prototypes for a driver with the prefix `"acme"`:
705 When creating a persistent key with an opaque driver which has an `"allocate_key"` entry point:
715 If a failure occurs after the `"allocate_key"` step but before the call to the second driver entry …
720 To destroy a key, the core calls the driver's `"destroy_key"` entry point.
722 …ust not rely solely on the key identifier in the key attributes to identify a key. Some implementa…
724 …ntain a set of free slot numbers which is stored either in the secure element or in the driver's p…
725 …a monotonic counter with a practically unbounded range in the secure element or in the driver's pe…
733 The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
749 If the driver has an [`"allocate_key"` entry point](#key-management-in-a-secure-element-with-storag…
755 The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
772 The core will only call `acme_export_public_key` on a private key. Drivers implementers may choose …
778 …tent state on behalf of an opaque driver. This persistent state consists of a single byte array wh…
780 …lization). It is adjusted to match the size declared by the driver, in case a driver upgrade chang…
782 * The first time the driver is loaded on a system, the persistent state is all-bits-zero.
786 … callback functions, which an opaque driver may call while it is processing a call from the driver:
792 …`*persistent_state_ptr` to a pointer to the first byte of the persistent state. This pointer remai…
798 In a multithreaded environment, the driver may only call these two functions from the thread that i…
804 …on and its **slot number**. Drivers that support built-in keys must provide a `"get_builtin_key"` …
816 …a persistence level with which the platform is attempting to register the key. The driver entry po…
818 The output parameter `key_buffer` points to a writable buffer of `key_buffer_size` bytes. If the dr…
820 …a built-in key, the key context is a reference to key material that is kept inside the secure elem…
825 …es`. In particular, `get_builtin_key(slot_number, &attributes, NULL, 0)` is a way for the core to …
827 … `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permane…
829 …core will pass authorized requests to destroy a built-in key to the [`"destroy_key"`](#key-managem…
839 Each opaque driver is assigned a [location](#lifetimes-and-locations). The driver is invoked for al…
859 … of a key that indicates where the key is stored and which application and system actions will cre…
861 * Bits 0–7 are a _persistence level_. This value indicates what device management actions can cause…
862 …a _location indicator_. This value indicates where the key material is stored and where operations…
864 …a specific location. Keys in the default location (`PSA_KEY_LOCATION_LOCAL_STORAGE = 0`) are trans…
866 ### Creating a key in a secure element
868 …a compile-time constant for each opaque driver indicating its location called `PSA_KEY_LOCATION_`*…
873 To declare a volatile key:
880 Generally speaking, to declare a key with a specified persistence:
893 …er if there was a uniform requirement on integer values. Do they have to be JSON integers? C prepr…
912 How does a driver author decide which location values to use? It should be possible to combine driv…
914 …lues as needed? This can be convenient, but it's also risky: if you upgrade a device, you need the…
916 The current plan is for Arm to maintain a registry of vendors and assign a location namespace to ea…
922 The current choice is that the first one is used, which allows having a preference order on drivers…
928 Should 0-size buffers be guaranteed to have a non-null pointers?
938 …arlier drafts of the driver interface had a concept of _substitution points_: places in the calcul…
941 * A processor that performs a block cipher operation only for a single block, or only in ECB mode, …
953 …e calculated from that. Both transparent drivers and opaque drivers provide a function to calculat…
955 …late it on creation, on demand, or anything in between. Opaque drivers have a choice of storing th…
963 …a good idea? It reduces driver portability, since a core that accepts a custom format would not wo…
965 …a problem with import: the core can't know the size of the key representation until it knows the b…
973 An example use case for updating the persistent state at arbitrary times is to renew a key that is …
975 …needs to remember which driver it's calling. This may require a thread-local variable in a multith…
981 …ion) be a full-entropy buffer (with data from all entropy sources already mixed), raw entropy dire…
993 May the core instantiate a random generation context more than once? In other words, can there be m…
995 …a deterministic generator for reproducibility, it can't use this interface anyway, since the RNG i…