Lines Matching full: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…
14 …n interface that allows applications to perform cryptographic operations in a uniform way regardle…
16 …mpositionally. An implementation of the PSA Cryptography API is composed of a **core** and zero or…
24 …a transparent driver is available for a particular combination of parameters (cryptographic algori…
25 …hat can only be used inside a protected environment such as a **secure element**, a hardware secur…
33 …the code of each driver and of the core separately, and link them together. A small amount of glue…
35 …that operate on keys in cleartext; cryptoprocessors that can wrap keys with a built-in keys but no…
37 … with platform-specific hardware happen only inside the driver (and in fact a driver need not invo…
41 …erator drivers can specify that they do not fully support a cryptographic mechanism and that a fal…
43 [Req.mechanisms] Drivers can specify which mechanisms they support. A driver's code will not be inv…
47 ### Deliverables for a driver
49 To write a driver, you need to implement some functions with C linkage, and to declare these functi…
51 The concrete syntax for a driver description file is JSON. The structure of this JSON file is speci…
53 A driver therefore consists of:
55 * A driver description file (in JSON format).
63 The concrete syntax for a driver description file is JSON.
67 …n an unspecified manner. This may be, for example, a list of file names passed on a command line, …
71 A driver description is a JSON object containing the following properties:
73 … a valid prefix for a C identifier. All the types and functions provided by the driver have a name…
75 …A list of header files. These header files must define the types, macros and constants referenced …
77 A list of **capabilities**. Each capability describes a family of functions that the driver impleme…
79 …e driver](#opaque-driver-persistent-state). This may be either a non-negative integer or a C const…
80 … lifetimes for which the driver is invoked. This may be either a non-negative integer or a C const…
86 A capability declares a family of functions that the driver implements for a certain class of crypt…
88 A capability is a JSON object containing the following properties:
90 … Each element is the name of a [driver entry point](#driver-entry-points) or driver entry point fa…
92 … a [key type specification](#key-type-specifications). If specified, the core will invoke this cap…
93 …ore will invoke this capability of the driver only for operations involving a key with one of the …
94 …A mapping from entry point names described by the `"entry_points"` property, to the name of the C …
99 When the PSA Cryptography implementation performs a cryptographic mechanism, it invokes available d…
101 A driver is considered available for a cryptographic mechanism that invokes a given entry point if …
103 * The driver specification includes a capability whose `"entry_points"` list either includes the en…
107 * If the mechanism involves a key:
110 * If the mechanism involves a key:
111 * either the capability does not have a `"key_types"` property;
112 …* or the value of the capability's `"key_types"` property includes a [key type specification](#key…
113 * If the mechanism involves a key:
114 * either the capability does not have a `"key_sizes"` property;
117 …a driver includes multiple applicable capabilities for a given combination of entry point, algorit…
119 If multiple transparent drivers have applicable capabilities for a given combination of entry point…
133 …er can perform deterministic ECDSA signatures using SHA-256 or SHA-384 with a SECP256R1 or SECP384…
148 …a string consisting of a `PSA_ALG_xxx` macro that specifies a cryptographic algorithm or an algori…
162 …a string consisting of a `PSA_KEY_TYPE_xxx` macro that specifies a key type defined by the PSA Cry…
164 The name `_` may be used instead of a curve or group to indicate that the capability concerns all c…
177 …a capability of a driver, such as a cryptographic operation, a part of a cryptographic operation, …
179 All driver entry points return a status of type `psa_status_t` which should use the status codes do…
181 The signature of a driver entry point generally looks like the signature of the PSA Cryptography AP…
183 * For entry points that operate on an existing key, the `psa_key_id_t` parameter is replaced by a s…
185 2. `const uint8_t *key_buffer`: a key material or key context buffer.
190 * For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operatio…
192 …olved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence of paramete…
193 1. `uint8_t *key_buffer`: a buffer for the key material or key context.
197 Some entry points are grouped in families that must be implemented as a whole. If a driver supports…
203 * An input buffer has the type `const uint8_t *` and is immediately followed by a parameter of type…
204 …e `uint8_t *` and is immediately followed by a parameter of type `size_t` that indicates the buffe…
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…
321 The entry points that create or format key data have the following prototypes for a driver with the…
341 … `key_buffer` is sufficient for the internal representation of the key. For a transparent driver, …
351 When importing a key, the key size recorded in the key attributes can be either a size specified by…
353 When the core calls the `"import_key"` entry point to process a call to `psa_import_key`, it passes…
357 …RGUMENT` if it does not match. If the driver entry point changes `*bits` to a different value but …
363 …If a cryptographic mechanism is defined as having keying material of a certain size, or if the key…
364 * If a cryptographic operation involves a division by an integer which is provided as part of a key…
365 …a cryptographic operation involves two keys A and B (or more), then the creation of A must ensure …
366 …a key that cannot be verified as valid if using this key would at most compromise the key itself a…
368 …h transparent drivers, the key context can potentially be used by code from a different provider, …
382 A driver may declare an `"init"` entry point in a capability with no algorithm, key type or key siz…
386 On platforms where the PSA Cryptography implementation is a subsystem of a single application, the …
392 To declare a cryptoprocessor can handle both cleartext and wrapped keys, you need to provide two dr…
398 The format of a key for transparent drivers is the same as in applications. Refer to the documentat…
404 …nsparent-drivers): called by `psa_import_key()`, only when importing a key pair or a public key (k…
405 * `"generate_key"`: called by `psa_generate_key()`, only when generating a key pair (key such that …
406 * `"key_derivation_output_key"`: called by `psa_key_derivation_output_key()`, only when deriving a …
407 …a key pair. The core may call this function at any time to obtain the public key, which can be for…
413 …ey-management), the key import entry points has the following prototype for a driver with the pref…
433 … deploy the same binary image on different devices, only some of which have a cryptographic accele…
434 For these purposes, a transparent driver can declare that it only supports a [capability](#driver-d…
436 If a transparent driver entry point is part of a capability which has a true `"fallback"` property …
439 As soon as a driver returns any value other than `PSA_ERROR_NOT_SUPPORTED` (`PSA_SUCCESS` or a diff…
441 If a transparent driver entry point is part of a capability where the `"fallback"` property is fals…
445 …a PSA Cryptography implementation to delegate cryptographic operations to a separate environment t…
447 …tent storage for individual keys. The representation of a key is the key material wrapped with a m…
448 * Some cryptoprocessors have persistent storage for individual keys. The representation of a key is…
452 The format of a key for opaque drivers is an opaque blob. The content of this blob is fully up to t…
454 …blob as it is in memory, it must only contain data that is meaningful after a reboot. In particula…
456 …op-level-element) specifies how to calculate the size of the key context as a function of the key …
459 …or string, optional): this many bytes are included in every key context for a key pair. If omitted…
460 …or string, optional): this many bytes are included in every key context for a public key. If omitt…
461 * `"symmetric_factor"` (integer or string, optional): every key context for a symmetric key include…
462 * `"store_public_key"` (boolean, optional): If specified and true, for a key pair, the key context …
463 …e of a function that returns the number of bytes that the driver needs in a key context for a key.…
465 …anguage constants. A typical value for `"base_size"` is `sizeof(acme_key_context_t)` where `acme_k…
467 #### Size of a dynamically allocated key context
478 #### Size of a statically allocated key context
480 …not include the `"size_function"` property, the size of the key context for a key of type `key_typ…
482 * For a key pair (`PSA_KEY_TYPE_IS_KEY_PAIR(key_type)` is true):
488 * For a public key (`PSA_KEY_TYPE_IS_PUBLIC_KEY(key_type)` is true):
493 * For a symmetric key (not a key pair or public key):
499 #### Key context size for a secure element with storage
501 If the key is stored in the secure element and the driver only needs to store a label for the key, …
503 …he secure element, but the secure element does not store the public part of a key pair and cannot …
505 #### Key context size for a secure element without storage
513 … called by `psa_export_key()`, or by `psa_copy_key()` when copying a key from or to a different [l…
514 …a key pair. The core may call this entry point at any time to obtain the public key, which can be …
515 * `"import_key"`: called by `psa_import_key()`, or by `psa_copy_key()` when copying a key from anot…
518 * `"copy_key"`: called by `psa_copy_key()` when copying a key within the same [location](#lifetimes…
522 …y()`, `psa_key_derivation_output_key()` or `psa_copy_key()` before creating a key in the location …
525 #### Key creation in a secure element without storage
527 …ey material. The driver must obtain a wrapped form of the key material which the core will store. …
529 When creating a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"…
535 To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
537 #### Key management in a secure element with storage
539 …secure elements that have persistent storage for the key material. A driver for such a secure elem…
541 …ains an internal identifier for the key. This may be, for example, a unique label or a slot number.
544 These functions have the following prototypes for a driver with the prefix `"acme"`:
554 When creating a persistent key with an opaque driver which has an `"allocate_key"` entry point:
564 If a failure occurs after the `"allocate_key"` step but before the call to the second driver entry …
569 To destroy a key, the core calls the driver's `"destroy_key"` entry point.
571 …ust not rely solely on the key identifier in the key attributes to identify a key. Some implementa…
573 …ntain a set of free slot numbers which is stored either in the secure element or in the driver's p…
574 …a monotonic counter with a practically unbounded range in the secure element or in the driver's pe…
582 The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
598 If the driver has an [`"allocate_key"` entry point](#key-management-in-a-secure-element-with-storag…
604 The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
621 The core will only call `acme_export_public_key` on a private key. Drivers implementers may choose …
627 …tent state on behalf of an opaque driver. This persistent state consists of a single byte array wh…
629 …lization). It is adjusted to match the size declared by the driver, in case a driver upgrade chang…
631 * The first time the driver is loaded on a system, the persistent state is all-bits-zero.
635 … callback functions, which an opaque driver may call while it is processing a call from the driver:
641 …`*persistent_state_ptr` to a pointer to the first byte of the persistent state. This pointer remai…
647 In a multithreaded environment, the driver may only call these two functions from the thread that i…
657 … driver is assigned a [location](#lifetimes-and-locations). The driver is invoked for all actions …
677 … of a key that indicates where the key is stored and which application and system actions will cre…
679 * Bits 0–7 are a _persistence level_. This value indicates what device management actions can cause…
680 …a _location indicator_. This value indicates where the key material is stored and where operations…
682 …a specific location. Keys in the default location (`PSA_KEY_LOCATION_LOCAL_STORAGE = 0`) are trans…
684 ### Creating a key in a secure element
686 …a compile-time constant for each opaque driver indicating its location called `PSA_KEY_LOCATION_`*…
691 To declare a volatile key:
698 Generally speaking, to declare a key with a specified persistence:
717 How does a driver author decide which location values to use? It should be possible to combine driv…
719 …lues as needed? This can be convenient, but it's also risky: if you upgrade a device, you need the…
721 The current plan is for Arm to maintain a registry of vendors and assign a location namespace to ea…
727 The current choice is that the first one is used, which allows having a preference order on drivers…
733 Should 0-size buffers be guaranteed to have a non-null pointers?
743 …arlier drafts of the driver interface had a concept of _substitution points_: places in the calcul…
745 * A processor that performs the RSA exponentiation, but not the padding. The driver should be able …
746 * A processor that performs a block cipher operation only for a single block, or only in ECB mode, …
758 …e calculated from that. Both transparent drivers and opaque drivers provide a function to calculat…
760 …late it on creation, on demand, or anything in between. Opaque drivers have a choice of storing th…
768 …a good idea? It reduces driver portability, since a core that accepts a custom format would not wo…
770 …a problem with import: the core can't know the size of the key representation until it knows the b…
778 An example use case for updating the persistent state at arbitrary times is to renew a key that is …
780 …needs to remember which driver it's calling. This may require a thread-local variable in a multith…