AnilKumar Chimata | e78789a | 2017-04-07 12:18:46 -0700 | [diff] [blame] | 1 | Introduction: |
| 2 | ============= |
| 3 | Storage encryption has been one of the most required feature from security |
| 4 | point of view. QTI based storage encryption solution uses general purpose |
| 5 | crypto engine. While this kind of solution provide a decent amount of |
| 6 | performance, it falls short as storage speed is improving significantly |
| 7 | continuously. To overcome performance degradation, newer chips are going to |
| 8 | have Inline Crypto Engine (ICE) embedded into storage device. ICE is supposed |
| 9 | to meet the line speed of storage devices. |
| 10 | |
| 11 | Hardware Description |
| 12 | ==================== |
| 13 | ICE is a HW block that is embedded into storage device such as UFS/eMMC. By |
| 14 | default, ICE works in bypass mode i.e. ICE HW does not perform any crypto |
| 15 | operation on data to be processed by storage device. If required, ICE can be |
| 16 | configured to perform crypto operation in one direction (i.e. either encryption |
| 17 | or decryption) or in both direction(both encryption & decryption). |
| 18 | |
| 19 | When a switch between the operation modes(plain to crypto or crypto to plain) |
| 20 | is desired for a particular partition, SW must complete all transactions for |
| 21 | that particular partition before switching the crypto mode i.e. no crypto, one |
| 22 | direction crypto or both direction crypto operation. Requests for other |
| 23 | partitions are not impacted due to crypto mode switch. |
| 24 | |
| 25 | ICE HW currently supports AES128/256 bit ECB & XTS mode encryption algorithms. |
| 26 | |
| 27 | Keys for crypto operations are loaded from SW. Keys are stored in a lookup |
| 28 | table(LUT) located inside ICE HW. Maximum of 32 keys can be loaded in ICE key |
| 29 | LUT. A Key inside the LUT can be referred using a key index. |
| 30 | |
| 31 | SW Description |
| 32 | ============== |
| 33 | ICE HW has catagorized ICE registers in 2 groups: those which can be accessed by |
| 34 | only secure side i.e. TZ and those which can be accessed by non-secure side such |
| 35 | as HLOS as well. This requires that ICE driver to be split in two pieces: one |
| 36 | running from TZ space and another from HLOS space. |
| 37 | |
| 38 | ICE driver from TZ would configure keys as requested by HLOS side. |
| 39 | |
| 40 | ICE driver on HLOS side is responsible for initialization of ICE HW. |
| 41 | |
| 42 | SW Architecture Diagram |
| 43 | ======================= |
| 44 | Following are all the components involved in the ICE driver for control path: |
| 45 | |
| 46 | +++++++++++++++++++++++++++++++++++++++++ |
| 47 | + App layer + |
| 48 | +++++++++++++++++++++++++++++++++++++++++ |
| 49 | + System layer + |
| 50 | + ++++++++ +++++++ + |
| 51 | + + VOLD + + PFM + + |
| 52 | + ++++++++ +++++++ + |
| 53 | + || || + |
| 54 | + || || + |
| 55 | + \/ \/ + |
| 56 | + ++++++++++++++ + |
| 57 | + + LibQSEECom + + |
| 58 | + ++++++++++++++ + |
| 59 | +++++++++++++++++++++++++++++++++++++++++ |
| 60 | + Kernel + +++++++++++++++++ |
| 61 | + + + KMS + |
| 62 | + +++++++ +++++++++++ +++++++++++ + +++++++++++++++++ |
| 63 | + + ICE + + Storage + + QSEECom + + + ICE Driver + |
| 64 | +++++++++++++++++++++++++++++++++++++++++ <===> +++++++++++++++++ |
| 65 | || || |
| 66 | || || |
| 67 | \/ \/ |
| 68 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 69 | + Storage Device + |
| 70 | + ++++++++++++++ + |
| 71 | + + ICE HW + + |
| 72 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 73 | |
| 74 | Use Cases: |
| 75 | ---------- |
| 76 | a) Device bootup |
| 77 | ICE HW is detected during bootup time and corresponding probe function is |
| 78 | called. ICE driver parses its data from device tree node. ICE HW and storage |
| 79 | HW are tightly coupled. Storage device probing is dependent upon ICE device |
| 80 | probing. ICE driver configures all the required registers to put the ICE HW |
| 81 | in bypass mode. |
| 82 | |
| 83 | b) Configuring keys |
| 84 | Currently, there are couple of use cases to configure the keys. |
| 85 | |
| 86 | 1) Full Disk Encryption(FDE) |
| 87 | System layer(VOLD) at invocation of apps layer would call libqseecom to create |
| 88 | the encryption key. Libqseecom calls qseecom driver to communicate with KMS |
| 89 | module on the secure side i.e. TZ. KMS would call ICE driver on the TZ side to |
| 90 | create and set the keys in ICE HW. At the end of transaction, VOLD would have |
| 91 | key index of key LUT where encryption key is present. |
| 92 | |
| 93 | 2) Per File Encryption (PFE) |
| 94 | Per File Manager(PFM) calls QSEECom api to create the key. PFM has a peer comp- |
| 95 | onent(PFT) at kernel layer which gets the corresponding key index from PFM. |
| 96 | |
| 97 | Following are all the components involved in the ICE driver for data path: |
| 98 | |
| 99 | +++++++++++++++++++++++++++++++++++++++++ |
| 100 | + App layer + |
| 101 | +++++++++++++++++++++++++++++++++++++++++ |
| 102 | + VFS + |
| 103 | +---------------------------------------+ |
| 104 | + File System (EXT4) + |
| 105 | +---------------------------------------+ |
| 106 | + Block Layer + |
| 107 | + --------------------------------------+ |
| 108 | + +++++++ + |
| 109 | + dm-req-crypt => + PFT + + |
| 110 | + +++++++ + |
| 111 | + + |
| 112 | +---------------------------------------+ |
| 113 | + +++++++++++ +++++++ + |
| 114 | + + Storage + + ICE + + |
| 115 | +++++++++++++++++++++++++++++++++++++++++ |
| 116 | + || + |
| 117 | + || (Storage Req with + |
| 118 | + \/ ICE parameters ) + |
| 119 | +++++++++++++++++++++++++++++++++++++++++ |
| 120 | + Storage Device + |
| 121 | + ++++++++++++++ + |
| 122 | + + ICE HW + + |
| 123 | +++++++++++++++++++++++++++++++++++++++++ |
| 124 | |
| 125 | c) Data transaction |
| 126 | Once the crypto key has been configured, VOLD/PFM creates device mapping for |
| 127 | data partition. As part of device mapping VOLD passes key index, crypto |
| 128 | algorithm, mode and key length to dm layer. In case of PFE, keys are provided |
| 129 | by PFT as and when request is processed by dm-req-crypt. When any application |
| 130 | needs to read/write data, it would go through DM layer which would add crypto |
| 131 | information, provided by VOLD/PFT, to Request. For each Request, Storage driver |
| 132 | would ask ICE driver to configure crypto part of request. ICE driver extracts |
| 133 | crypto data from Request structure and provide it to storage driver which would |
| 134 | finally dispatch request to storage device. |
| 135 | |
| 136 | d) Error Handling |
| 137 | Due to issue # 1 mentioned in "Known Issues", ICE driver does not register for |
| 138 | any interrupt. However, it enables sources of interrupt for ICE HW. After each |
| 139 | data transaction, Storage driver receives transaction completion event. As part |
| 140 | of event handling, storage driver calls ICE driver to check if any of ICE |
| 141 | interrupt status is set. If yes, storage driver returns error to upper layer. |
| 142 | |
| 143 | Error handling would be changed in future chips. |
| 144 | |
| 145 | Interfaces |
| 146 | ========== |
| 147 | ICE driver exposes interfaces for storage driver to : |
| 148 | 1. Get the global instance of ICE driver |
| 149 | 2. Get the implemented interfaces of the particular ice instance |
| 150 | 3. Initialize the ICE HW |
| 151 | 4. Reset the ICE HW |
| 152 | 5. Resume/Suspend the ICE HW |
| 153 | 6. Get the Crypto configuration for the data request for storage |
| 154 | 7. Check if current data transaction has generated any interrupt |
| 155 | |
| 156 | Driver Parameters |
| 157 | ================= |
| 158 | This driver is built and statically linked into the kernel; therefore, |
| 159 | there are no module parameters supported by this driver. |
| 160 | |
| 161 | There are no kernel command line parameters supported by this driver. |
| 162 | |
| 163 | Power Management |
| 164 | ================ |
| 165 | ICE driver does not do power management on its own as it is part of storage |
| 166 | hardware. Whenever storage driver receives request for power collapse/suspend |
| 167 | resume, it would call ICE driver which exposes APIs for Storage HW. ICE HW |
| 168 | during power collapse or reset, wipes crypto configuration data. When ICE |
| 169 | driver receives request to resume, it would ask ICE driver on TZ side to |
| 170 | restore the configuration. ICE driver does not do anything as part of power |
| 171 | collapse or suspend event. |
| 172 | |
| 173 | Interface: |
| 174 | ========== |
| 175 | ICE driver exposes following APIs for storage driver to use: |
| 176 | |
| 177 | int (*init)(struct platform_device *, void *, ice_success_cb, ice_error_cb); |
| 178 | -- This function is invoked by storage controller during initialization of |
| 179 | storage controller. Storage controller would provide success and error call |
| 180 | backs which would be invoked asynchronously once ICE HW init is done. |
| 181 | |
| 182 | int (*reset)(struct platform_device *); |
| 183 | -- ICE HW reset as part of storage controller reset. When storage controller |
| 184 | received reset command, it would call reset on ICE HW. As of now, ICE HW |
| 185 | does not need to do anything as part of reset. |
| 186 | |
| 187 | int (*resume)(struct platform_device *); |
| 188 | -- ICE HW while going to reset, wipes all crypto keys and other data from ICE |
| 189 | HW. ICE driver would reconfigure those data as part of resume operation. |
| 190 | |
| 191 | int (*suspend)(struct platform_device *); |
| 192 | -- This API would be called by storage driver when storage device is going to |
| 193 | suspend mode. As of today, ICE driver does not do anything to handle suspend. |
| 194 | |
| 195 | int (*config)(struct platform_device *, struct request* , struct ice_data_setting*); |
| 196 | -- Storage driver would call this interface to get all crypto data required to |
| 197 | perform crypto operation. |
| 198 | |
| 199 | int (*status)(struct platform_device *); |
| 200 | -- Storage driver would call this interface to check if previous data transfer |
| 201 | generated any error. |
| 202 | |
| 203 | Config options |
| 204 | ============== |
| 205 | This driver is enabled by the kernel config option CONFIG_CRYPTO_DEV_MSM_ICE. |
| 206 | |
| 207 | Dependencies |
| 208 | ============ |
| 209 | ICE driver depends upon corresponding ICE driver on TZ side to function |
| 210 | appropriately. |
| 211 | |
| 212 | Known Issues |
| 213 | ============ |
| 214 | 1. ICE HW emits 0s even if it has generated an interrupt |
| 215 | This issue has significant impact on how ICE interrupts are handled. Currently, |
| 216 | ICE driver does not register for any of the ICE interrupts but enables the |
| 217 | sources of interrupt. Once storage driver asks to check the status of interrupt, |
| 218 | it reads and clears the clear status and provide read status to storage driver. |
| 219 | This mechanism though not optimal but prevents filesystem curruption. |
| 220 | This issue has been fixed in newer chips. |
| 221 | |
| 222 | 2. ICE HW wipes all crypto data during power collapse |
| 223 | This issue necessiate that ICE driver on TZ side store the crypto material |
| 224 | which is not required in the case of general purpose crypto engine. |
| 225 | This issue has been fixed in newer chips. |
| 226 | |
| 227 | Further Improvements |
| 228 | ==================== |
| 229 | Currently, Due to PFE use case, ICE driver is dependent upon dm-req-crypt to |
| 230 | provide the keys as part of request structure. This couples ICE driver with |
| 231 | dm-req-crypt based solution. It is under discussion to expose an IOCTL based |
| 232 | and registeration based interface APIs from ICE driver. ICE driver would use |
| 233 | these two interfaces to find out if any key exists for current request. If |
| 234 | yes, choose the right key index received from IOCTL or registeration based |
| 235 | APIs. If not, dont set any crypto parameter in the request. |