1========================================
2Protected Storage service key management
3========================================
4
5:Author: Jamie Fox
6:Organization: Arm Limited
7:Contact: Jamie Fox <jamie.fox@arm.com>
8
9Background
10==========
11The PSA Protected Storage API requires confidentiality for external storage to
12be provided by:
13
14    **cryptographic ciphers using device-bound keys**, a tamper resistant
15    enclosure, or an inaccessible deployment location, depending on the threat
16    model of the deployed system.
17
18A TBSA-M-compliant device must embed a Hardware Unique Key (HUK), which provides
19the root of trust (RoT) for confidentiality in the system. It must have at least
20128 bits of entropy (and a 128 bit data size), and be accessible only to Trusted
21code or Trusted hardware that acts on behalf of Trusted code. [TBSA-M]_
22
23Design description
24==================
25Each time the system boots, PS will request that the Crypto service uses a key
26derivation function (KDF) to derive a storage key from the HUK, by referring to
27the builtin key handle for the HUK. The storage key could be kept in on-chip
28volatile memory private to the Crypto partition, or it could remain inside a
29secure element. Either way it will not be returned to PS.
30
31For each call to the PSA Protected Storage APIs, PS will make requests to the
32Crypto service to perform AEAD encryption and/or decryption operations using the
33storage key (providing a fresh nonce for each encryption).
34
35At no point will PS access the key material itself, only referring to the HUK
36and storage key by their handles in the Crypto service.
37
38Key derivation
39==============
40PS will make key derivation requests to the Crypto service with calls to the
41PSA Crypto APIs. In order to derive the storage key, the following calls are
42required:
43
44.. code-block:: c
45
46    status = psa_key_derivation_setup(&op, PSA_ALG_HKDF(PSA_ALG_SHA_256));
47
48    /* Set up a key derivation operation with HUK  */
49    status = psa_key_derivation_input_key(&op, PSA_KEY_DERIVATION_INPUT_SECRET,
50                                          TFM_BUILTIN_KEY_ID_HUK);
51
52    /* Supply the PS key label as an input to the key derivation */
53    status = psa_key_derivation_input_bytes(&op, PSA_KEY_DERIVATION_INPUT_INFO,
54                                            key_label,
55                                            key_label_len);
56
57    /* Create the storage key from the key derivation operation */
58    status = psa_key_derivation_output_key(&attributes, &op, &ps_key);
59
60.. note::
61    ``TFM_BUILTIN_KEY_ID_HUK`` is a static key ID that is used to identify the
62    HUK. It has an arbitrary value defined in ``tfm_crypto_defs.h``
63
64    ``ps_key`` is a PSA Crypto key handle to a volatile key, set by the
65    derivation operation. After the call to ``psa_key_derivation_output_key``,
66    it can be used to refer the storage key.
67
68    ``key_label`` can be any string that is independent of the input key
69    material and different to the label used in any other derivation from the
70    same input key. It prevents two different contexts from deriving the same
71    output key from the same input key.
72
73The key derivation function used by the crypto service to derive the storage key
74will be HKDF, with SHA-256 as the underlying hash function. HKDF is suitable
75because:
76
77- It is simple and efficient, requiring only two HMAC operations when the length
78  of the output key material is less than or equal to the hash length (as is the
79  case here).
80- The trade-off is that HKDF is only suitable when the input key material has at
81  least as much entropy as required for the output key material. But this is the
82  case here, as the HUK has 128 bits of entropy, the same as required by PS.
83- HKDF is standardised in RFC 5869 [RFC5869]_ and its security has been formally
84  analysed. [HKDF]_
85- It is supported by the TF-M Crypto service.
86
87The choice of underlying hash function is fairly straightforward: it needs to be
88a modern standardised algorithm, considered to be secure and supported by TF-M
89Crypto. This narrows it down to just the SHA-2 family. Of the hash functions in
90the family, SHA-256 is the simplest and provides more than enough output length.
91
92Keeping the storage key private to PS
93-------------------------------------
94
95The Crypto service derives a platform key from the HUK, using the partition ID
96as the input to that derivation, and that platform key is used for the key
97derivation by PS. This happens transparently, and to PS is indistinguishable
98from deriving from the HUK except that other partitions cannot derive the
99storage key even if they know the derivation parameters.
100
101Key use
102=======
103To encrypt and decrypt data, PS will call the PSA Crypto AEAD APIs in the same
104way as the current implementation, but ``ps_key`` will refer to the storage key,
105rather than the imported HUK. For each encryption operation, the following call
106is made (and analogously for decryption):
107
108.. code-block:: c
109
110    psa_aead_encrypt(ps_key, PS_CRYPTO_ALG,
111                     crypto->ref.iv, PS_IV_LEN_BYTES,
112                     add, add_len,
113                     in, in_len,
114                     out, out_size, out_len);
115
116References
117==========
118.. [TBSA-M] Arm Platform Security Architecture Trusted Base System Architecture
119   for Armv6-M, Armv7-M and Armv8-M, version 1.0
120.. [HKDF] Hugo Krawczyk. 2010. Cryptographic extraction and key derivation: the
121   HKDF scheme. In Proceedings of the 30th annual conference on Advances in
122   cryptology (CRYPTO'10)
123.. [RFC5869] IETF RFC 5869: HMAC-based Extract-and-Expand Key Derivation
124   Function (HKDF)
125
126--------------
127
128*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
129