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…
8 For a practical guide, with a description of the current state of drivers Mbed TLS, see our [PSA Cr…
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…
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…
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…
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 …es. Such properties must use names consisting of the implementation's name, a slash, and additiona…
71 …n an unspecified manner. This may be, for example, a list of file names passed on a command line, …
75 A driver description is a JSON object containing the following properties:
77 …a valid, non-empty prefix for a C identifier. All the types and functions provided by the driver h…
79 …pty. The header files must be present at the specified location relative to a directory on the com…
81 …t of **capabilities**. Each capability describes a family of functions that the driver implements …
83 …e driver](#opaque-driver-persistent-state). This may be either a non-negative integer or a C const…
84 … lifetimes for which the driver is invoked. This may be either a non-negative integer or a C const…
90 A capability declares a family of functions that the driver implements for a certain class of crypt…
92 A capability is a JSON object containing the following properties:
94 … Each element is the name of a [driver entry point](#driver-entry-points) or driver entry point fa…
96 … a [key type specification](#key-type-specifications). If specified, the core will invoke this cap…
97 …ore will invoke this capability of the driver only for operations involving a key with one of the …
98 …a function is not listed here, name of the driver function that implements it is the driver's pref…
103 When the PSA Cryptography implementation performs a cryptographic mechanism, it invokes available d…
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…
111 * If the mechanism involves a key:
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;
121 …a driver includes multiple applicable capabilities for a given combination of entry point, algorit…
123 If multiple transparent drivers have applicable capabilities for a given combination of entry point…
137 …er can perform deterministic ECDSA signatures using SHA-256 or SHA-384 with a SECP256R1 or SECP384…
152 …a string consisting of a `PSA_ALG_xxx` macro that specifies a cryptographic algorithm or an algori…
166 …a string consisting of a `PSA_KEY_TYPE_xxx` macro that specifies a key type defined by the PSA Cry…
168 The name `_` may be used instead of a curve or group to indicate that the capability concerns all c…
181 …a capability of a driver, such as a cryptographic operation, a part of a cryptographic operation, …
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…
187 * For entry points that operate on an existing key, the `psa_key_id_t` parameter is replaced by a s…
189 2. `const uint8_t *key_buffer`: a key material or key context buffer.
194 * For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operatio…
196 …olved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence of paramete…
197 1. `uint8_t *key_buffer`: a buffer for the key material or key context.
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…
209 * An input buffer has the type `const uint8_t *` and is immediately followed by a parameter of type…
210 * An output buffer has the type `uint8_t *` and is immediately followed by a parameter of type `siz…
211 * An in-out buffer has the type `uint8_t *` and is immediately followed by a parameter of type `siz…
213 Buffers of size 0 may be represented with either a null pointer or a non-null pointer.
215 … buffer and an output buffer, but not between two output buffers or between a non-buffer parameter…
219 The following driver entry points perform a cryptographic operation in one shot (single-part operat…
221 …sparent drivers only): calculation of a hash. Called by `psa_hash_compute()` and `psa_hash_compare…
222 * `"mac_compute"`: calculation of a MAC. Called by `psa_mac_compute()` and possibly `psa_mac_verify…
223 …`: verification of a MAC. Called by `psa_mac_verify()`. This entry point is mainly useful for driv…
230 …ash. Called by `psa_sign_hash()` and possibly `psa_sign_message()`. To sign a message with `psa_si…
231 …alled by `psa_verify_hash()` and possibly `psa_verify_message()`. To verify a message with `psa_ve…
232 * `"sign_message"`: signature of a message. Called by `psa_sign_message()`.
233 * `"verify_message"`: verification of a message. Called by `psa_verify_message()`.
234 * `"key_agreement"`: key agreement without a subsequent key derivation. Called by `psa_raw_key_agre…
240 …a multi-part operation are grouped into a family. A driver that implements a multi-part operation …
246 1. If a “finish” entry point fails, the core destroys the operation context object without calling …
248 If a driver implements a multi-part operation but not the corresponding single-part operation, the …
252 This family corresponds to the calculation of a hash in multiple steps.
258 * Type `"hash_operation_t"`: the type of a hash operation context. It must be possible to copy a ha…
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…
311 * Multiple drivers can be involved. This happens when an operation combines a key agreement and a s…
317 The core decides whether to dispatch a key derivation operation to a driver based on the location a…
319 1. If this step is passed via `psa_key_derivation_input_key()` for a key in a secure element:
323 2. Otherwise ([or on fallback?](#fallback-for-key-derivation-in-opaque-drivers)), if there is a tra…
331 * `"key_derivation_input_step"` (mandatory if the driver supports a key derivation algorithm with l…
337 …a driver with the prefix `"acme"` that implements the `"key_derivation"` entry point family with a…
345 The core conveys the initial inputs for a key derivation via an opaque data structure of type `psa_…
351 A driver receiving an argument that points to a `psa_crypto_driver_key_derivation_inputs_t` can ret…
369 The function `psa_crypto_driver_key_derivation_get_input_type()` determines whether a given step is…
373 …a transparent byte string. Call `psa_crypto_driver_key_derivation_get_input_size()` to obtain the …
374 …lid and present and is a byte string passed via a key object. Call `psa_crypto_driver_key_derivati…
399 * The first parameter `inputs` must be a pointer passed by the core to a key derivation driver setu…
401 * On a successful invocation of `psa_crypto_driver_key_derivation_get_input_size`, the core sets `*…
402 * On a successful invocation of `psa_crypto_driver_key_derivation_get_input_bytes`, the core fills …
403 …a successful invocation of `psa_crypto_driver_key_derivation_get_input_key`, the core sets `*key_b…
404 * On a successful invocation of `psa_crypto_driver_key_derivation_get_input_integer`, the core sets…
409 …is not part of the initial inputs. This is not a fatal error. The driver will receive the input la…
410 …t_input_type()` to find out the actual type of this input step. This is not a fatal error and the …
411 …er is too small. This is not a fatal error and the driver can, for example, subsequently call the …
424 * `operation` is a zero-initialized operation object.
425 * `alg` is the algorithm for the key derivation operation. It does not include a key agreement comp…
430 …r-initial-inputs). A driver that implements a key derivation algorithm that takes such inputs must…
443 …n-driver-outputs), i.e. for key types where the derived key material is not a direct copy of the k…
478 The core calls a key derivation driver's output entry point when the application calls `psa_key_der…
480 If the key derivation's `PSA_KEY_DERIVATION_INPUT_SECRET` input is in a secure element and the deri…
482 * For a call to `psa_key_derivation_output_key()`:
488 * For a call to `psa_key_derivation_verify_key()`:
489 1. If the driver has a `"key_derivation_verify_key"` entry point, call it and stop.
492 * For a call to `psa_key_derivation_verify_bytes()`:
493 …1. If the driver has a `"key_derivation_verify_bytes"` entry point, call that entry point on the e…
496 * For a call to `psa_key_derivation_output_bytes()`:
497 … call this entry point multiple times to implement a single call from the application when derivin…
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 …a derived (8×*n*)-bit key consists of the next *n* bytes of output from the key derivation, and *c…
508 A capability for cooked key derivation contains the following properties (this is not a subset of […
511 … strings). Each element is a [key type specification](#key-type-specifications). This capability o…
512 … list of integers). Each element is a size for the derived key, in bits. This capability only appl…
513 * `"memory"` (optional, boolean). If present and true, the driver must define a type `"derive_key_m…
529 * `input` is a buffer of `input_length` bytes which contains the raw key stream, i.e. the data that…
530 …a data structure that the driver may use to store data between successive calls of the `"derive_ke…
531 * `key_buffer` is a buffer for the output material, in the appropriate [export format](#key-format-…
536 * `PSA_SUCCESS`: a key was derived successfully. The driver has placed the representation of the ke…
537 … (only if fallback is enabled): the driver cannot fulfill this request, but a fallback driver migh…
539 * Any other error is a fatal error.
541 … `"derive_key"` entry point in a loop until it returns a status other than `PSA_ERROR_INSUFFICIENT…
543 For standard key types, the `"derive_key"` entry point is called with a certain input length as fol…
547 …IR`: an implementation-defined length. A future version of this specification may specify a length.
556 To implement a call to `psa_key_derivation_key_agreement()` where the private key is in a secure el…
558 1. Call the `"key_agreement_to_key"` entry point to create a key object containing the shared secre…
563 …s `psa_key_derivation_key_agreement()` as if it was a call to `psa_raw_key_agreement()` followed b…
565 The entry points related to key agreement have the following prototypes for a driver with the prefi…
595 The core decides whether to dispatch a PAKE operation to a driver based on the location of the prov…
599 - if there is a transparent driver for the specified ciphersuite, the core calls that driver's `"pa…
601 2. If the location of the `password` is the location of a secure element
610 * `"pake_get_implicit_key"` (mandatory): returns implicitly confirmed shared secret from a PAKE.
613 …a driver with the prefix `"acme"` that implements the PAKE entry point family with a capability th…
621 The core conveys the initial inputs for a PAKE operation via an opaque data structure of type `psa_…
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 …er is too small. This is not a fatal error and the driver can, for example, subsequently call the …
680 * `operation` is a zero-initialized operation object.
760 The entry points that create or format key data have the following prototypes for a driver with the…
781 … `key_buffer` is sufficient for the internal representation of the key. For a transparent driver, …
791 When importing a key, the key size recorded in the key attributes can be either a size specified by…
793 When the core calls the `"import_key"` entry point to process a call to `psa_import_key`, it passes…
797 …RGUMENT` if it does not match. If the driver entry point changes `*bits` to a different value but …
803 …If a cryptographic mechanism is defined as having keying material of a certain size, or if the key…
804 * If a cryptographic operation involves a division by an integer which is provided as part of a key…
805 …a cryptographic operation involves two keys A and B (or more), then the creation of A must ensure …
806 …a key that cannot be verified as valid if using this key would at most compromise the key itself a…
808 …h transparent drivers, the key context can potentially be used by code from a different provider, …
820 …lare an entropy source by providing a `"get_entropy"` entry point. This entry point has the follow…
831 * `flags`: a bit-mask of [entropy collection flags](#entropy-collection-flags).
832 …east `1` on success. The value is ignored on failure. Drivers should return a conservative estimat…
833 …a hardware peripheral, this should preferably be raw or lightly conditioned measurements from a ph…
834 …ize should be large enough to allow a driver to pass unconditioned data with a low density of entr…
842 * Other error codes indicate a transient or permanent failure of the entropy source.
844 Unlike most other entry points, if multiple transparent drivers include a `"get_entropy"` point, th…
849 …et_entropy` after a short time. If this flag is clear, the core is not expecting to call the `"get…
853 …(True Random Number Generator, i.e. an entropy source peripheral) that have a long ramp-up time, e…
855 Here is a suggested call sequence for entropy collection that leverages these flags:
857 1. The core makes a first round of calls to `"get_entropy"` on every source with the `BLOCK` flag c…
858 2. The core makes a second round of calls with the `BLOCK` flag set and the `KEEPALIVE` flag clear …
865 A driver may declare an `"init"` entry point in a capability with no algorithm, key type or key siz…
869 On platforms where the PSA Cryptography implementation is a subsystem of a single application, the …
875 To declare a cryptoprocessor can handle both cleartext and wrapped keys, you need to provide two dr…
881 The format of a key for transparent drivers is the same as in applications. Refer to the documentat…
887 …nsparent-drivers): called by `psa_import_key()`, only when importing a key pair or a public key (k…
888 * `"generate_key"`: called by `psa_generate_key()`, only when generating a key pair (key such that …
889 * `"key_derivation_output_key"`: called by `psa_key_derivation_output_key()`, only when deriving a …
890 …a key pair. The core may call this function at any time to obtain the public key, which can be for…
896 …ey-management), the key import entry points has the following prototype for a driver with the pref…
916 A transparent driver may provide an operation family that can be used as a cryptographic random num…
918 …ality, with a uniform distribution. Therefore, if the random generator includes an entropy source,…
919 * Random generation is expected to be fast. (If a device can provide entropy but is slow at generat…
920 …declared as an [entropy source](#entropy-collection-entry-point) instead of a random generator; th…
927 * Type `"random_context_t"`: the type of a random generation context.
928 …[the core calls it once](#random-generator-initialization) after allocating a `"random_context_t"`…
929 …opy](#entropy-injection). This entry point is optional if the driver is for a peripheral that incl…
931 …ore the driver can output random data. This can be `0` if the driver is for a peripheral that incl…
932 …a hint for the size to supply if the core makes additional calls to `"add_entropy"`, for example t…
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 * `context`: a random generation context. On the first call to `"add_entropy"`, this object has bee…
961 * `entropy`: a buffer containing full-entropy data to seed the random generator. “Full-entropy” mea…
969 * After a call to the `"get_random"` entry point returns less than the required amount of random da…
973 #### Combining entropy sources with a random generation driver
975 …py sources](#entropy-collection-entry-point) (each having a `"get_entropy"` entry point) with a ra…
977 …f entropy that is in general less than the buffer size. The core must apply a mixing algorithm to …
979 …a simple mixing scheme based on a pseudorandom function family $(F_k)$ with an $E$-bit output wher…
981 Note that the mechanism above is only given as an example. Implementations may choose a different m…
985 … all the entropy sources that are available on the platform. A driver where a call to `"add_entrop…
987 However, a driver may omit the `"add_entropy"` entry point. This limits the driver's portability: i…
994 The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
1005 …a random generation context. If the driver's `"initial_entropy_size"` property is nonzero, the cor…
1015 … `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permane…
1019 … deploy the same binary image on different devices, only some of which have a cryptographic accele…
1020 For these purposes, a transparent driver can declare that it only supports a [capability](#driver-d…
1022 If a transparent driver entry point is part of a capability which has a true `"fallback"` property …
1025 As soon as a driver returns any value other than `PSA_ERROR_NOT_SUPPORTED` (`PSA_SUCCESS` or a diff…
1027 If a transparent driver entry point is part of a capability where the `"fallback"` property is fals…
1031 …a PSA Cryptography implementation to delegate cryptographic operations to a separate environment t…
1033 …tent storage for individual keys. The representation of a key is the key material wrapped with a m…
1034 * Some cryptoprocessors have persistent storage for individual keys. The representation of a key is…
1038 The format of a key for opaque drivers is an opaque blob. The content of this blob is fully up to t…
1040 …blob as it is in memory, it must only contain data that is meaningful after a reboot. In particula…
1042 …op-level-element) specifies how to calculate the size of the key context as a function of the key …
1045 …or string, optional): this many bytes are included in every key context for a key pair. If omitted…
1046 …or string, optional): this many bytes are included in every key context for a public key. If omitt…
1047 * `"symmetric_factor"` (integer or string, optional): every key context for a symmetric key include…
1048 * `"store_public_key"` (boolean, optional): If specified and true, for a key pair, the key context …
1049 …e of a function that returns the number of bytes that the driver needs in a key context for a key.…
1052 …ze"` is `sizeof(acme_key_context_t)` where `acme_key_context_t` is a type defined in a driver head…
1054 #### Size of a dynamically allocated key context
1065 #### Size of a statically allocated key context
1067 …not include the `"size_function"` property, the size of the key context for a key of type `key_typ…
1069 * For a key pair (`PSA_KEY_TYPE_IS_KEY_PAIR(key_type)` is true):
1075 * For a public key (`PSA_KEY_TYPE_IS_PUBLIC_KEY(key_type)` is true):
1080 * For a symmetric key (not a key pair or public key):
1086 #### Key context size for a secure element with storage
1088 If the key is stored in the secure element and the driver only needs to store a label for the key, …
1090 …he secure element, but the secure element does not store the public part of a key pair and cannot …
1092 #### Key context size for a secure element without storage
1100 …`, or by `psa_copy_key()` when copying a key from or to a different [location](#lifetimes-and-loca…
1101 …a key pair. The core may call this entry point at any time to obtain the public key, which can be …
1102 * `"import_key"`: called by `psa_import_key()`, or by `psa_copy_key()` when copying a key from anot…
1105 * `"copy_key"`: called by `psa_copy_key()` when copying a key within the same [location](#lifetimes…
1106 * `"get_builtin_key"`: called by functions that access a key to retrieve information about a [built…
1110 …y()`, `psa_key_derivation_output_key()` or `psa_copy_key()` before creating a key in the location …
1113 #### Key creation in a secure element without storage
1115 …ey material. The driver must obtain a wrapped form of the key material which the core will store. …
1117 When creating a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"…
1123 To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
1125 #### Key management in a secure element with storage
1127 …ements that have persistent storage for the key material. A driver for such a secure element has t…
1129 …ains an internal identifier for the key. This may be, for example, a unique label or a slot number.
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:
1152 If a failure occurs after the `"allocate_key"` step but before the call to the second driver entry …
1157 To destroy a key, the core calls the driver's `"destroy_key"` entry point.
1159 …ust not rely solely on the key identifier in the key attributes to identify a key. Some implementa…
1161 …ntain a set of free slot numbers which is stored either in the secure element or in the driver's p…
1162 …a monotonic counter with a practically unbounded range in the secure element or in the driver's pe…
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"`:
1209 The core will only call `acme_export_public_key` on a private key. Drivers implementers may choose …
1215 …tent state on behalf of an opaque driver. This persistent state consists of a single byte array wh…
1217 …lization). It is adjusted to match the size declared by the driver, in case a driver upgrade chang…
1219 * The first time the driver is loaded on a system, the persistent state is all-bits-zero.
1223 … callback functions, which an opaque driver may call while it is processing a call from the driver:
1229 …`*persistent_state_ptr` to a pointer to the first byte of the persistent state. This pointer remai…
1235 In a multithreaded environment, the driver may only call these two functions from the thread that i…
1241 …on and its **slot number**. Drivers that support built-in keys must provide a `"get_builtin_key"` …
1253 …a persistence level with which the platform is attempting to register the key. The driver entry po…
1255 The output parameter `key_buffer` points to a writable buffer of `key_buffer_size` bytes. If the dr…
1257 …a built-in key, the key context is a reference to key material that is kept inside the secure elem…
1262 …es`. In particular, `get_builtin_key(slot_number, &attributes, NULL, 0)` is a way for the core to …
1264 … `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permane…
1266 …core will pass authorized requests to destroy a built-in key to the [`"destroy_key"`](#key-managem…
1276 Each opaque driver is assigned a [location](#lifetimes-and-locations). The driver is invoked for al…
1296 … of a key that indicates where the key is stored and which application and system actions will cre…
1298 * Bits 0–7 are a _persistence level_. This value indicates what device management actions can cause…
1299 …a _location indicator_. This value indicates where the key material is stored and where operations…
1301 …a specific location. Keys in the default location (`PSA_KEY_LOCATION_LOCAL_STORAGE = 0`) are trans…
1303 ### Creating a key in a secure element
1305 …a compile-time constant for each opaque driver indicating its location called `PSA_KEY_LOCATION_`*…
1310 To declare a volatile key:
1317 Generally speaking, to declare a key with a specified persistence:
1330 …er if there was a uniform requirement on integer values. Do they have to be JSON integers? C prepr…
1349 How does a driver author decide which location values to use? It should be possible to combine driv…
1351 …lues as needed? This can be convenient, but it's also risky: if you upgrade a device, you need the…
1353 The current plan is for Arm to maintain a registry of vendors and assign a location namespace to ea…
1359 The current choice is that the first one is used, which allows having a preference order on drivers…
1365 Should 0-size buffers be guaranteed to have a non-null pointers?
1373 Why is `psa_crypto_driver_key_derivation_get_input_bytes` a copy, rather than giving a pointer?
1375 …r entry point is making callbacks to the core: these functions could return a pointer that is vali…
1381 …arlier drafts of the driver interface had a concept of _substitution points_: places in the calcul…
1384 * A processor that performs a block cipher operation only for a single block, or only in ECB mode, …
1396 …e calculated from that. Both transparent drivers and opaque drivers provide a function to calculat…
1398 …late it on creation, on demand, or anything in between. Opaque drivers have a choice of storing th…
1406 …a good idea? It reduces driver portability, since a core that accepts a custom format would not wo…
1408 …a problem with import: the core can't know the size of the key representation until it knows the b…
1416 An example use case for updating the persistent state at arbitrary times is to renew a key that is …
1418 …needs to remember which driver it's calling. This may require a thread-local variable in a multith…
1422 `"derive_key"` is not a clear name. Can we use a better one?
1424 …a driver entry point to determine the length, or should there be a callback that allows the driver…
1430 …ypes the driver can derive? How should fallback work? For example, consider a secure element that …
1436 …ion) be a full-entropy buffer (with data from all entropy sources already mixed), raw entropy dire…
1448 May the core instantiate a random generation context more than once? In other words, can there be m…
1450 …a deterministic generator for reproducibility, it can't use this interface anyway, since the RNG i…