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.db).
  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/tee_fs_key_manager.c](../core/tee/tee_fs_key_manager.c):** Key
  46 manager
  47 - **[lib/libutee/](../lib/libutee/):** GlobalPlatform Internal API library
  48
  49 ### Basic File Operation Flow
  50
  51 When a TA is calling the write function provided by GP Trusted Storage API to
  52 write data to a persistent object, a corresponding syscall implemented in TEE
  53 Trusted Storage Service will be called, which in turn will invoke a series of
  54 TEE file operations to store the data. TEE file system will then encrypt the
  55 data and send REE file operation commands and the encrypted
  56 data to TEE supplicant by a series of RPC messages. TEE supplicant will receive
  57 the messages and store the encrypted data accordingly to the Linux file
  58 system. Reading files are handled in a similar manner.
  59
  60 ### GlobalPlatform Trusted Storage Requirement
  61
  62 Below is an excerpt from the specification listing the most vital requirements:
  63
  64 1. The Trusted Storage may be backed by non-secure resources as long as suitable
  65    cryptographic protection is applied, which MUST be as strong as the means
  66    used to protect the TEE code and data itself
  67 2. The Trusted Storage MUST be bound to a particular device, which means that it
  68    MUST be accessible or modifiable only by authorized TAs running in the same
  69    TEE and on the same device as when the data was created.
  70 3. Ability to hide sensitive key material from the TA itself.
  71 4. Each TA has access to its own storage space that is shared among all the
  72    instances of that TA but separated from the other TAs.
  73 5. The Trusted Storage must provide a minimum level of protection against
  74    rollback attacks. It is accepted that the actually physical storage may be in
  75    an unsecure areas and so is vulnerable to actions from outside of the TEE.
  76    Typically, an implementation may rely on the REE for that purpose (protection
  77    level 100) or on hardware assets controlled by the TEE (protection level
  78    1000).
  79
  80 ### TEE File Structure In Linux File System
  81
  82 ![TEE File Structure](images/secure_storage/tee_file_structure.png
  83 "TEE file structure in Linux file system")
  84
  85 OP-TEE by default use "/data/tee/" as the secure storage space in Linux
  86 file system. For each TA, OP-TEE use the TA's UUID to create a standalone folder
  87 for it under the secure storage space folder. For a persistent object belonging
  88 to a specific TA, OP-TEE creates a TEE file is object-id under the TA folder.
  89
  90 All fields in the REE file are duplicated with two versions 0 and 1. The
  91 active meta-data block is selected by the lowest bit in the
  92 meta-counter.  The active file block is selected by corresponding bit
  93 number instruct tee_fs_file_info.backup_version_table.
  94
  95 The atomicity of each operation is ensured by updating meta-counter when
  96 everything in the secondary blocks (both meta-data and file-data blocks)
  97 are successfully written.  The main purpose of the code is to perform block
  98 encryption and authentication of the file data, and properly handle seeking
  99 through the file. One file (in the sense of struct tee_file_operations)
 100 maps to one file in the REE filesystem, and has the following structure:
 101 ```
 102 [ 4 bytes meta-counter]
 103 [ meta-data version 0][ meta-data version 1 ]
 104 [ Block 0 version 0 ][ Block 0 version 1 ]
 105 [ Block 1 version 0 ][ Block 1 version 1 ]
 106 ...
 107 [ Block n version 0 ][ Block n version 1 ]
 108 ```
 109
 110 One meta-data block is built up as:
 111 ```
 112 [ struct meta_header | struct tee_fs_get_header_size ]
 113 ```
 114
 115 One data block is built up as:
 116 ```
 117 [ struct block_header | BLOCK_FILE_SIZE bytes ]
 118 ```
 119
 120 The reason why we store the TEE file content in many small blocks is to
 121 accelerate the file update speed when handling a large file. The block size
 122 (FILE_BLOCK_SIZE) and the maximum number of blocks of a TEE file
 123 (NUM_BLOCKS_PER_FILE) are defined in
 124 [core/tee/tee_ree_fs.c](../core/tee/tee_ree_fs.c).
 125
 126 For now, the default block size is 4KB and the maximum number of blocks of a
 127 TEE file is 1024.
 128
 129 ## Key Manager
 130
 131 Key manager is an component in TEE file system, and is responsible for handling
 132 data encryption and decryption and also management of the sensitive key
 133 materials. There are three types of keys used by the key manager: the Secure
 134 Storage Key (SSK), the TA Storage KEY (TSK) and the File Encryption Key (FEK).
 135
 136 ### Secure Storage Key (SSK)
 137
 138 SSK is a per-device key and is generated and stored in secure memory when OP-TEE
 139 is booting. SSK is used to derive the TA Storage Key (TSK).
 140
 141 SSK is derived by:
 142 > SSK = HMAC<sub>SHA256</sub> (HUK, Chip ID || "static string")
 143
 144 The functions to get Hardware Unique Key (HUK) and chip ID depend on platform
 145 implementation.
 146
 147 Currently, in OP-TEE OS we only have a per-device key, SSK, which is used for
 148 secure storage subsystem, but, for the future we might need to create different
 149 per-device keys for different subsystems using the same algorithm as we
 150 generate the SSK; An easy way to generate different per-device keys for
 151 different subsystems is using different static strings to generate the keys.
 152
 153 ### Trusted Application Storage Key (TSK)
 154
 155 The TSK is a per-Trusted Application key, which is generated from the SSK and
 156 the TA's identifier (UUID). It is used to protect the FEK, in other words,
 157 to encrypt/decrypt the FEK.
 158
 159 TSK is derived by:
 160 > TSK = HMAC<sub>SHA256</sub> (SSK, TA_UUID)
 161
 162 #### TA storage space isolation
 163
 164 OP-TEE provides different folders for different TAs in Linux file system for
 165 storing their own TEE files, but OP-TEE cannot prevent an attacker from
 166 directly copying a TEE file from one TA's folder to another TA's folder in
 167 Linux file system.
 168
 169 The TSK offers an effective protection against this kind of attack. If an
 170 attacker copies an TEE file from one TA's folder to another TA's folder,
 171 this TA would not be able to obtain the plaintext of the TEE file.
 172
 173 ### File Encryption Key (FEK)
 174
 175 When a new TEE file is created, key manager will generate a new FEK by
 176 PRNG (pesudo random number generator) for the TEE file and store the encrypted
 177 FEK in meta file. FEK is used for encrypting/decrypting the TEE file information
 178 stored in meta file or the data stored in block file.
 179
 180 ### Meta Data Encryption Flow
 181
 182 ![Meta Data Encryption](images/secure_storage/meta_data_encryption.png
 183 "Meta data encryption")
 184
 185 A new meta IV will be generated by PRNG when a meta data needs to be updated.
 186 The default size of meta IV is defined in
 187 [core/include/tee/tee_fs_key_manager.h](../core/include/tee/tee_fs_key_manager.h)
 188
 189 The data structure of meta data is defined in
 190 [core/tee/tee_fs_private.h](../core/tee/tee_fs_private.h) as follows:
 191
 192 ```
 193 struct tee_fs_file_info {
 194     size_t length;
 195     uint32_t backup_version_table[NUM_BLOCKS_PER_FILE / 32];
 196 };
 197 ```
 198
 199 ### Block Data Encryption Flow
 200
 201 ![Block Data Encryption](images/secure_storage/block_data_encryption.png
 202 "Block data encryption")
 203
 204 A new block IV will be generated by PRNG when a block data needs to be updated.
 205 The default size of block IV is defined in
 206 [core/include/tee/tee_fs_key_manager.h](../core/include/tee/tee_fs_key_manager.h)
 207
 208 ## Atomic Operation
 209
 210 According to GlobalPlatform Trusted Storage requirement of the atomicity, the
 211 following operations should support atomic update:
 212 > Write, Truncate, Rename, Create and Delete
 213
 214 The strategy used in OP-TEE secure storage to guarantee the atomicity is
 215 out-of-place update.
 216
 217 ## Important caveats
 218
 219 Currently **no OP-TEE platform is able to support retrieval of the Hardware
 220 Unique Key or Chip ID required for secure operation**.
 221
 222 For all platforms, a constant key is used, resulting in no protection against
 223 decryption, or Secure Storage duplication to other devices.
 224
 225 This is because information about how to retrieve key data from the SoC is
 226 considered sensitive by the vendors and it is not freely available.
 227
 228 In OP-TEE, there are apis for reading the keys generically from "One-Time
 229 Programmable" memory, or OTP.  But there are no existing platform implementations.
 230
 231 To allow Secure Storage to operate securely on your platform, you must:
 232
 233  - enable CFG_OTP_SUPPORT on your platform
 234
 235  - In your platform code, define implementations for:
 236
 237 ```
 238  void tee_otp_get_hw_unique_key(struct tee_hw_unique_key *hwkey);
 239  int tee_otp_get_die_id(uint8_t *buffer, size_t len);
 240 ```
 241
 242 These implementations should fetch the key data from your SoC-specific e-fuses,
 243 or crypto unit according to the method defined by your SoC vendor.
 244
 245 ## Future Work
 246
 247 - **TEE file renaming attack detection**
 248
 249 OP-TEE creates a specific folder under the TA's folder for each TEE file in
 250 Linux file system and use the filename of the TEE file as the folder's name.
 251 If an attacker directly rename the name of a TEE file folder, the renamed
 252 TEE file is still a valid TEE file in OP-TEE.
 253
 254 A solution to detect the attack is using TEE filename as AAD when calculating
 255 the tag of meta file.
 256
 257 - **Rollback attack detection**
 258
 259 An attacker can backup each version of a TEE file directly from Linux file
 260 system and can replace the TEE file by an old version one sooner or later.
 261
 262 The basic idea of detecting rollback attack is to add write counter both in
 263 meta file and another storage which has anti-rollback capability such as eMMC
 264 RPMB partition.
 265
 266 ## Reference
 267
 268 * [Secure Storage Presentation](http://www.slideshare.net/linaroorg/sfo15503-secure-storage-in-optee)
 269 * [TEE Internal Core API Specification v1.1](http://www.globalplatform.org/specificationsdevice.asp)