documentation/secure_storage.md

   1 # Secure Storage In OP-TEE
   2
   3 ## Background
   4
   5 Secure Storage (SST) in OP-TEE is implemented according to what has been defined
   6 in GloblaPlatform’s TEE Internal API specification (here called Trusted
   7 Storage). This specification mandates that it should be possible to store
   8 general-purpose data and key material that guarantees confidentiality and
   9 integrity of the data stored and the atomicity of the operations that modifies
  10 the storage (atomicity here means that either the entire operation completes
  11 successfully or no write is done).
  12
  13 There are currently three secure storage implementations in OP-TEE:
  14
  15 - The first one relies on the normal world (REE) file system. It is described in
  16 this document and is the default implementation. It is enabled at compile time
  17 by CFG_REE_FS=y.
  18 - The second one makes use of the Replay Protected Memory Block (RPMB) partition
  19 of an eMMC device, and is enabled by setting `CFG_RPMB_FS=y`. It is described
  20 in [secure_storage_rpmb.md](secure_storage_rpmb.md).
  21 - The third one stores objects in a SQLite database in normal world. It is
  22 enabled by `CFG_SQL_FS=y`. See [secure_storage_sql.md](secure_storage_sql.md).
  23
  24 It is possible to use the normal world filesystems and the RPMB implementations
  25 simultaneously. For this, three OP-TEE specific storage identifiers have been
  26 defined: TEE_STORAGE_PRIVATE_REE, TEE_STORAGE_PRIVATE_RPMB and
  27 TEE_STORAGE_PRIVATE_SQL. Depending on the
  28 compile-time configuration, one or several values may be used.
  29 The value TEE_STORAGE_PRIVATE selects the REE FS when available, otherwise the
  30 RPMB FS if available, otherwise the SQL FS (in this order).
  31
  32 The rest of this document describes the REE FS only.
  33
  34 ## Overview
  35
  36 ![Secure Storage System Architecture](images/secure_storage/secure_storage_system_architecture.png
  37 "Secure Storage System Architecture")
  38
  39 ### Source Files In OP-TEE OS
  40
  41 - **[core/tee/tee_svc_storage.c](../core/tee/tee_svc_storage.c):** TEE trusted
  42 storage service calls
  43 - **[core/tee/tee_ree_fs.c](../core/tee/tee_ree_fs):** TEE file system & REE
  44 file operation interface
  45 - **[core/tee/fs_htree.c](../core/tee/fs_htree.c):** Hash tree
  46 - **[core/tee/tee_fs_key_manager.c](../core/tee/tee_fs_key_manager.c):** Key
  47 manager
  48 - **[lib/libutee/](../lib/libutee/):** GlobalPlatform Internal API library
  49
  50 ### Basic File Operation Flow
  51
  52 When a TA is calling the write function provided by GP Trusted Storage API to
  53 write data to a persistent object, a corresponding syscall implemented in TEE
  54 Trusted Storage Service will be called, which in turn will invoke a series of
  55 TEE file operations to store the data. TEE file system will then encrypt the
  56 data and send REE file operation commands and the encrypted
  57 data to TEE supplicant by a series of RPC messages. TEE supplicant will receive
  58 the messages and store the encrypted data accordingly to the Linux file
  59 system. Reading files are handled in a similar manner.
  60
  61 ### GlobalPlatform Trusted Storage Requirement
  62
  63 Below is an excerpt from the specification listing the most vital requirements:
  64
  65 1. The Trusted Storage may be backed by non-secure resources as long as suitable
  66    cryptographic protection is applied, which MUST be as strong as the means
  67    used to protect the TEE code and data itself
  68 2. The Trusted Storage MUST be bound to a particular device, which means that it
  69    MUST be accessible or modifiable only by authorized TAs running in the same
  70    TEE and on the same device as when the data was created.
  71 3. Ability to hide sensitive key material from the TA itself.
  72 4. Each TA has access to its own storage space that is shared among all the
  73    instances of that TA but separated from the other TAs.
  74 5. The Trusted Storage must provide a minimum level of protection against
  75    rollback attacks. It is accepted that the actually physical storage may be in
  76    an insecure area and so is vulnerable to actions from outside of the TEE.
  77    Typically, an implementation may rely on the REE for that purpose (protection
  78    level 100) or on hardware assets controlled by the TEE (protection level
  79    1000).
  80
  81 ### TEE File Structure In Linux File System
  82
  83 ![TEE File Structure](images/secure_storage/tee_file_structure.png
  84 "TEE file structure in Linux file system")
  85
  86 OP-TEE by default use "/data/tee/" as the secure storage space in Linux
  87 file system. For each TA, OP-TEE use the TA's UUID to create a standalone folder
  88 for it under the secure storage space folder. For a persistent object belonging
  89 to a specific TA, OP-TEE creates a TEE file is object-id under the TA folder.
  90
  91 ## Key Manager
  92
  93 Key manager is an component in TEE file system, and is responsible for handling
  94 data encryption and decryption and also management of the sensitive key
  95 materials. There are three types of keys used by the key manager: the Secure
  96 Storage Key (SSK), the TA Storage KEY (TSK) and the File Encryption Key (FEK).
  97
  98 ### Secure Storage Key (SSK)
  99
 100 SSK is a per-device key and is generated and stored in secure memory when OP-TEE
 101 is booting. SSK is used to derive the TA Storage Key (TSK).
 102
 103 SSK is derived by:
 104 > SSK = HMAC<sub>SHA256</sub> (HUK, Chip ID || "static string")
 105
 106 The functions to get Hardware Unique Key (HUK) and chip ID depend on platform
 107 implementation.
 108
 109 Currently, in OP-TEE OS we only have a per-device key, SSK, which is used for
 110 secure storage subsystem, but, for the future we might need to create different
 111 per-device keys for different subsystems using the same algorithm as we
 112 generate the SSK; An easy way to generate different per-device keys for
 113 different subsystems is using different static strings to generate the keys.
 114
 115 ### Trusted Application Storage Key (TSK)
 116
 117 The TSK is a per-Trusted Application key, which is generated from the SSK and
 118 the TA's identifier (UUID). It is used to protect the FEK, in other words,
 119 to encrypt/decrypt the FEK.
 120
 121 TSK is derived by:
 122 > TSK = HMAC<sub>SHA256</sub> (SSK, TA_UUID)
 123
 124 #### TA storage space isolation
 125
 126 OP-TEE provides different folders for different TAs in Linux file system for
 127 storing their own TEE files, but OP-TEE cannot prevent an attacker from
 128 directly copying a TEE file from one TA's folder to another TA's folder in
 129 Linux file system.
 130
 131 The TSK offers an effective protection against this kind of attack. If an
 132 attacker copies an TEE file from one TA's folder to another TA's folder,
 133 this TA would not be able to obtain the plaintext of the TEE file.
 134
 135 ### File Encryption Key (FEK)
 136
 137 When a new TEE file is created, key manager will generate a new FEK by
 138 PRNG (pesudo random number generator) for the TEE file and store the encrypted
 139 FEK in meta file. FEK is used for encrypting/decrypting the TEE file information
 140 stored in meta file or the data stored in block file.
 141
 142 ## Hash Tree
 143
 144 The hash tree is responsible for handling data encryption and decryption of
 145 a secure storage file.
 146
 147 The hash tree is implemented as a binary tree where
 148 each node (`struct tee_fs_htree_node_image` below) in the tree protects its
 149 two child nodes and a data block.
 150
 151 The meta data is stored in a header (`struct tee_fs_htree_image` below)
 152 which also protects the top node.
 153
 154 All fields (header, nodes, and blocks) are duplicated with two versions, 0
 155 and 1, to ensure atomic updates. See
 156 [core/tee/fs_htree.c](../core/tee/fs_htree.c) for details.
 157
 158 ### Meta Data Encryption Flow
 159
 160 ![Meta Data Encryption](images/secure_storage/meta_data_encryption.png
 161 "Meta data encryption")
 162
 163 A new meta IV will be generated by PRNG when a meta data needs to be updated.
 164 The size of meta IV is defined in
 165 [core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h)
 166
 167 The data structures of meta data and node data are defined in
 168 [core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h) as follows:
 169
 170 ```
 171 struct tee_fs_htree_node_image {
 172         uint8_t hash[TEE_FS_HTREE_HASH_SIZE];
 173         uint8_t iv[TEE_FS_HTREE_IV_SIZE];
 174         uint8_t tag[TEE_FS_HTREE_TAG_SIZE];
 175         uint16_t flags;
 176 };
 177
 178 struct tee_fs_htree_meta {
 179         uint64_t length;
 180 };
 181
 182 struct tee_fs_htree_imeta {
 183         struct tee_fs_htree_meta meta;
 184         uint32_t max_node_id;
 185 };
 186
 187 struct tee_fs_htree_image {
 188         uint8_t iv[TEE_FS_HTREE_IV_SIZE];
 189         uint8_t tag[TEE_FS_HTREE_TAG_SIZE];
 190         uint8_t enc_fek[TEE_FS_HTREE_FEK_SIZE];
 191         uint8_t imeta[sizeof(struct tee_fs_htree_imeta)];
 192         uint32_t counter;
 193 };
 194 ```
 195
 196 ### Block Data Encryption Flow
 197
 198 ![Block Data Encryption](images/secure_storage/block_data_encryption.png
 199 "Block data encryption")
 200
 201 A new block IV will be generated by PRNG when a block data needs to be updated.
 202 The size of block IV is defined in
 203 [core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h)
 204
 205 ## Atomic Operation
 206
 207 According to GlobalPlatform Trusted Storage requirement of the atomicity, the
 208 following operations should support atomic update:
 209 > Write, Truncate, Rename, Create and Delete
 210
 211 The strategy used in OP-TEE secure storage to guarantee the atomicity is
 212 out-of-place update.
 213
 214 ## Important caveats
 215
 216 Currently **no OP-TEE platform is able to support retrieval of the Hardware
 217 Unique Key or Chip ID required for secure operation**.
 218
 219 For all platforms, a constant key is used, resulting in no protection against
 220 decryption, or Secure Storage duplication to other devices.
 221
 222 This is because information about how to retrieve key data from the SoC is
 223 considered sensitive by the vendors and it is not freely available.
 224
 225 In OP-TEE, there are apis for reading the keys generically from "One-Time
 226 Programmable" memory, or OTP.  But there are no existing platform implementations.
 227
 228 To allow Secure Storage to operate securely on your platform, you must:
 229
 230  - enable CFG_OTP_SUPPORT on your platform
 231
 232  - In your platform code, define implementations for:
 233
 234 ```
 235  void tee_otp_get_hw_unique_key(struct tee_hw_unique_key *hwkey);
 236  int tee_otp_get_die_id(uint8_t *buffer, size_t len);
 237 ```
 238
 239 These implementations should fetch the key data from your SoC-specific e-fuses,
 240 or crypto unit according to the method defined by your SoC vendor.
 241
 242 ## Future Work
 243
 244 - **TEE file renaming attack detection**
 245
 246 OP-TEE creates a specific folder under the TA's folder for each TEE file in
 247 Linux file system and use the filename of the TEE file as the folder's name.
 248 If an attacker directly rename the name of a TEE file folder, the renamed
 249 TEE file is still a valid TEE file in OP-TEE.
 250
 251 A solution to detect the attack is using TEE filename as AAD when calculating
 252 the tag of meta file.
 253
 254 - **Rollback attack detection**
 255
 256 An attacker can backup each version of a TEE file directly from Linux file
 257 system and can replace the TEE file by an old version one sooner or later.
 258
 259 The basic idea of detecting rollback attack is to add write counter both in
 260 meta file and another storage which has anti-rollback capability such as eMMC
 261 RPMB partition.
 262
 263 ## Reference
 264
 265 * [Secure Storage Presentation](http://www.slideshare.net/linaroorg/sfo15503-secure-storage-in-optee)
 266 * [TEE Internal Core API Specification v1.1](http://www.globalplatform.org/specificationsdevice.asp)