Lines Matching refs:key
16 … of a **core** and zero or more **drivers**. The core handles key management, enforces key usage p…
24 …lable for a particular combination of parameters (cryptographic algorithm, key type and size, etc.…
25 …oked for the specific [key location](#lifetimes-and-locations) that the driver is registered for: …
35 …ap keys with a built-in keys but not store user keys; and cryptoprocessors that store key material.
82 …atory for opaque drivers): information about the [representation of keys](#key-format-for-opaque-d…
90 … certain class of cryptographic mechanisms. The capability specifies which key types and algorithm…
96 …key type specification](#key-type-specifications). If specified, the core will invoke this capabil…
97 … involving a key with one of the specified key sizes. If omitted, the core will invoke this capabi…
111 * If the mechanism involves a key:
112 …* either the key is transparent (its location is `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver …
113 …* or the key is opaque (its location is not `PSA_KEY_LOCATION_LOCAL_STORAGE`) and the driver is an…
114 * If the mechanism involves a key:
116 … value of the capability's `"key_types"` property includes a [key type specification](#key-type-sp…
117 * If the mechanism involves a key:
119 * or the value of the capability's `"key_sizes"` property includes the key's size.
121 …key type and key size, and all the capabilities map the entry point to the same function name, the…
123 …ble capabilities for a given combination of entry point, algorithm, key type and key size, the fir…
137 … signatures using SHA-256 or SHA-384 with a SECP256R1 or SECP384R1 private key (with either hash b…
148 ### Algorithm and key specifications
166 …tion is a string consisting of a `PSA_KEY_TYPE_xxx` macro that specifies a key type defined by the…
181 …ch as a cryptographic operation, a part of a cryptographic operation, or a key management action. …
187 …at operate on an existing key, the `psa_key_id_t` parameter is replaced by a sequence of three par…
188 1. `const psa_key_attributes_t *attributes`: the key attributes.
189 2. `const uint8_t *key_buffer`: a key material or key context buffer.
190 3. `size_t key_buffer_size`: the size of the key buffer in bytes.
192 …key buffer contains the key material, in the same format as defined for `psa_export_key()` and `ps…
196 …that are involved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence…
197 1. `uint8_t *key_buffer`: a buffer for the key material or key context.
198 2. `size_t key_buffer_size`: the size of the key buffer in bytes.
199 2. `size_t *key_buffer_length`: the length of the data written to the key buffer in bytes.
234 * `"key_agreement"`: key agreement without a subsequent key derivation. Called by `psa_raw_key_agre…
306 ### Driver entry points for key derivation
311 …key agreement and a subsequent symmetric key derivation, each of which can have independent driver…
313 …n as the operation is set up (since `psa_key_derivation_setup()` does not determine the key input).
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:
321 …Note that for all currently specified algorithms, the key type for the secret input does not matte…
322 …* Otherwise the core calls the secure element driver's [`"export_key"`](#key-management-with-opaqu…
323 2. Otherwise ([or on fallback?](#fallback-for-key-derivation-in-opaque-drivers)), if there is a tra…
328 A key derivation driver has the following entry points:
330 …point provides the [initial inputs](#key-derivation-driver-initial-inputs). See [“Key derivation d…
331 …key derivation algorithm with long inputs, otherwise ignored): provide an extra input for the key …
332 …yptographic material and output it. See [“Key derivation driver outputs”](#key-derivation-driver-o…
333 …que drivers only): derive key material which remains inside the same secure element. See [“Key der…
334 …key types; ignored for other opaque drivers; not permitted for transparent drivers): update the ca…
345 The core conveys the initial inputs for a key derivation via an opaque data structure of type `psa_…
373 …put_bytes()` to make a copy of the input data (design note: [why a copy?](#key-derivation-inputs-a…
374 …a byte string passed via a key object. Call `psa_crypto_driver_key_derivation_get_input_key()` to …
399 * The first parameter `inputs` must be a pointer passed by the core to a key derivation driver setu…
403 …key context and `*key_buffer_size` to the size of the key context in bytes. The key context buffer…
409 … a fatal error. The driver will receive the input later as a [long input](#key-derivation-driver-l…
416 A key derivation driver must implement the following entry point:
425 * `alg` is the algorithm for the key derivation operation. It does not include a key agreement comp…
426 …puts` is an opaque pointer to the [initial inputs](#key-derivation-driver-initial-inputs) for the …
430 …key derivation algorithms take long inputs which it would not be practical to pass in the [initial…
439 At the time of writing, no standard key derivation algorithm has long inputs. It is likely that suc…
443 …tion_output_key"`](#key-derivation-driver-outputs), i.e. for key types where the derived key mater…
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…
480 If the key derivation's `PSA_KEY_DERIVATION_INPUT_SECRET` input is in a secure element and the deri…
484 …1. If the derived key is in the same secure element, if the driver has an `"key_derivation_output_…
485 … indicate that its `"import_key"` entry point does not support the derived key, stop and return `P…
486 …1. Otherwise proceed as for `psa_key_derivation_output_bytes()`, then import the resulting key mat…
490 …1. Call the driver's `"export_key"` entry point on the key object that contains the expected value…
497 …lement a single call from the application when deriving a cooked (non-raw) key as described below,…
499 If the key derivation operation is not handled by an opaque driver as described above, the core cal…
501 …some key types, the core calls a transparent driver's `"derive_key"` entry point. See [“Transparen…
502 * For a call to `psa_key_derivation_output_key()` where the derived key is in a secure element, cal…
504 #### Transparent cooked key derivation
506 …key types, where the key material of a derived (8×*n*)-bit key consists of the next *n* bytes of o…
508 A capability for cooked key derivation contains the following properties (this is not a subset of […
511 …rings). Each element is a [key type specification](#key-type-specifications). This capability only…
512 …ers). Each element is a size for the derived key, in bits. This capability only applies when deriv…
517 A transparent driver with the prefix `"acme"` that implements cooked key derivation must provide th…
528 * `attributes` contains the attributes of the specified key. Note that only the key type and the bi…
529 * `input` is a buffer of `input_length` bytes which contains the raw key stream, i.e. the data that…
530 …ween successive calls of the `"derive_key"` entry point to derive the same key. If the `"memory"` …
531 …output material, in the appropriate [export format](#key-format-for-transparent-drivers) for the k…
536 * `PSA_SUCCESS`: a key was derived successfully. The driver has placed the representation of the ke…
538 …key"` entry point again with the same `memory` object and with subsequent data from the key stream.
541 … `PSA_ERROR_INSUFFICIENT_DATA`. Each call has a successive fragment of the key stream. The `memory…
543 For standard key types, the `"derive_key"` entry point is called with a certain input length as fol…
545 * `PSA_KEY_TYPE_DES`: the length of the key.
546 …R(…)`, `PSA_KEY_TYPE_DH_KEY_PAIR(…)`: $m$ bytes, where the bit-size of the key $n$ satisfies $8 (m…
548 * Other key types: not applicable.
550 See [“Open questions around cooked key derivation”](#open-questions-around-cooked-key-derivation) f…
554 The core always decouples key agreement from symmetric key derivation.
556 …` where the private key is in a secure element that has a `"key_agreement_to_key"` entry point whi…
558 …he `"key_agreement_to_key"` entry point to create a key object containing the shared secret. The k…
559 2. Call the `"key_derivation_setup"` entry point, passing the resulting key object .
560 3. Perform the rest of the key derivation, up to and including the call to the `"key_derivation_abo…
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 …key creation entry points, in `"acme_key_agreement_to_key"`, the attributes for the shared secret …
685 …" entry point returns. Opaque drivers must copy all relevant data from the key buffer during the "…
705 * `PSA_JPAKE_X1_STEP_KEY_SHARE` Round 1: output our key share (for ephemeral private key X1)
706 * `PSA_JPAKE_X1_STEP_ZK_PUBLIC` Round 1: output Schnorr NIZKP public key for the X1 key
707 * `PSA_JPAKE_X1_STEP_ZK_PROOF` Round 1: output Schnorr NIZKP proof for the X1 key
708 * `PSA_JPAKE_X2_STEP_KEY_SHARE` Round 1: output our key share (for ephemeral private key X2)
709 * `PSA_JPAKE_X2_STEP_ZK_PUBLIC` Round 1: output Schnorr NIZKP public key for the X2 key
710 * `PSA_JPAKE_X2_STEP_ZK_PROOF` Round 1: output Schnorr NIZKP proof for the X2 key
711 * `PSA_JPAKE_X2S_STEP_KEY_SHARE` Round 2: output our X2S key
712 * `PSA_JPAKE_X2S_STEP_ZK_PUBLIC` Round 2: output Schnorr NIZKP public key for the X2S key
713 * `PSA_JPAKE_X2S_STEP_ZK_PROOF` Round 2: output Schnorr NIZKP proof for the X2S key
729 * `PSA_JPAKE_X1_STEP_KEY_SHARE` Round 1: input key share from peer (for ephemeral private key X…
730 * `PSA_JPAKE_X1_STEP_ZK_PUBLIC` Round 1: input Schnorr NIZKP public key for the X1 key
731 * `PSA_JPAKE_X1_STEP_ZK_PROOF` Round 1: input Schnorr NIZKP proof for the X1 key
732 * `PSA_JPAKE_X2_STEP_KEY_SHARE` Round 1: input key share from peer (for ephemeral private key X…
733 * `PSA_JPAKE_X2_STEP_ZK_PUBLIC` Round 1: input Schnorr NIZKP public key for the X2 key
734 * `PSA_JPAKE_X2_STEP_ZK_PROOF` Round 1: input Schnorr NIZKP proof for the X2 key
735 * `PSA_JPAKE_X4S_STEP_KEY_SHARE` Round 2: input X4S key from peer
736 * `PSA_JPAKE_X4S_STEP_ZK_PUBLIC` Round 2: input Schnorr NIZKP public key for the X4S key
737 * `PSA_JPAKE_X4S_STEP_ZK_PROOF` Round 2: input Schnorr NIZKP proof for the X4S key
742 ### PAKE driver get implicit key
752 * `output` Buffer where the implicit key is to be written.
754 * `output_length` On success, the number of bytes of the implicit key.
756 ### Driver entry points for key management
758 …oints for key management differ significantly between [transparent drivers](#key-management-with-t…
760 The entry points that create or format key data have the following prototypes for a driver with the…
775 …key-derivation-driver-outputs) and [`"key_agreement_key"`](#key-agreement) entry points. Transpare…
779 * The key attributes (`attributes`) have the same semantics as in the PSA Cryptography application …
781 …key data buffer `key_buffer` is sufficient for the internal representation of the key. For a trans…
782 * For an opaque driver with an `"allocate_key"` entry point, the content of the key data buffer on …
783 …st determine or validate the key size and set `*bits` as described in the section [“Key size deter…
785 …key creation entry points must ensure that the resulting key is valid as specified in the section …
789 The `"import_key"` entry point must determine or validate the key size.
790 The PSA Cryptography API exposes the key size as part of the key attributes.
791 When importing a key, the key size recorded in the key attributes can be either a size specified by…
793 …ey"` entry point must set the `bits` input-output parameter to the correct key size. The semantics…
796 …key size from the data and set `*bits` to this size. If the key size cannot be determined from the…
797 …to a different value but returns `PSA_SUCCESS`, the core will consider the key as invalid and the …
801 Key creation entry points must produce valid key data. Key data is _valid_ if operations involving …
803 … the keying material involves integers that have to be in a certain range, key creation must ensur…
804 …ration involves a division by an integer which is provided as part of a key, key creation must ens…
805 … potentially be used for key agreement are considered invalid and must not be created if they risk…
806 …key that cannot be verified as valid if using this key would at most compromise the key itself and…
808 …key context can only be used by code from the same driver, so key validity is primarily intended t…
810 This section describes some minimal validity requirements for standard key types.
812 * For symmetric key types, check that the key size is suitable for the type.
814 * For RSA (`PSA_KEY_TYPE_RSA_PUBLIC_KEY`, `PSA_KEY_TYPE_RSA_KEY_PAIR`), check the syntax of the key…
865 A driver may declare an `"init"` entry point in a capability with no algorithm, key type or key siz…
881 …key for transparent drivers is the same as in applications. Refer to the documentation of [`psa_ex…
885 Transparent drivers may provide the following key management entry points:
887 …`"import_key"`](#key-import-with-transparent-drivers): called by `psa_import_key()`, only when imp…
888 * `"generate_key"`: called by `psa_generate_key()`, only when generating a key pair (key such that …
889 …"`: called by `psa_key_derivation_output_key()`, only when deriving a key pair (key such that `PSA…
890 …key of a key pair. The core may call this function at any time to obtain the public key, which can…
896 …cussed in [the general section about key management entry points](#driver-entry-points-for-key-man…
909 1. Parse the key data in the input buffer `data`. The driver must support the export format for the…
910 2. Validate the key data. The necessary validation is described in the section [“Key validation”](#…
911 3. [Determine the key size](#key-size-determination-on-import) and output it through `*bits`.
912 4. Copy the validated key data from `data` to `key_buffer`. The output must be in the canonical for…
1019 …on language allows specifying some restrictions, including restrictions on key sizes, but it canno…
1031 …ow exporting key material in cleartext. The opaque driver interface is designed so that the core n…
1033 … key is the key material wrapped with a master key which is located in the cryptoprocessor and nev…
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 Note that since the core stores the key context blob as it is in memory, it must only contain data …
1042 …level-element) specifies how to calculate the size of the key context as a function of the key typ…
1044 * `"base_size"` (integer or string, optional): this many bytes are included in every key context. I…
1045 …teger or string, optional): this many bytes are included in every key context for a key pair. If o…
1046 …r or string, optional): this many bytes are included in every key context for a public key. If omi…
1047 …ctor"` (integer or string, optional): every key context for a symmetric key includes this many tim…
1048 …true, for a key pair, the key context includes space for the public key. If omitted or false, no a…
1049 …ction that returns the number of bytes that the driver needs in a key context for a key. This may …
1050 …e size of the key context for [built-in keys](#built-in-keys). This allows drivers to efficiently …
1054 #### Size of a dynamically allocated key context
1056 …ation for the key context and chooses to use it, and the driver specification includes the `"size_…
1060 …named in the `"size_function"` property, `key_type` is the key type and `key_bits` is the key size…
1065 #### Size of a statically allocated key context
1067 …key context or chooses not to use it, or if the driver specification does not include the `"size_f…
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):
1084 where `key_bytes = ((key_bits + 7) / 8)` is the key size in bytes.
1088 If the key is stored in the secure element and the driver only needs to store a label for the key, …
1090 …key is stored in the secure element, but the secure element does not store the public part of a ke…
1094 …key is stored in wrapped form outside the secure element, and the wrapped form of the key plus any…
1098 Opaque drivers may provide the following key management entry points:
1100 …_key()` when copying a key from or to a different [location](#lifetimes-and-locations), or [as a f…
1101 …key of a key pair. The core may call this entry point at any time to obtain the public key, which …
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 …et_builtin_key"`: called by functions that access a key to retrieve information about a [built-in …
1108 In addition, secure elements that store the key material internally must provide the following two …
1110 …`, `psa_key_derivation_output_key()` or `psa_copy_key()` before creating a key in the location of …
1115 …describes the key creation process for secure elements that do not store the key material. The dri…
1117 When creating a key with an opaque driver which does not have an `"allocate_key"` or `"destroy_key"…
1119 1. The core allocates memory for the key context.
1121 3. The core saves the resulting wrapped key material and any other data that the key context may co…
1123 To destroy a key, the core simply destroys the wrapped key material, without invoking driver code.
1127 …is section describes the key creation and key destruction processes for secure elements that have …
1129 * `"allocate_key"`: this function obtains an internal identifier for the key. This may be, for exam…
1130 …_key"`: this function invalidates the internal identifier and destroys the associated key material.
1142 When creating a persistent key with an opaque driver which has an `"allocate_key"` entry point:
1144 …an internal identifier for the key without modifying the state of the secure element and stores th…
1146 1. The core saves the key context to persistent storage.
1148 1. The core calls the driver's key creation entry point.
1150 1. The core saves the updated key context to persistent storage.
1154 …ation of the key without indicating this to the driver. This can happen, in particular, if the dev…
1157 To destroy a key, the core calls the driver's `"destroy_key"` entry point.
1159 …key allocation and destruction entry points must not rely solely on the key identifier in the key …
1161 …torage. To allocate a key slot, find a free slot number, mark it as occupied and store the number …
1162 …tent storage. To allocate a key slot, increment the counter and store the current value in the key…
1170 The key creation entry points have the following prototypes for a driver with the prefix `"acme"`:
1186 …key-management-in-a-secure-element-with-storage), the core calls the `"allocate_key"` entry point …
1192 The key export entry points have the following prototypes for a driver with the prefix `"acme"`:
1209 …key. Drivers implementers may choose to store the public key in the key context buffer or to recal…
1211 …sufficient to export any key with the given attributes. The driver must set `*data_length` to the …
1241 …key is identified by its location and its **slot number**. Drivers that support built-in keys must…
1251 …th the attributes of the key (except for the key identifier). On success, this function must also …
1253 …key. The driver entry point may choose to change the lifetime (`psa_set_key_lifetime(attributes, l…
1255 …rty](#key-format-for-opaque-drivers) property, `key_buffer_size` has this value, otherwise `key_bu…
1257 …n key, the key context is a reference to key material that is kept inside the secure element, simi…
1261 …A_SUCCESS`: the requested key exists, and the output parameters `attributes` and `key_buffer` cont…
1262 … the key's attributes in `*attributes`. In particular, `get_builtin_key(slot_number, &attributes, …
1263 * `PSA_ERROR_DOES_NOT_EXIST`: the requested key does not exist.
1266 The core will pass authorized requests to destroy a built-in key to the [`"destroy_key"`](#key-mana…
1276 …at use a key in that location. A key's location is indicated by its lifetime. The application choo…
1278 For example, the following snippet creates an AES-GCM key which is only accessible inside the secur…
1288 psa_key_id_t key;
1289 psa_generate_key(&attributes, &key);
1296 …a_key_lifetime_t#c.psa_key_lifetime_t) as an attribute of a key that indicates where the key is st…
1298 …ions can cause it to be destroyed. In particular, it indicates whether the key is volatile or pers…
1299 …ation indicator_. This value indicates where the key material is stored and where operations on th…
1301 …key material. For keys in a location that is managed by an opaque driver, only the secure element …
1303 ### Creating a key in a secure element
1305 … declare an opaque key in the location with the prefix `foo` with the default persistence, call `p…
1310 To declare a volatile key:
1317 Generally speaking, to declare a key with a specified persistence:
1375 …function does not own memory after the entry point returns. In the case of key derivation inputs, …
1390 #### Mixing drivers in key derivation
1394 #### Public key calculation
1396 …key pairs are represented as the private key value only. The public key needs to be calculated fro…
1398 …key might be calculated. The core may calculate it on creation, on demand, or anything in between.…
1400 #### Symmetric key validation with transparent drivers
1406 [“Driver entry points for key management”](#driver-entry-points-for-key-management) states that the…
1408 …key representation until it knows the bit-size of the key, but determining the bit-size of the key…
1416 An example use case for updating the persistent state at arbitrary times is to renew a key that is …
1420 #### Open questions around cooked key derivation
1424 …key types, it's impossible to predict the amount of input in advance, because it depends on some c…
1426 #### Fallback for key derivation in opaque drivers
1428 …key-derivation-driver-dispatch-logic) allow fallback, so that if `"key_derivation_setup"` returns …
1430 …key-derivation-driver-outputs) capability indicate which key types the driver can derive? How shou…