idnits 2.17.1 draft-pei-opentrustprotocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 26 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 882 has weird spacing: '...cluding the r...' -- The document date (July 2016) is 2840 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'JWS' is mentioned on line 1040, but not defined == Missing Reference: 'JWE' is mentioned on line 1040, but not defined == Unused Reference: 'RFC7516' is defined on line 3729, but no explicit reference was found in the text == Unused Reference: 'RFC7518' is defined on line 3737, but no explicit reference was found in the text == Unused Reference: 'GPTEE' is defined on line 3743, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Pei 3 Internet-Draft Symantec 4 Intended status: Informational N. Cook 5 Expires: January 2, 2017 Intercede 6 M. Yoo 7 Solacia 8 A. Atyeo 9 Intercede 10 H. Tschofenig 11 ARM Ltd. 12 July 2016 14 The Open Trust Protocol (OTrP) 15 draft-pei-opentrustprotocol-00.txt 17 Abstract 19 This document specifies the Open Trust Protocol (OTrP), a protocol to 20 install, update, and delete applications and to manage security 21 configuration in a Trust Execution Environment (TEE). 23 TEEs are used in environments where security services should be 24 isolated from a regular operating system (often called rich OS). 25 This form of compartmentlization grants a smaller codebase access to 26 security sensitive services and restricts communication from the rich 27 OS to those security services via mediated access. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 2, 2017. 46 Copyright Notice 48 Copyright (c) 2016 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 6 65 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 6 67 3.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 7 68 4. OTrP Entities and Trust Model . . . . . . . . . . . . . . . . 8 69 4.1. System Components . . . . . . . . . . . . . . . . . . . . 8 70 4.2. Trusted Anchors in TEE . . . . . . . . . . . . . . . . . 9 71 4.3. Trusted Anchors in TSM . . . . . . . . . . . . . . . . . 9 72 4.4. Keys and Cerificate Types . . . . . . . . . . . . . . . . 9 73 5. Protocol Scope and Entity Relations . . . . . . . . . . . . . 12 74 5.1. A Sample Device Setup Flow . . . . . . . . . . . . . . . 14 75 5.2. Derived Keys in the Protocol . . . . . . . . . . . . . . 14 76 5.3. Security Domain Hierarchy and Ownership . . . . . . . . . 14 77 5.4. SD Owner Identification and TSM Certificate 78 Requirements . . . . . . . . . . . . . . . . . . . . . . 15 79 5.5. Service Provider Container . . . . . . . . . . . . . . . 16 80 6. OTrP Agent . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 6.1. Role of OTrP Agent . . . . . . . . . . . . . . . . . . . 16 82 6.2. OTrP Agent and Global Platform TEE Client API . . . . . . 17 83 6.3. OTrP Agent Implementation Consideration . . . . . . . . . 17 84 6.3.1. OTrP Agent Distribution . . . . . . . . . . . . . . . 17 85 6.3.2. Number of OTrP Agent . . . . . . . . . . . . . . . . 17 86 6.3.3. OTrP Android Service Option . . . . . . . . . . . . . 18 87 6.4. OTrP Agent API for Client Applications . . . . . . . . . 18 88 6.4.1. API processMessage . . . . . . . . . . . . . . . . . 18 89 6.4.2. API getTAInformation . . . . . . . . . . . . . . . . 19 90 6.5. Sample End-to-End Client Application Flow . . . . . . . . 21 91 6.5.1. Case 1: A new Client App uses a TA . . . . . . . . . 21 92 6.5.2. Case 2: A previously installed Client Application 93 calls a TA . . . . . . . . . . . . . . . . . . . . . 23 95 7. OTrP Messages . . . . . . . . . . . . . . . . . . . . . . . . 24 96 7.1. Message Format . . . . . . . . . . . . . . . . . . . . . 24 97 7.2. Message Naming Convention . . . . . . . . . . . . . . . . 24 98 7.3. Request and Response Message Template . . . . . . . . . . 25 99 7.4. Signed Request and Response Message Structure . . . . . . 25 100 7.4.1. Identifying signing and Encryption keys for JWS/JWE 101 messaging . . . . . . . . . . . . . . . . . . . . . . 27 102 7.5. JSON Signing and Encryption Algorithms . . . . . . . . . 27 103 7.5.1. Supported JSON Signing Algorithms . . . . . . . . . . 29 104 7.5.2. Support JSON Encryption Algorithms . . . . . . . . . 29 105 7.6. Common Errors . . . . . . . . . . . . . . . . . . . . . . 29 106 7.7. OTrP Message List . . . . . . . . . . . . . . . . . . . . 30 107 7.8. OTrP Request Message Routing Rules . . . . . . . . . . . 31 108 7.8.1. SP Anonymous Attestation Key (SP AIK) . . . . . . . . 31 109 8. Detailed Messages Specification . . . . . . . . . . . . . . . 31 110 8.1. GetDeviceState . . . . . . . . . . . . . . . . . . . . . 31 111 8.1.1. GetDeviceStateRequest message . . . . . . . . . . . . 32 112 8.1.2. Request processing requirements at a TEE . . . . . . 33 113 8.1.3. Firmware signed data . . . . . . . . . . . . . . . . 34 114 8.1.3.1. Supported Firmware Signature Methods . . . . . . 34 115 8.1.4. Post Conditions . . . . . . . . . . . . . . . . . . . 35 116 8.1.5. GetDeviceStateResponse message . . . . . . . . . . . 35 117 8.1.6. Error Conditions . . . . . . . . . . . . . . . . . . 39 118 8.1.7. TSM Processing Requirements . . . . . . . . . . . . . 40 119 8.2. Security Domain Management . . . . . . . . . . . . . . . 41 120 8.2.1. CreateSD . . . . . . . . . . . . . . . . . . . . . . 41 121 8.2.1.1. CreateSDRequest Message . . . . . . . . . . . . . 41 122 8.2.1.2. Request processing requirements at a TEE . . . . 44 123 8.2.1.3. CreateSDResponse Message . . . . . . . . . . . . 45 124 8.2.1.4. Error Conditions . . . . . . . . . . . . . . . . 46 125 8.2.2. UpdateSD . . . . . . . . . . . . . . . . . . . . . . 47 126 8.2.2.1. UpdateSDRequest Message . . . . . . . . . . . . . 47 127 8.2.2.2. Request processing requirements at a TEE . . . . 50 128 8.2.2.3. UpdateSDResponse Message . . . . . . . . . . . . 51 129 8.2.2.4. Error Conditions . . . . . . . . . . . . . . . . 53 130 8.2.3. DeleteSD . . . . . . . . . . . . . . . . . . . . . . 53 131 8.2.3.1. DeleteSDRequest Message . . . . . . . . . . . . . 54 132 8.2.3.2. Request processing requirements at a TEE . . . . 55 133 8.2.3.3. DeleteSDResponse Message . . . . . . . . . . . . 57 134 8.2.3.4. Error Conditions . . . . . . . . . . . . . . . . 58 135 8.3. Trusted Application Management . . . . . . . . . . . . . 58 136 8.3.1. InstallTA . . . . . . . . . . . . . . . . . . . . . . 59 137 8.3.1.1. InstallTARequest Message . . . . . . . . . . . . 60 138 8.3.1.2. InstallTAResponse Message . . . . . . . . . . . . 62 139 8.3.1.3. Error Conditions . . . . . . . . . . . . . . . . 63 140 8.3.2. UpdateTA . . . . . . . . . . . . . . . . . . . . . . 64 141 8.3.2.1. UpdateTARequest Message . . . . . . . . . . . . . 65 142 8.3.2.2. UpdateTAResponse Message . . . . . . . . . . . . 67 143 8.3.2.3. Error Conditions . . . . . . . . . . . . . . . . 68 144 8.3.3. DeleteTA . . . . . . . . . . . . . . . . . . . . . . 69 145 8.3.3.1. DeleteTARequest Message . . . . . . . . . . . . . 69 146 8.3.3.2. Request processing requirements at a TEE . . . . 70 147 8.3.3.3. DeleteTAResponse Message . . . . . . . . . . . . 71 148 8.3.3.4. Error Conditions . . . . . . . . . . . . . . . . 72 149 9. Response Messages a TSM May Expect . . . . . . . . . . . . . 73 150 10. Attestation Implementation Consideration . . . . . . . . . . 73 151 10.1. OTrP Secure Boot Module . . . . . . . . . . . . . . . . 74 152 10.1.1. Attestation signer . . . . . . . . . . . . . . . . . 74 153 10.1.2. SBM initial requirements . . . . . . . . . . . . . . 74 154 10.2. TEE Loading . . . . . . . . . . . . . . . . . . . . . . 74 155 10.3. Attestation Hierarchy . . . . . . . . . . . . . . . . . 75 156 10.3.1. Attestation hierarchy establishment: manufacture . . 75 157 10.3.2. Attestation hierarchy establishment: device boot . . 75 158 10.3.3. Attestation hierarchy establishment: TSM . . . . . . 76 159 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 76 160 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 76 161 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 162 13.1. Error Code List . . . . . . . . . . . . . . . . . . . . 77 163 14. Security Consideration . . . . . . . . . . . . . . . . . . . 78 164 14.1. Cryptographic strength implementation . . . . . . . . . 78 165 14.2. Message Security . . . . . . . . . . . . . . . . . . . . 79 166 14.3. TEE Attestation . . . . . . . . . . . . . . . . . . . . 79 167 14.4. TA Protection . . . . . . . . . . . . . . . . . . . . . 79 168 14.5. TA Personalization data . . . . . . . . . . . . . . . . 80 169 14.6. TA trust check at TEE . . . . . . . . . . . . . . . . . 80 170 14.7. One TA Multiple SP Case . . . . . . . . . . . . . . . . 81 171 14.8. OTrP Agent Trust Model . . . . . . . . . . . . . . . . . 81 172 14.9. OCSP Stapling Data for TSM signed messages . . . . . . . 81 173 14.10. Data protection at TSM and TEE . . . . . . . . . . . . . 81 174 14.11. Privacy consideration . . . . . . . . . . . . . . . . . 81 175 14.12. Threat mitigation . . . . . . . . . . . . . . . . . . . 82 176 14.13. Compromised CA . . . . . . . . . . . . . . . . . . . . . 82 177 14.14. Compromised TSM . . . . . . . . . . . . . . . . . . . . 83 178 14.15. Certificate renewal . . . . . . . . . . . . . . . . . . 83 179 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 83 180 15.1. Normative References . . . . . . . . . . . . . . . . . . 83 181 15.2. Informative References . . . . . . . . . . . . . . . . . 84 182 Appendix A. Sample Messages . . . . . . . . . . . . . . . . . . 84 183 A.1. Sample Security Domain Management Messages . . . . . . . 84 184 A.1.1. Sample GetDeviceState . . . . . . . . . . . . . . . . 84 185 A.1.1.1. Sample GetDeviceStateRequest . . . . . . . . . . 84 186 A.1.1.2. Sample GetDeviceStateResponse . . . . . . . . . . 85 187 A.1.2. Sample CreateSD . . . . . . . . . . . . . . . . . . . 88 188 A.1.2.1. Sample CreateSDRequest . . . . . . . . . . . . . 88 189 A.1.2.2. Sample CreateSDResponse . . . . . . . . . . . . . 90 190 A.1.3. Sample UpdateSD . . . . . . . . . . . . . . . . . . . 92 191 A.1.3.1. Sample UpdateSDRequest . . . . . . . . . . . . . 92 192 A.1.3.2. Sample UpdateSDResponse . . . . . . . . . . . . . 94 193 A.1.4. Sample DeleteSD . . . . . . . . . . . . . . . . . . . 94 194 A.1.4.1. Sample DeleteSDRequest . . . . . . . . . . . . . 94 195 A.1.4.2. Sample DeleteSDResponse . . . . . . . . . . . . . 96 196 A.2. Sample TA Management Messages . . . . . . . . . . . . . . 97 197 A.2.1. Sample InstallTA . . . . . . . . . . . . . . . . . . 97 198 A.2.1.1. Sample InstallTARequest . . . . . . . . . . . . . 97 199 A.2.1.2. Sample InstallTAResponse . . . . . . . . . . . . 98 200 A.2.2. Sample UpdateTA . . . . . . . . . . . . . . . . . . . 100 201 A.2.2.1. Sample UpdateTARequest . . . . . . . . . . . . . 100 202 A.2.2.2. Sample UpdateTAResponse . . . . . . . . . . . . . 101 203 A.2.3. Sample DeleteTA . . . . . . . . . . . . . . . . . . . 104 204 A.2.3.1. Sample DeleteTARequest . . . . . . . . . . . . . 104 205 A.2.3.2. Sample DeleteTAResponse . . . . . . . . . . . . . 106 206 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 108 208 1. Introduction 210 The Trust Execution Environment (TEE) concept has been designed and 211 used to increase security by separating regular operating systems, 212 also referred as Rich Execution Environment (REE), from security- 213 sensitive applications. In an TEE ecosystem, a Trust Service Manager 214 (TSM) is used to authorize manage keys and the Trusted Applications 215 (TA) that run in a device. Different device vendors may use 216 different TEE implementations. Different application providers may 217 use different TSM providers. There arises a need of an open 218 interoperable protocol that allows trustworthy TSM to manage security 219 domains and contents running in different Trust Execution Environment 220 (TEE) of various devices. 222 The Open Trust Protocol (OTrP) defines a protocol between a TSM and a 223 TEE and relies on IETF-defined end-to-end security mechanisms, namely 224 JSON Web Encryption (JWE), JSON Web Signature (JWS), and JSON Web Key 225 (JWK). 227 Some deployed TEE and TSM implementations use symmetric key 228 cryptography as the underlying security foundation and rely on a 229 centralized database that holds these keys for every device that uses 230 a TEE. This specification follows a different design approach and 231 makes use of public key cryptography at the expensive of slower 232 performance but improved security. 234 This specification assumes that a device that utilizes this 235 specification is equipped with a TEE and is pre-provisioned with a 236 device-unique public/private key pair, which is securely stored. 237 This key pair is referred as the 'root of trust'. A Service Provider 238 (SP) uses such a device to run Trusted Applications (TA). 240 A security domain is defined as the TEE representation of a service 241 provider and is a logical space that contains the service provider's 242 trusted applications. Each security domain requires the management 243 operations of trusted applications (TAs) in the form of installation, 244 update and deletion. 246 The protocol builds on the following properties of the system: 248 1. The SP needs to determine security-relevant information of a 249 device before provisioning information to a TEE. Examples 250 include the verification of the root of trust, the type of 251 firmware installed, and the type of TEE included in a device. 253 2. A TEE in a device needs to determine whether a SP or the TSM is 254 authorized to manage applications in the TEE. 256 3. Secure Boot must be able to ensure a TEE is genuine. 258 This specification defines message payloads exchanged between devices 259 and a TSM but does not mandate a specific transport. 261 2. Requirements Language 263 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 264 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 265 document are to be interpreted as described in RFC 2119 [RFC2119]. 267 3. Terminology 269 3.1. Definitions 271 The definitions provided below are defined as used in this document. 272 The same terms may be defined differently in other documents. 274 Client Application: An application running on a rich OS, such as an 275 Android, Windows, or iOS application, provided by a SP. 277 Device: A physical piece of hardware that hosts symmetric key 278 cryptographic modules 280 OTrP Agent: An application running in the rich OS allowing 281 communication with the TSM and the TEE. 283 Rich Application: Alternative name of "Client Application". In this 284 document we may use these two terms interchangably. 286 Rich Execution Environment (REE) An environment that is provided and 287 governed by a rich OS, potentially in conjunction with other 288 supporting operating systems and hypervisors; it is outside of 289 the TEE. This environment and applications running on it are 290 considered un-trusted. 292 Secure Boot Module (SBM): A firmware in a device that delivers 293 secure boot functionality. It is also referred as Trusted 294 Firmware (TFW) in this document. 296 Trust Anchor: A root certificate that a module trusts. It is 297 usually embedded in one validating module, and used to validate 298 the trust of a remote entity's certificate. 300 Trusted Application (TA): Application that runs in TEE. 302 Trusted Execution Environment (TEE): An execution environment that 303 runs alongside but isolated from an REE. A TEE has security 304 capabilities and meets certain security-related requirements: It 305 protects TEE assets from general software attacks, defines rigid 306 safeguards as to data and functions that a program can access, 307 and resists a set of defined threats. There are multiple 308 technologies that can be used to implement a TEE, and the level 309 of security achieved varies accordingly. 311 3.2. Abbreviations 313 CA Certificate Authority 315 OTrP Open Trust Protocol 317 REE Rich Execution Environment 318 SD Security Domain 320 SP Service Provider 322 SBM Secure Boot Module 324 TA Trusted Application 326 TEE Trusted Execution Environment 328 TFW Trusted Firmware 330 TSM Trusted Service Manager 332 4. OTrP Entities and Trust Model 334 4.1. System Components 336 There are the following main components in this OTrP system. 338 TSM - The TSM is responsible for originating and coordinating 339 lifecycle management activity on a particular TEE. 341 A Trust Service Manager (TSM) is at the core to the protocol that 342 manages device trust check on behalf of service providers for the 343 ecosystem scalability. In addition to its device trust 344 management for a service provider, the TSM provides Security 345 Domain management and TA management in a device, in particularly, 346 over-the-air update to keep Trusted Application up to date and 347 clean up when a version should be removed. 349 Certificate Authority (CA) - Mutual trust between a device and a 350 TSM as well as a Service Provider is based on certificates. A 351 device embeds a list of root certificates, called Trust Anchors, 352 from trusted Certificate Authorities that a TSM will be validated 353 against. A TSM will remotely attest a device by checking whether 354 a device comes with a certificate from a trusted CA. 356 TEE - The TEE resides in the device chip security zone and is 357 responsible for protecting applications from attack, enabling the 358 application to perform secure operations 360 REE - The REE, usually called device OS such as Android OS in a 361 phone device, is responsible for enabling off device 362 communications to be established between the TEE and TSM. OTrP 363 must not require the device OS to be secure. 365 OTrP Agent - An application in the REE that can relay messages 366 between a Client Application and TEE. 368 Secure Boot - Secure boot (for the purposes of OTrP) must enable 369 authenticity checking of TEEs by the TSM. 371 The OTrP establishes appropriate trust anchors to enable TEE and TSMs 372 to communicate in a trusted way when performing lifecycle management 373 transactions. The main trust relationships between the components 374 are the following. 376 1. TSM must be able to ensure a TEE is genuine 378 2. TEE must be able to ensure a TSM is genuine 380 3. Secure Boot must be able to ensure a TEE is genuine 382 4.2. Trusted Anchors in TEE 384 The TEE in each device comes with a trust store that contains a 385 whitelist of TSM's root CA certificates, which are called Trust 386 Anchors. A TSM will be trusted to manage Security Domains and TAs in 387 a device only if its certificate is chained to one of the root CA 388 certificates in this trust store. 390 Such a list is typically embedded in TEE of a device, and the list 391 update is enabled and handled by device OEM provider. 393 4.3. Trusted Anchors in TSM 395 The Trust Anchor set in a TSM consists of a list of Certificate 396 Authority certificates that signs various device TEE certificates. A 397 TSM decides what TEE and TFW it will trust. 399 4.4. Keys and Cerificate Types 401 OTrP Protocol leverages the following list of trust anchors and 402 identities in generating signed and encrypted command messages that 403 are exchanged between a device with TEE and a TSM. With these 404 security artifacts, OTrP Messages are able to deliver end-to-end 405 security without relying on any transport security. 407 TBD - remove table to use hang list after further edit review. 409 +-------------+----------+--------+-------------------+-------------+ 410 | Key Entity | Location | Issuer | Trust Implication | Cardinality | 411 | Name | | | | | 412 +-------------+----------+--------+-------------------+-------------+ 413 | 1. TFW | Device | OEM CA | A white list of | 1 per | 414 | keypair and | secure | | FW root CA | device | 415 | Certificate | storage | | trusted by TSMs | | 416 | | | | | | 417 | 2. TEE | Device | TEE CA | A white list of | 1 per | 418 | keypair and | TEE | under | TEE root CA | device | 419 | Certificate | | a root | trusted by TSMs | | 420 | | | CA | | | 421 | | | | | | 422 | 3. TSM | TSM | TSM CA | A white list of | 1 or | 423 | keypair and | provider | under | TSM root CA | multiple | 424 | Certificate | | a root | embedded in TEE | can be used | 425 | | | CA | | by a TSM | 426 | | | | | | 427 | 4. SP | SP | SP | TSM manages SP. | 1 or | 428 | keypair and | | signer | TA trust is | multiple | 429 | Certificate | | CA | delegated to TSM. | can be used | 430 | | | | TEE trusts TSM to | by a TSM | 431 | | | | ensure that a TA | | 432 | | | | is trustworthy. | | 433 +-------------+----------+--------+-------------------+-------------+ 435 Table 1: Key and Certificate Types 437 ******* TBD choose table or list view later ******* 439 1. TFW keypair and Certificate: A key pair and certificate for 440 evidence of secure boot and trustworthy firmware in a device. 442 Location: Device secure storage 444 Supported Key Type: RSA and ECC 446 Issuer: OEM CA 448 Trust Implication: A white list of FW root CA trusted by TSMs 450 Cardinality: One per device 452 2. TEE keypair and Certificate: It is used for device attestation 453 to remote TSM and SP. A TEE certificate is expected to be long 454 lived that doesn't need to renew. 456 This key pair is burned into the device at device manufacturer. 457 The key pair and its certificate are valid for the expected 458 lifetime of the device. 460 Location: Device TEE 462 Supported Key Type: RSA and ECC 464 Issuer: TEE CA that chains to a root CA 466 Trust Implication: A white list of TEE root CA trusted by TSMs 468 Cardinality: One per device 470 3. TSM keypair and Certificate: A TSM provider acquires a 471 certificate from a CA that a TEE trusts. 473 Location: TSM provider 475 Supported Key Type: RSA and ECC. 477 Supported Key Size: RSA 2048-bit, ECC P-256 and P-384. 479 Issuer: TSM CA that chains to a root CA 481 Trust Implication: A white list of TSM root CA embedded in TEE 483 Cardinality: One or multiple can be used by a TSM 485 4. SP keypair and Certificate: A SP uses its own key pair and 486 certificate to sign a TA. 488 Location: SP 490 Supported Key Type: RSA and ECC 492 Supported Key Size: RSA 2048-bit, ECC P-256 and P-384 494 Issuer: SP signer CA that chains to a root CA 496 Trust Implication: TSM manages SP. TA trust is delegated to 497 TSM. TEE trusts TSM to ensure that a TA is trustworthy. 499 Cardinality: One or multiple can be used by a SP 501 5. Protocol Scope and Entity Relations 503 This document specifies the minimally required interoperable 504 artifacts to establish mutual trust between a TEE and TSM. The 505 protocol provides specifications for the following three entities: 507 1. Key and certificate types required for device firmware, TEE, TA, 508 SP, and TSM 510 2. Data message formats that should be exchanged between a TEE in a 511 device and a TSM 513 3. An OTrP Agent application in the REE that can relay messages 514 between a Client Application and TEE 516 Figure 1: Protocol Scope and Entity Relationship 518 PKI CA --CA CA-- 519 | | | 520 | | | 521 | | | 522 Device | | ----OTrP Agent --- Rich App --- | 523 SW | | | | | 524 | | | | | 525 | | | | | 526 OTrP | -- TEE TSM------- 527 | 528 | 529 FW 531 Figure 2: OTrP System Diagram 532 ---OTrP Message Protocol-- 533 | | 534 | | 535 -------------------- --------------- ---------- 536 | REE | TEE | | TSM | | SP | 537 | --- | --- | | --- | | -- | 538 | | | | | | | 539 | Client | SD (TAs)| | SD / TA | | TA | 540 | Apps | | | Mgmt | | | 541 | | | | | | | | 542 | | | | | | | | 543 | OTrP | Trusted | | Trusted | | | 544 | Agent | CAs | | FW, TEE CAs | | | 545 | | | | | | | 546 | |TEE Key/ | | TSM Key/ | |SP Key/ | 547 | | Cert | | Cert | | Cert | 548 | | FW Key/ | | | | | 549 | | Cert | | | | | 550 ------------------ --------------- ---------- 551 | | | 552 | | | 553 ----------------------------------------- 554 | 555 | 556 -------------- 557 | CA | 558 -------------- 560 In the previous diagram, different Certificate Authorities can be 561 used respectively for different types of certificates. OTrP Messages 562 are always signed, where the signer keys is the message creator's key 563 pair such as a FW key pair, TEE key pair or TSM key pair. 565 The main OTrP Protocol component is the set of standard JSON messages 566 created by TSM to deliver device SD and TA management commands to a 567 device, and device attestation and response messages created by TEE 568 to respond to TSM OTrP Messages. 570 The communication method of OTrP Messages between a TSM and TEE in a 571 device is left to TSM providers for maximal interoperability. A TSM 572 can work with its SP and Client Applications how it gets OTrP 573 Messages from a TSM. When a Client Application has had an OTrP 574 Message from its TSM, it is imperative to have an interoperable 575 interface to communicate with various TEE types. This is the OTrP 576 Agent interface that serves this purpose. The OTrP Agent doesn't 577 need to know the actual content of OTrP Messages except for the TEE 578 routing information. 580 5.1. A Sample Device Setup Flow 582 TBD 584 5.2. Derived Keys in the Protocol 586 The protocol generates the following two key pairs in run time to 587 assist message communication and anonymous verification between TSM 588 and TEE. 590 1. TEE Anonymous Key (TEE AIK): one derived key pair per TEE in a 591 device 593 The purpose of the key pair is to sign data by a TEE without using 594 its TEE device key for anonymous attestation to a Client Application. 595 This key is generated in the first GetDeviceState query. The public 596 key of the key pair is returned to the caller Client Application for 597 future TEE returned data validation. 599 2. TEE SP AIK: one derived key per SP in a device 601 The purpose of this key pair is for a TSM to encrypt TA binary data 602 when it sends a TA to a device for installation. This key is 603 generated in the first SD creation for a SP. It is deleted when all 604 SDs are removed for a SP in a device. 606 With the presence of a TEE SP AIK, it isn't necessary to have a 607 shared SP independent TEE AIK. For the initial release, this 608 specification will not use TEE AIK. 610 5.3. Security Domain Hierarchy and Ownership 612 The primary job of a TSM is to help a SP to manage its trusted 613 applications. A TA is typically installed in a SD. A SD is commonly 614 created for a SP. 616 When a SP delegates its SD and TA management to a TSM, a SD is 617 created on behalf of a TSM in a TEE and the owner of the SD is 618 assigned to the TSM. A SD may be associated with a SP but the TSM 619 has full privilege to manage the SD for the SP. 621 Each SD for a SP is associated with only one TSM. When a SP changes 622 TSM, a new SP SD must be created to associate with the new TSM. TEE 623 will maintain a registry of TSM ID and SP SD ID mapping. 625 From a SD ownership perspective SD tree is flat and there is only one 626 level. A SD is associated with its owner. It is up to TEE's 627 implementation how it maintains SD binding information for TSM and 628 different SPs under the same TSM. 630 It is an important decision in this protocol specification that a TEE 631 doesn't need to know whether a TSM is authorized to manage SD for a 632 SP. This authorization is implicitly triggered by a SP Client 633 Application, which instructs what TSM it wants to use. A SD is 634 always associated with a TSM in addition to its SP ID. A rogue TSM 635 isn't able to do anything on an unauthorized SP's SD managed by 636 another TSM. 638 Since a TSM may support multiple SPs, sharing the same SD name for 639 different SP creates a dependency in deleting a SD. A SD can be 640 deleted only after all TAs associated with this SD is deleted. A SP 641 cannot delete a Security Domain on its own with a TSM if a TSM 642 decides to introduce such sharing. There are cases where multiple 643 virtual SPs belong to the same organization, and a TSM chooses to use 644 the same SD name for those SPs. This is totally up to the TSM 645 implementation and out of scope of this specification. 647 5.4. SD Owner Identification and TSM Certificate Requirements 649 There is a need of cryptographically binding proof about the owner of 650 a SD in device. When a SD is created on behalf of a TSM, a future 651 request from the TSM must present itself as a way that the TEE can 652 verify it is the true owner. The certificate itself cannot reliably 653 used as the owner because TSM may change its certificate. 655 To this end, each TSM will be associated with a trusted identifier 656 defined as an attribute in the TSM certificate. This field is kept 657 the same when the TSM renew its certificates. A TSM CA is 658 responsible to vet the requested TSM attribute value. 660 This identifier value must not collide among different TSM providers, 661 and one TSM shouldn't be able to claim the identifier used by another 662 TSM provider. 664 The certificate extension name to carry the identifier can initially 665 use SubjectAltName:registeredID. A dedicated new extension name may 666 be registered later. 668 One common choice of the identifier value is the TSM's service URL. 669 A CA can verify the domain ownership of the URL with the TSM in the 670 certificate enrollment process. 672 TEE can assign this certificate attribute value as the TSM owner ID 673 for the SDs that are created for the TSM. 675 An alternative way to represent a SD ownership by a TSM is to have a 676 unique secret key upon SD creation such that only the creator TSM is 677 able to produce a Proof-of-Possession (POP) data with the secret. 679 5.5. Service Provider Container 681 A sample Security Domain hierarchy for the TEE is shown below. 683 TBD diagram 685 The OTrP assumes that a SP managed by TSM1 cannot be managed by TSM2. 686 Explicit permission grant should happen. SP can authorize TSM. 688 6. OTrP Agent 690 OTrP Agent is an Rich Application or SDK that facilitates 691 communication between a TSM and TEE. It also provides interfaces for 692 TSM SDK or Client Applications to query and trigger TA installation 693 that the application needs to use. 695 This interface for Client Applications may be commonly an Android 696 service call. A Client Application interacts with a TSM, and turns 697 around to pass messages received from TSM to OTrP Agent. 699 In all cases, a Client Application needs to be able to identify an 700 OTrP Agent that it can use. 702 6.1. Role of OTrP Agent 704 OTrP Agent is responsible to communicate with TEE. It takes request 705 messages from an application. The input data is mostly from a TSM 706 that an application communicates. An application may also directly 707 call OTrP Agent for some TA query functions. 709 OTrP Agent may internally process a request from TSM. At least, it 710 needs to know where to route a message, e.g. TEE instance. It 711 doesn't need to process or verify message content. 713 OTrP Agent returns TEE / TFW generated response messages to the 714 caller. OTrP Agent isn't expected to handle any network connection 715 with an application or TSM. 717 OTrP Agent only needs to return an OTrP Agent error message if TEE 718 isn't reachable for some reason. 720 6.2. OTrP Agent and Global Platform TEE Client API 722 A Client Application will rely on GP TEE API for TA communication. 723 OTrP may use GP TEE Client API but it is internal to OTrP 724 implementation that converts given messages from TSM. 726 6.3. OTrP Agent Implementation Consideration 728 A Provider should consider methods of distribution, scope and 729 concurrency on device and runtime options when implementing an OTrP 730 Agent. Several non-exhaustive options are discussed below. 731 Providers are encouraged to take advantage of the latest 732 communication and platform capabilities to offer the best user 733 experience. 735 6.3.1. OTrP Agent Distribution 737 OTrP Agent installation is commonly carried out at OEM time. A user 738 can dynamically download and install an OTrP Agent on-demand. 740 It is important to ensure a legitimate OTrP Agent is installed and 741 used. If an OTrP Agent is compromised it may send rogue messages to 742 TSM and TEE and introduce additional risks. 744 6.3.2. Number of OTrP Agent 746 We anticipate only one shared OTrP Agent instance in a device. The 747 device's TEE vendor will most probably supply one OTrP Agent. 748 Potentially we expect some open source. 750 With one shared OTrP Agent, the OTrP Agent provider is responsible to 751 allow multiple TSMs and TEE providers to achieve interoperability. 752 With a standard OTrP Agent interface, TSM can implement its own SDK 753 for its SP Client Applications to work with this OTrP Agent. 755 Multiple independent OTrP Agent providers can be used as long as they 756 have standard interface to a Client Application or TSM SDK. Only one 757 OTrP Agent is expected in a device. 759 OTrP Protocol MUST specify a standard way for applications to lookup 760 the active OTrP Agent instance in a device. 762 TSM providers are generally expected to provide SDK for SP 763 applications to interact with OTrP Agent for the TSM and TEE 764 interaction. 766 6.3.3. OTrP Android Service Option 768 OTrP Agent can be a bound service in Android with a service 769 registration ID that a Client Application can use. This option 770 allows a Client Application not to depend on any OTrP Agent SDK or 771 provider. 773 An OTrP Agent is responsible to detect and work with more than one 774 TEE if a device has more than one. In this version, there is only 775 one active TEE such that an OTrP Agent only needs to handle the 776 active TEE. 778 6.4. OTrP Agent API for Client Applications 780 A Client Application may commonly used to include target TSM contact 781 information for the Trusted Applications it need to use. The 782 application will rely on some TSM provided functions to communicate 783 with its TSM. 785 OTrP Agent APIs are defined below. An OTrP Agent in the form of an 786 Android bound service can take this to be the functionality it 787 provides via service call. 789 If a failure is occured during calling API, an error message 790 described in "Common Errors" section (Section 7.6) will be returned. 792 interface IOTrPAgentService { 793 String processMessage(String tsmInMsg) throws OTrPAgentException; 794 String getTAInformation(String spid, String taid) throws OTrPAgentException; 795 } 797 public class OTrPAgentException extends Throwable { 798 private int errCode; 799 } 801 6.4.1. API processMessage 803 String processMessage(String tsmInMsg) throws OTrPAgentException; 805 Description 807 A Client Application will use this method of the OTrP Agent in a 808 device to pass OTrP messages from a TSM. The method is 809 responsible to interact with a TEE and forward the input message 810 to the TEE. It also returns TEE generated response message back 811 to the Client Application. 813 Input 814 tsmInMsg - OTrP message generated in a TSM that is passed to this 815 method from a Client Application. 817 Output 819 A TEE generated OTrP message or an error message created by OTrP 820 Agent when it fails to interact with a TEE. This message is 821 forwarded to TSM. 823 6.4.2. API getTAInformation 825 String getTAInformation(String spid, String taid) throws OTrPAgentException; 827 Description 829 A Client Application calls this method to query a TA's 830 information. This method carries out locally by OTrP Agent 831 without relying on a TSM if it has had the TEE SP AIK. 833 Input 835 spid - SP identifier of the TA 837 taid - the identifier of the TA 839 Output 841 The API returns TA signer and TSM signer certificate along with 842 other metadata information about a TA. 844 The output is a JSON message that is generated by the TEE. It 845 contains the following information: 847 * TSMID 849 * SP ID 851 * TA signer certificate 853 * TSM certificate 855 The message is signed with TEE SP AIK private key. 857 The Client Application is expected to consume the response as 858 follows. 860 The Client Application gets signed TA metadata, in particularly, 861 the TA signer certificate. It is able to verify that the result 862 is from device by checking signer against TEE SP AIK public key it 863 gets in some earlier interaction with TSM. 865 If this is a new Client Application in the device that hasn't had 866 TEE SP AIK public key for the response verification, the 867 application can contact TSM first to do GetDeviceState, and TSM 868 will return TEE SP AIK public key to the app for this operation to 869 proceed. 871 JSON Message 873 { 874 "TAInformationTBS": { 875 "taid": "", 876 "tsmid": "", 878 "spid": "", 879 "signercert": "", 881 "signercacerts": [ // the full list of CA certificate chain 882 // including the root CA 883 "cacert": "" 885 ], 886 "tsmcert": "", 888 "tsmcacerts": [ // the full list of CA certificate chain 889 // including the root CA 890 "cacert":"" 892 ] 893 } 894 } 896 { 897 "TAInformation": { 898 "payload": "", 900 "protected": "", 901 "header": { 902 "signer": {""} 904 }, 905 "signature": "" 907 } 908 } 910 A sample JWK public key representation refers to an example in RFC 911 7517 [RFC7517] . 913 6.5. Sample End-to-End Client Application Flow 915 6.5.1. Case 1: A new Client App uses a TA 917 1. During the Client App installation time, the Client App calls 918 TSM to initialize device preparation 919 A. The Client Application knows it wants to use a TA1 but the 920 application doesn'tknow whether TA1 has been installed or 921 not. It can use GP TEE Client API to check the existence of 922 TA1 first. If it doesn't exist, it will contact TSM to 923 initiate the TA1 installation. Note that TA1 could have 924 been installed that is triggered by other Client 925 Applications of the same service provider in the same 926 device. 928 B. The Client Application sends TSM the TA list that it depends 929 on. The TSM will query a device for the Security Domains 930 and TAs that have been installed, and instructs the device 931 to install any dependent TAs that have not been installed. 933 C. In general, TSM has the latest information of TA list and 934 their status in a device because all operations are 935 instructed by TSM. TSM has such visibility because all 936 Security Domain deletion and TA deletion are managed by TSM; 937 the TSM could have stored the state when a TA is installed, 938 updated and deleted. There is possibility that an update 939 command is carried out inside TEE but a response is never 940 received in TSM. There is also possibility that some manual 941 local reset is done in a device that the TSM isn't aware of 942 the changes. 944 2. TSM generates message: GetDeviceStateRequest 946 3. The Client Application passes the JSON message 947 GetDeviceStateRequest to OTrP Agent API processMessage. The 948 communication between a Client Application and OTrP Agent is up 949 to the implementation of OTrP Agent. 951 4. OTrP Agent routes the message to the active TEE. Multiple TEE 952 case: it is up to OTrP Agent to figure this out. This 953 specification limits the support to only one active TEE, which 954 is the typical case today. 956 5. The target active TEE processes the received OTrP message, 957 returns a JSON message GetDeviceStateResponse 959 6. The OTrP Agent passes the GetDeviceStateResponse to the Client 960 App 962 7. The Client Application sends GetDeviceStateResponse to TSM 964 8. TSM processes GetDeviceStateResponse 965 A. Extract TEEspaik for the SP, signs TEEspaik with TSM signer 966 key 968 B. Examine SD list and TA list 970 9. TSM continues to carry out other actions basing on the need. 971 The next call could be instructing the device to install a 972 dependent TA. 974 A. Assume a dependent TA isn't in the device yet, the TSM may 975 do the following: 977 B. 979 Create a SD to install the TA by sending a message 980 CreateSDRequest. The message is sent back to the Client 981 Application, and then OTrP Agent and TEE to process. 983 Install a TA with a message InstallTARequest. 985 C. If a Client Application depends on multiple TAs, the Client 986 Application should expect multiple round trips of the TA 987 installation message exchanges. 989 10. At the last TSM and TEE operation, TSM returns the signed TEE SP 990 AIK public key to the application 992 11. The Client Application shall store the TEEspaik for future 993 loaded TA trust check purpose. 995 12. Assume TSM finds that this is a fresh device that doesn't have 996 any SD for the SP yet. TSM may move on to create a SD for the 997 SP next. 999 13. During Client Application installation, the application checks 1000 whether required Trusted Applications are already installed, 1001 which may have been provided by TEE. If needed, it will contact 1002 its TSM service to determine whether the device is ready or 1003 install TA list that this application needs. 1005 6.5.2. Case 2: A previously installed Client Application calls a TA 1007 1. The Client Application checks the device readiness: (a) whether 1008 it has a TEE; (b) whether it has TA that it depends. It may 1009 happen that TSM has removed TA this application depends on. 1011 2. The Client App calls OTrP Agent method "GetTAInformation" 1012 3. OTrP Agent queries the TEE to get TA information. If the given 1013 TA doesn't exist, an error is returned 1015 4. The Client App parses the TAInformation message. 1017 5. If the TA doesn't exist, the Client App calls its TSM to install 1018 the TA. If the TA exists, the Client App proceeds to call the 1019 TA. 1021 7. OTrP Messages 1023 The main OTrP Protocol component is the set of standard JSON messages 1024 created by TSM to deliver device SD and TA management commands to a 1025 device, and device attestation and response messages created by TEE 1026 to respond to TSM OTrP Messages. 1028 An OTrP Message is designed to provide end-to-end security. It 1029 always signed by its creator. In addition, an OTrP Message is 1030 typically encrypted such that only the targeted device TEE or TSM 1031 provider is able to decrypt and view the actual content. 1033 7.1. Message Format 1035 OTrP Messages use JSON format for JSON's simple readability and 1036 moderate data size in comparison with alternative TLV and XML 1037 formats. 1039 JSON Message security has developed JSON Web Signing and JSON Web 1040 Encryption standard in the IETF Workgroup JOSE, see [JWS] and [JWE]. 1041 The OTrP Messages in this protocol will leverage the basic JWS and 1042 JWE to handle JSON signing and encryption. 1044 7.2. Message Naming Convention 1046 For each TSM command "xyz"", OTrP Protocol use the following naming 1047 convention to represent its raw message content and complete request 1048 and response messages: 1050 +-----------------------+----------------+---------------------+ 1051 | Purpose | Message Name | Example | 1052 +-----------------------+----------------+---------------------+ 1053 | Request to be signed | xyzTBSRequest | CreateSDTBSRequest | 1054 | | | | 1055 | Request message | xyzRequest | CreateSDRequest | 1056 | | | | 1057 | Response to be signed | xyzTBSResponse | CreateSDTBSResponse | 1058 | | | | 1059 | Response message | xyzResponse | CreateSDResponse | 1060 +-----------------------+----------------+---------------------+ 1062 7.3. Request and Response Message Template 1064 An OTrP Request message uses the following format: 1066 { 1067 "TBSRequest": { 1068 1069 } 1070 } 1072 A corresponding OTrP Response message will be as follows. 1074 { 1075 "TBSResponse": { 1076 1077 } 1078 } 1080 7.4. Signed Request and Response Message Structure 1082 A signed request message will generally include only one signature, 1083 and uses the flattened JWS JSON Serialization Syntax, see 1084 Section 7.2.2 in RFC7515 [RFC7515] . 1086 A general JWS object looks like the following. 1088 { 1089 "payload": "", 1090 "protected":"", 1091 "header": { 1092 , 1093 }, 1094 "signature":"" 1095 } 1096 OTrP signed messages only requires the signing algorithm as the 1097 mandate header in the property "protected". The "non-integrity- 1098 protected header contents" is optional. 1100 OTrP signed message will be given an explicit Request or Response 1101 property name. In other words, a signed Request or Response uses the 1102 following template. 1104 A general JWS object looks like the following. 1106 { 1107 "[Request | Response]": { 1108 TBS[Request | Response] 1109 } 1110 } 1112 With the standard JWS message format, a signed OTrP Message looks 1113 like the following. 1115 { 1116 "[Request | Response]": { 1117 "payload": "TBS[Request | Response]>", 1118 "protected":"", 1119 "header": , 1120 "signature":"" 1121 } 1122 } 1124 The top element " [Signed][Request | Response]" cannot be fully 1125 trusted to match the content because it doesn't participate the 1126 signature generation. However, a recipient can always match it with 1127 the value associated with the property "payload". It purely serves 1128 to provide a quick reference for reading and method invocation. 1130 Furthermore, most properties in an unsigned OTrP messages are 1131 encrypted to provide end-to-end confidentiality. Only OTrP Message 1132 that isn't encrypted is the initial device query message that asks 1133 for the device state information. 1135 Thus a typical OTrP Message consists of an encrypted and then signed 1136 JSON message. Some transaction data such as transaction ID and TEE 1137 information may need to be exposed to OTrP Agent for routing purpose. 1138 Such information is excluded from JSON encryption. The device's 1139 signer certificate itself is encrypted. The overall final message is 1140 a standard signed JSON message. 1142 As required by JSW/JWE, those JWE and JWS related elements will be 1143 BASE64URL encoded. Other binary data elements specific to the OTrP 1144 specification are BASE64 encoded. This specification will identify 1145 elements that should be BASE64 and those elements that are to be 1146 BASE64URL encoded. 1148 7.4.1. Identifying signing and Encryption keys for JWS/JWE messaging 1150 JWS and JWE messaging allow various options for identifying the 1151 signing and encryption keys, for example, it allows optional elements 1152 including "x5c", "x5t" and "kid" in the header to cover various 1153 possibilities. 1155 In order to protect privacy, it is important that the device's 1156 certificate is released only to a trusted TSM, and that it is 1157 encrypted. The TSM will need to know the device certificate, but 1158 untrusted parties must not be able to get the device certificate. 1159 All OTrP messaging conversations between a TSM and device begin with 1160 GetDeviceStateRequest / GetDeviceStateResponse. These messages have 1161 elements built into them to exchange signing certificates, described 1162 in the "Detailed Message Specification" section. Any subsequent 1163 messages in the conversation that follow on from this are implicitly 1164 using the same certificates for signing/encryption, and as a result 1165 the certificates or references to the certificates/signer may not be 1166 exchanged in those subsequent messages. 1168 In other words, the signing key identifier in the use of JWS and JWE 1169 here may be absent in the subsequent messages after the initial 1170 GetDeviceState query. 1172 This has implication on the TEE and TSM implementation: they have to 1173 cache the signer certificates for the subsequent message signature 1174 validation in the session. It may be easier for a TSM service to 1175 cache transaction session information but not so for a TEE in a 1176 device. A TSM should check a device's capability to decide whether 1177 it should include its TSM signer certificate and OCSP data in each 1178 subsequent request message. The device's caching capability is 1179 reported in GetDeviceStateResponse. 1181 7.5. JSON Signing and Encryption Algorithms 1183 The OTrP JSON signing algorithm shall use SHA256 or a stronger hash 1184 method with respective key type. JSON Web Algorithm RS256 or ES256 1185 shall be used respectively for RSA with SHA256 and ECDSA with SHA256. 1186 If RSA with SHA256 is used, the JSON web algorithm representation is 1187 as follows. 1189 {"alg":"RS256"} 1191 The (BASE64URL encoded) "protected" header property in a signed 1192 message looks like the following: 1194 "protected":"eyJhbGciOiJSUzI1NiJ9" 1196 If ECSDA with P-256 curve and SHA256 are used for signing, the JSON 1197 signing algorithm representation is as follows. 1199 {"alg":"ES256"} 1201 The value for the "protected" field will be the following. 1203 eyJhbGciOiJFUzI1NiJ9 1205 Thus a common OTrP signed message with ES256 looks like the 1206 following. 1208 { 1209 "payload": "", 1210 "protected": "eyJhbGciOiJFUzI1NiJ9", 1211 "signature":"" 1212 } 1214 The OTrP JSON message encryption algorithm should use one of the 1215 supported algorithms defined in the later chapter of this document. 1216 JSON encryption uses a symmetric key as its "Content Encryption Key 1217 (CEK)". This CEK is encrypted or wrapped by a recipient's key. OTrP 1218 recipient typically has an asymmetric key pair. Therefore CEK will 1219 be encrypted by the recipient's public key. 1221 Symmetric encryption shall use the following algorithm. 1223 {"enc":"A128CBC-HS256"} 1225 This algorithm represents encryption with AES 128 in CBC mode with 1226 HMAC SHA 256 for integrity. The value of the property "protected" in 1227 a JWE message will be 1229 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1231 An encrypted JSON message looks like the following. 1233 { 1234 "protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1235 "recipients": [ 1236 { 1237 "header": { 1238 "alg": "" 1239 }, 1240 "encrypted_key": "" 1241 } 1242 ], 1243 "iv": "", 1244 "ciphertext": "", 1246 "tag": "" 1247 } 1249 OTrP doesn't use JWE AAD (Additional Authenticated Data) because each 1250 message is always signed after the message is encrypted. 1252 7.5.1. Supported JSON Signing Algorithms 1254 The following JSON signature algorithms are mandate support in TEE 1255 and TSM. 1257 o RS256 1259 o ES256 1261 7.5.2. Support JSON Encryption Algorithms 1263 The following JSON authenticated encryption algorithms are mandate 1264 support in TEE and TSM. 1266 o A128CBC-HS256 1268 o A256CBC-HS512 1270 7.6. Common Errors 1272 An OTrP Response message typically needs to report operation status 1273 and error causes if an operation fails. The following JSON message 1274 elements should be used across all OTrP Messages. 1276 "status": "pass | fail" 1278 "reason": { 1279 "error-code": "", 1280 "error-message": "" 1281 } 1282 } 1284 "ver": "" 1286 7.7. OTrP Message List 1288 The following table lists the OTrP commands and therefore 1289 corresponding Request and Response messages defined in this 1290 specification. Additional messages may be added in the future when 1291 new task messages are needed. 1293 GetDeviceState - 1294 A TSM queries a device's current state with a message 1295 GetDeviceStateRequest. A device TEE will report its version, its 1296 FW version, and list of all SD and TA in the device that is 1297 managed by the requesting TSM. TSM may determine whether the 1298 device is trustworthy and decide to carry out additional commands 1299 according to the response from this query. 1301 CreateSD - 1302 A TSM instructs a device TEE to create a SD for a SP. The 1303 recipient TEE will check whether the requesting TSM is 1304 trustworthy. 1306 UpdateSD - 1307 A TSM instructs a device TEE to update an existing SD. A typical 1308 update need comes from SP certificate change, TSM certificate 1309 change and so on. The recipient TEE will verify whether the TSM 1310 is trustworthy and owns the SD. 1312 DeleteSD - 1313 A TSM instructs a device TEE to delete an existing SD. A TEE 1314 conditionally deletes TAs loaded in the SD according to a request 1315 parameter. A SD cannot be deleted until all TAs in this SD are 1316 deleted. If this is the last SD for a SP, TEE can also delete 1317 TEE SP AIK key for this SP. 1319 InstallTA - 1320 A TSM instructs a device to install a TA into a SD for a SP. TEE 1321 in a device will check whether the TSM and TA are trustworthy. 1323 UpdateTA - 1324 A TSM instructs a device to update a TA into a SD for a SP. The 1325 change may commonly be bug fix for a previously installed TA. 1327 DeleteTA - 1328 A TSM instructs a device to delete a TA. TEE in a device will 1329 check whether the TSM and TA are trustworthy. 1331 7.8. OTrP Request Message Routing Rules 1333 For each command that a TSM wants to send to a device, the TSM 1334 generates a request message. This is typically triggered by a Client 1335 Application that uses the TSM. The Client Application initiates 1336 contact with the TSM and receives TSM OTrP Request messages according 1337 to the TSM's implementation. The Client Application forwards the 1338 OTrP message to an OTrP Agent in the device, which in turn sends the 1339 message to the active TEE in the device. 1341 The current version of specification assumes that each device has 1342 only one active TEE, and OTrP Agent is responsible to connect to the 1343 active TEE. This is the case today with devices in the market. 1345 Upon TEE responding with a request, the OTrP Agent gets OTrP response 1346 messages back to the Client Application that sends the request. In 1347 case the target TEE fails to respond the request, the OTrP Agent will 1348 be responsible to generate an error message to reply the Client 1349 Application. The Client Application forwards any data it received to 1350 its TSM. 1352 7.8.1. SP Anonymous Attestation Key (SP AIK) 1354 When the first new Security Domain is created in TEE for a SP, a new 1355 key pair is generated and associated with this SP. This key pair is 1356 used for future device attestation to the service provider instead of 1357 using device's TEE key pair. 1359 8. Detailed Messages Specification 1361 For each message in the following sections all JSON elements are 1362 mandatory if it isn't explicitly indicated as optional. 1364 8.1. GetDeviceState 1366 This is the first command that a TSM will query a device. This 1367 command is triggered when a SP's Client Application contacts its TSM 1368 to check whether the underlying device is ready for TA operations. 1370 This command queries a device's current TEE state. A device TEE will 1371 report its version, its FW version, and list of all SD and TA in the 1372 device that is managed by the requesting TSM. TSM may determine 1373 whether the device is trustworthy and decide to carry out additional 1374 commands according to the response from this query. 1376 The request message of this command is signed by TSM. The response 1377 message from TEE is encrypted. A random message encryption key (MK) 1378 is generated by TEE, and this encrypted key is encrypted by the 1379 receiving TSM public key such that only the TSM who sent the request 1380 is able to decrypt and view the response message. 1382 8.1.1. GetDeviceStateRequest message 1384 { 1385 "GetDeviceStateTBSRequest": { 1386 "ver": "1.0", 1387 "rid": "", 1388 "tid": "", 1389 "ocspdat": "", 1390 "icaocspdat": "", 1391 "supportedsigalgs": "" 1392 } 1393 } 1395 The request message consists of the following data elements: 1397 ver - version of the message format 1399 rid - a unique request ID generated by the TSM 1401 tid - a unique transaction ID to trace request and response. This 1402 can be from a prior transaction's tid field, and can be used in 1403 the subsequent message exchanges in this TSM session. The 1404 combination of rid and tid should be made unique. 1406 ocspdat - OCSP stapling data for the TSM certificate. The TSM 1407 provides OCSP data such that a recipient TEE can validate the 1408 validity of the TSM certificate without making its own external 1409 OCSP service call. This is a mandate field. 1411 icaocspdat - OCSP stapling data for the intermediate CA 1412 certificates of the TSM certificate up to the root. A TEE side 1413 can cache CA OCSP data such that this value isn't needed in each 1414 call. 1416 supportedsigalgs - an optional property to list the signing 1417 algorithms that TSM is able to support. A recipient TEE should 1418 choose algorithm in this list to sign its response message if 1419 this property is present in a request. 1421 The final request message is JSON signed message of the above raw 1422 JSON data with TSM's certificate. 1424 { 1425 "GetDeviceStateRequest": { 1426 "payload":"", 1428 "protected": "", 1429 "header": { 1430 "x5c": "" 1432 }, 1433 "signature":"" 1434 } 1435 } 1437 The signing algorithm should use SHA256 with respective key type. 1438 The mandatory algorithm support is the RSA signing algorithm. The 1439 signer header "x5c" is used to include the TSM signer certificate up 1440 to the root CA certificate. 1442 8.1.2. Request processing requirements at a TEE 1444 Upon receiving a request message GetDeviceStateRequest at a TEE, the 1445 TEE must validate a request: 1447 1. Validate JSON message signing 1449 2. Validate that the request TSM certificate is chained to a trusted 1450 CA that the TEE embeds as its trust anchor. 1452 * Cache the CA OCSP stapling data and certificate revocation 1453 check status for other subsequent requests. 1455 * A TEE can use its own clock time for the OCSP stapling data 1456 validation. 1458 3. Validate JSON message signing 1460 4. Collect Firmware signed data 1462 * This is a capability in ARM architecture that allows a TEE to 1463 query Firmware to get FW signed data. 1465 5. Collect SD information for the SD owned by this TSM 1467 8.1.3. Firmware signed data 1469 Firmware isn't expected to process or produce JSON data. It is 1470 expected to just sign some raw bytes of data. 1472 The data to be signed by TFW key needs be some unique random data 1473 each time. The (UTF-8 encoded) "tid" value from the 1474 GetDeviceStateTBSRequest shall be signed by the firmware. TSM isn't 1475 expected to parse TFW data except the signature validation and signer 1476 trust path validation. 1478 It is possible that a TEE can get some valid TFW signed data from 1479 another device. This is part of the TEE trust assumption where TSM 1480 will trust the TFW data supplied by the TEE. The TFW trust is more 1481 concerned by TEE than a TSM where a TEE needs to ensure that the 1482 underlying device firmware is trustworthy. 1484 TfwData: { 1485 "tbs": "", 1486 "cert": "", 1487 "sigalg": "Signing method", 1488 "sig": "" 1489 } 1491 It is expected that FW use a standard signature methods for maximal 1492 interoperability with TSM providers. The mandatory support list of 1493 signing algorithm is RSA with SHA256. 1495 The JSON object above is constructed by TEE with data returned from 1496 FW. It isn't a standard JSON signed object. The signer information 1497 and data to be signed must be specially processed by TSM according to 1498 definition given here. The data to be signed is the raw data. 1500 8.1.3.1. Supported Firmware Signature Methods 1502 TSM providers shall support the following signature methods. A 1503 firmware provider can choose one of the methods in signature 1504 generation. 1506 o RSA with SHA256 1508 o ECDSA with SHA 256 1510 The value of "sigalg" in the TfwData JSON message should use one of 1511 the following: 1513 o RS256 1514 o ES256 1516 8.1.4. Post Conditions 1518 Upon successful request validation, the TEE information is collected. 1519 There is no change in the TEE in the device. 1521 The response message shall be encrypted where the encryption key 1522 shall be a symmetric key that is wrapped by TSM's public key. The 1523 JSON Content Encryption Key (CEK) is used for this purpose. 1525 8.1.5. GetDeviceStateResponse message 1527 The message has the following structure. 1529 { 1530 "GetDeviceTEEStateTBSResponse": { 1531 "ver": "1.0", 1532 "status": "pass | fail", 1533 "rid": "", 1534 "tid": "", 1535 "signerreq": "true | false about whether TSM needs to send 1536 signer data again in subsequent messages", 1537 "edsi": "" 1538 } 1539 } 1541 where 1543 signerreq - true if the TSM should send its signer certificate and 1544 OCSP data again in the subsequent messages. The value may be 1545 "false" if the TEE caches the TSM's signer certificate and OCSP 1546 status. 1548 rid - the request ID from the request message 1550 tid - the tid from the request message 1552 edsi - the main data element whose value is JSON encrypted message 1553 over the following Device State Information (DSI). 1555 The Device State Information (DSI) message consists of the following. 1557 { 1558 "dsi": { 1559 "tfwdata": { 1560 "tbs": "" 1561 "cert": "", 1562 "sigalg": "Signing method", 1563 "sig": "" 1564 }, 1565 "tee": { 1566 "name": "", 1567 "ver": "", 1568 "cert": "", 1569 "cacert": "", 1571 "sdlist": { 1572 "cnt": "", 1573 "sd": [ 1574 { 1575 "name": "", 1576 "spid": "", 1577 "talist": [ 1578 { 1579 "taid": "", 1580 "taname": "" // optional 1582 } 1583 ] 1584 } 1585 ] 1586 }, 1587 "teeaiklist": [ 1588 { 1589 "spaik": "", 1590 "spaiktype": "", 1591 "spid": "" 1592 } 1593 ] 1594 } 1595 } 1596 } 1598 The encrypted JSON message looks like the following. 1600 { 1601 "protected": "", 1603 "recipients": [ 1604 { 1605 "header": { 1606 "alg": "RSA1_5" 1607 }, 1608 "encrypted_key": "" 1609 } 1610 ], 1611 "iv": "", 1612 "ciphertext": "", 1614 "tag": "" 1615 } 1617 Assume we encrypt plaintext with AES 128 in CBC mode with HMAC SHA 1618 256 for integrity, the encryption algorithm header is: 1620 {"enc":"A128CBC-HS256"} 1622 The value of the property "protected" in the above JWE message will 1623 be 1625 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1627 In other words, the above message looks like the following: 1629 { 1630 "protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1631 "recipients": [ 1632 { 1633 "header": { 1634 "alg": "RSA1_5" 1635 }, 1636 "encrypted_key": "" 1637 } 1638 ], 1639 "iv": "", 1640 "ciphertext": "", 1642 "tag": "" 1643 } 1645 The full response message looks like the following: 1647 { 1648 "GetDeviceTEEStateTBSResponse": { 1649 "ver": "1.0", 1650 "status": "pass | fail", 1651 "rid": "", 1652 "tid": "", 1653 "edsi": { 1654 "protected": "", 1656 "recipients": [ 1657 { 1658 "header": { 1659 "alg": "RSA1_5" 1660 }, 1661 "encrypted_key": "" 1662 } 1663 ], 1664 "iv": "", 1665 "ciphertext": "", 1667 "tag": "" 1668 } 1669 } 1670 } 1672 The CEK will be encrypted by the TSM public key in the device. The 1673 TEE signed message has the following structure. 1675 { 1676 "GetDeviceTEEStateResponse": { 1677 "payload": "", 1679 "protected": "", 1680 "signature": "" 1681 } 1682 } 1684 The signing algorithm shall use SHA256 with respective key type, see 1685 Section Section 7.5.1. 1687 The final response message GetDeviceStateResponse consists of array 1688 of TEE response. A typical device will have only one active TEE. An 1689 OTrP Agent is responsible to collect TEE response for all active TEEs 1690 in the future. 1692 { 1693 "GetDeviceStateResponse": [ // JSON array 1694 {"GetDeviceTEEStateResponse": ...}, 1695 ... 1696 {"GetDeviceTEEStateResponse": ...} 1697 ] 1698 } 1700 8.1.6. Error Conditions 1702 An error may occur if a request isn't valid or the TEE runs into some 1703 error. The list of possible error conditions is the following. 1705 ERR_REQUEST_INVALID The TEE meets the following conditions with a 1706 request message: (1) The request from a TSM has an invalid message 1707 structure; mandatory information is absent in the message. 1708 undefined member or structure is included. (2) TEE fails to verify 1709 signature of the message or fails to decrypt its contents. (3) etc. 1711 ERR_UNSUPPORTED_MSG_VERSION TEE receives the version of message that 1712 TEE can't deal with. 1714 ERR_UNSUPPORTED_CRYPTO_ALG TEE receives a request message encoded 1715 with cryptographic algorithms that TEE doesn't support. 1717 ERR_TFW_NOT_TRUSTED TEE may consider the underlying device firmware 1718 be not trustworthy. 1720 ERR_TSM_NOT_TRUSTED TEE needs to make sure whether the TSM is 1721 trustworthy by checking the validity of TSM certificate and OCSP 1722 stapling data and so on. If TEE finds TSM is not reliable, it may 1723 return this error code. 1725 ERR_TEE_FAIL TEE fails to respond to a TSM request. The OTrP Agent 1726 will construct an error message in responding the TSM's request. 1727 And also if TEE fails to process a request because of its internal 1728 error, it will return this error code. 1730 The response message will look like the following if the TEE signing 1731 can work to sign the error response message. 1733 { 1734 "GetDeviceTEEStateTBSResponse": { 1735 "ver": "1.0", 1736 "status": "fail", 1737 "rid": "", 1738 "tid": "", 1739 "reason": {"error-code":""} 1740 "supportedsigalgs": "" 1741 } 1742 } 1744 where 1746 supportedsigalgs - an optional property to list the signing 1747 algorithms that the active TEE is able to support. When a TSM 1748 sends a signed message that TEE isn't able to validate, it can 1749 include signature algorithms that it is able to consume in this 1750 status report. A TSM can generate a new request message to retry 1751 the management task with a TEE supported signing algorithm. 1753 If TEE isn't able to sign an error message, a general error message 1754 should be returned. 1756 8.1.7. TSM Processing Requirements 1758 Upon receiving a message of the type GetDeviceStateResponse at a TSM, 1759 the TSM should validate the following. 1761 o Parse to get list of GetDeviceTEEStateResponse JSON object 1763 o Parse the JSON "payload" property and decrypt the JSON element 1764 "edsi" 1766 o The decrypted message contains the TEE signer certificate 1768 o Validate GetDeviceTEEStateResponse JSON signature. The signer 1769 certificate is extracted from the decrypted message in the last 1770 step. 1772 o Extract TEE information and check it against its TEE acceptance 1773 policy. 1775 o Extract TFW signed element, and check the signer and data 1776 integration against its TFW policy 1778 o Check the SD list and TA list and prepare for a subsequent command 1779 such as "CreateSD" if it needs to have a new SD for a SP. 1781 8.2. Security Domain Management 1783 8.2.1. CreateSD 1785 This command is typically preceded with GetDeviceState command that 1786 has acquired the device information of the target device by the TSM. 1787 TSM sends such a command to instruct a TEE to create a new Security 1788 Domain for a SP. 1790 A TSM sends an OTrP Request message CreateSDRequest to a device TEE 1791 to create a Security Domain for a SP. Such a request is signed by 1792 TSM where the TSM signer may or may not be the same as the SP's TA 1793 signer certificate. The resulting SD is associated with two 1794 identifiers for future management: 1796 o TSM as the owner. The owner identifier is a registered unique TSM 1797 ID that is stored in the TSM certificate. 1799 o SP identified by its TA signer certificate as the authorization. 1800 A TSM can add more than one SP certificates to a SD. 1802 A Trusted Application that is signed by a matching SP signer 1803 certificate for a SD is eligible to be installed into that SD. The 1804 TA installation into a SD may be instructed from TSM or a Client 1805 Application. 1807 8.2.1.1. CreateSDRequest Message 1808 The request message for CreateSD has the following JSON format. 1810 { 1811 "CreateSDTBSRequest": { 1812 "ver": "1.0", 1813 "rid": "", 1814 "tid": "", // this may be from prior message 1815 "tee": "", 1816 "nextdsi": "true | false", 1817 "dsihash": "", 1818 "content": ENCRYPTED { // this piece of JSON data will be 1819 // encrypted 1820 "spid": "", 1821 "sdname": "", 1822 "spcert": "", 1823 "tsmid": "", 1825 "did": "" 1826 } 1827 } 1828 } 1830 In the message, 1832 rid - A unique value to identify this request 1834 tid - A unique value to identify this transaction. It can have the 1835 same value for the tid in the preceding GetDeviceStateRequest. 1837 tee - TEE ID returned from the previous response 1838 GetDeviceStateResponse 1840 nextdsi - Indicates whether the up to date Device State Information 1841 (DSI) should be returned in the response to this request. 1843 dsihash - The BASE64 encoded SHA256 hash value of the DSI data 1844 returned in the prior TSM operation with this target TEE. This 1845 value is always included such that a receiving TEE can check 1846 whether the device state has changed since its last query. It 1847 helps enforce SD update order in the right sequence without 1848 accidently overwrite an update that was done simultaneously. 1850 content - The "content" is a JSON encrypted message that includes 1851 actual input for the SD creation. The encryption key is TSMmk that 1852 is encrypted by the target TEE's public key. The entire message is 1853 signed by the TSM private key TSMpriv. A separate TSMmk isn't used 1854 in the latest specification because JSON encryption will use a 1855 content encryption key for exactly the same purpose. 1857 spid - A unique id assigned by the TSM for its SP. It should be 1858 unique within a TSM namespace. 1860 sdname - a name unique to the SP. TSM should ensure it is unique 1861 for each SP. 1863 spcert - The SP's TA signer certificate is included in the request. 1864 This certificate will be stored by the device TEE and uses it to 1865 check against TA installation. Only if a TA is signed by a 1866 matching spcert associated with a SD the TA will be installed into 1867 the SD. 1869 tsmid - SD owner claim by TSM - A SD owned by a TSM will be 1870 associated with a trusted identifier defined as an attribute in the 1871 signer TSM certificate. TEE will be responsible to assign this ID 1872 to the SD. The TSM certificate attribute for this attribute TSMID 1873 must be vetted by the TSM signer issuing CA. With this trusted 1874 identifier, SD query at TEE can be fast upon TSM signer 1875 verification. 1877 did - The SHA256 hash of the device TEE certificate. The encryption 1878 key CEK will be encrypted the recipient TEE's public key. This 1879 hash value in the "did" property allows the recipient TEE to check 1880 whether it is the expected target to receive such a request. If 1881 this isn't given, an OTrP message for device 2 could be sent to 1882 device 1. It is optional for TEE to check because the successful 1883 decryption of the request message with this device's TEE private 1884 key already proves it is the target. This explicit hash value 1885 makes the protocol not dependent on message encryption method in 1886 future. 1888 Following is the OTrP message template, the full request is signed 1889 message over the CreateSDTBSRequest as follows. 1891 { 1892 "CreateSDRequest": { 1893 "payload":"", 1894 "protected":"", 1895 "header": , 1896 "signature":"" 1897 } 1898 } 1900 TSM signer certificate is included in the "header" property. 1902 8.2.1.2. Request processing requirements at a TEE 1904 Upon receiving a request message CreateSDRequest at a TEE, the TEE 1905 must validate a request: 1907 1. Validate the JSON request message 1909 * Validate JSON message signing 1911 * Validate that the request TSM certificate is chained to a 1912 trusted CA that the TEE embeds as its trust anchor 1914 * Compare dsihash with its current state to make sure nothing 1915 has changed since this request was sent. 1917 * Decrypt to get the plaintext of the content: (a) spid, (b) sd 1918 name, (c) did 1920 * Check that a SPID is supplied 1922 * spcert check: check it is a valid certificate (signature and 1923 format verification only) 1925 * Check "did" is the SHA256 hash of its TEEcert BER raw binary 1926 data 1928 * Check whether the requested SD already exists for the SP 1930 * Check TSMID in the request matches TSM certificate's TSM ID 1931 attribute 1933 2. Create action 1935 * Create a SD for the SP with the given name 1937 * Assign the TSMID from the TSMCert to this SD 1939 * Assign the SPID and SPCert to this SD 1941 * Check whether a TEE SP AIK keypair already exists for the 1942 given SP ID 1944 * Create TEE SP AIK keypair if it doesn't exist for the given SP 1945 ID 1947 * Generate new DSI data if the request asks for updated DSI 1949 3. Construct CreateSDResponse message 1950 * Create raw content 1952 + Operation status + 1954 + "did" or full signer certificate information, 1956 + TEE SP AIK public key if DSI isn't going to be included 1958 + Updated DSI data if requested if the request asks for it 1960 * The response message is encrypted with the same JWE CEK of the 1961 request without recreating a new content encryption key. 1963 * The encrypted message is signed with TEEpriv. The signer 1964 information ("did" or TEEcert) is encrypted. 1966 4. Deliver response message. (a) OTrP Agent returns this to the app; 1967 (b) The app passes this back to TSM 1969 5. TSM process. (a) TSM processes the response message; (b) TSM can 1970 look up signer certificate from device ID "did". 1972 If a request is illegitimate or signature doesn't pass, a "status" 1973 property in the response will indicate the error code and cause. 1975 8.2.1.3. CreateSDResponse Message 1977 The response message for a CreateSDRequest contains the following 1978 content. 1980 { 1981 "CreateSDTBSResponse": { 1982 "ver": "1.0", 1983 "status": "", 1984 "rid": "", 1985 "tid": "", 1986 "content": ENCRYPTED { 1987 "reason":"", // optional 1988 "did": "", 1989 "sdname": "", 1990 "teespaik": "", 1991 "dsi": "" 1993 } 1994 } 1995 } 1997 In the response message, the following fields MUST be supplied. 1999 did - The SHA256 hash of the device TEE certificate. This shows 2000 the device ID explicitly to the receiving TSM. 2002 teespaik - The newly generated SP AIK public key for the given SP. 2003 This is an optional value if the device has had another domain for 2004 the SP that has triggered TEE SP AIK keypair for this specific SP. 2006 There is possible extreme error case where TEE isn't reachable or the 2007 TEE final response generation itself fails. In this case, TSM should 2008 still receive a response from the OTrP Agent. OTrP Agent is able to 2009 detect such error from TEE. In this case, a general error response 2010 message should be returned, assuming OTrP Agent even doesn't know any 2011 content and information about the request message. 2013 In other words, TSM should expect receive a TEE successfully signed 2014 JSON message, or a general "status" message. 2016 { 2017 "CreateSDResponse": { 2018 "payload":"", 2019 "protected": { 2020 "" 2021 }, 2022 "signature": "" 2024 } 2025 } 2027 A response message type "status" will be returned when TEE totally 2028 fails to respond. OTrP Agent is responsible to create this message. 2030 { 2031 "status": { 2032 "result": "fail", 2033 "error-code": "ERR_TEE_UNKNOWN", 2034 "error-message": "TEE fails to respond" 2035 } 2036 } 2038 8.2.1.4. Error Conditions 2040 An error may occur if a request isn't valid or the TEE runs into some 2041 error. The list of possible errors are the following. Refer to 2042 section Error Code List (Section 13.1) for detail causes and actions. 2044 ERR_REQUEST_INVALID 2045 ERR_UNSUPPORTED_MSG_VERSION 2047 ERR_UNSUPPORTED_CRYPTO_ALG 2049 ERR_DEV_STATE_MISMATCH 2051 ERR_SD_ALREADY_EXIST 2053 ERR_SD_NOT_FOUND 2055 ERR_SPCERT_INVALID 2057 ERR_TEE_FAIL 2059 ERR_TEE_UNKNOWN 2061 ERR_TSM_NOT_AUTHORIZED 2063 ERR_TSM_NOT_TRUSTED 2065 8.2.2. UpdateSD 2067 This TSM initiated command can update a SP's SD that it manages for 2068 the following need. (a) Update SP signer certificate; (b) Add SP 2069 signer certificate when a SP uses multiple to sign TA binary; (c) 2070 Update SP ID. 2072 The TSM presents the proof of the SD ownership to TEE, and includes 2073 related information in its signed message. The entire request is 2074 also encrypted for the end-to-end confidentiality. 2076 8.2.2.1. UpdateSDRequest Message 2077 The request message for UpdateSD has the following JSON format. 2079 { 2080 "UpdateSDTBSRequest": { 2081 "ver": "1.0", 2082 "rid": "", 2083 "tid": "", // this may be from prior message 2084 "tee": "", 2085 "nextdsi": "true | false", 2086 "dsihash": "", 2087 "content": ENCRYPTED { // this piece of JSON will be encrypted 2088 "tsmid": "", 2089 "spid": "", 2090 "sdname": "", 2091 "changes": { 2092 "newsdname": "", // Optional 2093 "newspid": "", // Optional 2094 "spcert": [""], // Optional 2095 "deloldspcert": [""], // Optional 2097 "renewteespaik": "true | false" 2098 } 2099 } 2100 } 2101 } 2103 In the message, 2105 rid - A unique value to identify this request 2107 tid - A unique value to identify this transaction. It can have the 2108 same value for the tid in the preceding GetDeviceStateRequest. 2110 tee - TEE ID returned from the previous response 2111 GetDeviceStateResponse 2113 nextdsi - Indicates whether the up to date Device State Information 2114 (DSI) should be returned in the response to this request. 2116 dsihash - The BASE64 encoded SHA256 hash value of the DSI data 2117 returned in the prior TSM operation with this target TEE. This 2118 value is always included such that a receiving TEE can check 2119 whether the device state has changed since its last query. It 2120 helps enforce SD update order in the right sequence without 2121 accidently overwrite an update that was done simultaneously. 2123 content - The "content" is a JSON encrypted message that includes 2124 actual input for the SD update. The standard JSON content 2125 encryption key (CEK) is used, and the CEK is encrypted by the 2126 target TEE's public key. 2128 tsmid - SD owner claim by TSM - A SD owned by a TSM will be 2129 associated with a trusted identifier defined as an attribute in the 2130 signer TSM certificate. 2132 spid - the identifier of the SP whose SD will be updated. This 2133 value is still needed because SD name is considered unique within a 2134 SP only. 2136 sdname - the name of the target SD to be updated. 2138 changes - its content consists of changes that should be updated in 2139 the given SD. 2141 newsdname - the new name of the target SD to be assigned if this 2142 value is present. 2144 newspid - the new SP ID of the target SD to be assigned if this 2145 value is present. 2147 spcert - a new TA signer certificate of this SP to be added to the 2148 SD if this is present. 2150 deloldspcert - a SP certificate assigned into the SD should be 2151 deleted if this is present. The value is the SHA256 fingerprint of 2152 the old SP certificate. 2154 renewteespaik - the value should be 'true' or 'false'. If it is 2155 present and the value is 'true', TEE should regenerate TEE SP AIK 2156 for this SD's owner SP. The newly generated TEE SP AIK for the SP 2157 must be returned in the response message of this request. If there 2158 are more than one SD for the SP, a new SPID for one of the domain 2159 will always trigger a new teespaik generation as if a new SP is 2160 introduced to the TEE. 2162 Following the OTrP message template, the full request is signed 2163 message over the UpdateSDTBSRequest as follows. 2165 { 2166 "UpdateSDRequest": { 2167 "payload":"", 2168 "protected":"", 2169 "header": , 2170 "signature":"" 2171 } 2172 } 2173 TSM signer certificate is included in the "header" property. 2175 8.2.2.2. Request processing requirements at a TEE 2177 Upon receiving a request message UpdateSDRequest at a TEE, the TEE 2178 must validate a request: 2180 1. Validate the JSON request message 2182 * Validate JSON message signing 2184 * Validate that the request TSM certificate is chained to a 2185 trusted CA that the TEE embeds as its trust anchor. TSM 2186 certificate status check is generally not needed anymore in 2187 this request. The prior request should have validated the TSM 2188 certificate's revocation status 2190 * Compare dsihash with TEE cached last response DSI data to this 2191 TSM 2193 * Decrypt to get the plaintext of the content 2195 * Check that the target SD name is supplied 2197 * Check whether the requested SD exists 2199 * Check that the TSM owns this TSM by verifying TSMID in the SD 2200 matches TSM certificate's TSM ID attribute 2202 * Now the TEE is ready to carry out update listed in the 2203 "content" message 2205 2. Update action 2207 * If "newsdname" is given, replace the SD name for the SD to the 2208 new value 2210 * If "newspid" is given, replace the SP ID assigned to this SD 2211 with the given new value 2213 * If "spcert" is given, add this new SP certificate to the SD. 2215 * If "deloldspcert" is present in the content, check previously 2216 assigned SP certificates to this SD, and delete the one that 2217 matches the given certificate hash value. 2219 * If "renewteespaik" is given and has a value as "true", 2220 generate a new TEE SP AIK keypair, and replace the old one 2221 with this. 2223 * Generate new DSI data if the request asks for updated DSI 2225 * Now the TEE is ready to construct the response message 2227 3. Construct UpdateSDResponse message 2229 * Create raw content 2231 + Operation status + 2233 + "did" or full signer certificate information, 2235 + TEE SP AIK public key if DSI isn't going to be included 2237 + Updated DSI data if requested if the request asks for it 2239 * The response message is encrypted with the same JWE CEK of the 2240 request without recreating a new content encryption key. 2242 * The encrypted message is signed with TEEpriv. The signer 2243 information ("did" or TEEcert) is encrypted. 2245 4. Deliver response message. (a) OTrP Agent returns this to the app; 2246 (b) The app passes this back to TSM 2248 5. TSM process. (a) TSM processes the response message; (b) TSM can 2249 look up signer certificate from device ID "did". 2251 If a request is illegitimate or signature doesn't pass, a "status" 2252 property in the response will indicate the error code and cause. 2254 8.2.2.3. UpdateSDResponse Message 2256 The response message for a UpdateSDRequest contains the following 2257 content. 2259 { 2260 "UpdateSDTBSResponse": { 2261 "ver": "1.0", 2262 "status": "", 2263 "rid": "", 2264 "tid": "", 2265 "content": ENCRYPTED { 2266 "reason":"", // optional 2267 "did": "", 2268 "cert": "", // optional 2269 "teespaik": "", 2270 "teespaiktype": "", 2271 "dsi": "" 2273 } 2274 } 2275 } 2277 In the response message, the following fields MUST be supplied. 2279 did - The request should have known the signer certificate of this 2280 device from a prior request. This hash value of the device TEE 2281 certificate serves as a quick identifier only. Full device 2282 certificate isn't necessary. 2284 teespaik - the newly generated SP AIK public key for the given SP 2285 if TEE SP AIK for the SP is asked to be renewed in the request. 2286 This is an optional value if "dsi" is included in the response, 2287 which will contain all up to date TEE SP AIK key pairs. 2289 Similar to the similar template for the creation of encrypted and 2290 signed CreateSDResponse, the final UpdateSDResponse looks like the 2291 following. 2293 { 2294 "UpdateSDResponse": { 2295 "payload":"", 2296 "protected": { 2297 "" 2298 }, 2299 "signature": "" 2301 } 2302 } 2304 A response message type "status" will be returned when TEE totally 2305 fails to respond. OTrP Agent is responsible to create this message. 2307 { 2308 "status": { 2309 "result": "fail", 2310 "error-code": "ERR_TEE_UNKNOWN", 2311 "error-message": "TEE fails to respond" 2312 } 2313 } 2315 8.2.2.4. Error Conditions 2317 An error may occur if a request isn't valid or the TEE runs into some 2318 error. The list of possible errors are the following. Refer to 2319 section Error Code List (Section 13.1) for detail causes and actions. 2321 ERR_REQUEST_INVALID 2323 ERR_UNSUPPORTED_MSG_VERSION 2325 ERR_UNSUPPORTED_CRYPTO_ALG 2327 ERR_DEV_STATE_MISMATCH 2329 ERR_SD_NOT_FOUND 2331 ERR_SDNAME_ALREADY_USED 2333 ERR_SPCERT_INVALID 2335 ERR_TEE_FAIL 2337 ERR_TEE_UNKNOWN 2339 ERR_TSM_NOT_AUTHORIZED 2341 ERR_TSM_NOT_TRUSTED 2343 8.2.3. DeleteSD 2345 A TSM sends a DeleteSDRequest message to TEE to delete a specified SD 2346 that it owns. A SD can be deleted only if there is no TA associated 2347 with this SD in the device. The request message can contain a flag 2348 to instruct TEE to delete all related TAs in a SD and then delete the 2349 SD. 2351 The target TEE will operate with the following logic. 2353 1. Lookup given SD specified in the request message 2354 2. Check that the TSM owns the SD 2356 3. Check that the device state hasn't changed since the last 2357 operation 2359 4. Check whether there are TAs in this SD 2361 5. If TA exists in a SD, check whether the request instructs whether 2362 TA should be deleted. If the request instructs TEE to delete 2363 TAs, delete all TAs in this SD. If the request doesn't instruct 2364 the TEE to delete TAs, return an error "ERR_SD_NOT_EMPTY". 2366 6. Delete SD 2368 7. If this is the last SD of this SP, delete TEE SP AIK key 2370 8.2.3.1. DeleteSDRequest Message 2372 The request message for DeleteSD has the following JSON format. 2374 { 2375 "DeleteSDTBSRequest": { 2376 "ver": "1.0", 2377 "rid": "", 2378 "tid": "", // this may be from prior message 2379 "tee": "", 2380 "nextdsi": "true | false", 2381 "dsihash": "", 2382 "content": ENCRYPTED { // this piece of JSON will be encrypted 2383 "tsmid": "", 2384 "sdname": "", 2385 "deleteta": "true | false" 2386 } 2387 } 2388 } 2390 In the message, 2392 rid - A unique value to identify this request 2394 tid - A unique value to identify this transaction. It can have the 2395 same value for the tid in the preceding GetDeviceStateRequest. 2397 tee - TEE ID returned from the previous response 2398 GetDeviceStateResponse 2400 nextdsi - Indicates whether the up to date Device State Information 2401 (DSI) should be returned in the response to this request. 2403 dsihash - The BASE64 encoded SHA256 hash value of the DSI data 2404 returned in the prior TSM operation with this target TEE. This 2405 value is always included such that a receiving TEE can check 2406 whether the device state has changed since its last query. It 2407 helps enforce SD update order in the right sequence without 2408 accidently overwrite an update that was done simultaneously. 2410 content - The "content" is a JSON encrypted message that includes 2411 actual input for the SD update. The standard JSON content 2412 encryption key (CEK) is used, and the CEK is encrypted by the 2413 target TEE's public key. 2415 tsmid - SD owner claim by TSM - A SD owned by a TSM will be 2416 associated with a trusted identifier defined as an attribute in the 2417 signer TSM certificate. 2419 sdname - the name of the target SD to be updated. 2421 deleteta - the value should be 'true' or 'false'. If it is present 2422 and the value is 'true', TEE should delete all TAs associated with 2423 the SD in the device. 2425 Following the OTrP message template, the full request is signed 2426 message over the DeleteSDTBSRequest as follows. 2428 { 2429 "DeleteSDRequest": { 2430 "payload":"", 2431 "protected":"", 2432 "header": , 2433 "signature":"" 2434 } 2435 } 2437 TSM signer certificate is included in the "header" property. 2439 8.2.3.2. Request processing requirements at a TEE 2441 Upon receiving a request message DeleteSDRequest at a TEE, the TEE 2442 must validate a request: 2444 1. Validate the JSON request message 2446 * Validate JSON message signing 2448 * Validate that the request TSM certificate is chained to a 2449 trusted CA that the TEE embeds as its trust anchor. TSM 2450 certificate status check is generally not needed anymore in 2451 this request. The prior request should have validated the TSM 2452 certificate's revocation status 2454 * Compare dsihash with TEE cached last response DSI data to this 2455 TSM 2457 * Decrypt to get the plaintext of the content 2459 * Check that the target SD name is supplied 2461 * Check whether the requested SD exists 2463 * Check that the TSM owns this TSM by verifying TSMID in the SD 2464 matches TSM certificate's TSM ID attribute 2466 * Now the TEE is ready to carry out update listed in the 2467 "content" message 2469 2. Deletion action 2471 * Check TA existence in this SD 2473 * If "deleteta" is "true", delete all TAs in this SD. If the 2474 value of "deleteta" is "false" and some TA exists, return an 2475 error "ERR_SD_NOT_EMPTY" 2477 * Delete the SD 2479 * Delete TEE SP AIK key pair if this SD is the last one for the 2480 SP 2482 * Now the TEE is ready to construct the response message 2484 3. Construct DeleteSDResponse message 2486 * Create response content 2488 + Operation status + 2490 + "did" or full signer certificate information, 2492 + Updated DSI data if requested if the request asks for it 2494 * The response message is encrypted with the same JWE CEK of the 2495 request without recreating a new content encryption key. 2497 * The encrypted message is signed with TEEpriv. The signer 2498 information ("did" or TEEcert) is encrypted. 2500 4. Deliver response message. (a) OTrP Agent returns this to the app; 2501 (b) The app passes this back to TSM 2503 5. TSM process. (a) TSM processes the response message; (b) TSM can 2504 look up signer certificate from device ID "did". 2506 If a request is illegitimate or signature doesn't pass, a "status" 2507 property in the response will indicate the error code and cause. 2509 8.2.3.3. DeleteSDResponse Message 2511 The response message for a DeleteSDRequest contains the following 2512 content. 2514 { 2515 "DeleteSDTBSResponse": { 2516 "ver": "1.0", 2517 "status": "", 2518 "rid": "", 2519 "tid": "", 2520 "content": ENCRYPTED { 2521 "reason":"", // optional 2522 "did": "", 2523 "dsi": "" 2525 } 2526 } 2527 } 2529 In the response message, the following fields MUST be supplied. 2531 did - The request should have known the signer certificate of this 2532 device from a prior request. This hash value of the device TEE 2533 certificate serves as a quick identifier only. Full device 2534 certificate isn't necessary. 2536 The final DeleteSDResponse looks like the following. 2538 { 2539 "DeleteSDResponse": { 2540 "payload":"", 2541 "protected": { 2542 "" 2543 }, 2544 "signature": "" 2546 } 2547 } 2548 A response message type "status" will be returned when TEE totally 2549 fails to respond. OTrP Agent is responsible to create this message. 2551 { 2552 "status": { 2553 "result": "fail", 2554 "error-code": "ERR_TEE_UNKNOWN", 2555 "error-message": "TEE fails to respond" 2556 } 2557 } 2559 8.2.3.4. Error Conditions 2561 An error may occur if a request isn't valid or the TEE runs into some 2562 error. The list of possible errors are the following. Refer to 2563 section Error Code List (Section 13.1) for detail causes and actions. 2565 ERR_REQUEST_INVALID 2567 ERR_UNSUPPORTED_MSG_VERSION 2569 ERR_UNSUPPORTED_CRYPTO_ALG 2571 ERR_DEV_STATE_MISMATCH 2573 ERR_SD_NOT_EMPTY 2575 ERR_SD_NOT_FOUND 2577 ERR_TEE_FAIL 2579 ERR_TEE_UNKNOWN 2581 ERR_TSM_NOT_AUTHORIZED 2583 ERR_TSM_NOT_TRUSTED 2585 8.3. Trusted Application Management 2587 This protocol doesn't introduce a TA container concept. All the TA 2588 authorization and management will be up to TEE implementation. 2590 The following three TA management commands will be supported. 2592 o InstallTA - provision a TA by TSM 2594 o UpdateTA - update a TA by TSM 2595 o DeleteTA - remove TA registration information with a SD, remove TA 2596 binary from TEE, remove all TA related data in TEE 2598 8.3.1. InstallTA 2600 TA binary data can be from two sources: 2602 1. TSM supplies the signed TA binary 2604 2. Client Application supplies the TA binary 2606 This specification considers only the first case where TSM supplies 2607 TA binary. When such a request is received by TEE, a SD is already 2608 created and is ready to take TA installation. 2610 A TSM sends the following information in message InstallTARequest to 2611 a target TEE: 2613 o The target SD information: SP ID and SD name 2615 o Encrypted TA binary data. TA data is encrypted with TEE SP AIK. 2617 o TA metadata. It is optional to include SP signer certificate for 2618 the SD to add if the SP has changed signer since the SD was 2619 created. 2621 TEE processes command given by TSM to install TA into a SP's SD. It 2622 does the following: 2624 o Validation 2626 * TEE validates TSM message authenticity 2628 * Decrypt to get request content 2630 * Lookup SD with SD name 2632 * Checks that the TSM owns the SD 2634 * Checks DSI hash matches that the device state hasn't changed 2636 o TA validation 2638 * Decrypt to get TA binary and any personalization data with "TEE 2639 SP AIK private key" 2641 * Check that SP ID is the one that is registered with the SP SD 2642 * TA signer is either the newly given SP certificate or the one 2643 in SD. The TA signing method is specific to TEE. This 2644 specification doesn't define how a TA should be signed. 2646 * If a TA signer is given in the request, add this signer into 2647 the SD. 2649 o TA installation 2651 * TEE re-encrypts TA binary and its personalization data with its 2652 own method 2654 * TEE enrolls and stores the TA onto TEE secure storage area. 2656 o Construct a response message. This involves signing a encrypted 2657 status information for the requesting TSM. 2659 8.3.1.1. InstallTARequest Message 2661 The request message for InstallTA has the following JSON format. 2663 { 2664 "InstallTATBSRequest": { 2665 "ver": "1.0", 2666 "rid": "", 2667 "tid": "", 2668 "tee": "", 2669 "nextdsi": "true | false", 2670 "dsihash": "", 2671 "content": ENCRYPTED { 2672 "tsmid": "", 2673 "spid": "", 2674 "sdname": "", 2675 "spcert": "", // optional 2676 "taid": "" 2677 }, 2678 "encrypted_ta": { 2679 "key": "", 2681 "iv": "", 2682 "alg": "", 2684 "cipherpdata": "" 2686 } 2687 } 2688 } 2689 In the message, 2691 rid - A unique value to identify this request 2693 tid - A unique value to identify this transaction. It can have the 2694 same value for the tid in the preceding GetDeviceStateRequest. 2696 tee - TEE ID returned from the previous response 2697 GetDeviceStateResponse 2699 nextdsi - Indicates whether the up to date Device State Information 2700 (DSI) should be returned in the response to this request. 2702 dsihash - The BASE64 encoded SHA256 hash value of the DSI data 2703 returned in the prior TSM operation with this target TEE. This 2704 value is always included such that a receiving TEE can check 2705 whether the device state has changed since its last query. It 2706 helps enforce SD update order in the right sequence without 2707 accidently overwrite an update that was done simultaneously. 2709 content - The "content" is a JSON encrypted message that includes 2710 actual input for the SD update. The standard JSON content 2711 encryption key (CEK) is used, and the CEK is encrypted by the 2712 target TEE's public key. 2714 tsmid - SD owner claim by TSM - A SD owned by a TSM will be 2715 associated with a trusted identifier defined as an attribute in the 2716 signer TSM certificate. 2718 spid - SP identifier of the TA owner SP 2720 spcert - an optional field to specify SP certificate that signed the 2721 TA. This is sent if the SP has a new certificate that hasn't been 2722 previously registered with the target SD where the TA should be 2723 installed. 2725 sdname - the name of the target SD where the TA should be installed 2727 encrypted_ta - the message portion contains encrypted TA binary data 2728 and personalization data. The TA data encryption key is placed in 2729 "key", which is encrypted by the recipient's public key. The TA 2730 data encryption uses symmetric key based encryption such as AESCBC. 2732 Following the OTrP message template, the full request is signed 2733 message over the InstallTATBSRequest as follows. 2735 { 2736 "InstallTARequest": { 2737 "payload":"", 2738 "protected":"", 2739 "header": , 2740 "signature":"" 2741 } 2742 } 2744 8.3.1.2. InstallTAResponse Message 2746 The response message for a InstallTARequest contains the following 2747 content. 2749 { 2750 "InstallTATBSResponse": { 2751 "ver": "1.0", 2752 "status": "", 2753 "rid": "", 2754 "tid": "", 2755 "content": ENCRYPTED { 2756 "reason":"", // optional 2757 "did": "", 2758 "dsi": "" 2760 } 2761 } 2762 } 2764 In the response message, the following fields MUST be supplied. 2766 did - the SHA256 hash of the device TEE certificate. This shows 2767 the device ID explicitly to the receiving TSM. 2769 The final message InstallTAResponse looks like the following. 2771 { 2772 "InstallTAResponse": { 2773 "payload":"", 2774 "protected": { 2775 "" 2776 }, 2777 "signature": "" 2779 } 2780 } 2782 A response message type "status" will be returned when TEE totally 2783 fails to respond. OTrP Agent is responsible to create this message. 2785 { 2786 "status": { 2787 "result": "fail", 2788 "error-code": "ERR_TEE_UNKNOWN", 2789 "error-message": "TEE fails to respond" 2790 } 2791 } 2793 8.3.1.3. Error Conditions 2795 An error may occur if a request isn't valid or the TEE runs into some 2796 error. The list of possible errors are the following. Refer to 2797 section Error Code List (Section 13.1) for detail causes and actions. 2799 ERR_REQUEST_INVALID 2801 ERR_UNSUPPORTED_MSG_VERSION 2803 ERR_UNSUPPORTED_CRYPTO_ALG 2805 ERR_DEV_STATE_MISMATCH 2807 ERR_SD_NOT_FOUND 2809 ERR_TA_INVALID 2811 ERR_TA_ALREADY_INSTALLED 2813 ERR_TEE_FAIL 2815 ERR_TEE_UNKNOWN 2817 ERR_TEE_RESOURCE_FULL 2818 ERR_TSM_NOT_AUTHORIZED 2820 ERR_TSM_NOT_TRUSTED 2822 8.3.2. UpdateTA 2824 This TSM initiated command can update TA and its data in a SP's SD 2825 that it manages for the following purposes. 2827 1. Update TA binary 2829 2. Update TA's personalization data 2831 The TSM presents the proof of the SD ownership to TEE, and includes 2832 related information in its signed message. The entire request is 2833 also encrypted for the end-to-end confidentiality. 2835 TEE processes command given by TSM to update TA of a SP SD. It does 2836 the following: 2838 o Validation 2840 * TEE validates TSM message authenticity 2842 * Decrypt to get request content 2844 * Lookup SD with SD name 2846 * Checks that the TSM owns the SD 2848 * Checks DSI hash matches that the device state hasn't changed 2850 o TA validation 2852 * Both TA binary and personalization data are optional, but at 2853 least one of them shall be present in the message 2855 * Decrypt to get TA binary and any personalization data with "TEE 2856 SP AIK private key" 2858 * Check that SP ID is the one that is registered with the SP SD 2860 * TA signer is either the newly given SP certificate or the one 2861 in SD. The TA signing method is specific to TEE. This 2862 specification doesn't define how a TA should be signed. 2864 * If a TA signer is given in the request, add this signer into 2865 the SD 2867 o TA update 2869 * TEE re-encrypts TA binary and its personalization data with its 2870 own method 2872 * TEE replaces the existing TA binary and its personalization 2873 data with the new binary and data. 2875 o Construct a response message. This involves signing a encrypted 2876 status information for the requesting TSM. 2878 8.3.2.1. UpdateTARequest Message 2880 The request message for UpdateTA has the following JSON format. 2882 { 2883 "UpdateTATBSRequest": { 2884 "ver": "1.0", 2885 "rid": "", 2886 "tid": "", 2887 "tee": "", 2888 "nextdsi": "true | false", 2889 "dsihash": "", 2890 "content": ENCRYPTED { 2891 "tsmid": "", 2892 "spid": "", 2893 "sdname": "", 2894 "spcert": "", // optional 2895 "taid": "" 2896 }, 2897 "encrypted_ta": { 2898 "key": "", 2900 "iv": "", 2901 "alg": "", 2904 "ciphernewpdata": "" 2906 // optional 2907 } 2908 } 2909 } 2911 In the message, 2913 rid - A unique value to identify this request 2914 tid - A unique value to identify this transaction. It can have the 2915 same value for the tid in the preceding GetDeviceStateRequest. 2917 tee - TEE ID returned from the previous response 2918 GetDeviceStateResponse 2920 nextdsi - Indicates whether the up to date Device State Information 2921 (DSI) should be returned in the response to this request. 2923 dsihash - The BASE64 encoded SHA256 hash value of the DSI data 2924 returned in the prior TSM operation with this target TEE. This 2925 value is always included such that a receiving TEE can check 2926 whether the device state has changed since its last query. It 2927 helps enforce SD update order in the right sequence without 2928 accidently overwrite an update that was done simultaneously. 2930 content - The "content" is a JSON encrypted message that includes 2931 actual input for the SD update. The standard JSON content 2932 encryption key (CEK) is used, and the CEK is encrypted by the 2933 target TEE's public key. 2935 tsmid - SD owner claim by TSM - A SD owned by a TSM will be 2936 associated with a trusted identifier defined as an attribute in the 2937 signer TSM certificate. 2939 spid - SP identifier of the TA owner SP 2941 spcert - an optional field to specify SP certificate that signed the 2942 TA. This is sent if the SP has a new certificate that hasn't been 2943 previously registered with the target SD where the TA should be 2944 installed. 2946 sdname - the name of the target SD where the TA should be updated 2948 taid - an identifier for the TA application to be updated 2950 encrypted_ta - the message portion contains new encrypted TA binary 2951 data and personalization data. 2953 Following the OTrP message template, the full request is signed 2954 message over the UpdateTATBSRequest as follows. 2956 { 2957 "UpdateTARequest": { 2958 "payload":"", 2959 "protected":"", 2960 "header": , 2961 "signature":"" 2962 } 2963 } 2965 8.3.2.2. UpdateTAResponse Message 2967 The response message for a UpdateTARequest contains the following 2968 content. 2970 { 2971 "UpdateTATBSResponse": { 2972 "ver": "1.0", 2973 "status": "", 2974 "rid": "", 2975 "tid": "", 2976 "content": ENCRYPTED { 2977 "reason":"", // optional 2978 "did": "", 2979 "dsi": "" 2981 } 2982 } 2983 } 2985 In the response message, the following fields MUST be supplied. 2987 did - the SHA256 hash of the device TEE certificate. This shows 2988 the device ID explicitly to the receiving TSM. 2990 The final message UpdateTAResponse looks like the following. 2992 { 2993 "UpdateTAResponse": { 2994 "payload":"", 2995 "protected": { 2996 "" 2997 }, 2998 "signature": "" 3000 } 3001 } 3003 A response message type "status" will be returned when TEE totally 3004 fails to respond. OTrP Agent is responsible to create this message. 3006 { 3007 "status": { 3008 "result": "fail", 3009 "error-code": "ERR_TEE_UNKNOWN", 3010 "error-message": "TEE fails to respond" 3011 } 3012 } 3014 8.3.2.3. Error Conditions 3016 An error may occur if a request isn't valid or the TEE runs into some 3017 error. The list of possible errors are the following. Refer to 3018 section Error Code List (Section 13.1) for detail causes and actions. 3020 ERR_REQUEST_INVALID 3022 ERR_UNSUPPORTED_MSG_VERSION 3024 ERR_UNSUPPORTED_CRYPTO_ALG 3026 ERR_DEV_STATE_MISMATCH 3028 ERR_SD_NOT_FOUND 3030 ERR_TA_INVALID 3032 ERR_TA_NOT_FOUND 3034 ERR_TEE_FAIL 3036 ERR_TEE_UNKNOWN 3038 ERR_TSM_NOT_AUTHORIZED 3039 ERR_TSM_NOT_TRUSTED 3041 8.3.3. DeleteTA 3043 This operation defines OTrP messages that allow a TSM instruct a TEE 3044 to delete a TA for a SP in a given SD. A TEE will delete a TA from a 3045 SD and also TA data in the TEE. A Client Application cannot directly 3046 access TEE or OTrP Agent to delete a TA. 3048 8.3.3.1. DeleteTARequest Message 3050 The request message for DeleteTA has the following JSON format. 3052 { 3053 "DeleteTATBSRequest": { 3054 "ver": "1.0", 3055 "rid": "", 3056 "tid": "", 3057 "tee": "", 3058 "nextdsi": "true | false", 3059 "dsihash": "", 3060 "content": ENCRYPTED { 3061 "tsmid": "", 3062 "sdname": "", 3063 "taid": "" 3065 } 3066 } 3067 } 3069 In the message, 3071 rid - A unique value to identify this request 3073 tid - A unique value to identify this transaction. It can have the 3074 same value for the tid in the preceding GetDeviceStateRequest. 3076 tee - TEE ID returned from the previous response 3077 GetDeviceStateResponse 3079 nextdsi - Indicates whether the up to date Device State Information 3080 (DSI) should be returned in the response to this request. 3082 dsihash - The BASE64 encoded SHA256 hash value of the DSI data 3083 returned in the prior TSM operation with this target TEE. This 3084 value is always included such that a receiving TEE can check 3085 whether the device state has changed since its last query. It 3086 helps enforce SD update order in the right sequence without 3087 accidently overwrite an update that was done simultaneously. 3089 content - The "content" is a JSON encrypted message that includes 3090 actual input for the SD update. The standard JSON content 3091 encryption key (CEK) is used, and the CEK is encrypted by the 3092 target TEE's public key. 3094 tsmid - SD owner claim by TSM - A SD owned by a TSM will be 3095 associated with a trusted identifier defined as an attribute in the 3096 signer TSM certificate. 3098 sdname - the name of the target SD where the TA is installed 3100 taid - an identifier for the TA application to be deleted 3102 Following the OTrP message template, the full request is signed 3103 message over the DeleteTATBSRequest as follows. 3105 { 3106 "DeleteTARequest": { 3107 "payload":"", 3108 "protected":"", 3109 "header": , 3110 "signature":"" 3112 } 3113 } 3115 8.3.3.2. Request processing requirements at a TEE 3117 TEE processes command given by TSM to delete a TA of a SP SD. It 3118 does the following: 3120 1. Validate the JSON request message 3122 * TEE validates TSM message authenticity 3124 * Decrypt to get request content 3126 * Lookup the SD and the TA with the given SD name and TA ID 3128 * Checks that the TSM owns the SD, and TA is installed in the SD 3130 * Checks DSI hash matches that the device state hasn't changed 3132 2. Deletion action 3134 * If all the above validation points pass, the TEE deletes the 3135 TA from the SD 3137 * The TEE may also delete all personalization data for the TA 3139 3. Construct DeleteTAResponse message. 3141 If a request is illegitimate or signature doesn't pass, a "status" 3142 property in the response will indicate the error code and cause. 3144 8.3.3.3. DeleteTAResponse Message 3146 The response message for a DeleteTARequest contains the following 3147 content. 3149 { 3150 "DeleteTATBSResponse": { 3151 "ver": "1.0", 3152 "status": "", 3153 "rid": "", 3154 "tid": "", 3155 "content": ENCRYPTED { 3156 "reason":"", // optional 3157 "did": "", 3158 "dsi": "" 3160 } 3161 } 3162 } 3164 In the response message, the following fields MUST be supplied. 3166 did - the SHA256 hash of the device TEE certificate. This shows 3167 the device ID explicitly to the receiving TSM. 3169 The final message DeleteTAResponse looks like the following. 3171 { 3172 "DeleteTAResponse": { 3173 "payload":"", 3174 "protected": { 3175 "" 3176 }, 3177 "signature": "" 3179 } 3180 } 3182 A response message type "status" will be returned when TEE totally 3183 fails to respond. OTrP Agent is responsible to create this message. 3185 { 3186 "status": { 3187 "result": "fail", 3188 "error-code": "ERR_TEE_UNKNOWN", 3189 "error-message": "TEE fails to respond" 3190 } 3191 } 3193 8.3.3.4. Error Conditions 3195 An error may occur if a request isn't valid or the TEE runs into some 3196 error. The list of possible errors are the following. Refer to 3197 section Error Code List (Section 13.1) for detail causes and actions. 3199 ERR_REQUEST_INVALID 3201 ERR_UNSUPPORTED_MSG_VERSION 3203 ERR_UNSUPPORTED_CRYPTO_ALG 3205 ERR_DEV_STATE_MISMATCH 3207 ERR_SD_NOT_FOUND 3209 ERR_TA_NOT_FOUND 3211 ERR_TEE_FAIL 3213 ERR_TEE_UNKNOWN 3215 ERR_TSM_NOT_AUTHORIZED 3217 ERR_TSM_NOT_TRUSTED 3219 9. Response Messages a TSM May Expect 3221 A TSM expects some feedback from a remote device when a request 3222 message is delivered to a device. The following three types of 3223 responses SHOULD be supplied. 3225 Type 1: Expect a valid TEE generated response message 3227 A valid TEE signed response may contain errors detected by TEE, 3228 e.g. TSM is trusted but TSM supplied data is missing, for 3229 example, SP ID doesn't exist. TEE MUST be able to sign and 3230 encrypt. 3232 If TEE isn't able to sign a response, TEE should returns an error 3233 to OTrP Agent without giving any other internal information. 3234 OTrP Agent will be generating the response. 3236 Type 2: OTrP Agent generated error message when TEE fails. OTrP 3237 Agent errors will be defined in this document. 3239 A Type 2 message has the following format. 3241 { 3242 "OTrPAgentError": { 3243 "ver": "1.0", 3244 "rid": "", 3245 "tid": "", 3246 "errcode": "ERR_TEE_FAIL | ERR_TEE_BUSY" 3247 } 3248 } 3250 Type 3: OTrP Agent itself isn't reachable or fails. A Client 3251 Application is responsible to handle error and response TSM in 3252 its own way. This is out of scope for this specification. 3254 10. Attestation Implementation Consideration 3256 It is important to know that the state of a device is appropriate 3257 before trusting that a device is what it says it is. The attestation 3258 scheme for OTrP must also be able to cope with different TEEs, those 3259 that are OTrP compliant and those that use another mechanism. In the 3260 initial version, only one active TEE is assumed. 3262 It is out of scope about how TSM and device implement the trust 3263 hierarchy verification. However, it is helpful to understand what 3264 each system provider should do in order to properly implement OTrP 3265 trust hierarchy. 3267 In this section, we provide some implementation reference 3268 consideration. 3270 10.1. OTrP Secure Boot Module 3272 10.1.1. Attestation signer 3274 It is proposed that attestation for OTrP is based on the SBM secure 3275 boot layer, and that further attestation is not performed within the 3276 TEE itself during security domain operations. The rationale is that 3277 the device boot process will be defined to start with a secure boot 3278 approach that, using eFuse, only releases attestation signing 3279 capabilities into the SBM once a secure boot has been established. 3280 In this way the release of the attestation signer can be considered 3281 the first "platform configuration metric", using TCG terminology. 3283 10.1.2. SBM initial requirements 3285 R1 SBM must be possible to load securely into the secure boot flow 3287 R2 SBM must allow a public / private key pair to be generated during 3288 device manufacture 3290 R3 The public key and certificate must be possible to store securely 3291 from tamper 3293 R4 The private key must be possible to store encrypted at rest 3295 R5 The private key must only be visible to the SBM when it is 3296 decrypted 3298 R6 The SBM must be able to read a list of root and intermediate 3299 certificates that it can use to check certificate chains with. 3300 The list must be stored such that it cannot be tampered with 3302 R7 Possible need to allow a TEE to access its unique TEE specific 3303 private key 3305 10.2. TEE Loading 3307 During boot SBM is required to start all of the ROOT TEEs. Before 3308 loading them the SBM must first determine whether the code sign 3309 signature of the TEE is valid. If TEE integrity is confirmed it may 3310 be started. The SBM must then be able to receive the identity 3311 certificate from the TEE (if that TEE is OTrP compliant). The 3312 identity certificate and keys will need to be baked into the TEE 3313 image, and therefore also covered by the code signer hash during the 3314 manufacture process. The private key for the identity certificate 3315 must be securely protected. The private key for a TEE identity must 3316 never be released no matter how the public key and certificate are 3317 released to the SBM. 3319 Once the SBM has successfully booted a TEE and retrieved the identity 3320 certificate it will commit this to the platform configuration 3321 register (PCR) set, for later use during attestation. As a minimum 3322 the following data must be committed to the PCR for each TEE: 3324 1. Public key and certificate for the TEE 3326 2. TEE reference that can be used later by a TSM to identify this 3327 TEE 3329 10.3. Attestation Hierarchy 3331 The attestation hierarchy and seed required for TSM protocol 3332 operation must be built into the device at manufacture. Additional 3333 TEEs can be added post manufacture using the scheme proposed however 3334 it is outside of the current scope of this document to detail that. 3336 It should be noted that the attestation scheme described is based on 3337 signatures. The only encryption that takes place is with eFuse to 3338 release the SBM signing key and later during protocol lifecycle 3339 management interchange with the TSM. 3341 10.3.1. Attestation hierarchy establishment: manufacture 3343 During manufacture the following steps are required: 3345 1. Device specific TFW key pair and certificate burnt into device, 3346 encrypted by eFuse. This key pair will be used for signing 3347 operations performed by SBM. 3349 2. TEE images are loaded and include a TEE instance specific key 3350 pair and certificate. The key pair and certificate are included 3351 in the image and covered by the code signing hash. 3353 3. The process for TEE images is repeated for any subordinate TEEs 3355 10.3.2. Attestation hierarchy establishment: device boot 3357 During device boot the following steps are required: 3359 1. Secure boot releases TFW private key by decrypting with eFuse 3361 2. SBM verifies the code-signing signature of the active TEE and 3362 places its TEE public key into a signing buffer, along with their 3363 reference for later access. For non-OTrP TEE, the SBM leaves the 3364 TEE public key field blank. 3366 3. SBM signs the signing buffer with TFW private key 3368 4. Each active TEE performs the same operation as SBM, building up 3369 their own signed buffer containing subordinate TEE information. 3371 10.3.3. Attestation hierarchy establishment: TSM 3373 Before a TSM can begin operation in the marketplace it must obtain a 3374 TSM key pair and certificate (TSMpub, TSMpriv) from a CA that is 3375 registered in the trust store of the TEE. In this way, the TEE can 3376 check the intermediate and root CA and verify that it trusts this TSM 3377 to perform operations on the TEE. 3379 11. Acknowledgements 3381 We thank Alin Mutu for his contribution to many discussion that 3382 helped to design the trust flow mechanisms, and the creation of the 3383 flow diagrams. Alin has contributed the context diagram and brought 3384 good point in trust establishment. 3386 We also thank the following people for their input, review, and 3387 discussions that have greatly helped to shape the document: Sangsu 3388 Baek, Marc Canel, Roger Casals, Rob Coombs, Lubna Dajani, and Richard 3389 Parris. 3391 12. Contributors 3393 Brian Witten 3394 Symantec 3395 900 Corporate Pointe 3396 Culver City, CA 90230 3397 USA 3399 Email: brian_witten@symantec.com 3401 Tyler Kim 3402 Solacia 3403 5F, Daerung Post Tower 2, 306 Digital-ro 3404 Seoul 152-790 3405 Korea 3407 Email: tkkim@sola-cia.com 3409 13. IANA Considerations 3411 The error code listed in the next section will be registered. 3413 13.1. Error Code List 3415 This section lists error codes that could be reported by a TA or TEE 3416 in a device in responding a TSM request. 3418 ERR_DEV_STATE_MISMATCH - TEE will return this error code if DSI hash 3419 value from TSM doesn't match with that of device's current DSI. 3421 ERR_SD_ALREADY_EXIST - This error will occur if SD to be created 3422 already exist in the TEE. 3424 ERR_SD_NOT_EMPTY - This is reported if a target SD isn't empty. 3426 ERR_SDNAME_ALREADY_USED TEE will return this error code if new SD 3427 name already exists in the namespace of TSM in the TEE. 3429 ERR_REQUEST_INVALID - This error will occur if the TEE meets the 3430 following conditions with a request message: (1) The request from a 3431 TSM has an invalid message structure; mandatory information is 3432 absent in the message. undefined member or structure is included. 3433 (2) TEE fails to verify signature of the message or fails to 3434 decrypt its contents. (3) etc. 3436 ERR_SPCERT_INVALID - If new SP certificate for the SD to be updated 3437 is not valid, then TEE will return this error code. 3439 ERR_TA_ALREADY_INSTALLED - while installing TA, TEE will return this 3440 error if the TA already has been installed in the SD. 3442 ERR_TA_INVALID - This error will occur when TEE meets any of 3443 following conditions while checking validity of TA: (1) TA binary 3444 has a format that TEE can't recognize. (2) TEE fails to decrypt the 3445 encoding of TA binary and personalization data. (3) If SP isn't 3446 registered with the SP SD where TA will be installed. (4) etc. 3448 ERR_TA_NOT_FOUND - This error will occurs when target TA doesn't 3449 exist in the SD. 3451 ERR_TEE_BUSY - The device TEE is busy. The request should be 3452 generally sent later to retry. 3454 ERR_TEE_FAIL - TEE fails to respond to a TSM request. The OTrP 3455 Agent will construct an error message in responding the TSM's 3456 request. And also if TEE fails to process a request because of its 3457 internal error, it will return this error code. 3459 ERR_TEE_RESOURCE_FULL - This error is reported when a device 3460 resource isn't available anymore such as storage space is full. 3462 ERR_TEE_UNKNOWN - This error will occur if the receiver TEE is not 3463 supposed to receive the request. That will be determined by 3464 checking TEE name or device id in the request message. 3466 ERR_TFW_NOT_TRUSTED - TEE may concern the underlying device firmware 3467 is trustworthy. If TEE determines TFW is not trustworthy, then 3468 this error will occur. 3470 ERR_TSM_NOT_TRUSTED - Before processing a request, TEE needs to make 3471 sure whether the sender TSM is trustworthy by checking the validity 3472 of TSM certificate etc. If TEE finds TSM is not reliable, then it 3473 will return this error code. 3475 ERR_UNSUPPORTED_CRYPTO_ALG - This error will occur if TEE receives a 3476 request message encoded with cryptographic algorithms that TEE 3477 doesn't support. 3479 ERR_UNSUPPORTED_MSG_VERSION - This error will occur if TEE receives 3480 the version of message that TEE can't deal with. 3482 14. Security Consideration 3484 14.1. Cryptographic strength implementation 3486 The strength of the cryptographic algorithms, using the measure of 3487 'bits of security' defined in NIST SP800-57 allowed for the OTrP 3488 protocol is: 3490 o At a minimum, 112 bits of security. The limiting factor for this 3491 is the RSA2048 algorithm, which is measured as 112 bits of 3492 security in sp800-57. It is important that RSA is supported in 3493 order to enhance the interoperability of the protocol. 3495 o The option exists to choose algorithms providing 128 bits of 3496 security. This does require using TEE devices that support ECC 3497 P256. 3499 The available algorithms and key sizes specified for the OTrP 3500 document, defined in this document are based on industry standards. 3501 Over time the recommended or allowed cryptographic algorithms may 3502 change. It is important that the OTrP protocol allows for this. 3504 14.2. Message Security 3506 OTrP messages between the TSM and TEE are protected by message 3507 security using JWS and JWE. The 'Basic protocol profile' section of 3508 this document describes the algorithms used for this. All OTrP TEE 3509 devices and OTrP TSMs must meet the requirements of the basic 3510 profile. In the future additional 'profiles' can be added. 3512 PKI is used to ensure that the TEE will only communicate with a 3513 trusted TSM, and to ensure that the TSM will only communicate with a 3514 trusted TEE. 3516 14.3. TEE Attestation 3518 It is important that the TSM trusts that that it is talking to a 3519 trusted TEE. This is achieved through attestation. The TEE has a 3520 private key and certificate built into it at manufacture, which is 3521 used to sign data supplied by the TSM. This allows the TSM to verify 3522 that the TEE is trusted. 3524 It is also important that the TFW (trusted firmware) can be checked. 3525 The TFW has a private key and certificate built into it at 3526 manufacturer, which allows the TEE to check that that the TFW is 3527 trusted. 3529 The GetDeviceState message therefore allows the TSM to check that it 3530 trusts the TEE, and the TEE at this point will check whether it 3531 trusts the TFW. 3533 14.4. TA Protection 3535 TA will be delivered in an encrypted form. This encryption is an 3536 additional layer within the message encryption described in the 3537 'Basic protocol profile' section of this document. The TA binary is 3538 encrypted for each target device with the device's TEE SP AIK public 3539 key. A TSM may do this encryption or provides the TEE SP AIK public 3540 key to a SP such that the SP encrypts the encrypted TA to TSM for 3541 distribution to TEE. 3543 The encryption algorithm can use a randomly AES 256 key "taek" with a 3544 16 byte random IV, and the "taek" is encrypted by the "TEE SP AIK 3545 public key". The following encrypted TA data structure is expected 3546 by TEE: 3548 "encrypted_ta_bin": { 3549 "key": "", 3551 "iv": ", 3552 "alg": "AESCBC", 3553 "cipherdata": "" 3554 } 3556 14.5. TA Personalization data 3558 A SP or TSM can supply personalization data for a TA to initialize 3559 for a device. Such data is passed through InstallTA command from 3560 TSM. The personalization data itself is opaque to TEE. The data can 3561 be from SP without revealing to TSM. The data is sent in encrypted 3562 manner in a request to a device such that only the device can 3563 decrypt. A device's TEE SP AIK public key for a SP is used to 3564 encrypt the data. 3566 "encrypted_ta_data": { // "TA personalization data" 3567 "key": "", 3569 "iv": "", 3570 "alg": "AESCBC", 3571 "cipherdata": "" 3573 } 3575 14.6. TA trust check at TEE 3577 A TA binary is signed by a TA signer certificate. This TA signing 3578 certificate/private key belongs to the SP, and may be self-signed 3579 (i.e. it need not participate in a trust hierarchy). It is the 3580 responsibility of the TSM to only allow verified TAs from trusted SPs 3581 into the system. Delivery of that TA to the TEE is then the 3582 responsibility of the TEE, using the security mechanisms provided by 3583 the OTrP protocol. 3585 We allow a way for application to check trustworthy of a TA. OTrP 3586 Agent will have a function to allow an application query the metadata 3587 of a TA. 3589 An application in the Rich O/S may perform verification of the TA by 3590 verifying the signature of the TA. The 3591 OTRPService.getTAInformation() function is available to return TEE 3592 supplied TA signer and TSM signer information to the application. An 3593 application can do additional trust check on the certificate returned 3594 for this TA. It may trust TSM, or require additional SP signer trust 3595 chaining. 3597 14.7. One TA Multiple SP Case 3599 A TA for different SP must have different identifier. A TA will be 3600 installed in different SD for the respective SP. 3602 14.8. OTrP Agent Trust Model 3604 An OTrP Agent could be malware in the vulnerable Android OS. A 3605 Client Application will connect its TSM provider for required TA 3606 installation. It gets command messages from TSM, and passes the 3607 message to the OTrP Agent. 3609 The OTrP protocol is a conduit for enabling the TSM to communicate 3610 with the device's TEE to manage SDs and TAs. All TSM messages are 3611 signed and sensitive data is encrypted such that the OTrP Agent 3612 cannot modify or capture sensitive data. 3614 14.9. OCSP Stapling Data for TSM signed messages 3616 The GetDeviceStateRequest message from TSM to TEE shall include OCSP 3617 stapling data for the TSM's signer certificate and that for 3618 intermediate CA certificates up to the root certificate so that the 3619 TEE side can verify the signer certificate's revocation status. 3621 Certificate revocation status check on a TA signer certificate is 3622 optional by a TEE. A TSM is generally expected to do proper TA 3623 application vetting and its SP signer trust validation. A TEE will 3624 trust a TA signer certificate's validation status done by a TSM when 3625 it trusts the TSM. 3627 14.10. Data protection at TSM and TEE 3629 The TEE implementation provides protection of data on the device. It 3630 is the responsibility of the TSM to protect data on its servers. 3632 14.11. Privacy consideration 3634 Devices are issued with a unique TEE certificate to attest a device 3635 validity. This uniqueness also creates a privacy and tracking risk 3636 that must be mitigated. 3638 The TEE will only release the TEE certificate to a trusted TSM (it 3639 must verify the TSM certificate before proceeding). The OTrP 3640 protocol is designed such that only the TSM can obtain the TEE device 3641 certificate and firmware certificate - the GetDeviceState message 3642 requires signature checks to validate the TSM is trusted, and then 3643 delivers the device's certificate(s) encrypted such that only that 3644 TSM may decrypt the response. A Client Application will never see 3645 device certificate. 3647 A SP specific TEE SP AIK (TEE SP Anonymous Key) is generated by the 3648 protocol for Client Applications. This provides a way for the Client 3649 Application to validate data sent from the TEE without requiring the 3650 TEE device certificate to be released to the client device rich O/S , 3651 and to optionally allow as SP to encrypt a TA for a target device 3652 without the SP needing to be supplied the TEE device certificate. 3654 14.12. Threat mitigation 3656 A rogue application may perform excessive TA loading. OTrP Agent 3657 implementation should protect against excessive calls. 3659 Rogue applications may request excessive SD creation request. The 3660 TSM is responsible to ensure this is properly guarded against. 3662 Rogue OTrP Agent could replay or send TSM messages out of 3663 sequence:e.g. TSM sends update1 and update2. OTrP Agent replays 3664 update2 and update1 again, create unexpected result that client 3665 wants. "dsihash" is used to mitigate this. The TEE MUST make sure 3666 it stores DSI state and checks DSI state matches before it does 3667 another update. 3669 Concurrent calls from TSM to TEE should be handled properly by a TEE. 3670 It is up to the device to manage concurrency to the TEE. If multiple 3671 concurrent TSM operations take place these could fail due "dsihash" 3672 being modified by another concurrent operation. If locking is 3673 implemented on the client, this must be done in such a way that one 3674 application cannot lock other applications from using the TEE, except 3675 for a short term duration of the TSM operation taking place. For 3676 example, an OTrP operation that starts but never completes (e.g. loss 3677 of connectivity) must not prevent subsequent OTrP messages from being 3678 executed. 3680 14.13. Compromised CA 3682 If a root CA for TSM certificates is found compromised, some TEE 3683 trust anchor update mechanism should be devised. A compromised 3684 intermediate CA is covered by OCSP stapling and OCSP validation check 3685 in the protocol. A TEE should validate certificate revocation about 3686 a TSM certificate chain. 3688 If the root CA of some TEE device certificates is compromised, these 3689 devices might be rejected by TSM, which is a decision of TSM 3690 implementation and policy choice. Any intermediate CA for TEE device 3691 certificates should be validated by TSM with common CRL or OCSP 3692 method. 3694 14.14. Compromised TSM 3696 The TEE should use validation of the supplied TSM certificates and 3697 OCSP stapled data to validate that the TSM is trustworthy. 3699 Since PKI is used, the integrity of the clock within the TEE 3700 determines the ability of the TEE to reject an expired TSM 3701 certificate, or revoked TSM certificate. Since OCSP stapling 3702 includes signature generation time, certificate validity dates are 3703 compared to the current time. 3705 14.15. Certificate renewal 3707 TFW and TEE device certificates are expected to long lived as the 3708 lifetime of a device. A TSM certificate usually has a moderate 3709 lifetime such as 2 to 5 years. TSM should get renewed certificates. 3710 The root CA certificates for TSM, which is embedded into the trust 3711 anchor store in a device, should have long lifetime that don't 3712 require device trust anchor update. On the other hand, it is 3713 imperative that OEM or device providers plan for support of trust 3714 anchor update in their shipped devices. 3716 15. References 3718 15.1. Normative References 3720 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3721 Requirement Levels", BCP 14, RFC 2119, 3722 DOI 10.17487/RFC2119, March 1997, 3723 . 3725 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3726 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3727 2015, . 3729 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 3730 RFC 7516, DOI 10.17487/RFC7516, May 2015, 3731 . 3733 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 3734 DOI 10.17487/RFC7517, May 2015, 3735 . 3737 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 3738 DOI 10.17487/RFC7518, May 2015, 3739 . 3741 15.2. Informative References 3743 [GPTEE] Global Platform, "Global Platform, GlobalPlatform Device 3744 Technology: TEE System Architecture, v1.0", 2013. 3746 Appendix A. Sample Messages 3748 A.1. Sample Security Domain Management Messages 3750 A.1.1. Sample GetDeviceState 3752 A.1.1.1. Sample GetDeviceStateRequest 3754 TSM builds a "GetDeviceStateTBSRequest" message. 3756 { 3757 "GetDeviceStateTBSRequest": { 3758 "ver": "1.0", 3759 "rid": "8C6F9DBB-FC39-435c-BC89-4D3614DA2F0B" 3760 "tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE", 3761 "ocspdat": "c2FtcGxlIG9jc3BkYXQgQjY0IGVuY29kZWQgQVNOMQ==", 3762 "icaocspdat": 3763 "...c2FtcGxlIGljYW9jc3BkYXQgQjY0IGVuY29kZWQgQVNOMQ==...", 3764 "supportedsigalgs": "RS256" 3765 } 3766 } 3768 TSM signs "GetDeviceStateTBSRequest", creating 3769 "GetDeviceStateRequest" 3771 { 3772 "GetDeviceStateRequest": { 3773 "payload":" 3774 ewoJIkdldERldmljZVN0YXRlVEJTUmVxdWVzdCI6IHsKCQkidmVyIjogIjEuMCIsCgkJ 3775 InJpZCI6IHs4QzZGOURCQi1GQzM5LTQzNWMtQkM4OS00RDM2MTREQTJGMEJ9LAoJCSJ0 3776 aWQiOiAiezRGNDU0QTdGLTAwMkQtNDE1Ny04ODRFLUIwREQxQTA2QThBRX0iLAoJCSJv 3777 Y3NwZGF0IjogImMyRnRjR3hsSUc5amMzQmtZWFFnUWpZMElHVnVZMjlrWldRZ1FWTk9N 3778 UT09IiwKCQkiaWNhb2NzcGRhdCI6ICJjMkZ0Y0d4bElHbGpZVzlqYzNCa1lYUWdRalkw 3779 SUdWdVkyOWtaV1FnUVZOT01RPT0iLAoJCSJzdXBwb3J0ZWRzaWdhbGdzIjogIlJTMjU2 3780 IgoJfQp9", 3781 "protected": "eyJhbGciOiJSUzI1NiJ9", 3782 "header": { 3783 "signer": "ZXhhbXBsZSBBU04xIHNpZ25lciBjZXJ0aWZpY2F0ZQ==" 3784 }, 3785 "signature":"c2FtcGxlIHNpZ25hdHVyZQ" 3786 } 3787 } 3789 A.1.1.2. Sample GetDeviceStateResponse 3791 TSM sends "GetDeviceStateRequest" to OTrP Agent 3793 OTrP Agent obtains "dsi" from each TEE. (in this example there is a 3794 single TEE). 3796 TEE obtains signed "fwdata" from firmware 3798 TEE builds "dsi" - summarizing device state of TEE 3800 { 3801 "dsi": { 3802 "fwdata": { 3803 "tbs": "ezRGNDU0QTdGLTAwMkQtNDE1Ny04ODRFLUIwREQxQTA2QThBRX0=" 3804 "cert": "ZXhhbXBsZSBGVyBjZXJ0aWZpY2F0ZQ==", 3805 "sigalg": "UlMyNTY=", 3806 "sig": "c2FtcGxlIEZXIHNpZ25hdHVyZQ==" 3807 }, 3808 "tee": { 3809 "name": "Primary TEE", 3810 "ver": "1.0", 3811 "cert": "c2FtcGxlIFRFRSBjZXJ0aWZpY2F0ZQ==", 3812 "cacert": [ 3813 "c2FtcGxlIENBIGNlcnRpZmljYXRlIDE=", 3814 "c2FtcGxlIENBIGNlcnRpZmljYXRlIDI=" 3815 ] 3816 "sdlist": { 3817 "cnt": "1", 3818 "sd": [ 3819 { 3820 "name": "default.acmebank.com", 3821 "spid": "acmebank.com", 3822 "talist": [ 3823 { 3824 "taid": "acmebank.secure.banking", 3825 "taname": "Acme secure banking app" 3826 }, 3827 { 3828 "taid": "acmebank.loyalty.rewards", 3829 "taname": "Acme loyalty rewards app" 3830 } 3831 ] 3832 } 3833 ], 3834 } 3835 "teeaiklist": [ 3836 { 3837 "spaik": "c2FtcGxlIEFTTjEgZW5jb2RlZCBQS0NTMSBwdWJsaWNrZXk=", 3838 "spaiktype": "RSA" 3839 "spid": "acmebank.com" 3840 } 3841 ] 3842 } 3843 } 3844 } 3846 TEE encrypts "dsi", and embeds into 3847 "GetDeviceTEEStateTBSResponse" message 3849
3850