SST: Rename SST(Secure STorage) to PS(Protected Storage)
This patches renames SST(Secure STorage) to
PS(Protected Storage) for files, folders and any contents
in files to align with the PSA Storage API spec.
Change-Id: Icf991f59512875780c159f22737b521b3b2d4924
Signed-off-by: Kevin Peng <kevin.peng@arm.com>
diff --git a/docs/design_documents/sst_key_management.rst b/docs/design_documents/ps_key_management.rst
similarity index 78%
rename from docs/design_documents/sst_key_management.rst
rename to docs/design_documents/ps_key_management.rst
index 0f617e8..80a39be 100644
--- a/docs/design_documents/sst_key_management.rst
+++ b/docs/design_documents/ps_key_management.rst
@@ -1,6 +1,6 @@
-=====================================
-Secure Storage service key management
-=====================================
+========================================
+Protected Storage service key management
+========================================
:Author: Jamie Fox
:Organization: Arm Limited
@@ -21,13 +21,13 @@
128 bits of entropy (and a 128 bit data size), and be accessible only to Trusted
code or Trusted hardware that acts on behalf of Trusted code. [TBSA-M]_
-In the current implementation, the Secure Storage (SST) service reads the HUK
+In the current implementation, the Protected Storage (PS) service reads the HUK
directly and imports it into the Crypto partition for further use. This has
multiple drawbacks:
-- If there were a flaw in SST that allowed an attacker to obtain its key, then
+- If there were a flaw in PS that allowed an attacker to obtain its key, then
the HUK would be exposed, and so the attacker would be able to decrypt not
- just secure storage but also anything else encrypted with the HUK or a key
+ just protected storage but also anything else encrypted with the HUK or a key
derived from the HUK.
- Using the same key for two or more different cryptographic algorithms may
reduce the security provided by one or more of them.
@@ -38,21 +38,21 @@
Proposal
========
-Each time the system boots, SST will request that the Crypto service uses a key
+Each time the system boots, PS will request that the Crypto service uses a key
derivation function (KDF) to derive a storage key from the HUK. The storage key
could be kept in on-chip volatile memory private to the Crypto partition, or it
-could remain inside a secure element. Either way it will not be returned to SST.
+could remain inside a secure element. Either way it will not be returned to PS.
-For each call to the PSA Protected Storage APIs, SST will make requests to the
+For each call to the PSA Protected Storage APIs, PS will make requests to the
Crypto service to perform AEAD encryption and/or decryption operations using the
storage key (providing a fresh nonce for each encryption).
-At no point will SST access the key material itself, only referring to the HUK
+At no point will PS access the key material itself, only referring to the HUK
and storage key by their handles in the Crypto service.
Key derivation
==============
-SST will make key derivation requests to the Crypto service with calls to the
+PS will make key derivation requests to the Crypto service with calls to the
PSA Crypto APIs. In order to derive the storage key, the following calls will be
made::
@@ -62,33 +62,33 @@
&huk_key_handle)
/* Set up a key derivation operation with the HUK as the input key */
- psa_key_derivation(&sst_key_generator,
+ psa_key_derivation(&ps_key_generator,
huk_key_handle,
TFM_CRYPTO_ALG_HUK_DERIVATION,
- SST_KEY_SALT, SST_KEY_SALT_LEN_BYTES,
- SST_KEY_LABEL, SST_KEY_LABEL_LEN_BYTES,
- SST_KEY_LEN_BYTES)
+ PS_KEY_SALT, PS_KEY_SALT_LEN_BYTES,
+ PS_KEY_LABEL, PS_KEY_LABEL_LEN_BYTES,
+ PS_KEY_LEN_BYTES)
/* Create the storage key from the key generator */
- psa_generator_import_key(sst_key_handle,
- SST_KEY_TYPE,
- PSA_BYTES_TO_BITS(SST_KEY_LEN_BYTES),
- &sst_key_generator)
+ psa_generator_import_key(ps_key_handle,
+ PS_KEY_TYPE,
+ PSA_BYTES_TO_BITS(PS_KEY_LEN_BYTES),
+ &ps_key_generator)
.. note:: ``TFM_CRYPTO_KEY_ID_HUK`` is a PSA Crypto key ID that is assumed in
this design to identify the hardware unique key.
- ``sst_key_handle`` is a PSA Crypto key handle to a volatile key, set
+ ``ps_key_handle`` is a PSA Crypto key handle to a volatile key, set
up in the normal way. After the call to ``psa_generator_import_key``,
it contains the storage key.
- ``SST_KEY_SALT`` can be ``NULL``, as it is only used in the 'extract'
+ ``PS_KEY_SALT`` can be ``NULL``, as it is only used in the 'extract'
step of HKDF, which is redundant when the input key material is a
cryptographically strong key. [RFC5869]_ It must be constant so that
the same key can be derived each boot, to decrypt previously-stored
data.
- ``SST_KEY_LABEL`` can be any string that is independent of the input
+ ``PS_KEY_LABEL`` can be any string that is independent of the input
key material and different to the label used in any other derivation
from the same input key. It prevents two different contexts from
deriving the same output key from the same input key.
@@ -109,7 +109,7 @@
case here).
- The trade-off is that HKDF is only suitable when the input key material has at
least as much entropy as required for the output key material. But this is the
- case here, as the HUK has 128 bits of entropy, the same as required by SST.
+ case here, as the HUK has 128 bits of entropy, the same as required by PS.
- HKDF is standardised in RFC 5869 [RFC5869]_ and its security has been formally
analysed. [HKDF]_
- It is supported by the TF-M Crypto service.
@@ -119,8 +119,8 @@
Crypto. This narrows it down to just the SHA-2 family. Of the hash functions in
the family, SHA-256 is the simplest and provides more than enough output length.
-Keeping the storage key private to SST
---------------------------------------
+Keeping the storage key private to PS
+-------------------------------------
The salt and label fields are not generally secret, so an Application RoT
service could request the Crypto service to derive the same storage key from the
HUK, which violates isolation between Application RoT partitions to some extent.
@@ -128,10 +128,10 @@
- Only PSA RoT partitions can request Crypto to derive keys from the HUK.
- - But then either SST has to be in the PSA RoT or request a service in the PSA
+ - But then either PS has to be in the PSA RoT or request a service in the PSA
RoT to do the derivation on its behalf.
-- SST has a secret (pseudo)random salt, accessible only to it, that it uses to
+- PS has a secret (pseudo)random salt, accessible only to it, that it uses to
derive the storage key.
- Where would this salt be stored? It cannot be generated fresh each boot
@@ -150,13 +150,13 @@
Key use
=======
-To encrypt and decrypt data, SST will call the PSA Crypto AEAD APIs in the same
-way as the current implementation, but ``sst_key_handle`` will refer to the
+To encrypt and decrypt data, PS will call the PSA Crypto AEAD APIs in the same
+way as the current implementation, but ``ps_key_handle`` will refer to the
storage key, rather than the imported HUK. For each encryption operation, the
following call is made (and analogously for decryption)::
- psa_aead_encrypt(sst_key_handle, SST_CRYPTO_ALG,
- crypto->ref.iv, SST_IV_LEN_BYTES,
+ psa_aead_encrypt(ps_key_handle, PS_CRYPTO_ALG,
+ crypto->ref.iv, PS_IV_LEN_BYTES,
add, add_len,
in, in_len,
out, out_size, out_len)