Lines Matching refs:key
1 PSA key store design
6 This document describes the architecture of the key storage in memory in the Mbed TLS and TF-PSA-Cr…
8 …ess key materials via a key identifier (key ID for short). Applications must first create a key ob…
14 ### Key store and key slots
16 …key store** consists of a collection of **key slots**. Each key slot contains the metadata for one…
18 A key slot has the type `psa_key_slot_t`. The key store is a global object which is private inside …
22 The following operations allocate a key slot by calling `psa_reserve_free_key_slot()`:
24 …key object, through means such as import, random generation, deterministic derivation, copy, or re…
25 …key from storage, or loading a built-in key. This is done through `psa_get_and_lock_key_slot()`, w…
27 The following operations free a key slot by calling `psa_wipe_key_slot()` and, if applicable, `psa_…
29 * **Destroying** a key.
30 * **Purging** a persistent key from memory, either explicitly at the application's request or to fr…
34 The library accesses key slots in the following scenarios:
36 * while the key is being created or loaded;
37 * while the key is being destroyed or purged;
38 * while the key metadata or key material is being accessed.
42 The state of a key slot is indicated by its `state` field of type `psa_key_slot_state_t`, which can…
44 * `PSA_SLOT_EMPTY`: a slot that occupies memory but does not currently contain a key.
45 * `PSA_SLOT_FILLING`: a slot that is being filled to create or load a key.
46 * `PSA_SLOT_FULL`: a slot containing a key.
47 * `PSA_SLOT_PENDING_DELETION`: a slot whose key is being destroy or purged.
49 …](#concurrency) below and [key slot states in the PSA thread safety specification](psa-thread-safe…
53 …vironment, since Mbed TLS 3.6.0, each key slot is protected by a reader-writer lock. (In earlier v…
67 There are three variants of the key store implementation, responding to different needs.
69 …key store ([static key slots](#static-key-store) with dynamic key data): the key store is a static…
70 …key store](#static-key-store) (since Mbed TLS 3.6.3): the key store is a statically allocated arra…
71 …key store](#dynamic-key-store) (since Mbed TLS 3.6.1): the key store is dynamically allocated as m…
73 #### Future improvement: merging the key store variants
75 In the future, we may reduce the number of key store variants to just two, perhaps even one.
77 …key store in a patch release of a long-time support version. As a consequence, we wanted to minimi…
79 The static key store could become a runtime decision, where only keys larger than some threshold re…
81 …key store is the need to preserve slot pointers while a slot may be accessed by another thread (se…
85 Some parts of the key slot management code use **key slices** as an abstraction. A key slice is an …
87 * With a [static key store](#static-key-store), there is a single, statically allocated slice, with…
88 * With a [dynamic key store](#dynamic-key-store), there is statically allocated array of pointers t…
92 …key, the slice containing the slot and index of the slot in its slice determine the key identifier…
94 ### Static key store
96 The static key store is the historical implementation. The key store is a statically allocated arra…
98 …key store: a hybrid variant (default), and a fully-static variant enabled by the configuration opt…
100 #### Volatile key identifiers in the static key store
102 For easy lookup, a volatile key whose index is `id` is stored at the index `id - PSA_KEY_ID_VOLATIL…
104 #### Key creation with a static key store
106 …key, `psa_reserve_free_key_slot()` searches the key slot array until it finds one that is empty. I…
108 #### Freeing a key slot with a static key store
110 With a static key store, `psa_wipe_key_slot()` destroys or purges a key by freeing any associated r…
112 ### Dynamic key store
114 The dynamic key store allows a large number of keys, at the expense of more complex memory manageme…
116 The dynamic key store was added in Mbed TLS 3.6.1. It is enabled by `MBEDTLS_PSA_KEY_STORE_DYNAMIC`…
118 #### Dynamic key slot performance characteristics
120 Key management and key access have $O(1)$ amortized performance, and mostly $O(1)$ performance for …
122 * Access to an existing volatile key takes $O(1)$ time.
123 * Access to a persistent key (including creation and destruction) takes time that is linear in `MBE…
124 * Allocating a key takes amortized $O(1)$ time. Usually the time is $O(s)$ where $s$ is the number …
125 * Destroying a volatile key takes $O(1)$ time as of Mbed TLS 3.6.1. Later improvements to memory co…
127 #### Key slices in the dynamic key store
129 The key slot is organized in slices, which are dynamically arrays of key slot. The number of slices…
133 One key slice contains only loaded keys: that key slice is thus the cache slice. See [“Persistent k…
135 #### Volatile key identifiers in the dynamic key store
137 A volatile key identifier encodes the slice index and the slot index at separate bit positions. Tha…
139 #### From key slot to key slice
141 …mine which key slice contains a key slot when given a pointer to the key slot. In principle, the k…
143 * for a volatile key identifier, the [slice index is encoded in the key identifier](#volatile-key-i…
144 * for a persistent key identifier or built-in key identifier, [the slot is in the sole cache slice]…
149 …key identifier field has not been filled yet or has been wiped. The implementation in Mbed TLS 3.6…
151 #### Length of the volatile key slices
153 The volatile key slices have exponentially increasing length: each slice is twice as long as the pr…
155 …key slots is less than the theoretical maximum of 2^30 - 2^16 (0x10000000..0x7ffeffff, the largest…
157 …TEST_HOOKS` is enabled, the length of key slices can be overridden. We use this in tests that need…
161 Each volatile key slice has a **free list**. This is a linked list of all the slots in the slice th…
165 #### Dynamic key slot allocation
167 …key, `psa_reserve_free_key_slot()` searches the free lists of each allocated slice until it finds …
173 #### Dynamic key slot deallocation
175 When destroying a volatile key, `psa_wipe_key_slot()` calls `psa_free_key_slot()`. This function ad…
179 …decreases (except when the PSA crypto subsystem is deinitialized). Freeing key slices intelligentl…
181 We should not free a key slice as soon as it becomes empty, because that would cause large allocati…
185 ### Persistent key cache
187 Persistent keys and built-in keys need to be loaded into the in-memory key store each time they are…
191 * to start performing an operation with the key;
192 * when destroying the key.
196 …key store](#static-key-store), a non-empty slot can contain either a volatile key or a cache entry…
198 …key cache is a fixed-size array of `MBEDTLS_PSA_KEY_SLOT_COUNT` slots. In the static key store, th…
200 #### Accessing a persistent key
202 …key identifier is in the corresponding range. To that effect, it traverses the key cache to see if…
206 A key slot must be allocated in the cache slice:
208 * to create a volatile key (static key store only);
209 * to create a persistent key;
210 * to load a persistent or built-in key.
212 … readers can be evicted (see [“Concurrency”](#concurrency)). In the static key store, slots contai…
214 As of Mbed TLS 3.6.1, there is no tracking of a key's usage frequency or age. The slot eviction cod…