Lines Matching refs:key
5 …key store. It is possible to create a persistent key and read it back later. This must work even i…
19 …key creation function in the PSA Crypto API reports to the application that a key has been created…
34 …key, all key management operations (creation or destruction) on persistent keys rely on a single c…
38 * [Key management for stateful secure element keys](#designing-key-management-for-secure-element-ke…
44 ## Designing key management for secure element keys
46 …key” to mean a key stored in a stateful secure element, i.e. a secure element that stores keys. Th…
50 **Assumption: driver calls for key management in stateful secure elements are atomic and committing…
56 For a secure element key, key management requires a commitment on both sites. For example, consider…
58 1. The core sends a request to the secure element to create a key.
59 2. The secure element modifies its key store to create the key.
60 3. The secure element reports to the core that the key has been created.
61 4. The core reports to the application that the key has been created.
63 …key does not exist yet. This is fine from an application's perspective since the core has not comm…
71 …key in a stateful secure element, a successful creation process goes as follows (see [“Key managem…
74 2. The driver allocates a unique identifier _D_ for the key. This is unrelated to the key identifie…
75 3. The core updates the storage to indicate that key identifier _A_ has the identifier _D_ in the d…
76 4. The core calls the driver's key creation entry point, passing it the driver's chosen identifier …
77 …key in the secure element. When this happens, it concludes the voting phase of the two-phase commi…
82 * Before step 3: the system state has not changed at all. As far as the world is concerned, the key…
84 * After step 6: the key has been created successfully.
88 1. The core updates the storage indicating that the key is being destroyed.
90 3. The secure element destroys the key.
91 4. The core updates the storage to indicate that the key has been destroyed.
95 * Before step 1: the system state has not changed at all. As far as the world is concerned, the key…
97 * After step 4: the key has been destroyed successfully.
101 … update its persistent state during a key management operation (or at least not in a way that is i…
107 …age writes are slow and communication with the secure element is fast, for key management operatio…
111 …name is or encodes the key identifier. It must start by traversing a small number of files whose n…
117 …key creation function must transform the internal storage from a state where file `id` does not ex…
119 For a key that is not in a stateful element, the transaction consists of a single write operation. …
121 …key `id` has a transaction in progress. The file `id` cannot be used for this purpose because ther…
129 Note that this pattern requires the state of `id` to be modified only once. In particular, if a key…
133 …tion will be stored in a persistent “transaction list”, with one entry per key. In this section, w…
137 … secure element driver's `"get_key_attributes"` entry point to find out whether the key is present.
139 * Key creation, key not present in the secure element:
140 …key creation. This requires all the input, for example the data to import. This seems impractical …
141 * Aborting means removing any trace of the key creation.
142 * Key creation, key present in the secure element:
144 …* Aborting means destroying the key in the secure element and removing any local storage used for …
145 * Key destruction, key not present in the secure element:
146 …he transaction had not been interrupted, by removing any remaining local storage used for that key.
147 …* Aborting would mean re-creating the key in the secure element, which is impossible in general si…
148 * Key destruction, key present in the secure element:
149 …rrupted, by removing any remaining local storage used for that key and destroying the key in the s…
150 …* Aborting means keeping the key. This requires no action on the secure element, and is only pract…
156 … where it left off. For key creation, this means that the key metadata needs to be saved before ca…
157 …key](#exploring-the-always-destroy-strategy), i.e. abort all key creations and commit all key dest…
158 …key creation, but always go ahead with key destruction. This requires the secure element driver to…
159 * Always abort key creation, but follow the state of the secure element for key destruction. I can'…
161 …key attributes: a key slot always exists, and it's up to the user to remember what, if anything, t…
165 …API key identifier, the key lifetime (or at least the location), the driver key identifier (not co…
167 …key creation, we have all the information to store in the key file once the `"allocate_key"` call …
170 2. Add the key to the transaction list, indicating that it is being created.
171 3. Write the key file.
172 4. Call the driver's key creation entry point.
173 5. Remove the key from the transaction list.
175 During recovery, for each key in the transaction list that was being created:
177 * If the key exists in the secure element, just remove it from the transaction list.
178 * If the key does not exist in the secure element, first remove the key file if it is present, then…
180 For key destruction, we need to preserve the key file until after the key has been destroyed. There…
182 1. Add the key to the transaction list, indicating that it is being destroyed.
184 3. Remove the key file.
185 4. Remove the key from the transaction list.
187 During recovery, for each key in the transaction list that was being created:
189 * If the key exists in the secure element, call the driver's `"destroy_key"` entry point, then remo…
190 * If the key does not exist in the secure element, remove the key file if it is still present, then…
194 …he transaction list contains the API key identifier, the key lifetime (or at least the location), …
196 For key creation, we do not need to store the key's metadata until it has been created in the secur…
199 2. Add the key to the transaction list.
200 3. Call the driver's key creation entry point.
201 4. Write the key file.
202 5. Remove the key from the transaction list.
204 For key destruction, we can remove the key file before contacting the secure element. Therefore the…
206 1. Add the key to the transaction list.
207 2. Remove the key file.
209 4. Remove the key from the transaction list.
211 …eans following the destruction process, starting after the point where the key has been added to t…
213 1. Remove the key file, treating `DOES_NOT_EXIST` as a success.
215 3. Remove the key from the transaction list.
219 …key file always exists if the key exists in the secure element, then the transaction list does not…
221 For key creation, we need to store the key's metadata before creating in the secure element. Theref…
224 2. Add the key to the transaction list.
225 3. Write the key file.
226 4. Call the driver's key creation entry point.
227 5. Remove the key from the transaction list.
229 For key destruction, we need to contact the secure element before removing the key file. Therefore …
231 1. Add the key to the transaction list.
233 3. Remove the key file.
234 4. Remove the key from the transaction list.
236 …eans following the destruction process, starting after the point where the key has been added to t…
238 1. Load the driver key identifier from the key file. If the key file does not exist, skip to step 4.
240 3. Remove the key file, treating `DOES_NOT_EXIST` as a success.
241 4. Remove the key from the transaction list.
246 …elements: we aren't just replacing “create the key material” by “tell the secure element to create…
252 …ormation to the driver for it to know that it should actively perform recovery related to that key.
254 …key might be in a transitional state, the core will request a key destruction from the driver. Thi…
258 …n [“Overview of API functions”](#overview-of-api-functions), this concerns key management in state…
268 For example, consider testing of one key creation operation (see [“Overview of two-phase commit wit…
303 …ed in key files. More generally, if a key is not in the transaction list, then the key must be pre…
305 …key identifier, or if the driver key identifier is only stored in the key file. This is because th…
307 …here the transaction list contains only key identifiers, and one where it also contains the secure…
309 #### Storage invariant if the transaction list contains application key identifiers only
313 * If the file `id` does not exist, then no resources corresponding to that key are in a secure elem…
314 …ction list and the file `id` exists and references a key in a stateful secure element, then the ke…
316 If `id` is in the transaction list and the file `id` exists, the key may or may not be present in t…
318 …key creation must create `id` before calling the secure element's key creation entry point, and ke…
324 …* It is correct to destroy the key in the secure element (treating a `DOES_NOT_EXIST` error as a s…
325 …* It is correct to check whether the key exists in the secure element, and if it does, keep it and…
327 #### Storage invariant if the transaction list contains driver key identifiers
331 … and the file `id` does not exist, then no resources corresponding to that key are in a secure ele…
332 * If `id` is not in the transaction list and the file `id` exists, then the key is present in the s…
334 …st, neither the state of `id` in the internal storage nor the state of the key in the secure eleme…
338 * If the file `id` does not exist, then destroy the key in the secure element (treating a `DOES_NOT…
340 …* It is correct to destroy the key in the secure element (treating a `DOES_NOT_EXIST` error as a s…
341 …* It is correct to check whether the key exists in the secure element, and if it does, keep it and…
345 For a given key, we have to consider three a priori independent boolean states:
347 * Whether the key file exists.
348 * Whether the key is in the secure element.
349 * Whether the key is in the transaction list.
351 There is full coverage for one key if we have tests of recovery for the states among these $2^3 = 8…
361 1. Add the key identifier to the transaction list.
362 2. Call the secure element's key creation or destruction entry point.
363 3. Remove the key identifier from the transaction list.
365 In addition, before or after step 2, create or remove the key file in the internal storage.
367 …he transaction list: a simple array of key identifiers. Since the transaction list does not contai…
369 * During key creation, create the key file in internal storage in the internal storage before calli…
370 * During key destruction, call the secure element's key destruction entry point before removing the…
376 The [storage invariant](#storage-invariant-if-the-transaction-list-contains-application-key-identif…
378 * If the file `id` does not exist, then no resources corresponding to that key are in a secure elem…
379 …ction list and the file `id` exists and references a key in a stateful secure element, then the ke…
380 * If `id` is in the transaction list and a key exists by that identifier, the key's location is a s…
387 * If the file `id` exists, call the secure element's key destruction entry point (treating a `DOES_…
389 ## Specification of key management in stateful secure elements
391 …eful secure elements as discussed in [“Designing key management for secure element keys”](#designi…
395 The transaction list is a simple array of key identifiers.
397 To add a key identifier to the list:
400 2. Append the key identifier to the array.
403 To remove a key identifier from the list:
406 2. Remove the key identifier from the array. If it wasn't the last element in array, move array ele…
411 Let _A_ be the application key identifier.
413 1. Call the driver's `"allocate_key"` entry point, obtaining the driver key identifier _D_ chosen b…
415 …key file _A_ in the internal storage. Note that this is done at a different time from what happens…
416 4. Call the secure element's key creation entry point.
421 * If the secure element's key creation entry point has been called and succeeded, call the secure e…
422 * If the key file has been created in the internal storage, remove it.
423 * Remove the key from the transaction list.
425 Note that this process is identical to key destruction, except that the key is already in the trans…
429 Let _A_ be the application key identifier.
431 …key is loaded in a key slot in memory: the core needs to know the key's location in order to deter…
435 3. Remove the key file _A_ from the internal storage.
437 5. Free the corresponding key slot in memory.
439 …ror but continue the process, to destroy the resources associated with the key as much as is pract…
443 For each key _A_ in the transaction list file, if the file _A_ exists in the internal storage:
445 1. Load the key into a key slot in memory (to get its location and the driver key identifier, altho…
447 3. Remove the key file _A_ from the internal storage.
449 5. Free the corresponding key slot in memory.
453 It is correct to update the transaction list after recovering each key, or to only delete the trans…
468 …to the key identifier which is required, we add some potentially useful information in case it bec…
473 * 0: destroy key.
474 * 1: import key.
475 * 2: generate key.
476 * 3: derive key.
477 * 4: import key.
486 ## Testing key management in secure elements
494 …chosen-storage-invariant). In addition, if there is some information about key ongoing operation (…
500 * When invoked from the test hook on a key file: on that key.
502 * When invoked from a test secure element: on the specified key.
506 … some of these tests to also indicate what operation is in progress on the key. See the GitHub iss…
518 * Create key files that we want to have in the test.
526 For a given key located in a secure element, the following combination of states are possible: