< draft-pei-opentrustprotocol-05.txt   draft-pei-opentrustprotocol-06.txt >
Internet Engineering Task Force M. Pei Internet Engineering Task Force M. Pei
Internet-Draft Symantec Internet-Draft Symantec
Intended status: Informational N. Cook Intended status: Informational N. Cook
Expires: July 18, 2018 ARM Ltd. Expires: September 16, 2018 ARM Ltd.
M. Yoo M. Yoo
Solacia Solacia
A. Atyeo A. Atyeo
Intercede Intercede
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
January 14, 2018 March 15, 2018
The Open Trust Protocol (OTrP) The Open Trust Protocol (OTrP)
draft-pei-opentrustprotocol-05.txt draft-pei-opentrustprotocol-06.txt
Abstract Abstract
This document specifies the Open Trust Protocol (OTrP), a protocol to This document specifies the Open Trust Protocol (OTrP), a protocol to
install, update, and delete applications and to manage security install, update, and delete applications in a Trusted Execution
configuration in a Trusted Execution Environment (TEE). Environment (TEE) and to manage their security configuration.
TEEs are used in environments where security services should be TEEs are used in environments where security services should be
isolated from a regular operating system (often called rich OS). isolated from a regular operating system (often called rich OS).
This form of compartmentlization grants a smaller codebase access to This form of compartmentlization grants a smaller codebase access to
security sensitive services and restricts communication from the rich security sensitive services and restricts communication from the rich
OS to those security services via mediated access. OS to those security services via mediated access.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 45 skipping to change at page 1, line 45
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 18, 2018. This Internet-Draft will expire on September 16, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 26 skipping to change at page 2, line 26
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 6 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 6
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 8
4. OTrP Entities and Trust Model . . . . . . . . . . . . . . . . 8 4. OTrP Entities and Trust Model . . . . . . . . . . . . . . . . 8
4.1. System Components . . . . . . . . . . . . . . . . . . . . 8 4.1. System Components . . . . . . . . . . . . . . . . . . . . 8
4.2. Trusted Anchors in TEE . . . . . . . . . . . . . . . . . 9 4.2. Trusted Anchors in TEE . . . . . . . . . . . . . . . . . 9
4.3. Trusted Anchors in TSM . . . . . . . . . . . . . . . . . 9 4.3. Trusted Anchors in TAM . . . . . . . . . . . . . . . . . 10
4.4. Keys and Cerificate Types . . . . . . . . . . . . . . . . 9 4.4. Keys and Cerificate Types . . . . . . . . . . . . . . . . 10
5. Protocol Scope and Entity Relations . . . . . . . . . . . . . 12 5. Protocol Scope and Entity Relations . . . . . . . . . . . . . 12
5.1. A Sample Device Setup Flow . . . . . . . . . . . . . . . 14 5.1. A Sample Device Setup Flow . . . . . . . . . . . . . . . 14
5.2. Derived Keys in The Protocol . . . . . . . . . . . . . . 14 5.2. Derived Keys in The Protocol . . . . . . . . . . . . . . 15
5.3. Security Domain Hierarchy and Ownership . . . . . . . . . 15 5.3. Security Domain Hierarchy and Ownership . . . . . . . . . 15
5.4. SD Owner Identification and TSM Certificate Requirements 16 5.4. SD Owner Identification and TAM Certificate Requirements 16
5.5. Service Provider Container . . . . . . . . . . . . . . . 16 5.5. Service Provider Container . . . . . . . . . . . . . . . 16
6. OTrP Agent . . . . . . . . . . . . . . . . . . . . . . . . . 17 6. OTrP Agent . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1. Role of OTrP Agent . . . . . . . . . . . . . . . . . . . 17 6.1. Role of OTrP Agent . . . . . . . . . . . . . . . . . . . 18
6.2. OTrP Agent and Global Platform TEE Client API . . . . . . 18 6.2. OTrP Agent and Global Platform TEE Client API . . . . . . 18
6.3. OTrP Agent Implementation Consideration . . . . . . . . . 18 6.3. OTrP Agent Implementation Consideration . . . . . . . . . 18
6.3.1. OTrP Agent Distribution . . . . . . . . . . . . . . . 18 6.3.1. OTrP Agent Distribution . . . . . . . . . . . . . . . 18
6.3.2. Number of OTrP Agent . . . . . . . . . . . . . . . . 18 6.3.2. Number of OTrP Agent . . . . . . . . . . . . . . . . 19
6.3.3. OTrP Android Service Option . . . . . . . . . . . . . 19 6.4. OTrP Agent Interfaces for Client Applications . . . . . . 19
6.4. OTrP Agent API for Client Applications . . . . . . . . . 19 6.4.1. ProcessOTrPMessage call . . . . . . . . . . . . . . . 19
6.4.1. API processMessage . . . . . . . . . . . . . . . . . 19 6.4.2. GetTAInformation call . . . . . . . . . . . . . . . . 20
6.4.2. API getTAInformation . . . . . . . . . . . . . . . . 20 6.5. Sample End-to-End Client Application Flow . . . . . . . . 23
6.5. Sample End-to-End Client Application Flow . . . . . . . . 22 6.5.1. Case 1: A New Client Application Uses a TA . . . . . 23
6.5.1. Case 1: A New Client Application Uses a TA . . . . . 22
6.5.2. Case 2: A Previously Installed Client Application 6.5.2. Case 2: A Previously Installed Client Application
Calls a TA . . . . . . . . . . . . . . . . . . . . . 24 Calls a TA . . . . . . . . . . . . . . . . . . . . . 24
7. OTrP Messages . . . . . . . . . . . . . . . . . . . . . . . . 25 7. OTrP Messages . . . . . . . . . . . . . . . . . . . . . . . . 25
7.1. Message Format . . . . . . . . . . . . . . . . . . . . . 25 7.1. Message Format . . . . . . . . . . . . . . . . . . . . . 25
7.2. Message Naming Convention . . . . . . . . . . . . . . . . 25 7.2. Message Naming Convention . . . . . . . . . . . . . . . . 25
7.3. Request and Response Message Template . . . . . . . . . . 26 7.3. Request and Response Message Template . . . . . . . . . . 26
7.4. Signed Request and Response Message Structure . . . . . . 26 7.4. Signed Request and Response Message Structure . . . . . . 26
7.4.1. Identifying Signing and Encryption Keys for JWS/JWE 7.4.1. Identifying Signing and Encryption Keys for JWS/JWE
Messaging . . . . . . . . . . . . . . . . . . . . . . 28 Messaging . . . . . . . . . . . . . . . . . . . . . . 28
7.5. JSON Signing and Encryption Algorithms . . . . . . . . . 28 7.5. JSON Signing and Encryption Algorithms . . . . . . . . . 28
7.5.1. Supported JSON Signing Algorithms . . . . . . . . . . 30 7.5.1. Supported JSON Signing Algorithms . . . . . . . . . . 30
7.5.2. Support JSON Encryption Algorithms . . . . . . . . . 30 7.5.2. Support JSON Encryption Algorithms . . . . . . . . . 30
7.5.3. Supported JSON Key Management Algorithms . . . . . . 30 7.5.3. Supported JSON Key Management Algorithms . . . . . . 30
7.6. Common Errors . . . . . . . . . . . . . . . . . . . . . . 31 7.6. Common Errors . . . . . . . . . . . . . . . . . . . . . . 31
7.7. OTrP Message List . . . . . . . . . . . . . . . . . . . . 31 7.7. OTrP Message List . . . . . . . . . . . . . . . . . . . . 31
7.8. OTrP Request Message Routing Rules . . . . . . . . . . . 32 7.8. OTrP Request Message Routing Rules . . . . . . . . . . . 32
7.8.1. SP Anonymous Attestation Key (SP AIK) . . . . . . . . 32 7.8.1. SP Anonymous Attestation Key (SP AIK) . . . . . . . . 32
8. Detailed Messages Specification . . . . . . . . . . . . . . . 32 8. Transport Protocol Support . . . . . . . . . . . . . . . . . 32
8.1. GetDeviceState . . . . . . . . . . . . . . . . . . . . . 33 9. Detailed Messages Specification . . . . . . . . . . . . . . . 33
8.1.1. GetDeviceStateRequest message . . . . . . . . . . . . 33 9.1. GetDeviceState . . . . . . . . . . . . . . . . . . . . . 33
8.1.2. Request processing requirements at a TEE . . . . . . 34 9.1.1. GetDeviceStateRequest message . . . . . . . . . . . . 33
8.1.3. Firmware Signed Data . . . . . . . . . . . . . . . . 35 9.1.2. Request processing requirements at a TEE . . . . . . 34
8.1.3.1. Supported Firmware Signature Methods . . . . . . 35 9.1.3. Firmware Signed Data . . . . . . . . . . . . . . . . 35
8.1.4. Post Conditions . . . . . . . . . . . . . . . . . . . 36 9.1.3.1. Supported Firmware Signature Methods . . . . . . 36
8.1.5. GetDeviceStateResponse Message . . . . . . . . . . . 36 9.1.4. Post Conditions . . . . . . . . . . . . . . . . . . . 36
8.1.6. Error Conditions . . . . . . . . . . . . . . . . . . 40 9.1.5. GetDeviceStateResponse Message . . . . . . . . . . . 36
8.1.7. TSM Processing Requirements . . . . . . . . . . . . . 41 9.1.6. Error Conditions . . . . . . . . . . . . . . . . . . 41
8.2. Security Domain Management . . . . . . . . . . . . . . . 42 9.1.7. TAM Processing Requirements . . . . . . . . . . . . . 42
8.2.1. CreateSD . . . . . . . . . . . . . . . . . . . . . . 42 9.2. Security Domain Management . . . . . . . . . . . . . . . 43
8.2.1.1. CreateSDRequest Message . . . . . . . . . . . . . 42 9.2.1. CreateSD . . . . . . . . . . . . . . . . . . . . . . 43
8.2.1.2. Request Processing Requirements at a TEE . . . . 45 9.2.1.1. CreateSDRequest Message . . . . . . . . . . . . . 43
8.2.1.3. CreateSDResponse Message . . . . . . . . . . . . 46 9.2.1.2. Request Processing Requirements at a TEE . . . . 46
8.2.1.4. Error Conditions . . . . . . . . . . . . . . . . 47 9.2.1.3. CreateSDResponse Message . . . . . . . . . . . . 47
8.2.2. UpdateSD . . . . . . . . . . . . . . . . . . . . . . 48 9.2.1.4. Error Conditions . . . . . . . . . . . . . . . . 49
8.2.2.1. UpdateSDRequest Message . . . . . . . . . . . . . 48 9.2.2. UpdateSD . . . . . . . . . . . . . . . . . . . . . . 49
8.2.2.2. Request Processing Requirements at a TEE . . . . 51 9.2.2.1. UpdateSDRequest Message . . . . . . . . . . . . . 49
8.2.2.3. UpdateSDResponse Message . . . . . . . . . . . . 53 9.2.2.2. Request Processing Requirements at a TEE . . . . 52
8.2.2.4. Error Conditions . . . . . . . . . . . . . . . . 54 9.2.2.3. UpdateSDResponse Message . . . . . . . . . . . . 54
8.2.3. DeleteSD . . . . . . . . . . . . . . . . . . . . . . 55 9.2.2.4. Error Conditions . . . . . . . . . . . . . . . . 55
8.2.3.1. DeleteSDRequest Message . . . . . . . . . . . . . 55 9.2.3. DeleteSD . . . . . . . . . . . . . . . . . . . . . . 56
8.2.3.2. Request Processing Requirements at a TEE . . . . 57 9.2.3.1. DeleteSDRequest Message . . . . . . . . . . . . . 56
8.2.3.3. DeleteSDResponse Message . . . . . . . . . . . . 58 9.2.3.2. Request Processing Requirements at a TEE . . . . 58
8.2.3.4. Error Conditions . . . . . . . . . . . . . . . . 60 9.2.3.3. DeleteSDResponse Message . . . . . . . . . . . . 59
8.3. Trusted Application Management . . . . . . . . . . . . . 60 9.2.3.4. Error Conditions . . . . . . . . . . . . . . . . 61
8.3.1. InstallTA . . . . . . . . . . . . . . . . . . . . . . 60 9.3. Trusted Application Management . . . . . . . . . . . . . 61
8.3.1.1. InstallTARequest Message . . . . . . . . . . . . 62 9.3.1. InstallTA . . . . . . . . . . . . . . . . . . . . . . 62
8.3.1.2. InstallTAResponse Message . . . . . . . . . . . . 64 9.3.1.1. InstallTARequest Message . . . . . . . . . . . . 63
8.3.1.3. Error Conditions . . . . . . . . . . . . . . . . 65 9.3.1.2. InstallTAResponse Message . . . . . . . . . . . . 65
8.3.2. UpdateTA . . . . . . . . . . . . . . . . . . . . . . 65 9.3.1.3. Error Conditions . . . . . . . . . . . . . . . . 67
8.3.2.1. UpdateTARequest Message . . . . . . . . . . . . . 67 9.3.2. UpdateTA . . . . . . . . . . . . . . . . . . . . . . 67
8.3.2.2. UpdateTAResponse Message . . . . . . . . . . . . 68 9.3.2.1. UpdateTARequest Message . . . . . . . . . . . . . 68
8.3.2.3. Error Conditions . . . . . . . . . . . . . . . . 70 9.3.2.2. UpdateTAResponse Message . . . . . . . . . . . . 70
8.3.3. DeleteTA . . . . . . . . . . . . . . . . . . . . . . 70 9.3.2.3. Error Conditions . . . . . . . . . . . . . . . . 72
8.3.3.1. DeleteTARequest Message . . . . . . . . . . . . . 70 9.3.3. DeleteTA . . . . . . . . . . . . . . . . . . . . . . 72
8.3.3.2. Request Processing Requirements at a TEE . . . . 72 9.3.3.1. DeleteTARequest Message . . . . . . . . . . . . . 72
8.3.3.3. DeleteTAResponse Message . . . . . . . . . . . . 73 9.3.3.2. Request Processing Requirements at a TEE . . . . 74
8.3.3.4. Error Conditions . . . . . . . . . . . . . . . . 74 9.3.3.3. DeleteTAResponse Message . . . . . . . . . . . . 75
9. Response Messages a TSM May Expect . . . . . . . . . . . . . 74 9.3.3.4. Error Conditions . . . . . . . . . . . . . . . . 76
10. Basic Protocol Profile . . . . . . . . . . . . . . . . . . . 75 10. Response Messages a TAM May Expect . . . . . . . . . . . . . 76
11. Attestation Implementation Consideration . . . . . . . . . . 76 11. Basic Protocol Profile . . . . . . . . . . . . . . . . . . . 77
11.1. OTrP Secure Boot Module . . . . . . . . . . . . . . . . 76 12. Attestation Implementation Consideration . . . . . . . . . . 78
11.1.1. Attestation signer . . . . . . . . . . . . . . . . . 76 12.1. OTrP Secure Boot Module . . . . . . . . . . . . . . . . 78
11.1.2. SBM Initial Requirements . . . . . . . . . . . . . . 76 12.1.1. Attestation signer . . . . . . . . . . . . . . . . . 78
11.2. TEE Loading . . . . . . . . . . . . . . . . . . . . . . 77 12.1.2. SBM Initial Requirements . . . . . . . . . . . . . . 78
11.3. Attestation Hierarchy . . . . . . . . . . . . . . . . . 77 12.2. TEE Loading . . . . . . . . . . . . . . . . . . . . . . 79
11.3.1. Attestation Hierarchy Establishment: Manufacture . . 78 12.3. Attestation Hierarchy . . . . . . . . . . . . . . . . . 79
11.3.2. Attestation Hierarchy Establishment: Device Boot . . 78 12.3.1. Attestation Hierarchy Establishment: Manufacture . . 80
11.3.3. Attestation Hierarchy Establishment: TSM . . . . . . 78 12.3.2. Attestation Hierarchy Establishment: Device Boot . . 80
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 78 12.3.3. Attestation Hierarchy Establishment: TAM . . . . . . 80
13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 79 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 81
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 81
14.1. Error Code List . . . . . . . . . . . . . . . . . . . . 79 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 81
15. Security Consideration . . . . . . . . . . . . . . . . . . . 80 15.1. Error Code List . . . . . . . . . . . . . . . . . . . . 81
15.1. Cryptographic Strength . . . . . . . . . . . . . . . . . 81 15.1.1. TEE Signed Error Code List . . . . . . . . . . . . . 81
15.2. Message Security . . . . . . . . . . . . . . . . . . . . 81 15.1.2. OTrP Agent Error Code List . . . . . . . . . . . . . 83
15.3. TEE Attestation . . . . . . . . . . . . . . . . . . . . 81 16. Security Consideration . . . . . . . . . . . . . . . . . . . 83
15.4. TA Protection . . . . . . . . . . . . . . . . . . . . . 82 16.1. Cryptographic Strength . . . . . . . . . . . . . . . . . 83
15.5. TA Personalization Data . . . . . . . . . . . . . . . . 82 16.2. Message Security . . . . . . . . . . . . . . . . . . . . 83
15.6. TA Trust Check at TEE . . . . . . . . . . . . . . . . . 82 16.3. TEE Attestation . . . . . . . . . . . . . . . . . . . . 84
15.7. One TA Multiple SP Case . . . . . . . . . . . . . . . . 83 16.4. TA Protection . . . . . . . . . . . . . . . . . . . . . 84
15.8. OTrP Agent Trust Model . . . . . . . . . . . . . . . . . 83 16.5. TA Personalization Data . . . . . . . . . . . . . . . . 84
15.9. OCSP Stapling Data for TSM Signed Messages . . . . . . . 83 16.6. TA Trust Check at TEE . . . . . . . . . . . . . . . . . 85
15.10. Data Protection at TSM and TEE . . . . . . . . . . . . . 84 16.7. One TA Multiple SP Case . . . . . . . . . . . . . . . . 85
15.11. Privacy Consideration . . . . . . . . . . . . . . . . . 84 16.8. OTrP Agent Trust Model . . . . . . . . . . . . . . . . . 85
15.12. Threat Mitigation . . . . . . . . . . . . . . . . . . . 84 16.9. OCSP Stapling Data for TAM Signed Messages . . . . . . . 86
15.13. Compromised CA . . . . . . . . . . . . . . . . . . . . . 85 16.10. Data Protection at TAM and TEE . . . . . . . . . . . . . 86
15.14. Compromised TSM . . . . . . . . . . . . . . . . . . . . 85 16.11. Privacy Consideration . . . . . . . . . . . . . . . . . 86
15.15. Certificate Renewal . . . . . . . . . . . . . . . . . . 85 16.12. Threat Mitigation . . . . . . . . . . . . . . . . . . . 86
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 85 16.13. Compromised CA . . . . . . . . . . . . . . . . . . . . . 87
16.1. Normative References . . . . . . . . . . . . . . . . . . 85 16.14. Compromised TAM . . . . . . . . . . . . . . . . . . . . 87
16.2. Informative References . . . . . . . . . . . . . . . . . 86 16.15. Certificate Renewal . . . . . . . . . . . . . . . . . . 88
Appendix A. Sample Messages . . . . . . . . . . . . . . . . . . 86 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 88
A.1. Sample Security Domain Management Messages . . . . . . . 86 17.1. Normative References . . . . . . . . . . . . . . . . . . 88
A.1.1. Sample GetDeviceState . . . . . . . . . . . . . . . . 86 17.2. Informative References . . . . . . . . . . . . . . . . . 88
A.1.1.1. Sample GetDeviceStateRequest . . . . . . . . . . 86 Appendix A. Sample Messages . . . . . . . . . . . . . . . . . . 89
A.1.1.2. Sample GetDeviceStateResponse . . . . . . . . . . 87 A.1. Sample Security Domain Management Messages . . . . . . . 89
A.1.2. Sample CreateSD . . . . . . . . . . . . . . . . . . . 90 A.1.1. Sample GetDeviceState . . . . . . . . . . . . . . . . 89
A.1.2.1. Sample CreateSDRequest . . . . . . . . . . . . . 90 A.1.1.1. Sample GetDeviceStateRequest . . . . . . . . . . 89
A.1.2.2. Sample CreateSDResponse . . . . . . . . . . . . . 93 A.1.1.2. Sample GetDeviceStateResponse . . . . . . . . . . 89
A.1.2. Sample CreateSD . . . . . . . . . . . . . . . . . . . 93
A.1.3. Sample UpdateSD . . . . . . . . . . . . . . . . . . . 94 A.1.2.1. Sample CreateSDRequest . . . . . . . . . . . . . 93
A.1.3.1. Sample UpdateSDRequest . . . . . . . . . . . . . 95 A.1.2.2. Sample CreateSDResponse . . . . . . . . . . . . . 96
A.1.3.2. Sample UpdateSDResponse . . . . . . . . . . . . . 96 A.1.3. Sample UpdateSD . . . . . . . . . . . . . . . . . . . 97
A.1.4. Sample DeleteSD . . . . . . . . . . . . . . . . . . . 96 A.1.3.1. Sample UpdateSDRequest . . . . . . . . . . . . . 98
A.1.4.1. Sample DeleteSDRequest . . . . . . . . . . . . . 96 A.1.3.2. Sample UpdateSDResponse . . . . . . . . . . . . . 99
A.1.4.2. Sample DeleteSDResponse . . . . . . . . . . . . . 98 A.1.4. Sample DeleteSD . . . . . . . . . . . . . . . . . . . 99
A.2. Sample TA Management Messages . . . . . . . . . . . . . . 100 A.1.4.1. Sample DeleteSDRequest . . . . . . . . . . . . . 99
A.2.1. Sample InstallTA . . . . . . . . . . . . . . . . . . 100 A.1.4.2. Sample DeleteSDResponse . . . . . . . . . . . . . 101
A.2.1.1. Sample InstallTARequest . . . . . . . . . . . . . 100 A.2. Sample TA Management Messages . . . . . . . . . . . . . . 103
A.2.1.2. Sample InstallTAResponse . . . . . . . . . . . . 101 A.2.1. Sample InstallTA . . . . . . . . . . . . . . . . . . 103
A.2.2. Sample UpdateTA . . . . . . . . . . . . . . . . . . . 103 A.2.1.1. Sample InstallTARequest . . . . . . . . . . . . . 103
A.2.2.1. Sample UpdateTARequest . . . . . . . . . . . . . 103 A.2.1.2. Sample InstallTAResponse . . . . . . . . . . . . 104
A.2.2.2. Sample UpdateTAResponse . . . . . . . . . . . . . 104 A.2.2. Sample UpdateTA . . . . . . . . . . . . . . . . . . . 106
A.2.3. Sample DeleteTA . . . . . . . . . . . . . . . . . . . 107 A.2.2.1. Sample UpdateTARequest . . . . . . . . . . . . . 106
A.2.3.1. Sample DeleteTARequest . . . . . . . . . . . . . 107 A.2.2.2. Sample UpdateTAResponse . . . . . . . . . . . . . 107
A.2.3.2. Sample DeleteTAResponse . . . . . . . . . . . . . 109 A.2.3. Sample DeleteTA . . . . . . . . . . . . . . . . . . . 110
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 A.2.3.1. Sample DeleteTARequest . . . . . . . . . . . . . 110
A.2.3.2. Sample DeleteTAResponse . . . . . . . . . . . . . 112
A.3. Example OTrP Agent Option . . . . . . . . . . . . . . . . 114
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 114
1. Introduction 1. Introduction
The Trusted Execution Environment (TEE) concept has been designed and The Trusted Execution Environment (TEE) concept has been designed and
used to increase security by separating regular operating systems, used to increase security by separating a regular operating system,
also referred as Rich Execution Environment (REE), from security- also referred as a Rich Execution Environment (REE), from security-
sensitive applications. In an TEE ecosystem, a Trust Service Manager sensitive applications. In an TEE ecosystem, a Trusted Application
(TSM) is used to authorize manage keys and the Trusted Applications Manager (TAM) is used to manage keys and the Trusted Applications
(TA) that run in a device. Different device vendors may use (TA) that run in a device. Different device vendors may use
different TEE implementations. Different application providers may different TEE implementations. Different application providers may
use different TSM providers. There arises a need of an open use different TAM providers. There arises a need of an open
interoperable protocol that allows trustworthy TSM to manage Security interoperable protocol that establishes trust between different
Domains and contents running in different Trusted Execution devices and TAM providers, and management capability for a
Environment (TEE) of various devices. trustworthy TAM to manage Security Domains and applications running
in different TEEs of various devices.
The Open Trust Protocol (OTrP) defines a protocol between a TSM and a The Open Trust Protocol (OTrP) defines a mutual trust message
TEE and relies on IETF-defined end-to-end security mechanisms, namely protocol between a TAM and a TEE and relies on IETF-defined end-to-
JSON Web Encryption (JWE), JSON Web Signature (JWS), and JSON Web Key end security mechanisms, namely JSON Web Encryption (JWE), JSON Web
(JWK). Signature (JWS), and JSON Web Key (JWK). Other message encoding
methods may be supported.
This specification assumes that a device that utilizes this This specification assumes that an applicable device is equipped with
specification is equipped with a TEE and is pre-provisioned with a a TEE and is pre-provisioned with a device-unique public/private key
device-unique public/private key pair, which is securely stored. pair, which is securely stored. This key pair is referred as the
This key pair is referred as the 'root of trust'. A Service Provider 'root of trust'. An entity that uses such a device to run Trusted
(SP) uses such a device to run Trusted Applications (TA). Applications (TAs) is known as a Service Provider (SP).
A security domain is defined as the TEE representation of a service A Security Domain is defined as the TEE representation of a Service
provider and is a logical space that contains the service provider's Provider, which is a logical space that contains the SP's TAs. Each
Trusted Applications. Each security domain requires the management Security Domain requires the management operations of TAs in the form
operations of Trusted Applications (TAs) in the form of installation, of installation, update and deletion.
update and deletion.
The protocol builds on the following properties of the system: The protocol builds on the following properties of the system:
1. The SP needs to determine security-relevant information of a 1. The SP needs to determine security-relevant information of a
device before provisioning information to a TEE. Examples device before provisioning information to a TEE. Examples
include the verification of the root of trust, the type of include the verification of the device 'root of trust', the type
firmware installed, and the type of TEE included in a device. of firmware installed, and the type of TEE included in a device.
2. A TEE in a device needs to determine whether a SP or the TSM is 2. A TEE in a device needs to determine whether an SP or a TAM is
authorized to manage applications in the TEE. trustworthy or authorized to manage applications in the TEE.
3. Secure Boot must be able to ensure a TEE is genuine. 3. Secure Boot must be able to ensure a TEE is genuine.
This specification defines message payloads exchanged between devices This specification defines message payloads exchanged between devices
and a TSM but does not mandate a specific transport. The messages and a TAM. The messages are designed in anticipation of the use of
are designed in anticipation of the use of the most common transport the most common transport methods such as HTTPS.
methods such as HTTPS via a wired or wireless network between a
device and a remote TSM web service. A TA binary and personalization data can be from two sources:
1. A TAM supplies the signed and encrypted TA binary
2. A Client Application supplies the TA binary
This specification considers the first case where TA binary and
personalization data are encrypted by recipient's public key that TAM
has to be involved. The second case will be addressed separately.
2. Requirements Language 2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in [RFC2119].
3. Terminology 3. Terminology
3.1. Definitions 3.1. Definitions
The definitions provided below are defined as used in this document. The definitions provided below are defined as used in this document.
The same terms may be defined differently in other documents. The same terms may be defined differently in other documents.
Client Application: An application running on a rich OS, such as an Client Application: An application running on a rich OS, such as an
Android, Windows, or iOS application, provided by a SP. Android, Windows, or iOS application, typically provided by an
SP.
Device: A physical piece of hardware that hosts symmetric key Device: A physical piece of hardware that hosts a TEE along with a
cryptographic modules rich OS.
OTrP Agent: An application running in the rich OS allowing OTrP Agent: An application running in the rich OS allowing
communication with the TSM and the TEE. communication with the TAM and the TEE.
Rich Application: Alternative name of "Client Application". In this Rich Application: Alternative name of "Client Application". In this
document we may use these two terms interchangably. document we may use these two terms interchangably.
Rich Execution Environment (REE) An environment that is provided and Rich Execution Environment (REE) An environment that is provided and
governed by a rich OS, potentially in conjunction with other governed by a standard OS, potentially in conjunction with other
supporting operating systems and hypervisors; it is outside of supporting operating systems and hypervisors; it is outside of
the TEE. This environment and applications running on it are the TEE. This environment and applications running on it are
considered un-trusted. considered un-trusted.
Secure Boot Module (SBM): A firmware in a device that delivers Secure Boot Module (SBM): A firmware in a device that delivers
secure boot functionality. It is also referred as Trusted secure boot functionality. It is generally signed and can be
Firmware (TFW) in this document. verified whether it can be trusted. We also call it a Trusted
Firmware (TFW).
Service Provider (SP): An entity that wishes to supply Trusted Service Provider (SP): An entity that wishes to supply Trusted
Applications to remote devices. A Service Provider requires the Applications to remote devices. A Service Provider requires the
help of a TSM in order to provision the Trusted Applications to help of a TAM in order to provision the Trusted Applications to
the devices. the devices.
Trust Anchor: A root certificate that a module trusts. It is Trust Anchor: A root certificate that can be used to validate its
usually embedded in one validating module, and used to validate children certificates. It is usually embedded in a device or
the trust of a remote entity's certificate. configured by a TAM for validating the trust of a remote entity's
certificate.
Trusted Application (TA): Application that runs in TEE. Trusted Application (TA): An Application that runs in a TEE.
Trusted Execution Environment (TEE): An execution environment that Trusted Execution Environment (TEE): An execution environment that
runs alongside but isolated from an REE. A TEE has security runs alongside of, but is isolated from, an REE. A TEE has
capabilities and meets certain security-related requirements: It security capabilities and meets certain security-related
protects TEE assets from general software attacks, defines rigid requirements. It protects TEE assets from general software
safeguards as to data and functions that a program can access, attacks, defines rigid safeguards as to data and functions that a
and resists a set of defined threats. There are multiple program can access, and resists a set of defined threats. It
technologies that can be used to implement a TEE, and the level should have at least the following three properties: (a) A unique
of security achieved varies accordingly. security identity that cannot be cloned; (b) Assuance that only
authorized code can run in the TEE; (c) Memory that cannot be
read by code outside of TEE. There are multiple technologies
that can be used to implement a TEE, and the level of security
achieved varies accordingly.
3.2. Abbreviations 3.2. Abbreviations
CA Certificate Authority CA Certificate Authority
OTrP Open Trust Protocol OTrP Open Trust Protocol
REE Rich Execution Environment REE Rich Execution Environment
SD Security Domain SD Security Domain
SP Service Provider SP Service Provider
SBM Secure Boot Module SBM Secure Boot Module
TA Trusted Application TA Trusted Application
TEE Trusted Execution Environment TEE Trusted Execution Environment
TFW Trusted Firmware TFW Trusted Firmware
TSM Trusted Service Manager TAM Trusted Application Manager
4. OTrP Entities and Trust Model 4. OTrP Entities and Trust Model
4.1. System Components 4.1. System Components
There are the following main components in this OTrP system. The following are the main components in this OTrP system.
TSM: The TSM is responsible for originating and coordinating TAM: The TAM is responsible for originating and coordinating
lifecycle management activity on a particular TEE. lifecycle management activity on a particular TEE.
A Trust Service Manager (TSM) is at the core to the protocol that A TAM manages device trust check on behalf of Service Providers.
manages device trust check on behalf of service providers for the A TAM may be used by one SP or many SPs. A TAM also provides
ecosystem scalability. In addition to its device trust Security Domain management and TA management in a device, in
management for a service provider, the TSM provides Security particularly, over-the-air update to keep TAs up-to-date and
Domain management and TA management in a device, in particularly,
over-the-air update to keep Trusted Applications up to date and
clean up when a version should be removed. clean up when a version should be removed.
In the context of this specification, the term Trusted Certificate Authority (CA): Mutual trust between a device and a TAM
Application Manager (TAM) and TSM are synonymous. as well as an SP is based on certificates. A device embeds a
list of root certificates, called Trust Anchors, from trusted
Certificate Authority (CA): Mutual trust between a device and a TSM Certificate Authorities that a TAM will be validated against. A
as well as a Service Provider is based on certificates. A device TAM will remotely attest a device by checking whether a device
embeds a list of root certificates, called Trust Anchors, from comes with a certificate from a trusted CA.
trusted Certificate Authorities that a TSM will be validated
against. A TSM will remotely attest a device by checking whether
a device comes with a certificate from a trusted CA.
TEE: The TEE resides in the device chip security zone and is TEE: The TEE in a device is responsible for protecting applications
responsible for protecting applications from attack, enabling the from attack, enabling the application to perform secure
application to perform secure operations operations.
REE: The REE, usually called device OS such as Android OS in a phone REE: The REE is responsible for enabling off device communications
device, is responsible for enabling off device communications to to be established between the TEE and TAM. OTrP does not require
be established between the TEE and TSM. OTrP does not require
the device OS to be secure. the device OS to be secure.
OTrP Agent: An application in the REE that can relay messages OTrP Agent: An application in the REE that can relay messages
between a Client Application and TEE. between a Client Application and TEE. Its implementation can be
TEE specific as to how it can interact with a TEE in a device.
Secure Boot: Secure boot (for the purposes of OTrP) must enable Secure Boot: Secure boot (for the purposes of OTrP) must enable
authenticity checking of TEEs by the TSM. authenticity checking of TEEs by the TAM.
The OTrP establishes appropriate trust anchors to enable TEE and TSMs
to communicate in a trusted way when performing lifecycle management
transactions. The main trust relationships between the components
are the following.
1. TSM must be able to ensure a TEE is genuine
2. TEE must be able to ensure a TSM is genuine
3. Secure Boot must be able to ensure a TEE is genuine The OTrP establishes appropriate trust anchors to enable TEEs and
TAMs to communicate in a trusted way when performing lifecycle
management transactions.
4.2. Trusted Anchors in TEE 4.2. Trusted Anchors in TEE
The TEE in each device comes with a trust store that contains a The TEE in each device comes with a trust store that contains a
whitelist of TSM's root CA certificates, which are called Trust whitelist of the TAM's root CA certificates, which are called Trust
Anchors. A TSM will be trusted to manage Security Domains and TAs in Anchors. A TAM will be trusted to manage Security Domains and TAs in
a device only if its certificate is chained to one of the root CA a device only if the TAM's certificate is chained to one of the root
certificates in this trust store. CA certificates in this trust store.
Such a list is typically embedded in TEE of a device, and the list Such a list is typically embedded in the TEE of a device, and the
update is enabled and handled by device OEM provider. list update should be generally enabled.
4.3. Trusted Anchors in TSM Before a TAM can begin operation in the marketplace to support
devices of a given TEE, it must obtain a TAM certificate from a CA
that is registered in the trust store of the TEE.
The Trust Anchor set in a TSM consists of a list of Certificate 4.3. Trusted Anchors in TAM
The Trust Anchor set in a TAM consists of a list of Certificate
Authority certificates that signs various device TEE certificates. A Authority certificates that signs various device TEE certificates. A
TSM decides what TEE and TFW it will trust. TAM decides what TEE and optionally TFW it will trust.
4.4. Keys and Cerificate Types 4.4. Keys and Cerificate Types
OTrP Protocol leverages the following list of trust anchors and OTrP leverages the following list of trust anchors and identities in
identities in generating signed and encrypted command messages that generating signed and encrypted command messages that are exchanged
are exchanged between a device with TEE and a TSM. With these between a device's TEE and a TAM. With these security artifacts,
security artifacts, OTrP Messages are able to deliver end-to-end OTrP Messages are able to deliver end-to-end security without relying
security without relying on any transport security. on any transport security.
+-------------+----------+--------+-------------------+-------------+ +-------------+----------+--------+-------------------+-------------+
| Key Entity | Location | Issuer | Trust Implication | Cardinality | | Key Entity | Location | Issuer | Trust Implication | Cardinality |
| Name | | | | | | Name | | | | |
+-------------+----------+--------+-------------------+-------------+ +-------------+----------+--------+-------------------+-------------+
| 1. TFW | Device | OEM CA | A white list of | 1 per | | 1. TFW key | Device | FW CA | A white list of | 1 per |
| keypair and | secure | | FW root CA | device | | pair and | secure | | FW root CA | device |
| Certificate | storage | | trusted by TSMs | | | certificate | storage | | trusted by TAMs | |
| | | | | | | | | | | |
| 2. TEE | Device | TEE CA | A white list of | 1 per | | 2. TEE key | Device | TEE CA | A white list of | 1 per |
| keypair and | TEE | under | TEE root CA | device | | pair and | TEE | under | TEE root CA | device |
| Certificate | | a root | trusted by TSMs | | | certificate | | a root | trusted by TAMs | |
| | | CA | | | | | | CA | | |
| | | | | | | | | | | |
| 3. TSM | TSM | TSM CA | A white list of | 1 or | | 3. TAM key | TAM | TAM CA | A white list of | 1 or |
| keypair and | provider | under | TSM root CA | multiple | | pair and | provider | under | TAM root CA | multiple |
| Certificate | | a root | embedded in TEE | can be used | | certificate | | a root | embedded in TEE | can be used |
| | | CA | | by a TSM | | | | CA | | by a TAM |
| | | | | | | | | | | |
| 4. SP | SP | SP | TSM manages SP. | 1 or | | 4. SP key | SP | SP | TAM manages SP. | 1 or |
| keypair and | | signer | TA trust is | multiple | | pair and | | signer | TA trust is | multiple |
| Certificate | | CA | delegated to TSM. | can be used | | certificate | | CA | delegated to TAM. | can be used |
| | | | TEE trusts TSM to | by a TSM | | | | | TEE trusts TAM to | by a TAM |
| | | | ensure that a TA | | | | | | ensure that a TA | |
| | | | is trustworthy. | | | | | | is trustworthy. | |
+-------------+----------+--------+-------------------+-------------+ +-------------+----------+--------+-------------------+-------------+
Table 1: Key and Certificate Types Table 1: Key and Certificate Types
1. TFW keypair and Certificate: A key pair and certificate for 1. TFW key pair and certificate: A key pair and certificate for
evidence of secure boot and trustworthy firmware in a device. evidence of secure boot and trustworthy firmware in a device.
Location: Device secure storage Location: Device secure storage
Supported Key Type: RSA and ECC Supported Key Type: RSA and ECC
Issuer: OEM CA Issuer: OEM CA
Trust Implication: A white list of FW root CA trusted by TSMs Trust Implication: A white list of FW root CA trusted by TAMs
Cardinality: One per device Cardinality: One per device
2. TEE keypair and Certificate: It is used for device attestation 2. TEE key pair and certificate: It is used for device attestation
to remote TSM and SP. to a remote TAM and SP.
This key pair is burned into the device at device manufacturer. This key pair is burned into the device at device manufacturer.
The key pair and its certificate are valid for the expected The key pair and its certificate are valid for the expected
lifetime of the device. lifetime of the device.
Location: Device TEE Location: Device TEE
Supported Key Type: RSA and ECC Supported Key Type: RSA and ECC
Issuer: TEE CA that chains to a root CA Issuer: A CA that chains to a TEE root CA
Trust Implication: A white list of TEE root CA trusted by TSMs Trust Implication: A white list of TEE root CA trusted by TAMs
Cardinality: One per device Cardinality: One per device
3. TSM keypair and Certificate: A TSM provider acquires a 3. TAM key pair and certificate: A TAM provider acquires a
certificate from a CA that a TEE trusts. certificate from a CA that a TEE trusts.
Location: TSM provider Location: TAM provider
Supported Key Type: RSA and ECC. Supported Key Type: RSA and ECC.
Supported Key Size: RSA 2048-bit, ECC P-256 and P-384. Supported Key Size: RSA 2048-bit, ECC P-256 and P-384. Other
sizes should be anticipated in future.
Issuer: TSM CA that chains to a root CA Issuer: TAM CA that chains to a root CA
Trust Implication: A white list of TSM root CA embedded in TEE Trust Implication: A white list of TAM root CA embedded in TEE
Cardinality: One or multiple can be used by a TSM Cardinality: One or multiple can be used by a TAM
4. SP keypair and Certificate: A SP uses its own key pair and 4. SP key pair and certificate: an SP uses its own key pair and
certificate to sign a TA. certificate to sign a TA.
Location: SP Location: SP
Supported Key Type: RSA and ECC Supported Key Type: RSA and ECC
Supported Key Size: RSA 2048-bit, ECC P-256 and P-384 Supported Key Size: RSA 2048-bit, ECC P-256 and P-384. Other
sizes should be anticipated in future.
Issuer: SP signer CA that chains to a root CA Issuer: an SP signer CA that chains to a root CA
Trust Implication: TSM manages SP. TA trust is delegated to Trust Implication: TAM manages SP. TA trusts an SP by
TSM. TEE trusts TSM to ensure that a TA is trustworthy. validating trust against a TAM that the SP uses. A TEE trusts
TAM to ensure that a TA from the TAM is trustworthy.
Cardinality: One or multiple can be used by a SP Cardinality: One or multiple can be used by an SP
5. Protocol Scope and Entity Relations 5. Protocol Scope and Entity Relations
This document specifies the minimally required interoperable This document specifies messages and key properties that can
artifacts to establish mutual trust between a TEE and TSM. The establish mutual trust between a TEE and a TAM. The protocol
protocol provides specifications for the following three entities: provides specifications for the following three entities:
1. Key and certificate types required for device firmware, TEE, TA, 1. Key and certificate types required for device firmware, TEEs,
SP, and TSM TAs, SPs, and TAMs
2. Data message formats that should be exchanged between a TEE in a 2. Data message formats that should be exchanged between a TEE in a
device and a TSM device and a TAM
3. An OTrP Agent application in the REE that can relay messages 3. An OTrP Agent application in the REE that can relay messages
between a Client Application and TEE between a Client Application and TEE
Figure 1: Protocol Scope and Entity Relationship Figure 1: Protocol Scope and Entity Relationship
PKI CA --CA CA-- PKI CA -- CA CA --
| | | | | |
| | | | | |
| | | | | |
Device | | ----OTrP Agent --- Rich App --- | Device | | --- OTrP Agent / Client App --- |
SW | | | | | SW | | | | |
| | | | | | | | | |
| | | | | | | | | |
OTrP | -- TEE TSM------- OTrP | -- TEE TAM-------
| |
| |
FW FW
Figure 2: OTrP System Diagram Figure 2: OTrP System Diagram
---OTrP Message Protocol-- -------OTrP Message Protocol---
| | | |
| | | |
-------------------- --------------- ---------- -------------------- --------------- ----------
| REE | TEE | | TSM | | SP | | REE | TEE | | TAM | | SP |
| --- | --- | | --- | | -- | | --- | --- | | --- | | -- |
| | | | | | | | | | | | | |
| Client | SD (TAs)| | SD / TA | | TA | | Client | SD (TAs)| | SD / TA | | TA |
| Apps | | | Mgmt | | | | Apps | | | Mgmt | | |
| | | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | |
| OTrP | Trusted | | Trusted | | | | OTrP | Trusted | | Trusted | | |
| Agent | CAs | | FW, TEE CAs | | | | Agent | TAM/SP | | FW/TEE | | |
| | CAs | | CAs | | |
| | | | | | | | | | | | | |
| |TEE Key/ | | TSM Key/ | |SP Key/ | | |TEE Key/ | | TAM Key/ | |SP Key/ |
| | Cert | | Cert | | Cert | | | Cert | | Cert | | Cert |
| | FW Key/ | | | | | | | FW Key/ | | | | |
| | Cert | | | | | | | Cert | | | | |
------------------ --------------- ---------- -------------------- --------------- ----------
| | | | | |
| | | | | |
----------------------------------------- ------------- ---------- ---------
| | TEE CA | | TAM CA | | SP CA |
| ------------- ---------- ---------
--------------
| CA |
--------------
In the previous diagram, different Certificate Authorities can be In the previous diagram, different Certificate Authorities can be
used respectively for different types of certificates. OTrP Messages used respectively for different types of certificates. OTrP Messages
are always signed, where the signer keys is the message creator's key are always signed, where the signer keys is the message creator's
pair such as a FW key pair, TEE key pair or TSM key pair. private key such as a FW's private key, a TEE's private key, or a
TAM's private key.
The main OTrP Protocol component is the set of standard JSON messages The main OTrP component consists of a set of standard JSON messages
created by TSM to deliver device SD and TA management commands to a created by a TAM to deliver device SD and TA management commands to a
device, and device attestation and response messages created by TEE device, and device attestation and response messages created by a TEE
to respond to TSM OTrP Messages. that responds to a TAM's OTrP message.
The communication method of OTrP Messages between a TSM and TEE in a The communication method of OTrP Messages between a TAM and TEE in a
device is left to TSM providers for maximal interoperability. A TSM device may vary between TAM and TEE providers. A mandatory transport
can work with its SP and Client Applications how it gets OTrP protocol is specified for a compliant TAM and a device TEE.
Messages from a TSM. When a Client Application has had an OTrP
Message from its TSM, it is imperative to have an interoperable It should be noted that network communication capability is generally
interface to communicate with various TEE types. This is the OTrP not available in today's TEE powered devices. The networking
Agent interface that serves this purpose. The OTrP Agent doesn't functionality is handled by a rich Client Application with a remote
need to know the actual content of OTrP Messages except for the TEE internet services; the Client Applications uses a local TEE interface
routing information. such as inter-process or a secure shared memory approach to interfact
with TA inside a TEE for message exchanges. Consequenly, a TAM
generally communicates with a Client Application about how it gets
OTrP Messages that originates from TEE inside a device. Similarly, a
TA or TEE generally gets OTrP messages from a TAM via some Client
Application, not direct to the internet.
It is imperative to have an interoperable interface to communicate
with differnet TEEs in differnent devices that a Client Application
needs to run and access a TA inside a TEE. This is the role of an
OTrP Agent, which is a software component to bridge communication
between a TAM and a TEE. The OTrP Agent doesn't need to know the
actual content of OTrP Messages except for the TEE routing
information.
5.1. A Sample Device Setup Flow 5.1. A Sample Device Setup Flow
Step 1: Prepare Images for Devices Step 1: Prepare Images for Devices
1. [TEE vendor] Deliver TEE Image (CODE Binary) 1. [TEE vendor] Deliver TEE Image (CODE Binary) to device OEM
2. [CA] Deliver root CA Whitelist 2. [CA] Deliver root CA Whitelist
3. [Soc] Deliver TFW Image 3. [Soc] Deliver TFW Image
Step 2: Inject Key Pairs and Images to Devices Step 2: Inject Key Pairs and Images to Devices
1. [OEM] Generate Secure Boot Key Pair (May be shared among multiple 1. [OEM] Generate Secure Boot Key Pair (May be shared among multiple
devices) devices)
2. [OEM] Flash signed TFW Image and signed TEE Image onto devices 2. [OEM] Flash signed TFW Image and signed TEE Image onto devices
(signed by Secure Boot Key) (signed by Secure Boot Key)
Step 3: Setup attestation key pair in devices Step 3: Setup attestation key pairs in devices
1. [OEM] Flash Secure Boot Public Key and eFuse Key (eFuse key is 1. [OEM] Flash Secure Boot Public Key and eFuse Key (eFuse key is
unique per device) unique per device)
2. [TFW/TEE] Generate a unique attestation key pair and get a 2. [TFW/TEE] Generate a unique attestation key pair and get a
certificate for the device. certificate for the device.
Step 4: Setup trust anchors in devices Step 4: Setup trust anchors in devices
1. [TFW/TEE] Store the key and certificate encrypted with the eFuse 1. [TFW/TEE] Store the key and certificate encrypted with the eFuse
key key
2. [TEE vendor or OEM] Store trusted CA certificate list into 2. [TEE vendor or OEM] Store trusted CA certificate list into
devices devices
5.2. Derived Keys in The Protocol 5.2. Derived Keys in The Protocol
The protocol generates the following two key pairs in run time to The protocol generates one key pair in run time to assist message
assist message communication and anonymous verification between TSM communication and anonymous verification between a TAM and a TEE.
and TEE.
1. TEE Anonymous Key (TEE AIK): one derived key pair per TEE in a TEE SP Anonymous Key (AIK): one derived key pair per SP in a device
device
The purpose of the key pair is to sign data by a TEE without using The purpose of the key pair is to sign data by a TEE without using
its TEE device key for anonymous attestation to a Client Application. its TEE device key for anonymous attestation to a Client Application.
This key is generated in the first GetDeviceState query. The public This key pair is generated in the first SD creation for an SP. It is
key of the key pair is returned to the caller Client Application for deleted when all SDs are removed for a SP in a device. The public
future TEE returned data validation. key of the key pair is given to the caller Client Application and TAM
for future TEE returned data validation. The public key of this AIK
2. TEE SP AIK: one derived key per SP in a device is also used by a TAM to encrypt TA binary data and personalization
data when it sends a TA to a device for installation.
The purpose of this key pair is for a TSM to encrypt TA binary data
when it sends a TA to a device for installation. This key is
generated in the first SD creation for a SP. It is deleted when all
SDs are removed for a SP in a device.
With the presence of a TEE SP AIK, it isn't necessary to have a
shared SP independent TEE AIK. For the initial release, this
specification will not use TEE AIK.
5.3. Security Domain Hierarchy and Ownership 5.3. Security Domain Hierarchy and Ownership
The primary job of a TSM is to help a SP to manage its trusted The primary job of a TAM is to help an SP to manage its trusted
applications. A TA is typically installed in a SD. A SD is commonly applications. A TA is typically installed in an SD. An SD is
created for a SP. commonly created for an SP.
When a SP delegates its SD and TA management to a TSM, a SD is When an SP delegates its SD and TA management to a TAM, an SD is
created on behalf of a TSM in a TEE and the owner of the SD is created on behalf of a TAM in a TEE and the owner of the SD is
assigned to the TSM. A SD may be associated with a SP but the TSM assigned to the TAM. An SD may be associated with an SP but the TAM
has full privilege to manage the SD for the SP. has full privilege to manage the SD for the SP.
Each SD for a SP is associated with only one TSM. When a SP changes Each SD for an SP is associated with only one TAM. When an SP
TSM, a new SP SD must be created to associate with the new TSM. TEE changes TAM, a new SP SD must be created to associate with the new
will maintain a registry of TSM ID and SP SD ID mapping. TAM. The TEE will maintain a registry of TAM ID and SP SD ID
mapping.
From a SD ownership perspective SD tree is flat and there is only one From an SD ownership perspective, the SD tree is flat and there is
level. A SD is associated with its owner. It is up to TEE's only one level. An SD is associated with its owner. It is up to TEE
implementation how it maintains SD binding information for TSM and implementation how it maintains SD binding information for a TAM and
different SPs under the same TSM. different SPs under the same TAM.
It is an important decision in this protocol specification that a TEE It is an important decision in this protocol specification that a TEE
doesn't need to know whether a TSM is authorized to manage SD for a doesn't need to know whether a TAM is authorized to manage the SD for
SP. This authorization is implicitly triggered by a SP Client an SP. This authorization is implicitly triggered by an SP Client
Application, which instructs what TSM it wants to use. A SD is Application, which instructs what TAM it wants to use. An SD is
always associated with a TSM in addition to its SP ID. A rogue TSM always associated with a TAM in addition to its SP ID. A rogue TAM
isn't able to do anything on an unauthorized SP's SD managed by isn't able to do anything on an unauthorized SP's SD managed by
another TSM. another TAM.
Since a TSM may support multiple SPs, sharing the same SD name for Since a TAM may support multiple SPs, sharing the same SD name for
different SP creates a dependency in deleting a SD. A SD can be different SPs creates a dependency in deleting an SD. An SD can be
deleted only after all TAs associated with this SD is deleted. A SP deleted only after all TAs associated with this SD is deleted. An SP
cannot delete a Security Domain on its own with a TSM if a TSM cannot delete a Security Domain on its own with a TAM if a TAM
decides to introduce such sharing. There are cases where multiple decides to introduce such sharing. There are cases where multiple
virtual SPs belong to the same organization, and a TSM chooses to use virtual SPs belong to the same organization, and a TAM chooses to use
the same SD name for those SPs. This is totally up to the TSM the same SD name for those SPs. This is totally up to the TAM
implementation and out of scope of this specification. implementation and out of scope of this specification.
5.4. SD Owner Identification and TSM Certificate Requirements 5.4. SD Owner Identification and TAM Certificate Requirements
There is a need of cryptographically binding proof about the owner of There is a need of cryptographically binding proof about the owner of
a SD in device. When a SD is created on behalf of a TSM, a future an SD in a device. When an SD is created on behalf of a TAM, a
request from the TSM must present itself as a way that the TEE can future request from the TAM must present itself as a way that the TEE
verify it is the true owner. The certificate itself cannot reliably can verify it is the true owner. The certificate itself cannot
used as the owner because TSM may change its certificate. reliably used as the owner because TAM may change its certificate.
To this end, each TSM will be associated with a trusted identifier To this end, each TAM will be associated with a trusted identifier
defined as an attribute in the TSM certificate. This field is kept defined as an attribute in the TAM certificate. This field is kept
the same when the TSM renew its certificates. A TSM CA is the same when the TAM renew its certificates. A TAM CA is
responsible to vet the requested TSM attribute value. responsible to vet the requested TAM attribute value.
This identifier value must not collide among different TSM providers, This identifier value must not collide among different TAM providers,
and one TSM shouldn't be able to claim the identifier used by another and one TAM shouldn't be able to claim the identifier used by another
TSM provider. TAM provider.
The certificate extension name to carry the identifier can initially The certificate extension name to carry the identifier can initially
use SubjectAltName:registeredID. A dedicated new extension name may use SubjectAltName:registeredID. A dedicated new extension name may
be registered later. be registered later.
One common choice of the identifier value is the TSM's service URL. One common choice of the identifier value is the TAM's service URL.
A CA can verify the domain ownership of the URL with the TSM in the A CA can verify the domain ownership of the URL with the TAM in the
certificate enrollment process. certificate enrollment process.
TEE can assign this certificate attribute value as the TSM owner ID A TEE can assign this certificate attribute value as the TAM owner ID
for the SDs that are created for the TSM. for the SDs that are created for the TAM.
An alternative way to represent a SD ownership by a TSM is to have a An alternative way to represent an SD ownership by a TAM is to have a
unique secret key upon SD creation such that only the creator TSM is unique secret key upon SD creation such that only the creator TAM is
able to produce a Proof-of-Possession (POP) data with the secret. able to produce a Proof-of-Possession (POP) data with the secret.
5.5. Service Provider Container 5.5. Service Provider Container
A sample Security Domain hierarchy for the TEE is shown below. A sample Security Domain hierarchy for the TEE is shown below.
---------- ----------
| TEE | | TEE |
---------- ----------
| |
| --------------- | ----------
|----------| SP1 Root SD | |----------| SP1 SD1 |
| --------------- | ----------
| | | ----------
| | -------------- |----------| SP1 SD2 |
| |----------| SP1 Sub SD | | ----------
| | -------------- | ----------
| | -------------- |----------| SP2 SD1 |
| |----------| SP1 Sub SD | ----------
| --------------
| ---------------
|----------| SP2 Root SD |
---------------
The OTrP assumes that a SP managed by TSM1 cannot be managed by TSM2. OTrP segregates SDs and TAs such that a TAM can only manage or
Explicit permission grant should happen. SP can authorize TSM. retrieve data for SDs and TAs that it previously created for the SPs
it represents.
6. OTrP Agent 6. OTrP Agent
OTrP Agent is an Rich Application or SDK that facilitates A TEE and TAs that run inside the TEE don't generally have capability
communication between a TSM and TEE. It also provides interfaces for to communicate to the outside of the hosting device, for example, the
TSM SDK or Client Applications to query and trigger TA installation TEE specified by Global Platform groups [GPTEE]. This calls for a
that the application needs to use. software module in the REE world to handle the network communication.
Each Client Application in REE may carry this communication
functionality but it must also interact with the TEE for the message
exchange. The TEE interaction will vary according to different TEEs.
In order for a Client Application to transparently support different
TEEs, it is imperative to have a common interface for a Client
Application to invoke for exchanging messages with TEEs.
A shared OTrP Agent comes to meed this need. An OTrP Agent is a Rich
Application or SDK that facilitates communication between a TAM and
TEE. It also provides interfaces for TAM SDK or Client Applications
to query and trigger TA installation that the application needs to
use.
This interface for Client Applications may be commonly an Android This interface for Client Applications may be commonly an Android
service call. A Client Application interacts with a TSM, and turns service call for an Android powered device. A Client Application
around to pass messages received from TSM to OTrP Agent. interacts with a TAM, and turns around to pass messages received from
TAM to OTrP Agent.
In all cases, a Client Application needs to be able to identify an In all cases, a Client Application needs to be able to identify an
OTrP Agent that it can use. OTrP Agent that it can use.
6.1. Role of OTrP Agent 6.1. Role of OTrP Agent
OTrP Agent is responsible to communicate with TEE. It takes request An OTrP Agent abstracts the message exchanges with the TEE in a
messages from an application. The input data is mostly from a TSM device. The input data is originated from a TAM that a Client
that an application communicates. An application may also directly Application connects. A Client Application may also directly call
call OTrP Agent for some TA query functions. OTrP Agent for some TA query functions.
OTrP Agent may internally process a request from TSM. At least, it OTrP Agent may internally process a request from TAM. At least, it
needs to know where to route a message, e.g. TEE instance. It needs to know where to route a message, e.g. TEE instance. It
doesn't need to process or verify message content. doesn't need to process or verify message content.
OTrP Agent returns TEE / TFW generated response messages to the OTrP Agent returns TEE / TFW generated response messages to the
caller. OTrP Agent isn't expected to handle any network connection caller. OTrP Agent isn't expected to handle any network connection
with an application or TSM. with an application or TAM.
OTrP Agent only needs to return an OTrP Agent error message if the OTrP Agent only needs to return an OTrP Agent error message if the
TEE is not reachable for some reason. Other errors are represented TEE is not reachable for some reason. Other errors are represented
as response messages returned from the TEE which will then be passed as response messages returned from the TEE which will then be passed
to the TSM. to the TAM.
6.2. OTrP Agent and Global Platform TEE Client API 6.2. OTrP Agent and Global Platform TEE Client API
A Client Application may rely on Global Platform (GP) TEE API for TA A Client Application may use Global Platform (GP) TEE API for TA
communication. OTrP may use the GP TEE Client API but it is internal communication. OTrP may use the GP TEE Client API but it is internal
to OTrP implementation that converts given messages from TSM. More to OTrP implementation that converts given messages from TAM. More
details can be found at [GPTEE]. details can be found at [GPTEECLAPI].
6.3. OTrP Agent Implementation Consideration 6.3. OTrP Agent Implementation Consideration
A Provider should consider methods of distribution, scope and A Provider should consider methods of distribution, scope and
concurrency on device and runtime options when implementing an OTrP concurrency on device and runtime options when implementing an OTrP
Agent. Several non-exhaustive options are discussed below. Agent. Several non-exhaustive options are discussed below.
Providers are encouraged to take advantage of the latest Providers are encouraged to take advantage of the latest
communication and platform capabilities to offer the best user communication and platform capabilities to offer the best user
experience. experience.
6.3.1. OTrP Agent Distribution 6.3.1. OTrP Agent Distribution
OTrP Agent installation is commonly carried out at OEM time. A user OTrP Agent installation is commonly carried out at OEM time. A user
can dynamically download and install an OTrP Agent on-demand. can dynamically download and install an OTrP Agent on-demand.
It is important to ensure a legitimate OTrP Agent is installed and It is important to ensure a legitimate OTrP Agent is installed and
used. If an OTrP Agent is compromised it may send rogue messages to used. If an OTrP Agent is compromised it may send rogue messages to
TSM and TEE and introduce additional risks. TAM and TEE and introduce additional risks.
6.3.2. Number of OTrP Agent 6.3.2. Number of OTrP Agent
We anticipate only one shared OTrP Agent instance in a device. The We anticipate only one shared OTrP Agent instance in a device. The
device's TEE vendor will most probably supply one OTrP Agent. device's TEE vendor will most probably supply one OTrP Agent.
Potentially we expect some open source. Potentially we expect some open source.
With one shared OTrP Agent, the OTrP Agent provider is responsible to With one shared OTrP Agent, the OTrP Agent provider is responsible to
allow multiple TSMs and TEE providers to achieve interoperability. allow multiple TAMs and TEE providers to achieve interoperability.
With a standard OTrP Agent interface, TSM can implement its own SDK With a standard OTrP Agent interface, TAM can implement its own SDK
for its SP Client Applications to work with this OTrP Agent. for its SP Client Applications to work with this OTrP Agent.
Multiple independent OTrP Agent providers can be used as long as they Multiple independent OTrP Agent providers can be used as long as they
have standard interface to a Client Application or TSM SDK. Only one have standard interface to a Client Application or TAM SDK. Only one
OTrP Agent is expected in a device. OTrP Agent is expected in a device.
OTrP Protocol MUST specify a standard way for applications to lookup TAM providers are generally expected to provide SDK for SP
the active OTrP Agent instance in a device. applications to interact with an OTrP Agent for the TAM and TEE
TSM providers are generally expected to provide SDK for SP
applications to interact with OTrP Agent for the TSM and TEE
interaction. interaction.
6.3.3. OTrP Android Service Option 6.4. OTrP Agent Interfaces for Client Applications
OTrP Agent can be a bound service in Android with a service
registration ID that a Client Application can use. This option
allows a Client Application not to depend on any OTrP Agent SDK or
provider.
An OTrP Agent is responsible to detect and work with more than one
TEE if a device has more than one. In this version, there is only
one active TEE such that an OTrP Agent only needs to handle the
active TEE.
6.4. OTrP Agent API for Client Applications
A Client Application shall be responsible for relaying messages A Client Application shall be responsible for relaying messages
between the OTrP agent and the TSM. between the OTrP agent and the TAM.
OTrP Agent APIs are defined below. An OTrP Agent in the form of an
Android bound service can take this to be the functionality it
provides via service call. The OTrP Agent implements this interface.
If a failure is occured during calling API, an error message If a failure is occured during calling OTrP Agent, an error message
described in "Common Errors" section (see Section 7.6) will be described in "Common Errors" section (see Section 7.6) will be
returned. returned.
interface IOTrPAgentService { 6.4.1. ProcessOTrPMessage call
String processMessage(String tsmInMsg) throws OTrPAgentException;
String getTAInformation(String spid, String taid)
throws OTrPAgentException;
}
public class OTrPAgentException extends Throwable {
private int errCode;
}
6.4.1. API processMessage
String processMessage(String tsmInMsg) throws OTrPAgentException;
Description Description
A Client Application will use this method of the OTrP Agent in a A Client Application will use this method of the OTrP Agent in a
device to pass OTrP messages from a TSM. The method is device to pass OTrP messages from a TAM. The method is
responsible for interation with the TEE and for forwarding the responsible for interacting with the TEE and for forwarding the
input message to the TEE. It also returns TEE generated response input message to the TEE. It also returns TEE generated response
message back to the Client Application. message back to the Client Application.
Input Inputs:
tsmInMsg - OTrP message generated in a TSM that is passed to this TAMInMsg - OTrP message generated in a TAM that is passed to this
method from a Client Application. method from a Client Application.
Output Outputs:
A TEE generated OTrP response message (which may be a successful A TEE-generated OTrP response message (which may be a successful
response or be a response message containing an error raised response or be a response message containing an error raised
within the TEE) for the client application to forward to the TSM. within the TEE) for the client application to forward to the TAM.
In the event of the OTrP agent not being able to communicate with In the event of the OTrP agent not being able to communicate with
the TEE, a OTrPAgentException shall be thrown. the TEE, a OTrPAgentException shall be thrown.
6.4.2. API getTAInformation 6.4.2. GetTAInformation call
String getTAInformation(String spid, String taid)
throws OTrPAgentException;
Description Description
A Client Application calls this method to query a TA's A Client Application may quickly query local TEE about a
information. This method is carried out locally by the OTrP Agent previously installed TA without requiring TAM each time if it has
without relying on a TSM if it has had the TEE SP AIK. had the TA's identifier and previously saved TEE SP AIK public key
for TA information integrity verification.
Input
spid - SP identifier of the TA Inputs:
taid - the identifier of the TA {
"TAQuery": {
"spid": "<SP identifier value of the TA>",
"taid": "<The identifier value of the TA>"
}
}
Output Outputs:
The API returns TA signer and TSM signer certificate along with The OTrP Agent is expected to return TA signer and TAM signer
other metadata information about a TA. certificate along with other metadata information about the TA
associated with the given identifier. It follows the underlying
TEE trust model for authoring the local TA query from a Client
Application.
The output is a JSON message that is generated by the TEE. It The output is a JSON message that is generated by the TEE. It
contains the following information: contains the following information:
* TSMID * tamid
* SP ID * SP ID
* TA signer certificate * TA signer certificate
* TSM certificate * TAM certificate
The message is signed with TEE SP AIK private key. The message is signed with TEE SP AIK private key.
The Client Application is expected to consume the response as The Client Application is expected to consume the response as
follows. follows.
The Client Application gets signed TA metadata, in particularly, The Client Application gets signed TA metadata, in particular, the
the TA signer certificate. It is able to verify that the result TA signer certificate. It is able to verify that the result is
is from device by checking signer against TEE SP AIK public key it from device by checking signer against TEE SP AIK public key it
gets in some earlier interaction with TSM. gets in some earlier interaction with TAM.
If this is a new Client Application in the device that hasn't had If this is a new Client Application in the device that hasn't had
TEE SP AIK public key for the response verification, the TEE SP AIK public key for the response verification, the
application can contact TSM first to do GetDeviceState, and TSM application can contact the TAM first to do GetDeviceState, and
will return TEE SP AIK public key to the app for this operation to TAM will return TEE SP AIK public key to the app for this
proceed. operation to proceed.
JSON Message Output Message:
{ {
"TAInformationTBS": { "TAInformationTBS": {
"taid": "<TA Identifier from the input>", "taid": "<TA Identifier from the input>",
"tsmid": "<TSM ID for the Security Domain where this TA "tamid": "<TAM ID for the Security Domain where this TA
resides>", resides>",
"spid": "<The service provider identifier of this TA>", "spid": "<The service provider identifier of this TA>",
"signercert": "<The BASE64 encoded certificate data of the TA "signercert": "<The BASE64 encoded certificate data of the
binary application's signer certificate>", TA binary application's signer certificate>",
"signercacerts": [ // the full list of CA certificate chain "signercacerts": [ // the full list of CA certificate chain
// including the root CA // including the root CA
"cacert": "<The BASE64 encoded CA certificate data of the TA ],
binary application's signer certificate>" "cacert": "<The BASE64 encoded CA certificate data of the TA
], binary application's signer certificate>"
"tsmcert": "<The BASE64 encoded certificate data of the TSM that ],
manages this TA.>", "tamcert": "<The BASE64 encoded certificate data of the TAM
"tsmcacerts": [ // the full list of CA certificate chain that manages this TA.>",
// including the root CA "tamcacerts": [ // the full list of CA certificate chain
"cacert":"<The BASE64 encoded CA certificate data of the TSM // including the root CA
that manages this TA>" ],
] "cacert":"<The BASE64 encoded CA certificate data of the TAM
} that manages this TA>"
} ]
}
}
{ {
"TAInformation": { "TAInformation": {
"payload": "<BASE64URL encoding of the TAInformationTBS "payload": "<The BASE64URL encoding of the TAInformationTBS
JSON above>", JSON above>",
"protected": "<BASE64URL encoded signing algorithm>", "protected": "<BASE64URL encoded signing algorithm>",
"header": { "header": {
"signer": {"<JWK definition of the TEE SP AIK public "signer": {"<JWK definition of the TEE SP AIK public
key>"} key>"}
}, },
"signature": "<signature contents signed by TEE SP AIK private "signature": "<signature contents signed by TEE SP AIK
key BASE64URL encoded>" private key BASE64URL encoded>"
} }
} }
A sample JWK public key representation refers to an example in RFC where the definitions of BASE64 and BASE64URL refer to [RFC4648].
7517 [RFC7517] .
A sample JWK public key representation refers to an example in
[RFC7517].
6.5. Sample End-to-End Client Application Flow 6.5. Sample End-to-End Client Application Flow
6.5.1. Case 1: A New Client Application Uses a TA 6.5.1. Case 1: A New Client Application Uses a TA
1. During the Client Application installation time, the Client 1. During the Client Application installation time, the Client
Application calls TSM to initialize the device preparation step. Application calls TAM to initialize the device preparation step.
A. The Client Application knows it wants to use a Trusted A. The Client Application knows it wants to use a Trusted
Application TA1 but the application doesn'tknow whether TA1 Application TA1 but the application doesn'tknow whether TA1
has been installed or not. It can use GP TEE Client API to has been installed or not. It can use GP TEE Client API
check the existence of TA1 first. If it detects that TA1 [GPTEECLAPI] to check the existence of TA1 first. If it
doesn't exist, it will contact TSM to initiate the detects that TA1 doesn't exist, it will contact TAM to
installation of TA1. Note that TA1 could have been initiate the installation of TA1. Note that TA1 could have
previously installed by other Client Applications from the been previously installed by other Client Applications from
same service provider in the device. the same service provider in the device.
B. The Client Application sends TSM the TA list that it depends B. The Client Application sends the TAM the TA list that it
on. The TSM will query a device for the Security Domains depends on. The TAM will query a device for the Security
and TAs that have been installed, and instructs the device Domains and TAs that have been installed, and instructs the
to install any dependent TAs that have not been installed. device to install any dependent TAs that have not been
installed.
C. In general, TSM has the latest information of TA list and C. In general, the TAM has the latest TA list and their status
their status in a device because all operations are in a device because all operations are instructed by TAM.
instructed by TSM. TSM has such visibility because all TAM has such visibility because all Security Domain deletion
Security Domain deletion and TA deletion are managed by TSM; and TA deletion are managed by the TAM; the TAM could have
the TSM could have stored the state when a TA is installed, stored the state when a TA is installed, updated and
updated and deleted. There is also the possibility that an deleted. There is also the possibility that an update
update command is carried out inside TEE but a response is command is carried out inside TEE but a response is never
never received in TSM. There is also possibility that some received in TAM. There is also possibility that some manual
manual local reset is done in a device that the TSM isn't local reset is done in a device that the TAM isn't aware of
aware of the changes. the changes.
2. TSM generates message: GetDeviceStateRequest 2. The TAM generates message: GetDeviceStateRequest
3. The Client Application passes the JSON message 3. The Client Application passes the JSON message
GetDeviceStateRequest to OTrP Agent API processMessage. The GetDeviceStateRequest to OTrP Agent call ProcessOTrPMessage.
communication between a Client Application and OTrP Agent is up The communication between a Client Application and an OTrP Agent
to the implementation of OTrP Agent. is up to the implementation of the OTrP Agent.
4. OTrP Agent routes the message to the active TEE. Multiple TEE 4. The OTrP Agent routes the message to the active TEE. Multiple
case: it is up to OTrP Agent to figure this out. This TEE case: it is up to OTrP Agent to figure this out. This
specification limits the support to only one active TEE, which specification limits the support to only one active TEE, which
is the typical case today. is the typical case today.
5. The target active TEE processes the received OTrP message, 5. The target active TEE processes the received OTrP message, and
returns a JSON message GetDeviceStateResponse returns a JSON message GetDeviceStateResponse.
6. The OTrP Agent passes the GetDeviceStateResponse to the Client 6. The OTrP Agent passes the GetDeviceStateResponse to the Client
App Application.
7. The Client Application sends GetDeviceStateResponse to TSM 7. The Client Application sends GetDeviceStateResponse to the TAM.
8. TSM processes GetDeviceStateResponse 8. The TAM processes the GetDeviceStateResponse.
A. Extract TEEspaik for the SP, signs TEEspaik with TSM signer
A. Extract TEEspaik for the SP, signs TEEspaik with TAM signer
key key
B. Examine SD list and TA list B. Examine SD list and TA list
9. TSM continues to carry out other actions basing on the need. 9. The TAM continues to carry out other actions based on the need.
The next call could be instructing the device to install a The next call could be instructing the device to install a
dependent TA. dependent TA.
A. Assume a dependent TA isn't in the device yet, the TSM may A. Assume a dependent TA isn't in the device yet, the TAM may
do the following: do the following: (1) create an SD in which to install the
TA by sending a CreateSDRequest message. The message is
B. sent back to the Client Application, and then the OTrP Agent
and TEE to process; (2) install a TA with an
Create a SD to install the TA by sending a message InstallTARequest message.
CreateSDRequest. The message is sent back to the Client
Application, and then OTrP Agent and TEE to process.
Install a TA with a message InstallTARequest.
C. If a Client Application depends on multiple TAs, the Client B. If a Client Application depends on multiple TAs, the Client
Application should expect multiple round trips of the TA Application should expect multiple round trips of the TA
installation message exchanges. installation message exchanges.
10. At the last TSM and TEE operation, TSM returns the signed TEE SP 10. At the last TAM and TEE operation, the TAM returns the signed
AIK public key to the application TEE SP AIK public key to the application.
11. The Client Application shall store the TEEspaik for future 11. The Client Application stores the TEEspaik for future loaded TA
loaded TA trust check purpose. trust check.
12. If the TSM finds that this is a fresh device that does not have 12. If the TAM finds that this is a fresh device that does not have
any SD for the SP yet, then the TSM may move on to create a SD any SD for the SP yet, then the TAM may next create an SD for
for the SP next. the SP.
13. During Client Application installation, the application checks 13. During Client Application installation, the application checks
whether required Trusted Applications are already installed, whether required Trusted Applications are already installed,
which may have been provided by TEE. If needed, it will contact which may have been provided by the TEE. If needed, it will
its TSM service to determine whether the device is ready or contact its TAM service to determine whether the device is ready
install TA list that this application needs. or install TA list that this application needs.
6.5.2. Case 2: A Previously Installed Client Application Calls a TA 6.5.2. Case 2: A Previously Installed Client Application Calls a TA
1. The Client Application checks the device readiness: (a) whether 1. The Client Application checks the device readiness: (a) whether
it has a TEE; (b) whether it has TA that it depends. It may it has a TEE; (b) whether it has TA that it depends. It may
happen that TSM has removed TA this application depends on. happen that TAM has removed the TA this application depends on.
2. The Client Application calls OTrP Agent method "GetTAInformation" 2. The Client Application calls the OTrP Agent to query the TA.
3. OTrP Agent queries the TEE to get TA information. If the given
TA doesn't exist, an error is returned. 3. The OTrP Agent queries the TEE to get TA information. If the
given TA doesn't exist, an error is returned.
4. The Client Application parses the TAInformation message. 4. The Client Application parses the TAInformation message.
5. If the TA doesn't exist, the Client Application calls its TSM to 5. If the TA doesn't exist, the Client Application calls its TAM to
install the TA. If the TA exists, the Client Application install the TA. If the TA exists, the Client Application
proceeds to call the TA. proceeds to call the TA.
7. OTrP Messages 7. OTrP Messages
The main OTrP Protocol component is the set of standard JSON messages The main OTrP component is the set of standard JSON messages created
created by TSM to deliver device SD and TA management commands to a by a TAM to deliver device SD and TA management commands to a device,
device, and device attestation and response messages created by TEE and device attestation and response messages created by TEE to
to respond to TSM OTrP Messages. respond to TAM OTrP Messages.
An OTrP Message is designed to provide end-to-end security. It is An OTrP Message is designed to provide end-to-end security. It is
always signed by its creator. In addition, an OTrP Message is always signed by its creator. In addition, an OTrP Message is
typically encrypted such that only the targeted device TEE or TSM typically encrypted such that only the targeted device TEE or TAM is
provider is able to decrypt and view the actual content. able to decrypt and view the actual content.
7.1. Message Format 7.1. Message Format
OTrP Messages use JSON format for JSON's simple readability and OTrP Messages use the JSON format for JSON's simple readability and
moderate data size in comparison with alternative TLV and XML moderate data size in comparison with alternative TLV and XML
formats. formats. More compact CBOR format may be used as an alternative
choice.
JSON Message security has developed JSON Web Signing and JSON Web JSON Message security has developed JSON Web Signing and JSON Web
Encryption standard in the IETF Workgroup JOSE, see JWS [RFC7515] and Encryption standard in the IETF Workgroup JOSE, see JWS [RFC7515] and
JWE [RFC7516]. The OTrP Messages in this protocol will leverage the JWE [RFC7516]. The OTrP Messages in this protocol will leverage the
basic JWS and JWE to handle JSON signing and encryption. basic JWS and JWE to handle JSON signing and encryption.
7.2. Message Naming Convention 7.2. Message Naming Convention
For each TSM command "xyz"", OTrP Protocol use the following naming For each TAM command "xyz"", OTrP use the following naming convention
convention to represent its raw message content and complete request to represent its raw message content and complete request and
and response messages: response messages:
+-----------------------+----------------+---------------------+ +-----------------------+----------------+---------------------+
| Purpose | Message Name | Example | | Purpose | Message Name | Example |
+-----------------------+----------------+---------------------+ +-----------------------+----------------+---------------------+
| Request to be signed | xyzTBSRequest | CreateSDTBSRequest | | Request to be signed | xyzTBSRequest | CreateSDTBSRequest |
| | | | | | | |
| Request message | xyzRequest | CreateSDRequest | | Request message | xyzRequest | CreateSDRequest |
| | | | | | | |
| Response to be signed | xyzTBSResponse | CreateSDTBSResponse | | Response to be signed | xyzTBSResponse | CreateSDTBSResponse |
| | | | | | | |
skipping to change at page 26, line 39 skipping to change at page 26, line 39
{ {
"<name>TBSResponse": { "<name>TBSResponse": {
<response message content> <response message content>
} }
} }
7.4. Signed Request and Response Message Structure 7.4. Signed Request and Response Message Structure
A signed request message will generally include only one signature, A signed request message will generally include only one signature,
and uses the flattened JWS JSON Serialization Syntax, see and uses the flattened JWS JSON Serialization Syntax, see
Section 7.2.2 in RFC7515 [RFC7515] . Section 7.2.2 in [RFC7515].
A general JWS object looks like the following. A general JWS object looks like the following.
{ {
"payload": "<payload contents>", "payload": "<payload contents>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": { "header": {
<non-integrity-protected header contents>, <non-integrity-protected header contents>,
}, },
"signature":"<signature contents>" "signature": "<signature contents>"
} }
OTrP signed messages only requires the signing algorithm as the OTrP signed messages only require the signing algorithm as the
mandate header in the property "protected". The "non-integrity- mandate header in the property "protected". The "non-integrity-
protected header contents" is optional. protected header contents" is optional.
OTrP signed message will be given an explicit Request or Response OTrP signed message will be given an explicit Request or Response
property name. In other words, a signed Request or Response uses the property name. In other words, a signed Request or Response uses the
following template. following template.
A general JWS object looks like the following. A general JWS object looks like the following.
{ {
skipping to change at page 27, line 26 skipping to change at page 27, line 26
<JWS Message of <name>TBS[Request | Response] <JWS Message of <name>TBS[Request | Response]
} }
} }
With the standard JWS message format, a signed OTrP Message looks With the standard JWS message format, a signed OTrP Message looks
like the following. like the following.
{ {
"<name>[Request | Response]": { "<name>[Request | Response]": {
"payload": "<payload contents of <name>TBS[Request | Response]>", "payload": "<payload contents of <name>TBS[Request | Response]>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": <non-integrity-protected header contents>,
"signature":"<signature contents>" "signature": "<signature contents>"
} }
} }
The top element " <name>[Signed][Request | Response]" cannot be fully The top element " <name>[Signed][Request | Response]" cannot be fully
trusted to match the content because it doesn't participate the trusted to match the content because it doesn't participate in the
signature generation. However, a recipient can always match it with signature generation. However, a recipient can always match it with
the value associated with the property "payload". It purely serves the value associated with the property "payload". It purely serves
to provide a quick reference for reading and method invocation. to provide a quick reference for reading and method invocation.
Furthermore, most properties in an unsigned OTrP messages are Furthermore, most properties in an unsigned OTrP messages are
encrypted to provide end-to-end confidentiality. The only OTrP encrypted to provide end-to-end confidentiality. The only OTrP
message that isn't encrypted is the initial device query message that message that isn't encrypted is the initial device query message that
asks for the device state information. asks for the device state information.
Thus a typical OTrP Message consists of an encrypted and then signed Thus a typical OTrP Message consists of an encrypted and then signed
JSON message. Some transaction data such as transaction ID and TEE JSON message. Some transaction data such as transaction ID and TEE
information may need to be exposed to OTrP Agent for routing purpose. information may need to be exposed to the OTrP Agent for routing
Such information is excluded from JSON encryption. The device's purpose. Such information is excluded from JSON encryption. The
signer certificate itself is encrypted. The overall final message is device's signer certificate itself is encrypted. The overall final
a standard signed JSON message. message is a standard signed JSON message.
As required by JSW/JWE, those JWE and JWS related elements will be As required by JSW/JWE, those JWE and JWS related elements will be
BASE64URL encoded. Other binary data elements specific to the OTrP BASE64URL encoded. Other binary data elements specific to the OTrP
specification are BASE64 encoded. This specification will identify specification are BASE64-encoded. This specification indicates
elements that should be BASE64 and those elements that are to be elements that should be BASE64 and those elements that are to be
BASE64URL encoded. BASE64URL encoded.
7.4.1. Identifying Signing and Encryption Keys for JWS/JWE Messaging 7.4.1. Identifying Signing and Encryption Keys for JWS/JWE Messaging
JWS and JWE messaging allow various options for identifying the JWS and JWE messaging allow various options for identifying the
signing and encryption keys, for example, it allows optional elements signing and encryption keys, for example, it allows optional elements
including "x5c", "x5t" and "kid" in the header to cover various including "x5c", "x5t" and "kid" in the header to cover various
possibilities. possibilities.
In order to protect privacy, it is important that the device's To protect privacy, it is important that the device's certificate is
certificate is released only to a trusted TSM, and that it is released only to a trusted TAM, and that it is encrypted. The TAM
encrypted. The TSM will need to know the device certificate, but will need to know the device certificate, but untrusted parties must
untrusted parties must not be able to get the device certificate. not be able to get the device certificate. All OTrP messaging
All OTrP messaging conversations between a TSM and device begin with conversations between a TAM and device begin with
GetDeviceStateRequest / GetDeviceStateResponse. These messages have GetDeviceStateRequest / GetDeviceStateResponse. These messages have
elements built into them to exchange signing certificates, described elements built into them to exchange signing certificates, described
in the "Detailed Message Specification" section. Any subsequent in the section Section 9. Any subsequent messages in the
messages in the conversation that follow on from this are implicitly conversation that follow on from this implicitly use the same
using the same certificates for signing/encryption, and as a result certificates for signing/encryption, and as a result the certificates
the certificates or references may be ommitted in those subsequent or references may be ommitted in those subsequent messages.
messages.
In other words, the signing key identifier in the use of JWS and JWE In other words, the signing key identifier in the use of JWS and JWE
here may be absent in the subsequent messages after the initial here may be absent in the subsequent messages after the initial
GetDeviceState query. GetDeviceState query.
This has implication on the TEE and TSM implementation: they have to This has an implication on the TEE and TAM implementation: they have
cache the signer certificates for the subsequent message signature to cache the signer certificates for the subsequent message signature
validation in the session. It may be easier for a TSM service to validation in the session. It may be easier for a TAM service to
cache transaction session information but not so for a TEE in a cache transaction session information but not so for a TEE in a
device. A TSM should check a device's capability to decide whether device. A TAM can get a device's capability by checking the response
it should include its TSM signer certificate and OCSP data in each message from a TEE to decide whether it should include its TAM signer
subsequent request message. The device's caching capability is certificate and OCSP data in each subsequent request message. The
reported in GetDeviceStateResponse signerreq parameter. device's caching capability is reported in GetDeviceStateResponse
signerreq parameter.
7.5. JSON Signing and Encryption Algorithms 7.5. JSON Signing and Encryption Algorithms
The OTrP JSON signing algorithm shall use SHA256 or a stronger hash The OTrP JSON signing algorithm shall use SHA256 or a stronger hash
method with respective key type. JSON Web Algorithm RS256 or ES256 method with respective key type. JSON Web Algorithm RS256 or ES256
[RFC7518] SHALL be used for RSA with SHA256 and ECDSA with SHA256. [RFC7518] SHALL be used for RSA with SHA256 and ECDSA with SHA256.
If RSA with SHA256 is used, the JSON web algorithm representation is If RSA with SHA256 is used, the JSON web algorithm representation is
as follows. as follows.
{"alg":"RS256"} {"alg":"RS256"}
skipping to change at page 29, line 19 skipping to change at page 29, line 19
If ECSDA with P-256 curve and SHA256 are used for signing, the JSON If ECSDA with P-256 curve and SHA256 are used for signing, the JSON
signing algorithm representation is as follows. signing algorithm representation is as follows.
{"alg":"ES256"} {"alg":"ES256"}
The value for the "protected" field will be the following. The value for the "protected" field will be the following.
eyJhbGciOiJFUzI1NiJ9 eyJhbGciOiJFUzI1NiJ9
Thus a common OTrP signed message with ES256 looks like the Thus, a common OTrP signed message with ES256 looks like the
following. following.
{ {
"payload": "<payload contents>", "payload": "<payload contents>",
"protected": "eyJhbGciOiJFUzI1NiJ9", "protected": "eyJhbGciOiJFUzI1NiJ9",
"signature":"<signature contents>" "signature": "<signature contents>"
} }
The OTrP JSON message encryption algorithm should use one of the The OTrP JSON message encryption algorithm SHOULD use one of the
supported algorithms defined in the later chapter of this document. supported algorithms defined in the later chapter of this document.
JSON encryption uses a symmetric key as its "Content Encryption Key JSON encryption uses a symmetric key as its "Content Encryption Key
(CEK)". This CEK is encrypted or wrapped by a recipient's key. OTrP (CEK)". This CEK is encrypted or wrapped by a recipient's key. The
recipient typically has an asymmetric key pair. Therefore CEK will OTrP recipient typically has an asymmetric key pair. Therefore, the
be encrypted by the recipient's public key. CEK will be encrypted by the recipient's public key.
Symmetric encryption shall use the following algorithm. A compliant implementation shall support the following symmetric
encryption algorithm and anticipate future new algorithms.
{"enc":"A128CBC-HS256"} {"enc":"A128CBC-HS256"}
This algorithm represents encryption with AES 128 in CBC mode with This algorithm represents encryption with AES 128 in CBC mode with
HMAC SHA 256 for integrity. The value of the property "protected" in HMAC SHA 256 for integrity. The value of the property "protected" in
a JWE message will be a JWE message will be
eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
An encrypted JSON message looks like the following. An encrypted JSON message looks like the following.
skipping to change at page 30, line 28 skipping to change at page 30, line 28
"ciphertext": "<Encrypted data over the JSON plaintext "ciphertext": "<Encrypted data over the JSON plaintext
(BASE64URL)>", (BASE64URL)>",
"tag": "<JWE authentication tag (BASE64URL)>" "tag": "<JWE authentication tag (BASE64URL)>"
} }
OTrP doesn't use JWE AAD (Additional Authenticated Data) because each OTrP doesn't use JWE AAD (Additional Authenticated Data) because each
message is always signed after the message is encrypted. message is always signed after the message is encrypted.
7.5.1. Supported JSON Signing Algorithms 7.5.1. Supported JSON Signing Algorithms
The following JSON signature algorithm are mandatory support in TEE The following JSON signature algorithm is mandatory support in the
and TSM: TEE and TAM:
o RS256 o RS256
ES256 is optional to support. ES256 is optional to support.
7.5.2. Support JSON Encryption Algorithms 7.5.2. Support JSON Encryption Algorithms
The following JSON authenticated encryption algorithm is mandatory The following JSON authenticated encryption algorithm is mandatory
support in TEE and TSM. support in TEE and TAM.
o A128CBC-HS256 o A128CBC-HS256
A256CBC-HS512 is optional to support. A256CBC-HS512 is optional to support.
7.5.3. Supported JSON Key Management Algorithms 7.5.3. Supported JSON Key Management Algorithms
The following JSON key management algorithm is mandatory support in The following JSON key management algorithm is mandatory support in
TEE and TSM. TEE and TAM.
o RSA1_5 o RSA1_5
ECDH-ES+A128KW and ECDH-ES+A256KW are optional to support. ECDH-ES+A128KW and ECDH-ES+A256KW are optional to support.
7.6. Common Errors 7.6. Common Errors
An OTrP Response message typically needs to report operation status An OTrP Response message typically needs to report the operation
and error causes if an operation fails. The following JSON message status and error causes if an operation fails. The following JSON
elements should be used across all OTrP Messages. message elements should be used across all OTrP Messages.
"status": "pass | fail" "status": "pass | fail"
"reason": { "reason": {
"error-code": "<error code if there is any>", "error-code": "<error code if there is any>",
"error-message": "<error message>" "error-message": "<error message>"
} }
"ver": "<version string>" "ver": "<version string>"
7.7. OTrP Message List 7.7. OTrP Message List
The following table lists the OTrP commands and therefore The following table lists the OTrP commands and therefore
corresponding Request and Response messages defined in this corresponding Request and Response messages defined in this
specification. Additional messages may be added in the future when specification. Additional messages may be added in the future when
new task messages are needed. new task messages are needed.
GetDeviceState - GetDeviceState -
A TSM queries a device's current state with a message A TAM queries a device's current state with a message
GetDeviceStateRequest. A device TEE will report its version, its GetDeviceStateRequest. A device TEE will report its version, its
FW version, and list of all SD and TA in the device that is FW version, and list of all SDs and TAs in the device that is
managed by the requesting TSM. TSM may determine whether the managed by the requesting TAM. TAM may determine whether the
device is trustworthy and decide to carry out additional commands device is trustworthy and decide to carry out additional commands
according to the response from this query. according to the response from this query.
CreateSD - CreateSD -
A TSM instructs a device TEE to create a SD for a SP. The A TAM instructs a device TEE to create an SD for an SP. The
recipient TEE will check whether the requesting TSM is recipient TEE will check whether the requesting TAM is
trustworthy. trustworthy.
UpdateSD - UpdateSD -
A TSM instructs a device TEE to update an existing SD. A typical A TAM instructs a device TEE to update an existing SD. A typical
update need comes from SP certificate change, TSM certificate update need comes from SP certificate change, TAM certificate
change and so on. The recipient TEE will verify whether the TSM change and so on. The recipient TEE will verify whether the TAM
is trustworthy and owns the SD. is trustworthy and owns the SD.
DeleteSD - DeleteSD -
A TSM instructs a device TEE to delete an existing SD. A TEE A TAM instructs a device TEE to delete an existing SD. A TEE
conditionally deletes TAs loaded in the SD according to a request conditionally deletes TAs loaded in the SD according to a request
parameter. A SD cannot be deleted until all TAs in this SD are parameter. An SD cannot be deleted until all TAs in this SD are
deleted. If this is the last SD for a SP, TEE can also delete deleted. If this is the last SD for an SP, TEE MAY also delete
TEE SP AIK key for this SP. TEE SP AIK key for this SP.
InstallTA - InstallTA -
A TSM instructs a device to install a TA into a SD for a SP. TEE A TAM instructs a device to install a TA into an SD for a SP.
in a device will check whether the TSM and TA are trustworthy. The TEE in a device will check whether the TAM and TA are
trustworthy.
UpdateTA - UpdateTA -
A TSM instructs a device to update a TA into a SD for a SP. The A TAM instructs a device to update a TA into an SD for an SP.
change may commonly be bug fix for a previously installed TA. The change may commonly be bug fix for a previously installed TA.
DeleteTA - DeleteTA -
A TSM instructs a device to delete a TA. TEE in a device will A TAM instructs a device to delete a TA. The TEE in a device
check whether the TSM and TA are trustworthy. will check whether the TAM and TA are trustworthy.
7.8. OTrP Request Message Routing Rules 7.8. OTrP Request Message Routing Rules
For each command that a TSM wants to send to a device, the TSM For each command that a TAM wants to send to a device, the TAM
generates a request message. This is typically triggered by a Client generates a request message. This is typically triggered by a Client
Application that uses the TSM. The Client Application initiates Application that uses the TAM. The Client Application initiates
contact with the TSM and receives TSM OTrP Request messages according contact with the TAM and receives TAM OTrP Request messages according
to the TSM's implementation. The Client Application forwards the to the TAM's implementation. The Client Application forwards the
OTrP message to an OTrP Agent in the device, which in turn sends the OTrP message to an OTrP Agent in the device, which in turn sends the
message to the active TEE in the device. message to the active TEE in the device.
The current version of specification assumes that each device has The current version of this specification assumes that each device
only one active TEE, and OTrP Agent is responsible to connect to the has only one active TEE, and the OTrP Agent is responsible to connect
active TEE. This is the case today with devices in the market. to the active TEE. This is the case today with devices in the
market.
Upon TEE responding with a request, the OTrP Agent gets OTrP response When the TEE responds to a request, the OTrP Agent gets the OTrP
messages back to the Client Application that sends the request. In response messages back to the Client Application that sent the
case the target TEE fails to respond the request, the OTrP Agent will request. In case the target TEE fails to respond to the request, the
be responsible to generate an error message to reply the Client OTrP Agent will be responsible to generate an error message to reply
Application. The Client Application forwards any data it received to the Client Application. The Client Application forwards any data it
its TSM. received to its TAM.
7.8.1. SP Anonymous Attestation Key (SP AIK) 7.8.1. SP Anonymous Attestation Key (SP AIK)
When the first new Security Domain is created in TEE for a SP, a new When the first new Security Domain is created in a TEE for an SP, a
key pair is generated and associated with this SP. This key pair is new key pair is generated and associated with this SP. This key pair
used for future device attestation to the service provider instead of is used for future device attestation to the service provider instead
using device's TEE key pair. of using the device's TEE key pair.
8. Detailed Messages Specification 8. Transport Protocol Support
The OTrP message exchange between a TEE device and TAM generally
takes place between a Client Application in REE and TAM. A device
that is capable to run a TEE and PKI based cryptographic attestation
isn't generally resource constraint to carry out standard HTTPS
connections. A compliant device and TAM SHOULD support HTTPs.
9. Detailed Messages Specification
For each message in the following sections all JSON elements are For each message in the following sections all JSON elements are
mandatory if it isn't explicitly indicated as optional. mandatory if not explicitly indicated as optional.
8.1. GetDeviceState 9.1. GetDeviceState
This is the first command that a TSM will query a device. This This is the first command that a TAM will send to a device. This
command is triggered when a SP's Client Application contacts its TSM command is triggered when an SP's Client Application contacts its TAM
to check whether the underlying device is ready for TA operations. to check whether the underlying device is ready for TA operations.
This command queries a device's current TEE state. A device TEE will This command queries a device's current TEE state. A device TEE will
report its version, its FW version, and list of all SD and TA in the report its version, its FW version, and list of all SDs and TAs in
device that is managed by the requesting TSM. TSM may determine the device that is managed by the requesting TAM. TAM may determine
whether the device is trustworthy and decide to carry out additional whether the device is trustworthy and decide to carry out additional
commands according to the response from this query. commands according to the response from this query.
The request message of this command is signed by TSM. The response The request message of this command is signed by the TAM. The
message from TEE is encrypted. A random message encryption key (MK) response message from the TEE is encrypted. A random message
is generated by TEE, and this encrypted key is encrypted by the encryption key (MK) is generated by TEE, and this encrypted key is
receiving TSM public key such that only the TSM who sent the request encrypted by the TAM's public key such that only the TAM that sent
is able to decrypt and view the response message. the request is able to decrypt and view the response message.
8.1.1. GetDeviceStateRequest message 9.1.1. GetDeviceStateRequest message
{ {
"GetDeviceStateTBSRequest": { "GetDeviceStateTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<Unique request ID>", "rid": "<Unique request ID>",
"tid": "<transaction ID>", "tid": "<transaction ID>",
"ocspdat": "<OCSP stapling data of TSM certificate>", "ocspdat": [<a list of OCSP stapling data>"],
"icaocspdat": "<OCSP stapling data for TSM CA certificates>", "supportedsigalgs": [<array of supported signing algorithms>]
"supportedsigalgs": "<comma separated signing algorithms>"
} }
} }
The request message consists of the following data elements: The request message consists of the following data elements:
ver - version of the message format ver - version of the message format
rid - a unique request ID generated by the TSM rid - a unique request ID generated by the TAM
tid - a unique transaction ID to trace request and response. This tid - a unique transaction ID to trace request and response. This
can be from a prior transaction's tid field, and can be used in can be from a prior transaction's tid field, and can be used in
the subsequent message exchanges in this TSM session. The subsequent message exchanges in this TAM session. The
combination of rid and tid should be made unique. combination of rid and tid MUST be made unique.
ocspdat - OCSP stapling data for the TSM certificate. The TSM
provides OCSP data such that a recipient TEE can validate the
validity of the TSM certificate without making its own external
OCSP service call. This is a mandate field.
icaocspdat - OCSP stapling data for the intermediate CA ocspdat - A list of OCSP stapling data respectively for the TAM
certificates of the TSM certificate up to the root. A TEE side certificate and each of the CA certificates up to the root
can cache CA OCSP data such that this value isn't needed in each certificate. The TAM provides OCSP data such that a recipient
call. TEE can validate the TAM certificate chain revocaton status
without making its own external OCSP service call. A TEE MAY
cache the CA OCSP data such that the array may contain only the
OCSP stapling data for the TAM certificate in subsequent
exchanges. This is a mandatory field.
supportedsigalgs - an optional property to list the signing supportedsigalgs - an optional property to list the signing
algorithms that TSM is able to support. A recipient TEE should algorithms that the TAM is able to support. A recipient TEE MUST
choose algorithm in this list to sign its response message if choose an algorithm in this list to sign its response message if
this property is present in a request. this property is present in a request. If it is absent, the TEE
may use any compliant signing algorithm that is listed as
mandatory support in this specification.
The final request message is JSON signed message of the above raw The final request message is JSON signed message of the above raw
JSON data with TSM's certificate. JSON data with TAM's certificate.
{ {
"GetDeviceStateRequest": { "GetDeviceStateRequest": {
"payload":"<BASE64URL encoding of the GetDeviceStateTBSRequest "payload": "<BASE64URL encoding of the GetDeviceStateTBSRequest
JSON above>", JSON above>",
"protected": "<BASE64URL encoded signing algorithm>", "protected": "<BASE64URL encoded signing algorithm>",
"header": { "header": {
"x5c": "<BASE64 encoded TSM certificate chain up to the "x5c": "<BASE64 encoded TAM certificate chain up to the
root CA certificate>" root CA certificate>"
}, },
"signature":"<signature contents signed by TSM private key>" "signature":"<signature contents signed by TAM private key>"
} }
} }
The signing algorithm should use SHA256 with respective key type. The signing algorithm SHOULD use SHA256 with respective key type.
The mandatory algorithm support is the RSA signing algorithm. The The mandatory algorithm support is the RSA signing algorithm. The
signer header "x5c" is used to include the TSM signer certificate up signer header "x5c" is used to include the TAM signer certificate up
to the root CA certificate. to the root CA certificate.
8.1.2. Request processing requirements at a TEE 9.1.2. Request processing requirements at a TEE
Upon receiving a request message GetDeviceStateRequest at a TEE, the Upon receiving a request message GetDeviceStateRequest at a TEE, the
TEE must validate a request: TEE MUST validate a request:
1. Validate JSON message signing 1. Validate JSON message signing. If it doesn't pass, an error
message is returned.
2. Validate that the request TSM certificate is chained to a trusted 2. Validate that the request TAM certificate is chained to a trusted
CA that the TEE embeds as its trust anchor. CA that the TEE embeds as its trust anchor.
* Cache the CA OCSP stapling data and certificate revocation * Cache the CA OCSP stapling data and certificate revocation
check status for other subsequent requests. check status for other subsequent requests.
* A TEE can use its own clock time for the OCSP stapling data * A TEE can use its own clock time for the OCSP stapling data
validation. validation.
3. Collect Firmware signed data 3. Collect Firmware signed data
* This is a capability in ARM architecture that allows a TEE to * This is a capability in ARM architecture that allows a TEE to
query Firmware to get FW signed data. query Firmware to get FW signed data.
4. Collect SD information for the SD owned by this TSM 4. Collect SD information for the SD owned by this TAM
8.1.3. Firmware Signed Data 9.1.3. Firmware Signed Data
Firmware isn't expected to process or produce JSON data. It is Firmware isn't expected to process or produce JSON data. It is
expected to just sign some raw bytes of data. expected to just sign some raw bytes of data.
The data to be signed by TFW key needs be some unique random data The data to be signed by TFW key needs be some unique random data
each time. The (UTF-8 encoded) "tid" value from the each time. The (UTF-8 encoded) "tid" value from the
GetDeviceStateTBSRequest shall be signed by the firmware. TSM isn't GetDeviceStateTBSRequest shall be signed by the firmware. TAM isn't
expected to parse TFW data except the signature validation and signer expected to parse TFW data except the signature validation and signer
trust path validation. trust path validation.
It is possible that a TEE can get some valid TFW signed data from It is possible that a TEE can get some valid TFW signed data from
another device. This is part of the TEE trust assumption where TSM another device. The TEE is responsible to validate TFW integrity to
will trust the TFW data supplied by the TEE. The TFW trust is more ensure that the underlying device firmware is trustworthy. A TAM
concerned by TEE than a TSM where a TEE needs to ensure that the trusts the TEE and the TFW trust status check carried out by the TEE.
underlying device firmware is trustworthy.
TfwData: { TfwData: {
"tbs": "<TFW to be signed data, BASE64 encoded>", "tbs": "<TFW to be signed data, BASE64 encoded>",
"cert": "<BASE64 encoded TFW certificate>", "cert": "<BASE64 encoded TFW certificate>",
"sigalg": "Signing method", "sigalg": "Signing method",
"sig": "<Tfw signed data, BASE64 encoded>" "sig": "<TFW signed data, BASE64 encoded>"
} }
It is expected that FW use a standard signature methods for maximal It is expected that a FW uses standard signature methods for maximal
interoperability with TSM providers. The mandatory support list of interoperability with TAM providers. The mandatory support list of
signing algorithm is RSA with SHA256. signing algorithm is RSA with SHA256.
The JSON object above is constructed by TEE with data returned from The JSON object above is constructed by a TEE with data returned from
FW. It isn't a standard JSON signed object. The signer information the FW. It isn't a standard JSON signed object. The signer
and data to be signed must be specially processed by TSM according to information and data to be signed must be specially processed by a
definition given here. The data to be signed is the raw data. TAM according to the definition given here. The data to be signed is
the raw data.
8.1.3.1. Supported Firmware Signature Methods 9.1.3.1. Supported Firmware Signature Methods
TSM providers shall support the following signature methods. A TAM providers shall support the following signature methods. A
firmware provider can choose one of the methods in signature firmware provider can choose one of the methods in signature
generation. generation.
o RSA with SHA256 o RSA with SHA256
o ECDSA with SHA 256 o ECDSA with SHA 256
The value of "sigalg" in the TfwData JSON message should use one of
The value of "sigalg" in the TfwData JSON message SHOULD use one of
the following: the following:
o RS256 o RS256
o ES256 o ES256
8.1.4. Post Conditions 9.1.4. Post Conditions
Upon successful request validation, the TEE information is collected. Upon successful request validation, the TEE information is collected.
There is no change in the TEE in the device. There is no change in the TEE in the device.
The response message shall be encrypted where the encryption key The response message shall be encrypted where the encryption key
shall be a symmetric key that is wrapped by TSM's public key. The shall be a symmetric key that is wrapped by TAM's public key. The
JSON Content Encryption Key (CEK) is used for this purpose. JSON Content Encryption Key (CEK) is used for this purpose.
8.1.5. GetDeviceStateResponse Message 9.1.5. GetDeviceStateResponse Message
The message has the following structure. The message has the following structure.
{ {
"GetDeviceTEEStateTBSResponse": { "GetDeviceTEEStateTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "pass | fail", "status": "pass | fail",
"rid": "<the request ID from the request message>", "rid": "<the request ID from the request message>",
"tid": "<the transaction ID from the request message>", "tid": "<the transaction ID from the request message>",
"signerreq": "true | false about whether TSM needs to send "signerreq": true | false // about whether TAM needs to send
signer data again in subsequent messages", signer data again in subsequent messages,
"edsi": "<Encrypted JSON dsi information>" "edsi": "<Encrypted JSON DSI information>"
} }
} }
where where
signerreq - true if the TSM should send its signer certificate and signerreq - true if the TAM should send its signer certificate and
OCSP data again in the subsequent messages. The value may be OCSP data again in the subsequent messages. The value may be
"false" if the TEE caches the TSM's signer certificate and OCSP "false" if the TEE caches the TAM's signer certificate and OCSP
status. status.
rid - the request ID from the request message rid - the request ID from the request message
tid - the tid from the request message tid - the tid from the request message
edsi - the main data element whose value is JSON encrypted message edsi - the main data element whose value is JSON encrypted message
over the following Device State Information (DSI). over the following Device State Information (DSI).
The Device State Information (DSI) message consists of the following. The Device State Information (DSI) message consists of the following.
{ {
"dsi": { "dsi": {
"tfwdata": { "tfwdata": {
"tbs": "<TFW to be signed data is the tid>" "tbs": "<TFW to be signed data is the tid>"
"cert": "<BASE64 encoded TFW certificate>", "cert": "<BASE64 encoded TFW certificate>",
"sigalg": "Signing method", "sigalg": "Signing method",
"sig": "<Tfw signed data, BASE64 encoded>" "sig": "<TFW signed data, BASE64 encoded>"
}, },
"tee": { "tee": {
"name": "<TEE name>", "name": "<TEE name>",
"ver": "<TEE version>", "ver": "<TEE version>",
"cert": "<BASE64 encoded TEE cert>", "cert": "<BASE64 encoded TEE cert>",
"cacert": "<JSON array value of CA certificates up to "cacert": "<JSON array value of CA certificates up to
the root CA>", the root CA>",
"sdlist": { "sdlist": {
"cnt": "<Number of SD owned by this TSM>", "cnt": "<Number of SD owned by this TAM>",
"sd": [ "sd": [
{ {
"name": "<SD name>", "name": "<SD name>",
"spid": "<SP owner ID of this SD>", "spid": "<SP owner ID of this SD>",
"talist": [ "talist": [
{ {
"taid": "<TA application identifier>", "taid": "<TA application identifier>",
"taname": "<TA application friendly "taname": "<TA application friendly
name>" // optional name>" // optional
} }
skipping to change at page 39, line 31 skipping to change at page 40, line 31
} }
], ],
"iv": "<BASE64URL encoded IV data>", "iv": "<BASE64URL encoded IV data>",
"ciphertext": "<Encrypted data over the JSON object of dsi "ciphertext": "<Encrypted data over the JSON object of dsi
(BASE64URL)>", (BASE64URL)>",
"tag": "<JWE authentication tag (BASE64URL)>" "tag": "<JWE authentication tag (BASE64URL)>"
} }
} }
} }
The CEK will be encrypted by the TSM public key in the device. The The CEK will be encrypted by the TAM public key in the device. The
TEE signed message has the following structure. TEE signed message has the following structure.
{ {
"GetDeviceTEEStateResponse": { "GetDeviceTEEStateResponse": {
"payload": "<BASE64URL encoding of the JSON message "payload": "<BASE64URL encoding of the JSON message
GetDeviceTEEStateTBSResponse>", GetDeviceTEEStateTBSResponse>",
"protected": "<BASE64URL encoding of signing algorithm>", "protected": "<BASE64URL encoding of signing algorithm>",
"signature": "<BASE64URL encoding of the signature value>" "signature": "<BASE64URL encoding of the signature value>"
} }
} }
The signing algorithm shall use SHA256 with respective key type, see The signing algorithm shall use SHA256 with respective key type, see
Section Section 7.5.1. Section 7.5.1.
The final response message GetDeviceStateResponse consists of array The final GetDeviceStateResponse response message consists of an
of TEE response. A typical device will have only one active TEE. An array of TEE responses.
OTrP Agent is responsible to collect TEE response for all active TEEs
in the future.
{ {
"GetDeviceStateResponse": [ // JSON array "GetDeviceStateResponse": [ // JSON array
{"GetDeviceTEEStateResponse": ...}, {"GetDeviceTEEStateResponse": ...},
... ...
{"GetDeviceTEEStateResponse": ...} {"GetDeviceTEEStateResponse": ...}
] ]
} }
8.1.6. Error Conditions 9.1.6. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error may occur if a request isn't valid or the TEE runs into some
error. The list of possible error conditions is the following. error. The list of possible error conditions is the following.
ERR_REQUEST_INVALID The TEE meets the following conditions with a ERR_REQUEST_INVALID The TEE meets the following conditions with a
request message: (1) The request from a TSM has an invalid message request message: (1) The request from a TAM has an invalid message
structure; mandatory information is absent in the message. structure; mandatory information is absent in the message; or an
undefined member or structure is included. (2) TEE fails to verify undefined member or structure is included. (2) TEE fails to verify
signature of the message or fails to decrypt its contents. (3) etc. the signature of the message or fails to decrypt its contents.
ERR_UNSUPPORTED_MSG_VERSION TEE receives the version of message that ERR_UNSUPPORTED_MSG_VERSION The TEE receives a version of message
TEE can't deal with. that the TEE can't deal with.
ERR_UNSUPPORTED_CRYPTO_ALG TEE receives a request message encoded ERR_UNSUPPORTED_CRYPTO_ALG The TEE receives a request message
with cryptographic algorithms that TEE doesn't support. encoded with a cryptographic algorithm that the TEE doesn't
support.
ERR_TFW_NOT_TRUSTED TEE may consider the underlying device firmware ERR_TFW_NOT_TRUSTED The TEE considers the underlying device firmware
be not trustworthy. be not trustworthy.
ERR_TSM_NOT_TRUSTED TEE needs to make sure whether the TSM is ERR_TAM_NOT_TRUSTED The TEE needs to make sure whether the TAM is
trustworthy by checking the validity of TSM certificate and OCSP trustworthy by checking the validity of the TAM certificate and
stapling data and so on. If TEE finds TSM is not reliable, it may OCSP stapling data and so on. If the TEE finds the TAM is not
return this error code. reliable, it returns this error code.
ERR_TEE_FAIL TEE fails to respond to a TSM request. The OTrP Agent ERR_TEE_FAIL If the TEE fails to process a request because of its
will construct an error message in responding the TSM's request. internal error but is able to sign an error response message, it
And also if TEE fails to process a request because of its internal will return this error code.
error, it will return this error code.
ERR_AGENT_TEE_FAIL The TEE failed to respond to a TAM request. The
OTrP Agent will construct an error message in responding to the
TAM's request. The error message will not be signed.
The response message will look like the following if the TEE signing The response message will look like the following if the TEE signing
can work to sign the error response message. can work to sign the error response message.
{ {
"GetDeviceTEEStateTBSResponse": { "GetDeviceTEEStateTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "fail", "status": "fail",
"rid": "<the request ID from the request message>", "rid": "<the request ID from the request message>",
"tid": "<the transaction ID from the request message>", "tid": "<the transaction ID from the request message>",
"reason": {"error-code":"<error code>"} "reason": {"error-code":"<error code>"}
"supportedsigalgs": "<signature algorithms TEE supports>" "supportedsigalgs": [<an array of signature algorithms that
the TEE supports>]
} }
} }
where where
supportedsigalgs - an optional property to list the JWS signing supportedsigalgs - an optional property to list the JWS signing
algorithms that the active TEE supports. When a TSM sends a algorithms that the active TEE supports. When a TAM sends a
signed message that the TEE isn't able to validate, it can signed message that the TEE isn't able to validate, it can
include signature algorithms that it is able to consume in this include signature algorithms that it is able to consume in this
status report. A TSM can generate a new request message to retry status report. A TAM can generate a new request message to retry
the management task with a TEE supported signing algorithm. the management task with a TEE-supported signing algorithm.
If TEE isn't able to sign an error message, a general error message If the TEE isn't able to sign an error message due to an internal
should be returned. device error, a general error message should be returned by the OTrP
Agent.
8.1.7. TSM Processing Requirements 9.1.7. TAM Processing Requirements
Upon receiving a message of the type GetDeviceStateResponse at a TSM, Upon receiving a GetDeviceStateResponse message at a TAM, the TAM
the TSM should validate the following. MUST validate the following.
o Parse to get list of GetDeviceTEEStateResponse JSON object o Parse to get list of GetDeviceTEEStateResponse JSON objects
o Parse the JSON "payload" property and decrypt the JSON element o Parse the JSON "payload" property and decrypt the JSON element
"edsi" "edsi". The decrypted message contains the TEE signer
certificate.
o The decrypted message contains the TEE signer certificate
o Validate GetDeviceTEEStateResponse JSON signature. The signer o Validate the GetDeviceTEEStateResponse JSON signature. The signer
certificate is extracted from the decrypted message in the last certificate is extracted from the decrypted message in the last
step. step.
o Extract TEE information and check it against its TEE acceptance o Extract TEE information and check it against its TEE acceptance
policy. policy.
o Extract TFW signed element, and check the signer and data o Extract the TFW signed element, and check the signer and data
integration against its TFW policy integration against its TFW policy.
o Check the SD list and TA list and prepare for a subsequent command o Check the SD list and TA list and prepare for a subsequent command
such as "CreateSD" if it needs to have a new SD for a SP. such as "CreateSD" if it needs to have a new SD for an SP.
8.2. Security Domain Management 9.2. Security Domain Management
8.2.1. CreateSD 9.2.1. CreateSD
This command is typically preceded with GetDeviceState command that This command is typically preceded with a GetDeviceState command that
has acquired the device information of the target device by the TSM. has acquired the device information of the target device by the TAM.
TSM sends such a command to instruct a TEE to create a new Security The TAM sends such a command to instruct a TEE to create a new
Domain for a SP. Security Domain for an SP.
A TSM sends an OTrP Request message CreateSDRequest to a device TEE A TAM sends an OTrP CreateSDRequest Request message to a device TEE
to create a Security Domain for a SP. Such a request is signed by to create a Security Domain for an SP. Such a request is signed by
TSM where the TSM signer may or may not be the same as the SP's TA the TAM where the TAM signer may or may not be the same as the SP's
signer certificate. The resulting SD is associated with two TA signer certificate. The resulting SD is associated with two
identifiers for future management: identifiers for future management:
o TSM as the owner. The owner identifier is a registered unique TSM o TAM as the owner. The owner identifier is a registered unique TAM
ID that is stored in the TSM certificate. ID that is stored in the TAM certificate.
o SP identified by its TA signer certificate as the authorization. o SP identified by its TA signer certificate as the authorization.
A TSM can add more than one SP certificates to a SD. A TAM can add more than one SP certificate to an SD.
A Trusted Application that is signed by a matching SP signer A Trusted Application that is signed by a matching SP signer
certificate for a SD is eligible to be installed into that SD. The certificate for an SD is eligible to be installed into that SD. The
TA installation into a SD by a subsequent InstallTARequest message TA installation into an SD by a subsequent InstallTARequest message
may be instructed from TSM or a Client Application. may be instructed from a TAM.
8.2.1.1. CreateSDRequest Message 9.2.1.1. CreateSDRequest Message
The request message for CreateSD has the following JSON format. The request message for CreateSD has the following JSON format.
{ {
"CreateSDTBSRequest": { "CreateSDTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<unique request ID>", "rid": "<unique request ID>",
"tid": "<transaction ID>", // this may be from prior message "tid": "<transaction ID>", // this may be from prior message
"tee": "<TEE routing name from the DSI for the SD's target>", "tee": "<TEE routing name from the DSI for the SD's target>",
"nextdsi": "true | false", "nextdsi": true | false,
"dsihash": "<hash of DSI returned in the prior query>", "dsihash": "<hash of DSI returned in the prior query>",
"content": ENCRYPTED { // this piece of JSON data will be "content": ENCRYPTED { // this piece of JSON data will be
// encrypted // encrypted
"spid": "<SP ID value>", "spid": "<SP ID value>",
"sdname": "<SD name for the domain to be created>", "sdname": "<SD name for the domain to be created>",
"spcert": "<BASE64 encoded SP certificate>", "spcert": "<BASE64 encoded SP certificate>",
"tsmid": "<An identifiable attribute of the TSM "tamid": "<An identifiable attribute of the TAM
certificate>", certificate>",
"did": "<SHA256 hash of the TEE cert>" "did": "<SHA256 hash of the TEE cert>"
} }
} }
} }
In the message, In the message,
rid - A unique value to identify this request rid - A unique value to identify this request
tid - A unique value to identify this transaction. It can have the tid - A unique value to identify this transaction. It can have the
same value for the tid in the preceding GetDeviceStateRequest. same value for the tid in the preceding GetDeviceStateRequest.
tee - TEE ID returned from the previous response tee - TEE ID returned from the previous GetDeviceStateResponse.
GetDeviceStateResponse
nextdsi - Indicates whether the up to date Device State Information nextdsi - Indicates whether the up-to-date Device State Information
(DSI) should be returned in the response to this request. (DSI) is expected in the response from the TEE to this request.
dsihash - The BASE64 encoded SHA256 hash value of the DSI data dsihash - The BASE64-encoded SHA256 hash value of the DSI data
returned in the prior TSM operation with this target TEE. This returned in the prior TAM operation with this target TEE. This
value is always included such that a receiving TEE can check value is always included such that a receiving TEE can check
whether the device state has changed since its last query. It whether the device state has changed since its last query. It
helps enforce SD update order in the right sequence without helps enforce SD update order in the right sequence without
accidently overwrite an update that was done simultaneously. accidently overwriting an update that was done simultaneously.
content - The "content" is a JSON encrypted message that includes content - The "content" is a JSON encrypted message that includes
actual input for the SD creation. The encryption key is TSMmk that actual input for the SD creation. The encryption key is TAMmk that
is encrypted by the target TEE's public key. The entire message is is encrypted by the target TEE's public key. The entire message is
signed by the TSM private key TSMpriv. A separate TSMmk isn't used signed by the TAM private key TAMpriv. A separate TAMmk isn't used
in the latest specification because JSON encryption will use a in the latest specification because JSON encryption will use a
content encryption key for exactly the same purpose. content encryption key for exactly the same purpose.
spid - A unique id assigned by the TSM for its SP. It should be spid - A unique id assigned by the TAM for its SP. It should be
unique within a TSM namespace. unique within a TAM namespace.
sdname - a name unique to the SP. TSM should ensure it is unique sdname - a name unique to the SP. TAM should ensure it is unique
for each SP. for each SP.
spcert - The SP's TA signer certificate is included in the request. spcert - The SP's TA signer certificate is included in the request.
This certificate will be stored by the device TEE and uses it to This certificate will be stored by the device TEE which uses it to
check against TA installation. Only if a TA is signed by a check against TA installation. Only if a TA is signed by a
matching spcert associated with a SD the TA will be installed into matching spcert associated with an SD will the TA be installed into
the SD. the SD.
tsmid - SD owner claim by TSM - A SD owned by a TSM will be tamid - SD owner claim by TAM - an SD owned by a TAM will be
associated with a trusted identifier defined as an attribute in the associated with a trusted identifier defined as an attribute in the
signer TSM certificate. TEE will be responsible to assign this ID signer TAM certificate. TEE will be responsible to assign this ID
to the SD. The TSM certificate attribute for this attribute TSMID to the SD. The TAM certificate attribute for this attribute tamid
must be vetted by the TSM signer issuing CA. With this trusted MUST be vetted by the TAM signer issuing CA. With this trusted
identifier, SD query at TEE can be fast upon TSM signer identifier, the SD query at TEE can be fast upon TAM signer
verification. verification.
did - The SHA256 hash of the binary encoded device TEE certificate. did - The SHA256 hash of the binary-encoded device TEE certificate.
The encryption key CEK will be encrypted the recipient TEE's public The encryption key CEK will be encrypted the recipient TEE's public
key. This hash value in the "did" property allows the recipient key. This hash value in the "did" property allows the recipient
TEE to check whether it is the expected target to receive such a TEE to check whether it is the expected target to receive such a
request. If this isn't given, an OTrP message for device 2 could request. If this isn't given, an OTrP message for device 2 could
be sent to device 1. It is optional for TEE to check because the be sent to device 1. It is optional for the TEE to check because
successful decryption of the request message with this device's TEE the successful decryption of the request message with this device's
private key already proves it is the target. This explicit hash TEE private key already proves it is the target. This explicit
value makes the protocol not dependent on message encryption method hash value makes the protocol not dependent on message encryption
in future. method in future.
Following is the OTrP message template, the full request is signed A CreateSDTBSRequest message is signed to generate a final
message over the CreateSDTBSRequest as follows. CreateSDRequest message as follows.
{ {
"CreateSDRequest": { "CreateSDRequest": {
"payload":"<CreateSDTBSRequest JSON above>", "payload": "<CreateSDTBSRequest JSON above>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": "<non-integrity-protected header contents>",
"signature":"<signature contents signed by TSM private key>" "signature": "<signature contents signed by TAM private key>"
} }
} }
TSM signer certificate is included in the "header" property. The TAM signer certificate is included in the "header" property.
8.2.1.2. Request Processing Requirements at a TEE 9.2.1.2. Request Processing Requirements at a TEE
Upon receiving a request message CreateSDRequest at a TEE, the TEE Upon receiving a CreateSDRequest request message at a TEE, the TEE
must validate a request: MUST do the following:
1. Validate the JSON request message 1. Validate the JSON request message as follows
* Validate JSON message signing * Validate JSON message signing.
* Validate that the request TSM certificate is chained to a * Validate that the request TAM certificate is chained to a
trusted CA that the TEE embeds as its trust anchor trusted CA that the TEE embeds as its trust anchor.
* Compare dsihash with its current state to make sure nothing * Compare dsihash with its current state to make sure nothing
has changed since this request was sent. has changed since this request was sent.
* Decrypt to get the plaintext of the content: (a) spid, (b) sd * Decrypt to get the plaintext of the content: (a) spid, (b) sd
name, (c) did name, (c) did.
* Check that a SPID is supplied * Check that an SPID is supplied.
* spcert check: check it is a valid certificate (signature and * spcert check: check it is a valid certificate (signature and
format verification only) format verification only).
* Check "did" is the SHA256 hash of its TEEcert BER raw binary * Check "did" is the SHA256 hash of its TEEcert BER raw binary
data data.
* Check whether the requested SD already exists for the SP * Check whether the requested SD already exists for the SP.
* Check TSMID in the request matches TSM certificate's TSM ID * Check that the tamid in the request matches the TAM
attribute certificate's TAM ID attribute.
2. Create action 2. If the request was valid, create action
* Create a SD for the SP with the given name * Create an SD for the SP with the given name.
* Assign the TSMID from the TSMCert to this SD * Assign the tamid from the TAMCert to this SD.
* Assign the SPID and SPCert to this SD * Assign the SPID and SPCert to this SD.
* Check whether a TEE SP AIK keypair already exists for the * Check whether a TEE SP AIK key pair already exists for the
given SP ID given SP ID.
* Create TEE SP AIK keypair if it doesn't exist for the given SP * Create TEE SP AIK key pair if it doesn't exist for the given
ID SP ID.
* Generate new DSI data if the request asks for updated DSI * Generate new DSI data if the request asks for updated DSI.
3. Construct CreateSDResponse message 3. Construct a CreateSDResponse message
* Create raw content * Create raw content
+ Operation status + Operation status
+ "did" or full signer certificate information, + "did" or full signer certificate information,
+ TEE SP AIK public key if DSI isn't going to be included + TEE SP AIK public key if DSI isn't going to be included
+ Updated DSI data if requested if the request asks for it + Updated DSI data if requested
* The response message is encrypted with the same JWE CEK of the * The response message is encrypted with the same JWE CEK of the
request without recreating a new content encryption key. request without recreating a new content encryption key.
* The encrypted message is signed with TEEpriv. The signer * The encrypted message is signed with TEEpriv. The signer
information ("did" or TEEcert) is encrypted. information ("did" or TEEcert) is encrypted.
4. Deliver response message. (a) OTrP Agent returns this to the app; 4. Deliver the response message. (a) The OTrP Agent returns this to
(b) The app passes this back to TSM the Client Application; (b) The Client App passes this back to
the TAM.
5. TSM process. (a) TSM processes the response message; (b) TSM can 5. TAM processing. (a) The TAM processes the response message; (b)
look up signer certificate from device ID "did". the TAM can look up signer certificate from the device ID "did".
If a request is illegitimate or signature doesn't pass, a "status" If a request is illegitimate or signature doesn't pass, a "status"
property in the response will indicate the error code and cause. property in the response will indicate the error code and cause.
8.2.1.3. CreateSDResponse Message 9.2.1.3. CreateSDResponse Message
The response message for a CreateSDRequest contains the following The response message for a CreateSDRequest contains the following
content. content.
{ {
"CreateSDTBSResponse": { "CreateSDTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "<operation result>", "status": "<operation result>",
"rid": "<the request ID received>", "rid": "<the request ID received>",
"tid": "<the transaction ID received>", "tid": "<the transaction ID received>",
"content": ENCRYPTED { "content": ENCRYPTED {
"reason":"<failure reason detail>", // optional "reason": "<failure reason detail>", // optional
"did": "<the device id received from the request>", "did": "<the device id received from the request>",
"sdname": "<SD name for the domain created>", "sdname": "<SD name for the domain created>",
"teespaik": "<TEE SP AIK public key, BASE64 encoded>", "teespaik": "<TEE SP AIK public key, BASE64 encoded>",
"dsi": "<Updated TEE state, including all SD owned by "dsi": "<Updated TEE state, including all SDs owned by
this TSM>" this TAM>"
} }
} }
} }
In the response message, the following fields MUST be supplied. In the response message, the following fields MUST be supplied.
did - The SHA256 hash of the device TEE certificate. This shows did - The SHA256 hash of the device TEE certificate. This shows
the device ID explicitly to the receiving TSM. the device ID explicitly to the receiving TAM.
teespaik - The newly generated SP AIK public key for the given SP. teespaik - The newly generated SP AIK public key for the given SP.
This is an optional value if the device has had another domain for This is an optional value if the device has had another domain for
the SP that has triggered TEE SP AIK keypair for this specific SP. the SP that has triggered TEE SP AIK key pair for this specific SP.
There is possible extreme error case where TEE isn't reachable or the There is a possible extreme error case where the TEE isn't reachable
TEE final response generation itself fails. In this case, TSM should or the TEE final response generation itself fails. In this case, the
still receive a response from the OTrP Agent. OTrP Agent is able to TAM might still receive a response from the OTrP Agent if the OTrP
detect such error from TEE. In this case, a general error response Agent is able to detect such error from TEE. In this case, a general
message should be returned, assuming OTrP Agent even doesn't know any error response message should be returned by the OTrP Agent, assuming
content and information about the request message. OTrP Agent even doesn't know any content and information about the
request message.
In other words, TSM should expect receive a TEE successfully signed In other words, the TAM should expect to receive a TEE successfully
JSON message, or a general "status" message. signed JSON message, a general "status" message, or none when a
client experiences a network error.
{ {
"CreateSDResponse": { "CreateSDResponse": {
"payload":"<CreateSDTBSResponse JSON above>", "payload": "<CreateSDTBSResponse JSON above>",
"protected": { "protected": {
"<BASE64URL of signing algorithm>" "<BASE64URL of signing algorithm>"
}, },
"signature": "<signature contents signed by TEE device private "signature": "<signature contents signed by the TEE device private
key (BASE64URL)>" key (BASE64URL)>"
} }
} }
A response message type "status" will be returned when TEE totally A response message type "status" will be returned when the TEE fails
fails to respond. OTrP Agent is responsible to create this message. to respond. The OTrP Agent is responsible to create this message.
{ {
"status": { "status": {
"result": "fail", "result": "fail",
"error-code": "ERR_TEE_UNKNOWN", "error-code": "ERR_AGENT_TEE_FAIL",
"error-message": "TEE fails to respond" "error-message": "TEE fails to respond"
} }
} }
8.2.1.4. Error Conditions 9.2.1.4. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error might occur if a request isn't valid or the TEE runs into
error. The list of possible errors are the following. Refer to some error. The list of possible errors are as follows. Refer to
section Error Code List (Section 14.1) for detail causes and actions. the Error Code List (Section 15.1) for detailed causes and actions.
ERR_AGENT_TEE_BUSY
ERR_AGENT_TEE_FAIL
ERR_AGENT_TEE_UNKNOWN
ERR_REQUEST_INVALID ERR_REQUEST_INVALID
ERR_UNSUPPORTED_MSG_VERSION ERR_UNSUPPORTED_MSG_VERSION
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_ALREADY_EXIST ERR_SD_ALREADY_EXIST
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
ERR_SPCERT_INVALID ERR_SPCERT_INVALID
ERR_TEE_FAIL ERR_TEE_FAIL
ERR_TEE_UNKNOWN ERR_TAM_NOT_AUTHORIZED
ERR_TSM_NOT_AUTHORIZED
ERR_TSM_NOT_TRUSTED ERR_TAM_NOT_TRUSTED
8.2.2. UpdateSD 9.2.2. UpdateSD
This TSM initiated command can update a SP's SD that it manages for This TAM initiated command can update an SP's SD that it manages for
the following need. (a) Update SP signer certificate; (b) Add SP any of the following needs: (a) Update an SP signer certificate; (b)
signer certificate when a SP uses multiple to sign TA binary; (c) Add an SP signer certificate when an SP uses multiple to sign TA
Update SP ID. binaries; (c) Update an SP ID.
The TSM presents the proof of the SD ownership to TEE, and includes The TAM presents the proof of the SD ownership to the TEE, and
related information in its signed message. The entire request is includes related information in its signed message. The entire
also encrypted for the end-to-end confidentiality. request is also encrypted for end-to-end confidentiality.
8.2.2.1. UpdateSDRequest Message 9.2.2.1. UpdateSDRequest Message
The request message for UpdateSD has the following JSON format. The UpdateSD request message has the following JSON format.
{ {
"UpdateSDTBSRequest": { "UpdateSDTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<unique request ID>", "rid": "<unique request ID>",
"tid": "<transaction ID>", // this may be from prior message "tid": "<transaction ID>", // this may be from prior message
"tee": "<TEE routing name from the DSI for the SD's target>", "tee": "<TEE routing name from the DSI for the SD's target>",
"nextdsi": "true | false", "nextdsi": true | false,
"dsihash": "<hash of DSI returned in the prior query>", "dsihash": "<hash of DSI returned in the prior query>",
"content": ENCRYPTED { // this piece of JSON will be encrypted "content": ENCRYPTED { // this piece of JSON will be encrypted
"tsmid": "<TSMID associated with this SD>", "tamid": "<tamid associated with this SD>",
"spid": "<SP ID>", "spid": "<SP ID>",
"sdname": "<SD name for the domain to be updated>", "sdname": "<SD name for the domain to be updated>",
"changes": { "changes": {
"newsdname": "<Change the SD name to this new name>", "newsdname": "<Change the SD name to this new name>",
// Optional // Optional
"newspid": "<Change SP ID of the domain to this new value>", "newspid": "<Change SP ID of the domain to this new value>",
// Optional // Optional
"spcert": ["<BASE64 encoded new SP signer cert to be added>"], "spcert": ["<BASE64 encoded new SP signer cert to be added>"],
// Optional // Optional
"deloldspcert": ["<The SHA256 hex value of an old SP cert "deloldspcert": ["<The SHA256 hex value of an old SP cert
assigned into this SD that should be deleted >"], assigned into this SD that should be deleted >"],
// Optional // Optional
"renewteespaik": "true | false" "renewteespaik": true | false
} }
} }
} }
} }
In the message, In the message,
rid - A unique value to identify this request rid - A unique value to identify this request
tid - A unique value to identify this transaction. It can have the tid - A unique value to identify this transaction. It can have the
same value for the tid in the preceding GetDeviceStateRequest. same value as the tid in the preceding GetDeviceStateRequest.
tee - TEE ID returned from the previous response tee - TEE ID returned from the previous GetDeviceStateResponse
GetDeviceStateResponse
nextdsi - Indicates whether the up to date Device State Information nextdsi - Indicates whether the up-to-date Device State Information
(DSI) should be returned in the response to this request. (DSI) is expected to be returned in the response from the TEE to
this request.
dsihash - The BASE64 encoded SHA256 hash value of the DSI data dsihash - The BASE64-encoded SHA256 hash value of the DSI data
returned in the prior TSM operation with this target TEE. This returned in the prior TAM operation with this target TEE. This
value is always included such that a receiving TEE can check value is always included such that a receiving TEE can check
whether the device state has changed since its last query. It whether the device state has changed since its last query. It
helps enforce SD update order in the right sequence without helps enforce SD update order in the right sequence without
accidently overwrite an update that was done simultaneously. accidently overwriting an update that was done simultaneously.
content - The "content" is a JSON encrypted message that includes content - The "content" is a JSON encrypted message that includes
actual input for the SD update. The standard JSON content actual input for the SD update. The standard JSON content
encryption key (CEK) is used, and the CEK is encrypted by the encryption key (CEK) is used, and the CEK is encrypted by the
target TEE's public key. target TEE's public key.
tsmid - SD owner claim by TSM - A SD owned by a TSM will be tamid - SD owner claim by TAM - an SD owned by a TAM will be
associated with a trusted identifier defined as an attribute in the associated with a trusted identifier defined as an attribute in the
signer TSM certificate. signer TAM certificate.
spid - the identifier of the SP whose SD will be updated. This spid - the identifier of the SP whose SD will be updated. This
value is still needed because SD name is considered unique within a value is still needed because the SD name is considered unique only
SP only. within an SP.
sdname - the name of the target SD to be updated. sdname - the name of the target SD to be updated.
changes - its content consists of changes that should be updated in changes - its content consists of changes are to be updated in the
the given SD. given SD.
newsdname - the new name of the target SD to be assigned if this newsdname - the new name of the target SD to be assigned if this
value is present. value is present.
newspid - the new SP ID of the target SD to be assigned if this newspid - the new SP ID of the target SD to be assigned if this
value is present. value is present.
spcert - a new TA signer certificate of this SP to be added to the spcert - a new TA signer certificate of this SP to be added to the
SD if this is present. SD if this is present.
deloldspcert - a SP certificate assigned into the SD should be deloldspcert - an SP certificate assigned into the SD is to be
deleted if this is present. The value is the SHA256 fingerprint of deleted if this is present. The value is the SHA256 fingerprint of
the old SP certificate. the old SP certificate.
renewteespaik - the value should be 'true' or 'false'. If it is renewteespaik - the value should be true or false. If it is present
present and the value is 'true', TEE should regenerate TEE SP AIK and the value is true, the TEE MUST regenerate TEE SP AIK for this
for this SD's owner SP. The newly generated TEE SP AIK for the SP SD's owner SP. The newly generated TEE SP AIK for the SP must be
must be returned in the response message of this request. If there returned in the response message of this request. If there is more
are more than one SD for the SP, a new SPID for one of the domain than one SD for the SP, a new SPID for one of the domains will
will always trigger a new teespaik generation as if a new SP is always trigger a new teespaik generation as if a new SP were
introduced to the TEE. introduced to the TEE.
Following the OTrP message template, the full request is signed The UpdateSDTBSRequest message is signed to generate the final
message over the UpdateSDTBSRequest as follows. UpdateSDRequest message.
{ {
"UpdateSDRequest": { "UpdateSDRequest": {
"payload":"<UpdateSDTBSRequest JSON above>", "payload": "<UpdateSDTBSRequest JSON above>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": "<non-integrity-protected header contents>",
"signature":"<signature contents signed by TSM private key>" "signature":"<signature contents signed by TAM private key>"
} }
} }
TSM signer certificate is included in the "header" property. TAM signer certificate is included in the "header" property.
8.2.2.2. Request Processing Requirements at a TEE 9.2.2.2. Request Processing Requirements at a TEE
Upon receiving a request message UpdateSDRequest at a TEE, the TEE Upon receiving a request message UpdateSDRequest at a TEE, the TEE
must validate a request: must validate a request:
1. Validate the JSON request message 1. Validate the JSON request message
* Validate JSON message signing * Validate JSON message signing
* Validate that the request TSM certificate is chained to a * Validate that the request TAM certificate is chained to a
trusted CA that the TEE embeds as its trust anchor. TSM trusted CA that the TEE embeds as its trust anchor.The TAM
certificate status check is generally not needed anymore in certificate status check is generally not needed anymore in
this request. The prior request should have validated the TSM this request. The prior request should have validated the TAM
certificate's revocation status certificate's revocation status.
* Compare dsihash with TEE cached last response DSI data to this * Compare dsihash with the TEE cached last response DSI data to
TSM this TAM.
* Decrypt to get the plaintext of the content * Decrypt to get the plaintext of the content.
* Check that the target SD name is supplied * Check that the target SD name is supplied.
* Check whether the requested SD exists * Check whether the requested SD exists.
* Check that the TSM owns this TSM by verifying TSMID in the SD * Check that the TAM owns this TAM by verifying tamid in the SD
matches TSM certificate's TSM ID attribute matches TAM certificate's TAM ID attribute.
* Now the TEE is ready to carry out update listed in the * Now the TEE is ready to carry out update listed in the
"content" message "content" message.
2. Update action 2. If the request is valid, update action
* If "newsdname" is given, replace the SD name for the SD to the * If "newsdname" is given, replace the SD name for the SD to the
new value new value
* If "newspid" is given, replace the SP ID assigned to this SD * If "newspid" is given, replace the SP ID assigned to this SD
with the given new value with the given new value
* If "spcert" is given, add this new SP certificate to the SD. * If "spcert" is given, add this new SP certificate to the SD.
* If "deloldspcert" is present in the content, check previously * If "deloldspcert" is present in the content, check previously
assigned SP certificates to this SD, and delete the one that assigned SP certificates to this SD, and delete the one that
matches the given certificate hash value. matches the given certificate hash value.
* If "renewteespaik" is given and has a value as "true", * If "renewteespaik" is given and has a value of 'true',
generate a new TEE SP AIK keypair, and replace the old one generate a new TEE SP AIK key pair, and replace the old one
with this. with this.
* Generate new DSI data if the request asks for updated DSI * Generate new DSI data if the request asks for updated DSI
* Now the TEE is ready to construct the response message * Now the TEE is ready to construct the response message
3. Construct UpdateSDResponse message 3. Construct UpdateSDResponse message
* Create raw content * Create raw content
+ Operation status + Operation status
+ "did" or full signer certificate information, + "did" or full signer certificate information,
+ TEE SP AIK public key if DSI isn't going to be included + TEE SP AIK public key if DSI isn't going to be included
+ Updated DSI data if requested if the request asks for it + Updated DSI data if requested
* The response message is encrypted with the same JWE CEK of the * The response message is encrypted with the same JWE CEK of the
request without recreating a new content encryption key. request without recreating a new content encryption key.
* The encrypted message is signed with TEEpriv. The signer * The encrypted message is signed with TEEpriv. The signer
information ("did" or TEEcert) is encrypted. information ("did" or TEEcert) is encrypted.
4. Deliver response message. (a) OTrP Agent returns this to the app; 4. Deliver response message. (a) The OTrP Agent returns this to the
(b) The app passes this back to TSM app; (b) The app passes this back to the TAM.
5. TSM process. (a) TSM processes the response message; (b) TSM can 5. TAM processing. (a) The TAM processes the response message; (b)
look up signer certificate from device ID "did". The TAM can look up the signer certificate from the device ID
"did".
If a request is illegitimate or signature doesn't pass, a "status" If a request is illegitimate or the signature doesn't pass, a
property in the response will indicate the error code and cause. "status" property in the response will indicate the error code and
cause.
8.2.2.3. UpdateSDResponse Message 9.2.2.3. UpdateSDResponse Message
The response message for a UpdateSDRequest contains the following The response message for a UpdateSDRequest contains the following
content. content.
{ {
"UpdateSDTBSResponse": { "UpdateSDTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "<operation result>", "status": "<operation result>",
"rid": "<the request ID received>", "rid": "<the request ID received>",
"tid": "<the transaction ID received>", "tid": "<the transaction ID received>",
"content": ENCRYPTED { "content": ENCRYPTED {
"reason":"<failure reason detail>", // optional "reason": "<failure reason detail>", // optional
"did": "<the device id hash>", "did": "<the device id hash>",
"cert": "<TEE certificate>", // optional "cert": "<TEE certificate>", // optional
"teespaik": "<TEE SP AIK public key, BASE64 encoded>", "teespaik": "<TEE SP AIK public key, BASE64 encoded>",
"teespaiktype": "<TEE SP AIK key type: RSA or ECC>", "teespaiktype": "<TEE SP AIK key type: RSA or ECC>",
"dsi": "<Updated TEE state, including all SD owned by "dsi": "<Updated TEE state, including all SD owned by
this TSM>" this TAM>"
} }
} }
} }
In the response message, the following fields MUST be supplied. In the response message, the following fields MUST be supplied.
did - The request should have known the signer certificate of this did - The request should have known the signer certificate of this
device from a prior request. This hash value of the device TEE device from a prior request. This hash value of the device TEE
certificate serves as a quick identifier only. Full device certificate serves as a quick identifier only. A full device
certificate isn't necessary. certificate isn't necessary.
teespaik - the newly generated SP AIK public key for the given SP teespaik - the newly generated SP AIK public key for the given SP
if TEE SP AIK for the SP is asked to be renewed in the request. if the TEE SP AIK for the SP is asked to be renewed in the request.
This is an optional value if "dsi" is included in the response, This is an optional value if "dsi" is included in the response,
which will contain all up to date TEE SP AIK key pairs. which will contain all up-to-date TEE SP AIK key pairs.
Similar to the template for the creation of the encrypted and signed Similar to the template for the creation of the encrypted and signed
CreateSDResponse, the final UpdateSDResponse looks like the CreateSDResponse, the final UpdateSDResponse looks like the
following. following.
{ {
"UpdateSDResponse": { "UpdateSDResponse": {
"payload":"<UpdateSDTBSResponse JSON above>", "payload": "<UpdateSDTBSResponse JSON above>",
"protected": { "protected": {
"<BASE64URL of signing algorithm>" "<BASE64URL of signing algorithm>"
}, },
"signature": "<signature contents signed by TEE device private "signature": "<signature contents signed by TEE device private
key (BASE64URL)>" key (BASE64URL)>"
} }
} }
A response message type "status" will be returned when TEE totally A response message type "status" will be returned when the TEE fails
fails to respond. OTrP Agent is responsible to create this message. to respond. The OTrP Agent is responsible to create this message.
{ {
"status": { "status": {
"result": "fail", "result": "fail",
"error-code": "ERR_TEE_UNKNOWN", "error-code": "ERR_AGENT_TEE_FAIL",
"error-message": "TEE fails to respond" "error-message": "<TEE fails to respond message>"
} }
} }
8.2.2.4. Error Conditions 9.2.2.4. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error may occur if a request isn't valid or the TEE runs into some
error. The list of possible errors are the following. Refer to error. The list of possible errors are as follows. Refer to the
section Error Code List (Section 14.1) for detail causes and actions. Error Code List (Section 15.1) for detailed causes and actions.
ERR_AGENT_TEE_BUSY
ERR_AGENT_TEE_FAIL
ERR_AGENT_TEE_UNKNOWN
ERR_REQUEST_INVALID ERR_REQUEST_INVALID
ERR_UNSUPPORTED_MSG_VERSION ERR_UNSUPPORTED_MSG_VERSION
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
skipping to change at page 54, line 46 skipping to change at page 56, line 4
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
ERR_SDNAME_ALREADY_USED ERR_SDNAME_ALREADY_USED
ERR_SPCERT_INVALID ERR_SPCERT_INVALID
ERR_TEE_FAIL ERR_TEE_FAIL
ERR_TEE_UNKNOWN ERR_TAM_NOT_AUTHORIZED
ERR_TSM_NOT_AUTHORIZED ERR_TAM_NOT_TRUSTED
ERR_TSM_NOT_TRUSTED
8.2.3. DeleteSD 9.2.3. DeleteSD
A TSM sends a DeleteSDRequest message to TEE to delete a specified SD A TAM sends a DeleteSDRequest message to a TEE to delete a specified
that it owns. A SD can be deleted only if there is no TA associated SD that it owns. An SD can be deleted only if there is no TA
with this SD in the device. The request message can contain a flag associated with this SD in the device. The request message can
to instruct TEE to delete all related TAs in a SD and then delete the contain a flag to instruct the TEE to delete all related TAs in an SD
SD. and then delete the SD.
The target TEE will operate with the following logic. The target TEE will operate with the following logic.
1. Lookup given SD specified in the request message 1. Look up the given SD specified in the request message
2. Check that the TSM owns the SD 2. Check that the TAM owns the SD
3. Check that the device state hasn't changed since the last 3. Check that the device state hasn't changed since the last
operation operation
4. Check whether there are TAs in this SD 4. Check whether there are TAs in this SD
5. If TA exists in a SD, check whether the request instructs whether 5. If TA exists in an SD, check whether the request instructs
TA should be deleted. If the request instructs TEE to delete whether the TA should be deleted. If the request instructs the
TAs, delete all TAs in this SD. If the request doesn't instruct TEE to delete TAs, delete all TAs in this SD. If the request
the TEE to delete TAs, return an error "ERR_SD_NOT_EMPTY". doesn't instruct the TEE to delete TAs, return an error
"ERR_SD_NOT_EMPTY".
6. Delete SD 6. Delete the SD
7. If this is the last SD of this SP, delete TEE SP AIK key 7. If this is the last SD of this SP, delete the TEE SP AIK key.
8.2.3.1. DeleteSDRequest Message 9.2.3.1. DeleteSDRequest Message
The request message for DeleteSD has the following JSON format. The request message for DeleteSD has the following JSON format.
{ {
"DeleteSDTBSRequest": { "DeleteSDTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<unique request ID>", "rid": "<unique request ID>",
"tid": "<transaction ID>", // this may be from prior message "tid": "<transaction ID>", // this may be from prior message
"tee": "<TEE routing name from the DSI for the SD's target>", "tee": "<TEE routing name from the DSI for the SD's target>",
"nextdsi": "true | false", "nextdsi": true | false,
"dsihash": "<hash of DSI returned in the prior query>", "dsihash": "<hash of DSI returned in the prior query>",
"content": ENCRYPTED { // this piece of JSON will be encrypted "content": ENCRYPTED { // this piece of JSON will be encrypted
"tsmid": "<TSMID associated with this SD>", "tamid": "<tamid associated with this SD>",
"sdname": "<SD name for the domain to be updated>", "sdname": "<SD name for the domain to be updated>",
"deleteta": "true | false" "deleteta": true | false
} }
} }
} }
In the message, In the message,
rid - A unique value to identify this request rid - A unique value to identify this request
tid - A unique value to identify this transaction. It can have the tid - A unique value to identify this transaction. It can have the
same value for the tid in the preceding GetDeviceStateRequest. same value for the tid in the preceding GetDeviceStateRequest.
tee - TEE ID returned from the previous response tee - TEE ID returned from the previous response
GetDeviceStateResponse GetDeviceStateResponse
nextdsi - Indicates whether the up to date Device State Information nextdsi - Indicates whether the up-to-date Device State Information
(DSI) should be returned in the response to this request. (DSI) is to be returned in the response to this request.
dsihash - The BASE64 encoded SHA256 hash value of the DSI data dsihash - The BASE64-encoded SHA256 hash value of the DSI data
returned in the prior TSM operation with this target TEE. This returned in the prior TAM operation with this target TEE. This
value is always included such that a receiving TEE can check value is always included such that a receiving TEE can check
whether the device state has changed since its last query. It whether the device state has changed since its last query. It
helps enforce SD update order in the right sequence without helps enforce SD update order in the right sequence without
accidently overwrite an update that was done simultaneously. accidently overwriting an update that was done simultaneously.
content - The "content" is a JSON encrypted message that includes content - The "content" is a JSON encrypted message that includes
actual input for the SD update. The standard JSON content actual input for the SD update. The standard JSON content
encryption key (CEK) is used, and the CEK is encrypted by the encryption key (CEK) is used, and the CEK is encrypted by the
target TEE's public key. target TEE's public key.
tsmid - SD owner claim by TSM - A SD owned by a TSM will be tamid - SD owner claim by TAM - an SD owned by a TAM will be
associated with a trusted identifier defined as an attribute in the associated with a trusted identifier defined as an attribute in the
signer TSM certificate. signer TAM certificate.
sdname - the name of the target SD to be updated. sdname - the name of the target SD to be updated.
deleteta - the value should be 'true' or 'false'. If it is present deleteta - the value should be boolean 'true' or 'false'. If it is
and the value is 'true', TEE should delete all TAs associated with present and the value is 'true', the TEE should delete all TAs
the SD in the device. associated with the SD in the device.
Following the OTrP message template, the full request is signed According to the OTrP message template, the full request
message over the DeleteSDTBSRequest as follows. DeleteSDRequest is a signed message over the DeleteSDTBSRequest as
follows.
{ {
"DeleteSDRequest": { "DeleteSDRequest": {
"payload":"<DeleteSDTBSRequest JSON above>", "payload": "<DeleteSDTBSRequest JSON above>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": "<non-integrity-protected header contents>",
"signature":"<signature contents signed by TSM private key>" "signature": "<signature contents signed by TAM private key>"
} }
} }
TSM signer certificate is included in the "header" property. TAM signer certificate is included in the "header" property.
8.2.3.2. Request Processing Requirements at a TEE 9.2.3.2. Request Processing Requirements at a TEE
Upon receiving a request message DeleteSDRequest at a TEE, the TEE Upon receiving a request message DeleteSDRequest at a TEE, the TEE
must validate a request: must validate a request:
1. Validate the JSON request message 1. Validate the JSON request message
* Validate JSON message signing * Validate JSON message signing
* Validate that the request TSM certificate is chained to a * Validate that the request TAM certificate is chained to a
trusted CA that the TEE embeds as its trust anchor. TSM trusted CA that the TEE embeds as its trust anchor. The TAM
certificate status check is generally not needed anymore in certificate status check is generally not needed anymore in
this request. The prior request should have validated the TSM this request. The prior request should have validated the TAM
certificate's revocation status certificate's revocation status.
* Compare dsihash with TEE cached last response DSI data to this * Compare dsihash with the TEE cached last response DSI data to
TSM this TAM
* Decrypt to get the plaintext of the content * Decrypt to get the plaintext of the content
* Check that the target SD name is supplied * Check that the target SD name is supplied
* Check whether the requested SD exists * Check whether the requested SD exists
* Check that the TSM owns this TSM by verifying TSMID in the SD * Check that the TAM owns this TAM by verifying that the tamid
matches TSM certificate's TSM ID attribute in the SD matches the TAM certificate's TAM ID attribute
* Now the TEE is ready to carry out update listed in the * Now the TEE is ready to carry out the update listed in the
"content" message "content" message
2. Deletion action 2. If the request is valid, deletion action
* Check TA existence in this SD * Check TA existence in this SD
* If "deleteta" is "true", delete all TAs in this SD. If the * If "deleteta" is "true", delete all TAs in this SD. If the
value of "deleteta" is "false" and some TA exists, return an value of "deleteta" is false and some TA exists, return an
error "ERR_SD_NOT_EMPTY" error "ERR_SD_NOT_EMPTY"
* Delete the SD * Delete the SD
* Delete TEE SP AIK key pair if this SD is the last one for the * Delete the TEE SP AIK key pair if this SD is the last one for
SP the SP
* Now the TEE is ready to construct the response message * Now the TEE is ready to construct the response message
3. Construct DeleteSDResponse message 3. Construct a DeleteSDResponse message
* Create response content * Create response content
+ Operation status + Operation status
+ "did" or full signer certificate information, + "did" or full signer certificate information,
+ Updated DSI data if requested if the request asks for it + Updated DSI data if requested
* The response message is encrypted with the same JWE CEK of the * The response message is encrypted with the same JWE CEK of the
request without recreating a new content encryption key. request without recreating a new content encryption key.
* The encrypted message is signed with TEEpriv. The signer * The encrypted message is signed with TEEpriv. The signer
information ("did" or TEEcert) is encrypted. information ("did" or TEEcert) is encrypted.
4. Deliver response message. (a) OTrP Agent returns this to the app; 4. Deliver response message. (a) The OTrP Agent returns this to the
(b) The app passes this back to TSM app; (b) The app passes this back to the TAM
5. TSM process. (a) TSM processes the response message; (b) TSM can 5. TAM processing. (a) The TAM processes the response message; (b)
look up signer certificate from device ID "did". The TAM can look up signer certificate from the device ID "did".
If a request is illegitimate or signature doesn't pass, a "status" If a request is illegitimate or the signature doesn't pass, a
property in the response will indicate the error code and cause. "status" property in the response will indicate the error code and
cause.
8.2.3.3. DeleteSDResponse Message 9.2.3.3. DeleteSDResponse Message
The response message for a DeleteSDRequest contains the following The response message for a DeleteSDRequest contains the following
content. content.
{ {
"DeleteSDTBSResponse": { "DeleteSDTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "<operation result>", "status": "<operation result>",
"rid": "<the request ID received>", "rid": "<the request ID received>",
"tid": "<the transaction ID received>", "tid": "<the transaction ID received>",
"content": ENCRYPTED { "content": ENCRYPTED {
"reason":"<failure reason detail>", // optional "reason": "<failure reason detail>", // optional
"did": "<the device id hash>", "did": "<the device id hash>",
"dsi": "<Updated TEE state, including all SD owned by "dsi": "<Updated TEE state, including all SD owned by
this TSM>" this TAM>"
} }
} }
} }
In the response message, the following fields MUST be supplied. In the response message, the following fields MUST be supplied.
did - The request should have known the signer certificate of this did - The request should have known the signer certificate of this
device from a prior request. This hash value of the device TEE device from a prior request. This hash value of the device TEE
certificate serves as a quick identifier only. Full device certificate serves as a quick identifier only. A full device
certificate isn't necessary. certificate isn't necessary.
The final DeleteSDResponse looks like the following. The final DeleteSDResponse looks like the following.
{ {
"DeleteSDResponse": { "DeleteSDResponse": {
"payload":"<DeleteSDTBSResponse JSON above>", "payload": "<DeleteSDTBSResponse JSON above>",
"protected": { "protected": {
"<BASE64URL of signing algorithm>" "<BASE64URL of signing algorithm>"
}, },
"signature": "<signature contents signed by TEE device "signature": "<signature contents signed by TEE device
private key (BASE64URL)>" private key (BASE64URL)>"
} }
} }
A response message type "status" will be returned when TEE totally A response message type "status" will be returned when the TEE fails
fails to respond. OTrP Agent is responsible to create this message. to respond. The OTrP Agent is responsible to create this message.
{ {
"status": { "status": {
"result": "fail", "result": "fail",
"error-code": "ERR_TEE_UNKNOWN", "error-code": "ERR_AGENT_TEE_FAIL",
"error-message": "TEE fails to respond" "error-message": "TEE fails to respond"
} }
} }
8.2.3.4. Error Conditions 9.2.3.4. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error may occur if a request isn't valid or the TEE runs into some
error. The list of possible errors are the following. Refer to error. The list of possible errors is as follows. Refer to the
section Error Code List (Section 14.1) for detail causes and actions. Error Code List (Section 15.1) for detailed causes and actions.
ERR_AGENT_TEE_BUSY
ERR_AGENT_TEE_FAIL
ERR_AGENT_TEE_UNKNOWN
ERR_REQUEST_INVALID ERR_REQUEST_INVALID
ERR_UNSUPPORTED_MSG_VERSION ERR_UNSUPPORTED_MSG_VERSION
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_NOT_EMPTY ERR_SD_NOT_EMPTY
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
ERR_TEE_FAIL ERR_TEE_FAIL
ERR_TEE_UNKNOWN ERR_TAM_NOT_AUTHORIZED
ERR_TSM_NOT_AUTHORIZED ERR_TAM_NOT_TRUSTED
ERR_TSM_NOT_TRUSTED 9.3. Trusted Application Management
8.3. Trusted Application Management This protocol doesn't introduce a TA container concept. All TA
authorization and management will be up to the TEE implementation.
This protocol doesn't introduce a TA container concept. All the TA The following three TA management commands are supported.
authorization and management will be up to TEE implementation.
The following three TA management commands will be supported. o InstallTA - provision a TA by TAM
o InstallTA - provision a TA by TSM o UpdateTA - update a TA by TAM
o UpdateTA - update a TA by TSM o DeleteTA - remove TA registration information with an SD, remove
the TA binary and all TA-related data in a TEE
o DeleteTA - remove TA registration information with a SD, remove TA 9.3.1. InstallTA
binary from TEE, remove all TA related data in TEE
8.3.1. InstallTA TA binary data and related personalization data if there is any can
be from two sources:
TA binary data can be from two sources: 1. A TAM supplies the signed and encrypted TA binary
1. TSM supplies the signed TA binary 2. A Client Application supplies the TA binary
2. Client Application supplies the TA binary This specification primarily considers the first case where a TAM
This specification considers only the first case where TSM supplies supplies a TA binary. This is to ensure that a TEE can properly
TA binary. When such a request is received by TEE, a SD is already validate whether a TA is trustworthy. Further, TA personalization
created and is ready to take TA installation. data will be encrypted by the TEE device's SP public key for end-to-
end protection. A Client Application bundled TA case will be
addressed separately later.
A TSM sends the following information in message InstallTARequest to A TAM sends the following information in a InstallTARequest message
a target TEE: to a target TEE:
o The target SD information: SP ID and SD name o The target SD information: SP ID and SD name
o Encrypted TA binary data. TA data is encrypted with TEE SP AIK. o Encrypted TA binary data. TA data is encrypted with the TEE SP
AIK.
o TA metadata. It is optional to include SP signer certificate for o TA metadata. It is optional to include the SP signer certificate
the SD to add if the SP has changed signer since the SD was for the SD to add if the SP has changed signer since the SD was
created. created.
TEE processes command given by TSM to install TA into a SP's SD. It The TEE processes the command given by the TAM to install a TA into
does the following: an SP's SD. It does the following:
o Validation o Validation
* TEE validates TSM message authenticity * The TEE validates the TAM message authenticity
* Decrypt to get request content * Decrypt to get request content
* Lookup SD with SD name * Look up the SD with the SD name
* Checks that the TSM owns the SD * Checks that the TAM owns the SD
* Checks DSI hash matches that the device state hasn't changed * Checks that the DSI hash matches which shows that the device
state hasn't changed
o TA validation o If the request is valid, continue to do the TA validation
* Decrypt to get TA binary and any personalization data with "TEE * Decrypt to get the TA binary data and any personalization data
SP AIK private key" with the "TEE SP AIK private key"
* Check that SP ID is the one that is registered with the SP SD * Check that SP ID is the one that is registered with the SP SD
* TA signer is either the newly given SP certificate or the one * Check that the TA signer is either a newly given SP certificate
in SD. The TA signing method is specific to TEE. This or the one that is already trusted by the SD from the previous
specification doesn't define how a TA should be signed. TA installation. The TA signing method is specific to a TEE.
This specification doesn't define how a TA should be signed; a
TAM should support TEE specific TA signing when it supports
that TEE.
* If a TA signer is given in the request, add this signer into * If a TA signer is given in the request, add this signer into
the SD. the SD.
o TA installation o If the above validation passed, continue to do TA installation
* TEE re-encrypts TA binary and its personalization data with its
own method
* TEE enrolls and stores the TA onto TEE secure storage area. * The TEE re-encrypts the TA binary and its personalization data
with its own method.
o Construct a response message. This involves signing a encrypted * The TEE enrolls and stores the TA in a secure storage.
status information for the requesting TSM.
8.3.1.1. InstallTARequest Message o Construct a response message. This involves signing encrypted
status information for the requesting TAM.
9.3.1.1. InstallTARequest Message
The request message for InstallTA has the following JSON format. The request message for InstallTA has the following JSON format.
{ {
"InstallTATBSRequest": { "InstallTATBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<unique request ID>", "rid": "<unique request ID>",
"tid": "<transaction ID>", "tid": "<transaction ID>",
"tee": "<TEE routing name from the DSI for the SD's target>", "tee": "<TEE routing name from the DSI for the SD's target>",
"nextdsi": "true | false", "nextdsi": true | false,
"dsihash": "<hash of DSI returned in the prior query>", "dsihash": "<hash of DSI returned in the prior query>",
"content": ENCRYPTED { "content": ENCRYPTED {
"tsmid": "<TSM ID previously assigned to the SD>", "tamid": "<TAM ID previously assigned to the SD>",
"spid": "<SPID value>", "spid": "<SPID value>",
"sdname": "<SD name for the domain to install the TA>", "sdname": "<SD name for the domain to install the TA>",
"spcert": "<BASE64 encoded SP certificate >", // optional "spcert": "<BASE64 encoded SP certificate >", // optional
"taid": "<TA identifier>" "taid": "<TA identifier>"
}, },
"encrypted_ta": { "encrypted_ta": {
"key": "<A 256-bit symmetric key encrypted by TEEspaik public "key": "<JWE enveloped data of a 256-bit symmetric key by
key>", the recipient's TEEspaik public key>",
"iv": "<hex of 16 random bytes>", "iv": "<hex of 16 random bytes>",
"alg": "<encryption algoritm. AESCBC by default.", "alg": "<encryption algoritm. AESCBC by default.",
"ciphertadata": "<BASE64 encoded encrypted TA binary data>", "ciphertadata": "<BASE64 encoded encrypted TA binary data>",
"cipherpdata": "<BASE64 encoded encrypted TA personalization "cipherpdata": "<BASE64 encoded encrypted TA personalization
data>" data>"
} }
} }
} }
In the message, In the message,
rid - A unique value to identify this request rid - A unique value to identify this request
tid - A unique value to identify this transaction. It can have the tid - A unique value to identify this transaction. It can have the
same value for the tid in the preceding GetDeviceStateRequest. same value for the tid in the preceding GetDeviceStateRequest.
tee - TEE ID returned from the previous response tee - TEE ID returned from the previous GetDeviceStateResponse
GetDeviceStateResponse
nextdsi - Indicates whether the up to date Device State Information nextdsi - Indicates whether the up-to-date Device State Information
(DSI) should be returned in the response to this request. (DSI) is to be returned in the response to this request.
dsihash - The BASE64 encoded SHA256 hash value of the DSI data dsihash - The BASE64-encoded SHA256 hash value of the DSI data
returned in the prior TSM operation with this target TEE. This returned in the prior TAM operation with this target TEE. This
value is always included such that a receiving TEE can check value is always included such that a receiving TEE can check
whether the device state has changed since its last query. It whether the device state has changed since its last query. It
helps enforce SD update order in the right sequence without helps enforce SD update order in the right sequence without
accidently overwrite an update that was done simultaneously. accidently overwriting an update that was done simultaneously.
content - The "content" is a JSON encrypted message that includes content - The "content" is a JSON encrypted message that includes
actual input for the SD update. The standard JSON content actual input for the SD update. The standard JSON content
encryption key (CEK) is used, and the CEK is encrypted by the encryption key (CEK) is used, and the CEK is encrypted by the
target TEE's public key. target TEE's public key.
tsmid - SD owner claim by TSM - A SD owned by a TSM will be tamid - SD owner claim by TAM - An SD owned by a TAM will be
associated with a trusted identifier defined as an attribute in the associated with a trusted identifier defined as an attribute in the
signer TSM certificate. signer TAM certificate.
spid - SP identifier of the TA owner SP spid - SP identifier of the TA owner SP
sdname - the name of the target SD where the TA should be installed sdname - the name of the target SD where the TA is to be installed
spcert - an optional field to specify SP certificate that signed the spcert - an optional field to specify the SP certificate that signed
TA. This is sent if the SP has a new certificate that hasn't been the TA. This is sent if the SP has a new certificate that hasn't
previously registered with the target SD where the TA should be been previously registered with the target SD where the TA should
installed. be installed.
taid - the identifier of the TA application to be installed taid - the identifier of the TA application to be installed
encrypted_ta - the message portion contains encrypted TA binary data encrypted_ta - the message portion contains encrypted TA binary data
and personalization data. The TA data encryption key is placed in and personalization data. The TA data encryption key is placed in
"key", which is encrypted by the recipient's public key. The TA "key", which is encrypted by the recipient's public key, using JWE
data encryption uses symmetric key based encryption such as AESCBC. enveloped structure. The TA data encryption uses symmetric key
based encryption such as AESCBC.
Following the OTrP message template, the full request is signed According to the OTrP message template, the full request
message over the InstallTATBSRequest as follows. InstallTARequest is a signed message over the InstallTATBSRequest as
follows.
{ {
"InstallTARequest": { "InstallTARequest": {
"payload":"<InstallTATBSRequest JSON above>", "payload": "<InstallTATBSRequest JSON above>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": "<non-integrity-protected header contents>",
"signature":"<signature contents signed by TSM private key>" "signature": "<signature contents signed by TAM private key>"
} }
} }
8.3.1.2. InstallTAResponse Message 9.3.1.2. InstallTAResponse Message
The response message for a InstallTARequest contains the following The response message for a InstallTARequest contains the following
content. content.
{ {
"InstallTATBSResponse": { "InstallTATBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "<operation result>", "status": "<operation result>",
"rid": "<the request ID received>", "rid": "<the request ID received>",
"tid": "<the transaction ID received>", "tid": "<the transaction ID received>",
"content": ENCRYPTED { "content": ENCRYPTED {
"reason":"<failure reason detail>", // optional "reason":"<failure reason detail>", // optional
"did": "<the device id hash>", "did": "<the device id hash>",
"dsi": "<Updated TEE state, including all SD owned by "dsi": "<Updated TEE state, including all SD owned by
this TSM>" this TAM>"
} }
} }
} }
In the response message, the following fields MUST be supplied. In the response message, the following fields MUST be supplied.
did - the SHA256 hash of the device TEE certificate. This shows did - the SHA256 hash of the device TEE certificate. This shows
the device ID explicitly to the receiving TSM. the device ID explicitly to the receiving TAM.
The final message InstallTAResponse looks like the following. The final message InstallTAResponse looks like the following.
{ {
"InstallTAResponse": { "InstallTAResponse": {
"payload":"<InstallTATBSResponse JSON above>", "payload":"<InstallTATBSResponse JSON above>",
"protected": { "protected": {
"<BASE64URL of signing algorithm>" "<BASE64URL of signing algorithm>"
}, },
"signature": "<signature contents signed by TEE device "signature": "<signature contents signed by TEE device
private key (BASE64URL)>" private key (BASE64URL)>"
} }
} }
A response message type "status" will be returned when TEE totally A response message type "status" will be returned when the TEE fails
fails to respond. OTrP Agent is responsible to create this message. to respond. The OTrP Agent is responsible to create this message.
{ {
"status": { "status": {
"result": "fail", "result": "fail",
"error-code": "ERR_TEE_UNKNOWN", "error-code": "ERR_AGENT_TEE_FAIL",
"error-message": "TEE fails to respond" "error-message": "TEE fails to respond"
} }
} }
8.3.1.3. Error Conditions 9.3.1.3. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error may occur if a request isn't valid or the TEE runs into some
error. The list of possible errors are the following. Refer to error. The list of possible errors are as follows. Refer to the
section Error Code List (Section 14.1) for detail causes and actions. Error Code List (Section 15.1) for detailed causes and actions.
ERR_AGENT_TEE_BUSY
ERR_AGENT_TEE_FAIL
ERR_AGENT_TEE_UNKNOWN
ERR_REQUEST_INVALID ERR_REQUEST_INVALID
ERR_UNSUPPORTED_MSG_VERSION ERR_UNSUPPORTED_MSG_VERSION
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
ERR_TA_INVALID ERR_TA_INVALID
ERR_TA_ALREADY_INSTALLED ERR_TA_ALREADY_INSTALLED
ERR_TEE_FAIL ERR_TEE_FAIL
ERR_TEE_UNKNOWN
ERR_TEE_RESOURCE_FULL ERR_TEE_RESOURCE_FULL
ERR_TSM_NOT_AUTHORIZED ERR_TAM_NOT_AUTHORIZED
ERR_TSM_NOT_TRUSTED ERR_TAM_NOT_TRUSTED
8.3.2. UpdateTA 9.3.2. UpdateTA
This TSM initiated command can update TA and its data in a SP's SD This TAM-initiated command can update a TA and its data in an SP's SD
that it manages for the following purposes. that it manages for the following purposes.
1. Update TA binary 1. Update TA binary
2. Update TA's personalization data 2. Update TA's personalization data
The TSM presents the proof of the SD ownership to TEE, and includes
The TAM presents the proof of the SD ownership to a TEE, and includes
related information in its signed message. The entire request is related information in its signed message. The entire request is
also encrypted for the end-to-end confidentiality. also encrypted for end-to-end confidentiality.
TEE processes command given by TSM to update TA of a SP SD. It does The TEE processes the command from the TAM to update the TA of an SP
the following: SD. It does the following:
o Validation o Validation
* TEE validates TSM message authenticity * The TEE validates the TAM message authenticity
* Decrypt to get request content * Decrypt to get request content
* Lookup SD with SD name * Look up the SD with the SD name
* Checks that the TSM owns the SD * Checks that the TAM owns the SD
* Checks DSI hash matches that the device state hasn't changed * Checks DSI hash matches that the device state hasn't changed
o TA validation o TA validation
* Both TA binary and personalization data are optional, but at * Both TA binary and personalization data are optional, but at
least one of them shall be present in the message least one of them shall be present in the message
* Decrypt to get TA binary and any personalization data with "TEE * Decrypt to get the TA binary and any personalization data with
SP AIK private key" the "TEE SP AIK private key"
* Check that SP ID is the one that is registered with the SP SD * Check that SP ID is the one that is registered with the SP SD
* TA signer is either the newly given SP certificate or the one * Check that the TA signer is either a newly given SP certificate
in SD. The TA signing method is specific to TEE. This or the one in SD.
specification doesn't define how a TA should be signed.
* If a TA signer is given in the request, add this signer into * If a TA signer is given in the request, add this signer into
the SD the SD.
o TA update o If the above validation passes, continue to do TA update
* TEE re-encrypts TA binary and its personalization data with its * The TEE re-encrypts the TA binary and its personalization data
own method with its own method
* TEE replaces the existing TA binary and its personalization * The TEE replaces the existing TA binary and its personalization
data with the new binary and data. data with the new binary and data.
o Construct a response message. This involves signing a encrypted o Construct a response message. This involves signing a encrypted
status information for the requesting TSM. status information for the requesting TAM.
8.3.2.1. UpdateTARequest Message
9.3.2.1. UpdateTARequest Message
The request message for UpdateTA has the following JSON format. The request message for UpdateTA has the following JSON format.
{ {
"UpdateTATBSRequest": { "UpdateTATBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<unique request ID>", "rid": "<unique request ID>",
"tid": "<transaction ID>", "tid": "<transaction ID>",
"tee": "<TEE routing name from the DSI for the SD's target>", "tee": "<TEE routing name from the DSI for the SD's target>",
"nextdsi": "true | false", "nextdsi": true | false,
"dsihash": "<hash of DSI returned in the prior query>", "dsihash": "<hash of DSI returned in the prior query>",
"content": ENCRYPTED { "content": ENCRYPTED {
"tsmid": "<TSM ID previously assigned to the SD>", "tamid": "<TAM ID previously assigned to the SD>",
"spid": "<SPID value>", "spid": "<SPID value>",
"sdname": "<SD name for the domain to be created>", "sdname": "<SD name for the domain to be created>",
"spcert": "<BASE64 encoded SP certificate >", // optional "spcert": "<BASE64 encoded SP certificate >", // optional
"taid": "<TA identifier>" "taid": "<TA identifier>"
}, },
"encrypted_ta": { "encrypted_ta": {
"key": "<A 256-bit symmetric key encrypted by TEEspaik public "key": "<JWE enveloped data of a 256-bit symmetric key by
key>", the recipient's TEEspaik public key>",
"iv": "<hex of 16 random bytes>", "iv": "<hex of 16 random bytes>",
"alg": "<encryption algoritm. AESCBC by default.", "alg": "<encryption algoritm. AESCBC by default.",
"ciphernewtadata": "<Change existing TA binary to this new TA "ciphernewtadata": "<Change existing TA binary to this new TA
binary data(BASE64 encoded and encrypted)>", binary data(BASE64 encoded and encrypted)>",
"ciphernewpdata": "<Change the existing data to this new TA "ciphernewpdata": "<Change the existing data to this new TA
personalization data(BASE64 encoded and encrypted)>" personalization data(BASE64 encoded and encrypted)>"
// optional // optional
} }
} }
} }
In the message, In the message,
rid - A unique value to identify this request rid - A unique value to identify this request
tid - A unique value to identify this transaction. It can have the tid - A unique value to identify this transaction. It can have the
same value for the tid in the preceding GetDeviceStateRequest. same value for the tid in the preceding GetDeviceStateRequest.
tee - TEE ID returned from the previous response tee - TEE ID returned from the previous GetDeviceStateResponse
GetDeviceStateResponse
nextdsi - Indicates whether the up to date Device State Information nextdsi - Indicates whether the up-to-date Device State Information
(DSI) should be returned in the response to this request. (DSI) is to be returned in the response to this request.
dsihash - The BASE64 encoded SHA256 hash value of the DSI data dsihash - The BASE64-encoded SHA256 hash value of the DSI data
returned in the prior TSM operation with this target TEE. This returned in the prior TAM operation with this target TEE. This
value is always included such that a receiving TEE can check value is always included such that a receiving TEE can check
whether the device state has changed since its last query. It whether the device state has changed since its last query. It
helps enforce SD update order in the right sequence without helps enforce SD update order in the right sequence without
accidently overwrite an update that was done simultaneously. accidently overwriting an update that was done simultaneously.
content - The "content" is a JSON encrypted message that includes content - The "content" is a JSON encrypted message that includes
actual input for the SD update. The standard JSON content actual input for the SD update. The standard JSON content
encryption key (CEK) is used, and the CEK is encrypted by the encryption key (CEK) is used, and the CEK is encrypted by the
target TEE's public key. target TEE's public key.
tsmid - SD owner claim by TSM - A SD owned by a TSM will be tamid - SD owner claim by TAM - an SD owned by a TAM will be
associated with a trusted identifier defined as an attribute in the associated with a trusted identifier defined as an attribute in the
signer TSM certificate. signer TAM certificate.
spid - SP identifier of the TA owner SP spid - SP identifier of the TA owner SP
spcert - an optional field to specify SP certificate that signed the spcert - an optional field to specify the SP certificate that signed
TA. This is sent if the SP has a new certificate that hasn't been the TA. This is sent if the SP has a new certificate that hasn't
previously registered with the target SD where the TA should be been previously registered with the target SD where the TA is to be
installed. installed.
sdname - the name of the target SD where the TA should be updated sdname - the name of the target SD where the TA should be updated
taid - an identifier for the TA application to be updated taid - an identifier for the TA application to be updated
encrypted_ta - the message portion contains new encrypted TA binary encrypted_ta - the message portion contains newly encrypted TA
data and personalization data. binary data and personalization data.
Following the OTrP message template, the full request is signed According to the OTrP message template, the full request
message over the UpdateTATBSRequest as follows. UpdateTARequest is a signed message over the UpdateTATBSRequest as
follows.
{ {
"UpdateTARequest": { "UpdateTARequest": {
"payload":"<UpdateTATBSRequest JSON above>", "payload": "<UpdateTATBSRequest JSON above>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": "<non-integrity-protected header contents>",
"signature":"<signature contents signed by TSM private key>" "signature": "<signature contents signed by TAM private key>"
} }
} }
8.3.2.2. UpdateTAResponse Message 9.3.2.2. UpdateTAResponse Message
The response message for a UpdateTARequest contains the following The response message for a UpdateTARequest contains the following
content. content.
{ {
"UpdateTATBSResponse": { "UpdateTATBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "<operation result>", "status": "<operation result>",
"rid": "<the request ID received>", "rid": "<the request ID received>",
"tid": "<the transaction ID received>", "tid": "<the transaction ID received>",
"content": ENCRYPTED { "content": ENCRYPTED {
"reason":"<failure reason detail>", // optional "reason": "<failure reason detail>", // optional
"did": "<the device id hash>", "did": "<the device id hash>",
"dsi": "<Updated TEE state, including all SD owned by "dsi": "<Updated TEE state, including all SD owned by
this TSM>" this TAM>"
} }
} }
} }
In the response message, the following fields MUST be supplied. In the response message, the following fields MUST be supplied.
did - the SHA256 hash of the device TEE certificate. This shows did - the SHA256 hash of the device TEE certificate. This shows
the device ID explicitly to the receiving TSM. the device ID explicitly to the receiving TAM.
The final message UpdateTAResponse looks like the following. The final message UpdateTAResponse looks like the following.
{ {
"UpdateTAResponse": { "UpdateTAResponse": {
"payload":"<UpdateTATBSResponse JSON above>", "payload":"<UpdateTATBSResponse JSON above>",
"protected": { "protected": {
"<BASE64URL of signing algorithm>" "<BASE64URL of signing algorithm>"
}, },
"signature": "<signature contents signed by TEE device "signature": "<signature contents signed by TEE device
private key (BASE64URL)>" private key (BASE64URL)>"
} }
} }
A response message type "status" will be returned when TEE totally A response message type "status" will be returned when the TEE fails
fails to respond. OTrP Agent is responsible to create this message. to respond. The OTrP Agent is responsible to create this message.
{ {
"status": { "status": {
"result": "fail", "result": "fail",
"error-code": "ERR_TEE_UNKNOWN", "error-code": "ERR_AGENT_TEE_FAIL",
"error-message": "TEE fails to respond" "error-message": "TEE fails to respond"
} }
} }
8.3.2.3. Error Conditions 9.3.2.3. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error may occur if a request isn't valid or the TEE runs into some
error. The list of possible errors are the following. Refer to error. The list of possible errors are as follows. Refer to the
section Error Code List (Section 14.1) for detail causes and actions. Error Code List (Section 15.1) for detailed causes and actions.
ERR_AGENT_TEE_BUSY
ERR_AGENT_TEE_FAIL
ERR_AGENT_TEE_UNKNOWN
ERR_REQUEST_INVALID ERR_REQUEST_INVALID
ERR_UNSUPPORTED_MSG_VERSION ERR_UNSUPPORTED_MSG_VERSION
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
ERR_TA_INVALID ERR_TA_INVALID
ERR_TA_NOT_FOUND ERR_TA_NOT_FOUND
ERR_TEE_FAIL ERR_TEE_FAIL
ERR_TEE_UNKNOWN ERR_TAM_NOT_AUTHORIZED
ERR_TSM_NOT_AUTHORIZED
ERR_TSM_NOT_TRUSTED ERR_TAM_NOT_TRUSTED
8.3.3. DeleteTA 9.3.3. DeleteTA
This operation defines OTrP messages that allow a TSM instruct a TEE This operation defines OTrP messages that allow a TAM to instruct a
to delete a TA for a SP in a given SD. A TEE will delete a TA from a TEE to delete a TA for an SP in a given SD. A TEE will delete a TA
SD and also TA data in the TEE. A Client Application cannot directly from an SD and also TA data in the TEE. A Client Application cannot
access TEE or OTrP Agent to delete a TA. directly access TEE or OTrP Agent to delete a TA.
8.3.3.1. DeleteTARequest Message 9.3.3.1. DeleteTARequest Message
The request message for DeleteTA has the following JSON format. The request message for DeleteTA has the following JSON format.
{ {
"DeleteTATBSRequest": { "DeleteTATBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "<unique request ID>", "rid": "<unique request ID>",
"tid": "<transaction ID>", "tid": "<transaction ID>",
"tee": "<TEE routing name from the DSI for the SD's target>", "tee": "<TEE routing name from the DSI for the SD's target>",
"nextdsi": "true | false", "nextdsi": true | false,
"dsihash": "<hash of DSI returned in the prior query>", "dsihash": "<hash of DSI returned in the prior query>",
"content": ENCRYPTED { "content": ENCRYPTED {
"tsmid": "<TSM ID previously assigned to the SD>", "tamid": "<TAM ID previously assigned to the SD>",
"sdname": "<SD name of the TA>", "sdname": "<SD name of the TA>",
"taid": "<the identifier of the TA to be deleted from the "taid": "<the identifier of the TA to be deleted from the
specified SD>" specified SD>"
} }
} }
} }
In the message, In the message,
rid - A unique value to identify this request rid - A unique value to identify this request
tid - A unique value to identify this transaction. It can have the tid - A unique value to identify this transaction. It can have the
same value for the tid in the preceding GetDeviceStateRequest. same value for the tid in the preceding GetDeviceStateRequest.
tee - TEE ID returned from the previous response tee - The TEE ID returned from the previous GetDeviceStateResponse
GetDeviceStateResponse
nextdsi - Indicates whether the up to date Device State Information nextdsi - Indicates whether the up-to-date Device State Information
(DSI) should be returned in the response to this request. (DSI) is to be returned in the response to this request.
dsihash - The BASE64 encoded SHA256 hash value of the DSI data dsihash - The BASE64-encoded SHA256 hash value of the DSI data
returned in the prior TSM operation with this target TEE. This returned in the prior TAM operation with this target TEE. This
value is always included such that a receiving TEE can check value is always included such that a receiving TEE can check
whether the device state has changed since its last query. It whether the device state has changed since its last query. It
helps enforce SD update order in the right sequence without helps enforce SD update order in the right sequence without
accidently overwrite an update that was done simultaneously. accidently overwriting an update that was done simultaneously.
content - The "content" is a JSON encrypted message that includes content - The "content" is a JSON encrypted message that includes
actual input for the SD update. The standard JSON content actual input for the SD update. The standard JSON content
encryption key (CEK) is used, and the CEK is encrypted by the encryption key (CEK) is used, and the CEK is encrypted by the
target TEE's public key. target TEE's public key.
tsmid - SD owner claim by TSM - A SD owned by a TSM will be tamid - SD owner claim by TAM - an SD owned by a TAM will be
associated with a trusted identifier defined as an attribute in the associated with a trusted identifier defined as an attribute in the
signer TSM certificate. signer TAM certificate.
sdname - the name of the target SD where the TA is installed sdname - the name of the target SD where the TA is installed
taid - an identifier for the TA application to be deleted taid - an identifier for the TA application to be deleted
Following the OTrP message template, the full request is signed According to the OTrP message template, the full request
message over the DeleteTATBSRequest as follows. DeleteTARequest is a signed message over the DeleteTATBSRequest as
follows.
{ {
"DeleteTARequest": { "DeleteTARequest": {
"payload":"<DeleteTATBSRequest JSON above>", "payload": "<DeleteTATBSRequest JSON above>",
"protected":"<integrity-protected header contents>", "protected": "<integrity-protected header contents>",
"header": <non-integrity-protected header contents>, "header": "<non-integrity-protected header contents>",
"signature":"<signature contents signed by TSM "signature": "<signature contents signed by TAM
private key>" private key>"
} }
} }
8.3.3.2. Request Processing Requirements at a TEE 9.3.3.2. Request Processing Requirements at a TEE
TEE processes command given by TSM to delete a TA of a SP SD. It A TEE processes a command from a TAM to delete a TA of an SP SD. It
does the following: does the following:
1. Validate the JSON request message 1. Validate the JSON request message
* TEE validates TSM message authenticity * The TEE validates TAM message authenticity
* Decrypt to get request content * Decrypt to get request content
* Lookup the SD and the TA with the given SD name and TA ID * Look up the SD and the TA with the given SD name and TA ID
* Checks that the TSM owns the SD, and TA is installed in the SD * Checks that the TAM owns the SD, and TA is installed in the SD
* Checks DSI hash matches that the device state hasn't changed * Checks that the DSI hash matches and the the device state
hasn't changed
2. Deletion action 2. Deletion action
* If all the above validation points pass, the TEE deletes the * If all the above validation points pass, the TEE deletes the
TA from the SD TA from the SD
* The TEE may also delete all personalization data for the TA * The TEE SHOULD also delete all personalization data for the TA
3. Construct DeleteTAResponse message. 3. Construct DeleteTAResponse message.
If a request is illegitimate or signature doesn't pass, a "status" If a request is illegitimate or the signature doesn't pass, a
property in the response will indicate the error code and cause. "status" property in the response will indicate the error code and
cause.
8.3.3.3. DeleteTAResponse Message 9.3.3.3. DeleteTAResponse Message
The response message for a DeleteTARequest contains the following The response message for a DeleteTARequest contains the following
content. content.
{ {
"DeleteTATBSResponse": { "DeleteTATBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "<operation result>", "status": "<operation result>",
"rid": "<the request ID received>", "rid": "<the request ID received>",
"tid": "<the transaction ID received>", "tid": "<the transaction ID received>",
"content": ENCRYPTED { "content": ENCRYPTED {
"reason":"<failure reason detail>", // optional "reason": "<failure reason detail>", // optional
"did": "<the device id hash>", "did": "<the device id hash>",
"dsi": "<Updated TEE state, including all SD owned by "dsi": "<Updated TEE state, including all SD owned by
this TSM>" this TAM>"
} }
} }
} }
In the response message, the following fields MUST be supplied. In the response message, the following fields MUST be supplied.
did - the SHA256 hash of the device TEE certificate. This shows did - the SHA256 hash of the device TEE certificate. This shows
the device ID explicitly to the receiving TSM. the device ID explicitly to the receiving TAM.
The final message DeleteTAResponse looks like the following. The final message DeleteTAResponse looks like the following.
{ {
"DeleteTAResponse": { "DeleteTAResponse": {
"payload":"<DeleteTATBSResponse JSON above>", "payload": "<DeleteTATBSResponse JSON above>",
"protected": { "protected": {
"<BASE64URL of signing algorithm>" "<BASE64URL of signing algorithm>"
}, },
"signature": "<signature contents signed by TEE device "signature": "<signature contents signed by TEE device
private key (BASE64URL)>" private key (BASE64URL)>"
} }
} }
A response message type "status" will be returned when TEE totally A response message type "status" will be returned when the TEE fails
fails to respond. OTrP Agent is responsible to create this message. to respond. The OTrP Agent is responsible to create this message.
{ {
"status": { "status": {
"result": "fail", "result": "fail",
"error-code": "ERR_TEE_UNKNOWN", "error-code": "ERR_AGENT_TEE_FAIL",
"error-message": "TEE fails to respond" "error-message": "TEE fails to respond"
} }
} }
8.3.3.4. Error Conditions 9.3.3.4. Error Conditions
An error may occur if a request isn't valid or the TEE runs into some An error may occur if a request isn't valid or the TEE runs into some
error. The list of possible errors are the following. Refer to error. The list of possible errors are as follows. Refer to the
section Error Code List (Section 14.1) for detail causes and actions. Error Code List (Section 15.1) for detailed causes and actions.
ERR_AGENT_TEE_BUSY
ERR_AGENT_TEE_FAIL
ERR_AGENT_TEE_UNKNOWN
ERR_REQUEST_INVALID ERR_REQUEST_INVALID
ERR_UNSUPPORTED_MSG_VERSION ERR_UNSUPPORTED_MSG_VERSION
ERR_UNSUPPORTED_CRYPTO_ALG ERR_UNSUPPORTED_CRYPTO_ALG
ERR_DEV_STATE_MISMATCH ERR_DEV_STATE_MISMATCH
ERR_SD_NOT_FOUND ERR_SD_NOT_FOUND
ERR_TA_NOT_FOUND ERR_TA_NOT_FOUND
ERR_TEE_FAIL ERR_TEE_FAIL
ERR_TEE_UNKNOWN ERR_TAM_NOT_AUTHORIZED
ERR_TSM_NOT_AUTHORIZED
ERR_TSM_NOT_TRUSTED ERR_TAM_NOT_TRUSTED
9. Response Messages a TSM May Expect 10. Response Messages a TAM May Expect
A TSM expects some feedback from a remote device when a request A TAM expects some feedback from a remote device when a request
message is delivered to a device. The following three types of message is delivered to a device. The following three types of
responses SHOULD be supplied. responses SHOULD be supplied.
Type 1: Expect a valid TEE generated response message Type 1: Expect a valid TEE-generated response message
A valid TEE signed response may contain errors detected by TEE, A valid TEE signed response may contain errors detected by a TEE,
e.g. TSM is trusted but TSM supplied data is missing, for e.g. a TAM is trusted but some TAM-supplied data is missing, for
example, SP ID doesn't exist. TEE MUST be able to sign and example, SP ID doesn't exist. TEE MUST be able to sign and
encrypt. encrypt.
If TEE isn't able to sign a response, TEE should returns an error If a TEE isn't able to sign a response, the TEE returns an error
to OTrP Agent without giving any other internal information. to the OTrP Agent without giving any other internal information.
OTrP Agent will be generating the response. The OTrP Agent will be generating the response.
Type 2: OTrP Agent generated error message when TEE fails. OTrP Type 2: The OTrP Agent generated error message when TEE fails.
Agent errors will be defined in this document. OTrP Agent errors will be defined in this document.
A Type 2 message has the following format. A Type 2 message has the following format.
{ {
"OTrPAgentError": { "OTrPAgentError": {
"ver": "1.0", "ver": "1.0",
"rid": "", "rid": "",
"tid": "", "tid": "",
"errcode": "ERR_TEE_FAIL | ERR_TEE_BUSY" "errcode": "ERR_AGENT_TEE_UNKNOWN | ERR_AGENT_TEE_BUSY"
} }
} }
Type 3: OTrP Agent itself isn't reachable or fails. A Client Type 3: OTrP Agent itself isn't reachable or fails. A Client
Application is responsible to handle error and response TSM in Application is responsible to handle error and respond the TAM in
its own way. This is out of scope for this specification. its own way. This is out of scope for this specification.
10. Basic Protocol Profile 11. Basic Protocol Profile
This section describes a baseline for interoperability among the This section describes a baseline for interoperability among the
protocol entities, mainly, the TSM and TEE. protocol entities, mainly, the TAM and TEE.
A TEE MUST support RSA algorithms. It is optional to support ECC A TEE MUST support RSA algorithms. It is optional to support ECC
algorithms. A TSM should use a RSA certificate for TSM message algorithms. A TAM SHOULD use a RSA certificate for TAM message
signing. It may use an ECC certificate if it detects that the TEE signing. It may use an ECC certificate if it detects that the TEE
supports ECC. supports ECC according to the field "supportedsigalgs" in a TEE
response.
A TSM MUST support both RSA 2048-bit algorithm and ECC P-256 A TAM MUST support both RSA 2048-bit algorithm and ECC P-256
algorithms. With this, a TEE and TFW certificate can be either RSA algorithms. With this, a TEE and TFW certificate can be either RSA
or ECC type. or ECC type.
JSON signing algorithms JSON signing algorithms
o RSA PKCS#1 with SHA256 signing : "RS256" o RSA PKCS#1 with SHA256 signing : "RS256"
o ECDSA with SHA256 signing : "ES256" o ECDSA with SHA256 signing : "ES256"
JSON asymmetric encryption algorithms (describes key-exchange or key- JSON asymmetric encryption algorithms (describes key-exchange or key-
skipping to change at page 76, line 4 skipping to change at page 78, line 6
JSON signing algorithms JSON signing algorithms
o RSA PKCS#1 with SHA256 signing : "RS256" o RSA PKCS#1 with SHA256 signing : "RS256"
o ECDSA with SHA256 signing : "ES256" o ECDSA with SHA256 signing : "ES256"
JSON asymmetric encryption algorithms (describes key-exchange or key- JSON asymmetric encryption algorithms (describes key-exchange or key-
agreement algorithm for sharing symmetric key with TEE): agreement algorithm for sharing symmetric key with TEE):
o RSA PKCS#1 : "RSA1_5" o RSA PKCS#1 : "RSA1_5"
o ECDH using TEE ECC P-256 key and ephemeral ECC key generated by o ECDH using TEE ECC P-256 key and ephemeral ECC key generated by
TSM : "ECDH-ES+A128W" TAM : "ECDH-ES+A128W"
JSON symmetric encryption algorithms (describes symmetric algorithm JSON symmetric encryption algorithms (describes symmetric algorithm
for encrypting body of data, using symmetric key transferred to TEE for encrypting body of data, using symmetric key transferred to TEE
using asymmetric encryption): using asymmetric encryption):
o Authenticated encryption AES 128 CBC with SHA256 : o Authenticated encryption AES 128 CBC with SHA256 :
{"enc":"A128CBC-HS256"} {"enc":"A128CBC-HS256"}
11. Attestation Implementation Consideration 12. Attestation Implementation Consideration
It is important to know that the state of a device is appropriate It is important to know that the state of a device is appropriate
before trusting that a device is what it says it is. The attestation before trusting that a device is what it says it is. The attestation
scheme for OTrP must also be able to cope with different TEEs, those scheme for OTrP must also be able to cope with different TEEs,
that are OTrP compliant and those that use another mechanism. In the including those that are OTrP compliant and those that use another
initial version, only one active TEE is assumed. mechanism. In the initial version, only one active TEE is assumed.
It is out of scope about how TSM and device implement the trust It is out of scope how the TAM and the device implement the trust
hierarchy verification. However, it is helpful to understand what hierarchy verification. However, it is helpful to understand what
each system provider should do in order to properly implement OTrP each system provider should do in order to properly implement an OTrP
trust hierarchy. trust hierarchy.
In this section, we provide some implementation reference In this section, we provide some implementation reference
consideration. consideration.
11.1. OTrP Secure Boot Module 12.1. OTrP Secure Boot Module
11.1.1. Attestation signer 12.1.1. Attestation signer
It is proposed that attestation for OTrP is based on the SBM secure It is proposed that attestation for OTrP is based on the SBM secure
boot layer, and that further attestation is not performed within the boot layer, and that further attestation is not performed within the
TEE itself during security domain operations. The rationale is that TEE itself during Security Domain operations. The rationale is that
the device boot process will be defined to start with a secure boot the device boot process will be defined to start with a secure boot
approach that, using eFuse, only releases attestation signing approach that, using eFuse, only releases attestation signing
capabilities into the SBM once a secure boot has been established. capabilities into the SBM once a secure boot has been established.
In this way the release of the attestation signer can be considered In this way the release of the attestation signer can be considered
the first "platform configuration metric", using TCG terminology. the first "platform configuration metric", using Trust Computing
Group (TCG) terminology.
11.1.2. SBM Initial Requirements 12.1.2. SBM Initial Requirements
R1 SBM must be possible to load securely into the secure boot flow R1 The SBM must be possible to load securely into the secure boot
flow
R2 SBM must allow a public / private key pair to be generated during R2 The SBM must allow a public / private key pair to be generated
device manufacture during device manufacture
R3 The public key and certificate must be possible to store securely R3 The public key and certificate must be possible to store securely
from tamper
R4 The private key must be possible to store encrypted at rest R4 The private key must be possible to store encrypted at rest
R5 The private key must only be visible to the SBM when it is R5 The private key must only be visible to the SBM when it is
decrypted decrypted
R6 The SBM must be able to read a list of root and intermediate R6 The SBM must be able to read a list of root and intermediate
certificates that it can use to check certificate chains with. certificates that it can use to check certificate chains with.
The list must be stored such that it cannot be tampered with The list must be stored such that it cannot be tampered with
R7 Possible need to allow a TEE to access its unique TEE specific R7 Need to allow a TEE to access its unique TEE specific private key
private key
11.2. TEE Loading 12.2. TEE Loading
During boot SBM is required to start all of the ROOT TEEs. Before During boot, the SBM is required to start all of the root TEEs.
loading them the SBM must first determine whether the code sign Before loading them, the SBM must first determine whether the code
signature of the TEE is valid. If TEE integrity is confirmed it may sign signature of the TEE is valid. If TEE integrity is confirmed,
be started. The SBM must then be able to receive the identity the TEE may be started. The SBM must then be able to receive the
certificate from the TEE (if that TEE is OTrP compliant). The identity certificate from the TEE (if that TEE is OTrP compliant).
identity certificate and keys will need to be baked into the TEE The identity certificate and keys will need to be baked into the TEE
image, and therefore also covered by the code signer hash during the image, and therefore also covered by the code signer hash during the
manufacture process. The private key for the identity certificate manufacturing process. The private key for the identity certificate
must be securely protected. The private key for a TEE identity must must be securely protected. The private key for a TEE identity must
never be released no matter how the public key and certificate are never be released no matter how the public key and certificate are
released to the SBM. released to the SBM.
Once the SBM has successfully booted a TEE and retrieved the identity Once the SBM has successfully booted a TEE and retrieved the identity
certificate it will commit this to the platform configuration certificate, the SBM will commit this to the platform configuration
register (PCR) set, for later use during attestation. As a minimum register (PCR) set, for later use during attestation. At minimum,
the following data must be committed to the PCR for each TEE: the following data must be committed to the PCR for each TEE:
1. Public key and certificate for the TEE 1. Public key and certificate for the TEE
2. TEE reference that can be used later by a TSM to identify this 2. TEE identifier that can be used later by a TAM to identify this
TEE TEE
11.3. Attestation Hierarchy 12.3. Attestation Hierarchy
The attestation hierarchy and seed required for TSM protocol The attestation hierarchy and seed required for TAM protocol
operation must be built into the device at manufacture. Additional operation must be built into the device at manufacture. Additional
TEEs can be added post manufacture using the scheme proposed however TEEs can be added post-manufacture using the scheme proposed, but it
it is outside of the current scope of this document to detail that. is outside of the current scope of this document to detail that.
It should be noted that the attestation scheme described is based on It should be noted that the attestation scheme described is based on
signatures. The only encryption that takes place is with eFuse to signatures. The only encryption that takes place is with eFuse to
release the SBM signing key and later during protocol lifecycle release the SBM signing key and later during the protocol lifecycle
management interchange with the TSM. management interchange with the TAM.
11.3.1. Attestation Hierarchy Establishment: Manufacture 12.3.1. Attestation Hierarchy Establishment: Manufacture
During manufacture the following steps are required: During manufacture the following steps are required:
1. Device specific TFW key pair and certificate burnt into device, 1. A device-specific TFW key pair and certificate are burnt into the
encrypted by eFuse. This key pair will be used for signing device, encrypted by eFuse. This key pair will be used for
operations performed by SBM. signing operations performed by the SBM.
2. TEE images are loaded and include a TEE instance specific key 2. TEE images are loaded and include a TEE instance-specific key
pair and certificate. The key pair and certificate are included pair and certificate. The key pair and certificate are included
in the image and covered by the code signing hash. in the image and covered by the code signing hash.
3. The process for TEE images is repeated for any subordinate TEEs 3. The process for TEE images is repeated for any subordinate TEEs,
which are additional TEEs after the root TEE that some devices
have.
11.3.2. Attestation Hierarchy Establishment: Device Boot 12.3.2. Attestation Hierarchy Establishment: Device Boot
During device boot the following steps are required: During device boot the following steps are required:
1. Secure boot releases TFW private key by decrypting with eFuse 1. Secure boot releases the TFW private key by decrypting it with
eFuse
2. SBM verifies the code-signing signature of the active TEE and 2. The SBM verifies the code-signing signature of the active TEE and
places its TEE public key into a signing buffer, along with their places its TEE public key into a signing buffer, along with its
reference for later access. For non-OTrP TEE, the SBM leaves the identifier for later access. For a non-OTrP TEE, the SBM leaves
TEE public key field blank. the TEE public key field blank.
3. SBM signs the signing buffer with TFW private key 3. The SBM signs the signing buffer with the TFW private key.
4. Each active TEE performs the same operation as SBM, building up 4. Each active TEE performs the same operation as the SBM, building
their own signed buffer containing subordinate TEE information. up their own signed buffer containing subordinate TEE
information.
11.3.3. Attestation Hierarchy Establishment: TSM 12.3.3. Attestation Hierarchy Establishment: TAM
Before a TSM can begin operation in the marketplace it must obtain a Before a TAM can begin operation in the marketplace to support
TSM key pair and certificate (TSMpub, TSMpriv) from a CA that is devices of a given TEE, it must obtain a TAM certificate from a CA
registered in the trust store of the TEE. In this way, the TEE can that is registered in the trust store of devices with that TEE. In
check the intermediate and root CA and verify that it trusts this TSM this way, the TEE can check the intermediate and root CA and verify
to perform operations on the TEE. that it trusts this TAM to perform operations on the TEE.
12. Acknowledgements 13. Acknowledgements
We thank Alin Mutu for his contribution to many discussion that We thank Alin Mutu for his contribution to many discussion that
helped to design the trust flow mechanisms, and the creation of the helped to design the trust flow mechanisms, and the creation of the
flow diagrams. We also thank the following people (by alphabetical flow diagrams. We also thank the following people (in alphabetical
order) for their input and review: Sangsu Baek, Marc Canel, Roger order) for their input and review: Sangsu Baek, Marc Canel, Roger
Casals, Rob Coombs, Lubna Dajani, Richard Parris, and Pengfei Zhao. Casals, Rob Coombs, Lubna Dajani, Richard Parris, Dave Thaler, and
Pengfei Zhao.
13. Contributors 14. Contributors
Brian Witten Brian Witten
Symantec Symantec
900 Corporate Pointe 900 Corporate Pointe
Culver City, CA 90230 Culver City, CA 90230
USA USA
Email: brian_witten@symantec.com Email: brian_witten@symantec.com
Tyler Kim Tyler Kim
Solacia Solacia
5F, Daerung Post Tower 2, 306 Digital-ro 5F, Daerung Post Tower 2, 306 Digital-ro
Seoul 152-790 Seoul 152-790
Korea Korea
Email: tkkim@sola-cia.com Email: tkkim@sola-cia.com
14. IANA Considerations 15. IANA Considerations
The error code listed in the next section will be registered. The error code listed in the next section will be registered.
14.1. Error Code List 15.1. Error Code List
This section lists error codes that could be reported by a TA or TEE This section lists error codes that could be reported by a TA or TEE
in a device in responding a TSM request. in a device in responding to a TAM request, and a separate list that
OTrP Agent may return when the TEE fails to respond.
ERR_DEV_STATE_MISMATCH - TEE will return this error code if DSI hash 15.1.1. TEE Signed Error Code List
value from TSM doesn't match with that of device's current DSI.
ERR_SD_ALREADY_EXIST - This error will occur if SD to be created ERR_DEV_STATE_MISMATCH - A TEE will return this error code if the
already exist in the TEE. DSI hash value from TAM doesn't match the has value of the device's
current DSI.
ERR_SD_ALREADY_EXISTS - This error will occur if an SD to be created
already exists in the TEE.
ERR_SD_NOT_EMPTY - This is reported if a target SD isn't empty. ERR_SD_NOT_EMPTY - This is reported if a target SD isn't empty.
ERR_SDNAME_ALREADY_USED TEE will return this error code if new SD ERR_SDNAME_ALREADY_USED A TEE will return this error code if the new
name already exists in the namespace of TSM in the TEE. SD name already exists in the TEE.
ERR_REQUEST_INVALID - This error will occur if the TEE meets the ERR_REQUEST_INVALID - This error will occur if the TEE meets any of
following conditions with a request message: (1) The request from a the following conditions with a request message: (1) The request
TSM has an invalid message structure; mandatory information is from a TAM has an invalid message structure; mandatory information
absent in the message. undefined member or structure is included. is absent in the message. undefined member or structure is
(2) TEE fails to verify signature of the message or fails to included. (2) TEE fails to verify signature of the message or
decrypt its contents. (3) etc. fails to decrypt its contents.
ERR_SPCERT_INVALID - If new SP certificate for the SD to be updated ERR_SPCERT_INVALID - If a new SP certificate for the SD to be
is not valid, then TEE will return this error code. updated is not valid, then the TEE will return this error code.
ERR_TA_ALREADY_INSTALLED - while installing TA, TEE will return this ERR_TA_ALREADY_INSTALLED - While installing a TA, a TEE will return
error if the TA already has been installed in the SD. this error if the TA has already been installed in the SD.
ERR_TA_INVALID - This error will occur when TEE meets any of ERR_TA_INVALID - This error will occur when a TEE meets any of
following conditions while checking validity of TA: (1) TA binary following conditions while checking validity of TA: (1) The TA
has a format that TEE can't recognize. (2) TEE fails to decrypt the binary has a format that the TEE can't recognize. (2) The TEE fails
encoding of TA binary and personalization data. (3) If SP isn't to decrypt the encoding of the TA binary and personalization data.
registered with the SP SD where TA will be installed. (4) etc. (3) If an SP isn't registered with the SP SD where the TA will be
installed.
ERR_TA_NOT_FOUND - This error will occurs when target TA doesn't ERR_TA_NOT_FOUND - This error will occur when the target TA doesn't
exist in the SD. exist in the SD.
ERR_TEE_BUSY - The device TEE is busy. The request should be ERR_TEE_FAIL - If the TEE fails to process a request because of an
generally sent later to retry.
ERR_TEE_FAIL - TEE fails to respond to a TSM request. The OTrP
Agent will construct an error message in responding the TSM's
request. And also if TEE fails to process a request because of its
internal error, it will return this error code. internal error, it will return this error code.
ERR_TEE_RESOURCE_FULL - This error is reported when a device ERR_TEE_RESOURCE_FULL - This error is reported when a device
resource isn't available anymore such as storage space is full. resource isn't available anymore such as storage space is full.
ERR_TEE_UNKNOWN - This error will occur if the receiver TEE is not ERR_TFW_NOT_TRUSTED - A TEE is responsible for determining that the
supposed to receive the request. That will be determined by underlying device firmware is trustworthy. If the TEE determines
checking TEE name or device id in the request message. the TFW is not trustworthy, then this error will occur.
ERR_TFW_NOT_TRUSTED - TEE may concern the underlying device firmware ERR_TAM_NOT_TRUSTED - Before processing a request, a TEE needs to
is trustworthy. If TEE determines TFW is not trustworthy, then make sure whether the sender TAM is trustworthy by checking the
this error will occur. validity of the TAM certificate, etc. If the TEE finds that the
TAM is not trustworthy, then it will return this error code.
ERR_TSM_NOT_TRUSTED - Before processing a request, TEE needs to make ERR_UNSUPPORTED_CRYPTO_ALG - This error will occur if a TEE receives
sure whether the sender TSM is trustworthy by checking the validity a request message encoded with cryptographic algorithms that the
of TSM certificate etc. If TEE finds TSM is not reliable, then it TEE doesn't support.
will return this error code.
ERR_UNSUPPORTED_CRYPTO_ALG - This error will occur if TEE receives a ERR_UNSUPPORTED_MSG_VERSION - This error will occur if a TEE
request message encoded with cryptographic algorithms that TEE receives a message version that the TEE can't deal with.
doesn't support.
ERR_UNSUPPORTED_MSG_VERSION - This error will occur if TEE receives 15.1.2. OTrP Agent Error Code List
the version of message that TEE can't deal with.
15. Security Consideration ERR_AGENT_TEE_UNKNOWN - This error will occur if the receiver TEE is
15.1. Cryptographic Strength not supposed to receive the request. That will be determined by
checking the TEE name or device id in the request message.
ERR_AGENT_TEE_BUSY - The device TEE is busy. The request can be
generally sent again to retry.
ERR_AGENT_TEE_FAIL - The TEE fails to respond to a TAM request. The
OTrP Agent will construct an error message in responding to the
TAM's request.
16. Security Consideration
16.1. Cryptographic Strength
The strength of the cryptographic algorithms, using the measure of The strength of the cryptographic algorithms, using the measure of
'bits of security' defined in NIST SP800-57 allowed for the OTrP 'bits of security' defined in NIST SP800-57 allowed for OTrP is:
protocol is:
o At a minimum, 112 bits of security. The limiting factor for this o At a minimum, 112 bits of security. The limiting factor for this
is the RSA-2048 algorithm, which is indicated as providing 112 is the RSA-2048 algorithm, which is indicated as providing 112
bits of symmetric key strength in SP800-57. It is important that bits of symmetric key strength in SP800-57. It is important that
RSA is supported in order to enhance the interoperability of the RSA is supported in order to enhance the interoperability of the
protocol. protocol.
o The option exists to choose algorithms providing 128 bits of o The option exists to choose algorithms providing 128 bits of
security. This requires using TEE devices that support ECC P256. security. This requires using TEE devices that support ECC P256.
The available algorithms and key sizes specified in this document are The available algorithms and key sizes specified in this document are
based on industry standards. Over time the recommended or allowed based on industry standards. Over time the recommended or allowed
cryptographic algorithms may change. It is important that the OTrP cryptographic algorithms may change. It is important that the OTrP
protocol allows for crypto-agility. allows for crypto-agility. In this specification, TAM and TEE can
negotiate an agreed upon algorithm where both include their supported
algorithm in OTrP message.
15.2. Message Security 16.2. Message Security
OTrP messages between the TSM and TEE are protected by message OTrP messages between the TAM and TEE are protected by message
security using JWS and JWE. The 'Basic protocol profile' section of security using JWS and JWE. The 'Basic protocol profile' section of
this document describes the algorithms used for this. All OTrP TEE this document describes the algorithms used for this. All OTrP TEE
devices and OTrP TSMs must meet the requirements of the basic devices and OTrP TAMs must meet the requirements of the basic
profile. In the future additional 'profiles' can be added. profile. In the future additional 'profiles' can be added.
PKI is used to ensure that the TEE will only communicate with a PKI is used to ensure that the TEE will only communicate with a
trusted TSM, and to ensure that the TSM will only communicate with a trusted TAM, and to ensure that the TAM will only communicate with a
trusted TEE. trusted TEE.
15.3. TEE Attestation 16.3. TEE Attestation
It is important that the TSM can trust that it is talking to a It is important that the TAM can trust that it is talking to a
trusted TEE. This is achieved through attestation. The TEE has a trusted TEE. This is achieved through attestation. The TEE has a
private key and certificate built into it at manufacture, which is private key and certificate built into it at manufacture, which is
used to sign data supplied by the TSM. This allows the TSM to verify used to sign data supplied by the TAM. This allows the TAM to verify
that the TEE is trusted. that the TEE is trusted.
It is also important that the TFW (trusted firmware) can be checked. It is also important that the TFW (trusted firmware) can be checked.
The TFW has a private key and certificate built into it at The TFW has a private key and certificate built into it at
manufacturer, which allows the TEE to check that that the TFW is manufacture, which allows the TEE to check that that the TFW is
trusted. trusted.
The GetDeviceState message therefore allows the TSM to check that it The GetDeviceState message therefore allows the TAM to check that it
trusts the TEE, and the TEE at this point will check whether it trusts the TEE, and the TEE at this point will check whether it
trusts the TFW. trusts the TFW.
15.4. TA Protection 16.4. TA Protection
TA will be delivered in an encrypted form. This encryption is an A TA will be delivered in an encrypted form. This encryption is an
additional layer within the message encryption described in the additional layer within the message encryption described in the
'Basic protocol profile' section of this document. The TA binary is Section 11 of this document. The TA binary is encrypted for each
encrypted for each target device with the device's TEE SP AIK public target device with the device's TEE SP AIK public key. A TAM can
key. A TSM may do this encryption or provides the TEE SP AIK public either do this encryption itself or provide the TEE SP AIK public key
key to a SP such that the SP encrypts the encrypted TA to TSM for to an SP such that the SP encrypts the encrypted TA for distribution
distribution to TEE. to the TEE.
The encryption algorithm can use a randomly AES 256 key "taek" with a The encryption algorithm can use a random AES 256 key "taek" with a
16 byte random IV, and the "taek" is encrypted by the "TEE SP AIK 16 byte random IV, and the "taek" is encrypted by the "TEE SP AIK
public key". The following encrypted TA data structure is expected public key". The following encrypted TA data structure is expected
by TEE: by a TEE:
"encrypted_ta_bin": { "encrypted_ta_bin": {
"key": "<A 256-bit symmetric key encrypted by TEE SP AIK public "key": "<JWE enveloped data of a 256-bit symmetric key by
key>", the recipient's TEEspaik public key>",
"iv": <hex of 16 random bytes>", "iv": <hex of 16 random bytes>",
"alg": "AESCBC", "alg": "AESCBC",
"cipherdata": "<BASE64 encoded encrypted TA binary data>" "cipherdata": "<BASE64 encoded encrypted TA binary data>"
} }
15.5. TA Personalization Data 16.5. TA Personalization Data
A SP or TSM can supply personalization data for a TA to initialize An SP or TAM can supply personalization data for a TA to initialize
for a device. Such data is passed through InstallTA command from for a device. Such data is passed through an InstallTA command from
TSM. The personalization data itself is (or can be) opaque to the a TAM. The personalization data itself is (or can be) opaque to the
TSM. The data can be from the SP without being revealed to the TSM. TAM. The data can be from the SP without being revealed to the TAM.
The data is sent in encrypted manner in a request to a device such The data is sent in an encrypted manner in a request to a device such
that only the device can decrypt. A device's TEE SP AIK public key that only the device can decrypt. A device's TEE SP AIK public key
for a SP is used to encrypt the data. for an SP is used to encrypt the data. Here JWE enveloping is used
to carry all encryption key parameters along with encrypted data.
"encrypted_ta_data": { // "TA personalization data" "encrypted_ta_data": { // "TA personalization data"
"key": "<A 256-bit symmetric key encrypted by TEE SP AIK public "key": "<JWE enveloped data of a 256-bit symmetric key by
key>", the recipient's TEEspaik public key>",
"iv": "<hex of 16 random bytes>", "iv": "<hex of 16 random bytes>",
"alg": "AESCBC", "alg": "AESCBC",
"cipherdata": "<BASE64 encoded encrypted TA personalization "cipherdata": "<BASE64 encoded encrypted TA personalization
data>" data>"
} }
15.6. TA Trust Check at TEE 16.6. TA Trust Check at TEE
A TA binary is signed by a TA signer certificate. This TA signing A TA binary is signed by a TA signer certificate. This TA signing
certificate/private key belongs to the SP, and may be self-signed certificate/private key belongs to the SP, and may be self-signed
(i.e. it need not participate in a trust hierarchy). It is the (i.e., it need not participate in a trust hierarchy). It is the
responsibility of the TSM to only allow verified TAs from trusted SPs responsibility of the TAM to only allow verified TAs from trusted SPs
into the system. Delivery of that TA to the TEE is then the into the system. Delivery of that TA to the TEE is then the
responsibility of the TEE, using the security mechanisms provided by responsibility of the TEE, using the security mechanisms provided by
the OTrP protocol. the OTrP.
We allow a way for application to check trustworthy of a TA. OTrP We allow a way for an (untrusted) application to check the
Agent will have a function to allow an application query the metadata trustworthiness of a TA. OTrP Agent has a function to allow an
of a TA. application to query the information about a TA.
An application in the Rich O/S may perform verification of the TA by An application in the Rich O/S may perform verification of the TA by
verifying the signature of the TA. The verifying the signature of the TA. The GetTAInformation function is
OTRPService.getTAInformation() function is available to return TEE available to return the TEE supplied TA signer and TAM signer
supplied TA signer and TSM signer information to the application. An information to the application. An application can do additional
application can do additional trust check on the certificate returned trust checks on the certificate returned for this TA. It might trust
for this TA. It may trust TSM, or require additional SP signer trust the TAM, or require additional SP signer trust chaining.
chaining.
15.7. One TA Multiple SP Case 16.7. One TA Multiple SP Case
A TA for different SP must have different identifier. A TA will be A TA for multiple SPs must have a different identifier per SP. A TA
installed in different SD for the respective SP. will be installed in a different SD for each respective SP.
15.8. OTrP Agent Trust Model 16.8. OTrP Agent Trust Model
An OTrP Agent could be malware in the vulnerable Android OS. A An OTrP Agent could be malware in the vulnerable Rich OS. A Client
Client Application will connect its TSM provider for required TA Application will connect its TAM provider for required TA
installation. It gets command messages from TSM, and passes the installation. It gets command messages from the TAM, and passes the
message to the OTrP Agent. message to the OTrP Agent.
The OTrP protocol is a conduit for enabling the TSM to communicate The OTrP is a conduit for enabling the TAM to communicate with the
with the device's TEE to manage SDs and TAs. All TSM messages are device's TEE to manage SDs and TAs. All TAM messages are signed and
signed and sensitive data is encrypted such that the OTrP Agent sensitive data is encrypted such that the OTrP Agent cannot modify or
cannot modify or capture sensitive data. capture sensitive data.
15.9. OCSP Stapling Data for TSM Signed Messages 16.9. OCSP Stapling Data for TAM Signed Messages
The GetDeviceStateRequest message from TSM to TEE shall include OCSP The GetDeviceStateRequest message from a TAM to a TEE shall include
stapling data for the TSM's signer certificate and that for OCSP stapling data for the TAM's signer certificate and for
intermediate CA certificates up to the root certificate so that the intermediate CA certificates up to the root certificate so that the
TEE side can verify the signer certificate's revocation status. TEE can verify the signer certificate's revocation status.
Certificate revocation status check on a TA signer certificate is A certificate revocation status check on a TA signer certificate is
optional by a TEE. A TSM is generally expected to do proper TA OPTIONAL by a TEE. A TAM is responsible for vetting a TA and the SP
application vetting and its SP signer trust validation. A TEE will before it distributes them to devices. A TEE will trust a TA signer
trust a TA signer certificate's validation status done by a TSM when certificate's validation status done by a TAM when it trusts the TAM.
it trusts the TSM.
15.10. Data Protection at TSM and TEE 16.10. Data Protection at TAM and TEE
The TEE implementation provides protection of data on the device. It The TEE implementation provides protection of data on the device. It
is the responsibility of the TSM to protect data on its servers. is the responsibility of the TAM to protect data on its servers.
15.11. Privacy Consideration 16.11. Privacy Consideration
Devices are issued with a unique TEE certificate to attest a device Devices are issued with a unique TEE certificate to attest the
validity. This uniqueness also creates a privacy and tracking risk device's validity. This uniqueness also creates a privacy and
that must be mitigated. tracking risk that must be mitigated.
The TEE will only release the TEE certificate to a trusted TSM (it The TEE will only release the TEE certificate to a trusted TAM (it
must verify the TSM certificate before proceeding). The OTrP must verify the TAM certificate before proceeding). OTrP is designed
protocol is designed such that only the TSM can obtain the TEE device such that only a TAM can obtain the TEE device certificate and
certificate and firmware certificate - the GetDeviceState message firmware certificate - the GetDeviceState message requires signature
requires signature checks to validate the TSM is trusted, and then checks to validate the TAM is trusted, and OTrP delivers the device's
delivers the device's certificate(s) encrypted such that only that certificate(s) encrypted such that only that TAM can decrypt the
TSM may decrypt the response. A Client Application will never see response. A Client Application will never see the device
device certificate. certificate.
A SP specific TEE SP AIK (TEE SP Anonymous Key) is generated by the An SP-specific TEE SP AIK (TEE SP Anonymous Key) is generated by the
protocol for Client Applications. This provides a way for the Client protocol for Client Applications. This provides a way for the Client
Application to validate data sent from the TEE without requiring the Application to validate some data that the TEE may send without
TEE device certificate to be released to the client device rich O/S , requiring the TEE device certificate to be released to the client
and to optionally allow an SP to encrypt a TA for a target device device rich O/S , and to optionally allow an SP to encrypt a TA for a
without the SP needing to be supplied the TEE device certificate. target device without the SP needing to be supplied with the TEE
device certificate.
15.12. Threat Mitigation 16.12. Threat Mitigation
A rogue application may perform excessive TA loading. OTrP Agent A rogue application may perform excessive TA loading. An OTrP Agent
implementation should protect against excessive calls. implementation should protect against excessive calls.
Rogue applications may request excessive SD creation request. The Rogue applications might request excessive SD creation. The TAM is
TSM is responsible to ensure this is properly guarded against. responsible to ensure this is properly guarded against.
Rogue OTrP Agent could replay or send TSM messages out of Rogue OTrP Agent could replay or send TAM messages out of sequence:
sequence:e.g. TSM sends update1 and update2. OTrP Agent replays e.g., a TAM sends update1 and update2. The OTrP Agent replays
update2 and update1 again, create unexpected result that client update2 and update1 again, creating an unexpected result that a
wants. "dsihash" is used to mitigate this. The TEE MUST make sure client wants. "dsihash" is used to mitigate this. The TEE MUST store
it stores DSI state and checks DSI state matches before it does DSI state and check that the DSI state matches before it does another
another update. update.
Concurrent calls from TSM to TEE should be handled properly by a TEE. Concurrent calls from a TAM to a TEE MUST be handled properly by a
It is up to the device to manage concurrency to the TEE. If multiple TEE. If multiple concurrent TAM operations take place, these could
concurrent TSM operations take place these could fail due "dsihash" fail due to the "dsihash" being modified by another concurrent
being modified by another concurrent operation. If locking is operation. The TEE is responsible for resolve any locking such that
implemented on the client, this must be done in such a way that one one application cannot lock other applications from using the TEE,
application cannot lock other applications from using the TEE, except except for a short term duration of the TAM operation taking place.
for a short term duration of the TSM operation taking place. For For example, an OTrP operation that starts but never completes (e.g.
example, an OTrP operation that starts but never completes (e.g. loss loss of connectivity) must not prevent subsequent OTrP messages from
of connectivity) must not prevent subsequent OTrP messages from being being executed.
executed.
15.13. Compromised CA 16.13. Compromised CA
If a root CA for TSM certificates is found compromised, some TEE A root CA for TAM certificates might get compromised. Some TEE trust
trust anchor update mechanism should be devised. A compromised anchor update mechanism is expected from device OEM. A compromised
intermediate CA is covered by OCSP stapling and OCSP validation check intermediate CA is covered by OCSP stapling and OCSP validation check
in the protocol. A TEE should validate certificate revocation about in the protocol. A TEE should validate certificate revocation about
a TSM certificate chain. a TAM certificate chain.
If the root CA of some TEE device certificates is compromised, these If the root CA of some TEE device certificates is compromised, these
devices might be rejected by TSM, which is a decision of TSM devices might be rejected by a TAM, which is a decision of the TAM
implementation and policy choice. Any intermediate CA for TEE device implementation and policy choice. Any intermediate CA for TEE device
certificates should be validated by TSM with common CRL or OCSP certificates SHOULD be validated by TAM with a Certificate Revocation
method. List (CRL) or Online Certificate Status Protocol (OCSP) method.
15.14. Compromised TSM 16.14. Compromised TAM
The TEE should use validation of the supplied TSM certificates and The TEE SHOULD use validation of the supplied TAM certificates and
OCSP stapled data to validate that the TSM is trustworthy. OCSP stapled data to validate that the TAM is trustworthy.
Since PKI is used, the integrity of the clock within the TEE Since PKI is used, the integrity of the clock within the TEE
determines the ability of the TEE to reject an expired TSM determines the ability of the TEE to reject an expired TAM
certificate, or revoked TSM certificate. Since OCSP stapling certificate, or revoked TAM certificate. Since OCSP stapling
includes signature generation time, certificate validity dates are includes signature generation time, certificate validity dates are
compared to the current time. compared to the current time.
15.15. Certificate Renewal 16.15. Certificate Renewal
TFW and TEE device certificates are expected to be long lived, longer TFW and TEE device certificates are expected to be long lived, longer
than the lifetime of a device. A TSM certificate usually has a than the lifetime of a device. A TAM certificate usually has a
moderate lifetime of 2 to 5 years. TSM should get renewed or rekeyed moderate lifetime of 2 to 5 years. A TAM should get renewed or
certificates.The root CA certificates for TSM, which is embedded into rekeyed certificates. The root CA certificates for a TAM, which are
the trust anchor store in a device, should have long lifetime that embedded into the trust anchor store in a device, should have long
don't require device trust anchor update. On the other hand, it is lifetimes that don't require device trust anchor update. On the
imperative that OEM or device providers plan for support of trust other hand, it is imperative that OEMs or device providers plan for
anchor update in their shipped devices. support of trust anchor update in their shipped devices.
16. References 17. References
16.1. Normative References 17.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, <https://www.rfc- DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
editor.org/info/rfc2119>. editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015, RFC 7516, DOI 10.17487/RFC7516, May 2015,
<https://www.rfc-editor.org/info/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015, <https://www.rfc- DOI 10.17487/RFC7517, May 2015, <https://www.rfc-
editor.org/info/rfc7517>. editor.org/info/rfc7517>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, <https://www.rfc- DOI 10.17487/RFC7518, May 2015, <https://www.rfc-
editor.org/info/rfc7518>. editor.org/info/rfc7518>.
16.2. Informative References 17.2. Informative References
[GPTEE] Global Platform, "Global Platform, GlobalPlatform Device [GPTEE] Global Platform, "Global Platform, GlobalPlatform Device
Technology: TEE System Architecture, v1.0", 2013. Technology: TEE System Architecture, v1.0", 2013.
[GPTEECLAPI]
Global Platform, "Global Platform, GlobalPlatform Device
Technology: TEE Client API Specification, v1.0", 2013.
Appendix A. Sample Messages Appendix A. Sample Messages
A.1. Sample Security Domain Management Messages A.1. Sample Security Domain Management Messages
A.1.1. Sample GetDeviceState A.1.1. Sample GetDeviceState
A.1.1.1. Sample GetDeviceStateRequest A.1.1.1. Sample GetDeviceStateRequest
TSM builds a "GetDeviceStateTBSRequest" message. The TAM builds a "GetDeviceStateTBSRequest" message.
{ {
"GetDeviceStateTBSRequest": { "GetDeviceStateTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "8C6F9DBB-FC39-435c-BC89-4D3614DA2F0B", "rid": "8C6F9DBB-FC39-435c-BC89-4D3614DA2F0B",
"tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE", "tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE",
"ocspdat": "c2FtcGxlIG9jc3BkYXQgQjY0IGVuY29kZWQgQVNOMQ==", "ocspdat": "c2FtcGxlIG9jc3BkYXQgQjY0IGVuY29kZWQgQVNOMQ==",
"icaocspdat": "c2FtcGxlIGljYW9jc3BkYXQgQjY0IGVuY29kZWQgQVNOMQ==", "icaocspdat": "c2FtcGxlIGljYW9jc3BkYXQgQjY0IGVuY29kZWQgQVNOMQ==",
"supportedsigalgs": "RS256" "supportedsigalgs": "RS256"
} }
} }
TSM signs "GetDeviceStateTBSRequest", creating
The TAM signs "GetDeviceStateTBSRequest", creating
"GetDeviceStateRequest" "GetDeviceStateRequest"
{ {
"GetDeviceStateRequest": { "GetDeviceStateRequest": {
"payload":" "payload":"
ewoJIkdldERldmljZVN0YXRlVEJTUmVxdWVzdCI6IHsKCQkidmVyIjogIjEuMCIsCgkJ ewoJIkdldERldmljZVN0YXRlVEJTUmVxdWVzdCI6IHsKCQkidmVyIjogIjEuMCIsCgkJ
InJpZCI6IHs4QzZGOURCQi1GQzM5LTQzNWMtQkM4OS00RDM2MTREQTJGMEJ9LAoJCSJ0 InJpZCI6IHs4QzZGOURCQi1GQzM5LTQzNWMtQkM4OS00RDM2MTREQTJGMEJ9LAoJCSJ0
aWQiOiAiezRGNDU0QTdGLTAwMkQtNDE1Ny04ODRFLUIwREQxQTA2QThBRX0iLAoJCSJv aWQiOiAiezRGNDU0QTdGLTAwMkQtNDE1Ny04ODRFLUIwREQxQTA2QThBRX0iLAoJCSJv
Y3NwZGF0IjogImMyRnRjR3hsSUc5amMzQmtZWFFnUWpZMElHVnVZMjlrWldRZ1FWTk9N Y3NwZGF0IjogImMyRnRjR3hsSUc5amMzQmtZWFFnUWpZMElHVnVZMjlrWldRZ1FWTk9N
UT09IiwKCQkiaWNhb2NzcGRhdCI6ICJjMkZ0Y0d4bElHbGpZVzlqYzNCa1lYUWdRalkw UT09IiwKCQkiaWNhb2NzcGRhdCI6ICJjMkZ0Y0d4bElHbGpZVzlqYzNCa1lYUWdRalkw
skipping to change at page 87, line 28 skipping to change at page 89, line 50
"header": { "header": {
"x5c": ["ZXhhbXBsZSBBU04xIHNpZ25lciBjZXJ0aWZpY2F0ZQ==", "x5c": ["ZXhhbXBsZSBBU04xIHNpZ25lciBjZXJ0aWZpY2F0ZQ==",
"ZXhhbXBsZSBBU04xIENBIGNlcnRpZmljYXRl"] "ZXhhbXBsZSBBU04xIENBIGNlcnRpZmljYXRl"]
}, },
"signature":"c2FtcGxlIHNpZ25hdHVyZQ" "signature":"c2FtcGxlIHNpZ25hdHVyZQ"
} }
} }
A.1.1.2. Sample GetDeviceStateResponse A.1.1.2. Sample GetDeviceStateResponse
TSM sends "GetDeviceStateRequest" to OTrP Agent The TAM sends "GetDeviceStateRequest" to the OTrP Agent
The OTrP Agent obtains "dsi" from each TEE. (In this example there
is a single TEE.)
OTrP Agent obtains "dsi" from each TEE. (in this example there is a The TEE obtains signed "fwdata" from firmware.
single TEE).
TEE obtains signed "fwdata" from firmware The TEE builds "dsi" - summarizing device state of the TEE.
TEE builds "dsi" - summarizing device state of TEE
{ {
"dsi": { "dsi": {
"tfwdata": { "tfwdata": {
"tbs": "ezRGNDU0QTdGLTAwMkQtNDE1Ny04ODRFLUIwREQxQTA2QThBRX0=", "tbs": "ezRGNDU0QTdGLTAwMkQtNDE1Ny04ODRFLUIwREQxQTA2QThBRX0=",
"cert": "ZXhhbXBsZSBGVyBjZXJ0aWZpY2F0ZQ==", "cert": "ZXhhbXBsZSBGVyBjZXJ0aWZpY2F0ZQ==",
"sigalg": "RS256", "sigalg": "RS256",
"sig": "c2FtcGxlIEZXIHNpZ25hdHVyZQ==" "sig": "c2FtcGxlIEZXIHNpZ25hdHVyZQ=="
}, },
"tee": { "tee": {
"name": "Primary TEE", "name": "Primary TEE",
skipping to change at page 88, line 50 skipping to change at page 91, line 51
{ {
"spaik": "c2FtcGxlIEFTTjEgZW5jb2RlZCBQS0NTMSBwdWJsaWNrZXk=", "spaik": "c2FtcGxlIEFTTjEgZW5jb2RlZCBQS0NTMSBwdWJsaWNrZXk=",
"spaiktype": "RSA", "spaiktype": "RSA",
"spid": "acmebank.com" "spid": "acmebank.com"
} }
] ]
} }
} }
} }
TEE encrypts "dsi", and embeds into "GetDeviceTEEStateTBSResponse" The TEE encrypts "dsi", and embeds it into a
message "GetDeviceTEEStateTBSResponse" message.
{ {
"GetDeviceTEEStateTBSResponse": { "GetDeviceTEEStateTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "pass", "status": "pass",
"rid": "{8C6F9DBB-FC39-435c-BC89-4D3614DA2F0B}", "rid": "{8C6F9DBB-FC39-435c-BC89-4D3614DA2F0B}",
"tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}", "tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}",
"signerreq":"false", "signerreq":"false",
"edsi": { "edsi": {
"protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0K", "protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0K",
skipping to change at page 89, line 35 skipping to change at page 92, line 35
"iv": "ySGmfZ69YlcEilNr5_SGbA", "iv": "ySGmfZ69YlcEilNr5_SGbA",
"ciphertext": "ciphertext":
" "
c2FtcGxlIGRzaSBkYXRhIGVuY3J5cHRlZCB3aXRoIEFFUzEyOCBrZXkgZnJvbSByZW c2FtcGxlIGRzaSBkYXRhIGVuY3J5cHRlZCB3aXRoIEFFUzEyOCBrZXkgZnJvbSByZW
NpcGllbnRzLmVuY3J5cHRlZF9rZXk", NpcGllbnRzLmVuY3J5cHRlZF9rZXk",
"tag": "c2FtcGxlIGF1dGhlbnRpY2F0aW9uIHRhZw" "tag": "c2FtcGxlIGF1dGhlbnRpY2F0aW9uIHRhZw"
} }
} }
} }
TEE signs "GetDeviceTEEStateTBSResponse" and returns to OTrP Agent. The TEE signs "GetDeviceTEEStateTBSResponse" and returns it to the
OTrP Agent encodes "GetDeviceTEEStateResponse" into an array to form OTrP Agent. The OTrP Agent encodes "GetDeviceTEEStateResponse" into
"GetDeviceStateResponse" an array to form "GetDeviceStateResponse".
{ {
"GetDeviceStateResponse": [ "GetDeviceStateResponse": [
{ {
"GetDeviceTEEStateResponse": { "GetDeviceTEEStateResponse": {
"payload": "payload":
" "
ewogICJHZXREZXZpY2VURUVTdGF0ZVRCU1Jlc3BvbnNlIjogewogICAgInZlciI6 ewogICJHZXREZXZpY2VURUVTdGF0ZVRCU1Jlc3BvbnNlIjogewogICAgInZlciI6
ICIxLjAiLAogICAgInN0YXR1cyI6ICJwYXNzIiwKICAgICJyaWQiOiAiezhDNkY5 ICIxLjAiLAogICAgInN0YXR1cyI6ICJwYXNzIiwKICAgICJyaWQiOiAiezhDNkY5
REJCLUZDMzktNDM1Yy1CQzg5LTREMzYxNERBMkYwQn0iLAogICAgInRpZCI6ICJ7 REJCLUZDMzktNDM1Yy1CQzg5LTREMzYxNERBMkYwQn0iLAogICAgInRpZCI6ICJ7
skipping to change at page 90, line 35 skipping to change at page 93, line 35
eVpXCiAgICAgIE5wY0dsbGJuUnpMbVZ1WTNKNWNIUmxaRjlyWlhrIiwKICAgICAg eVpXCiAgICAgIE5wY0dsbGJuUnpMbVZ1WTNKNWNIUmxaRjlyWlhrIiwKICAgICAg
InRhZyI6ICJjMkZ0Y0d4bElHRjFkR2hsYm5ScFkyRjBhVzl1SUhSaFp3IgogICAg InRhZyI6ICJjMkZ0Y0d4bElHRjFkR2hsYm5ScFkyRjBhVzl1SUhSaFp3IgogICAg
fQogIH0KfQ", fQogIH0KfQ",
"protected": "eyJhbGciOiJSUzI1NiJ9", "protected": "eyJhbGciOiJSUzI1NiJ9",
"signature": "c2FtcGxlIHNpZ25hdHVyZQ" "signature": "c2FtcGxlIHNpZ25hdHVyZQ"
} }
} }
] ]
} }
TEE returns "GetDeviceStateResponse" back to OTrP Agent, which The TEE returns "GetDeviceStateResponse" back to the OTrP Agent,
returns message back to TSM. which returns message back to the TAM.
A.1.2. Sample CreateSD A.1.2. Sample CreateSD
A.1.2.1. Sample CreateSDRequest A.1.2.1. Sample CreateSDRequest
{ {
"CreateSDTBSRequest": { "CreateSDTBSRequest": {
"ver":"1.0", "ver":"1.0",
"rid":"req-01", "rid":"req-01",
"tid":"tran-01", "tid":"tran-01",
"tee":"SecuriTEE", "tee":"SecuriTEE",
"nextdsi":"false", "nextdsi":"false",
"dsihash":"Iu-c0-fGrpMmzbbtiWI1U8u7wMJE7IK8wkJpsVuf2js", "dsihash":"Iu-c0-fGrpMmzbbtiWI1U8u7wMJE7IK8wkJpsVuf2js",
"content":{ "content":{
"spid":"bank.com", "spid":"bank.com",
"sdname":"sd.bank.com", "sdname":"sd.bank.com",
"spcert":"MIIDFjCCAn- "spcert":"MIIDFjCCAn-
gAwIBAgIJAIk0Tat0tquDMA0GCSqGSIb3DQEBBQUAMGwxCzAJBgNVBAYTAktSMQ4wD gAwIBAgIJAIk0Tat0tquDMA0GCSqGSIb3DQEBBQUAMGwxCzAJBgNVBAYTAkTAMQ4wD
AYDVQQIDAVTZW91bDESMBAGA1UEBwwJR3Vyby1kb25nMRAwDgYDVQQKDAdTb2xhY2l AYDVQQIDAVTZW91bDESMBAGA1UEBwwJR3Vyby1kb25nMRAwDgYDVQQKDAdTb2xhY2l
hMRAwDgYDVQQLDAdTb2xhY2lhMRUwEwYDVQQDDAxTb2xhLWNpYS5jb20wHhcNMTUwN hMRAwDgYDVQQLDAdTb2xhY2lhMRUwEwYDVQQDDAxTb2xhLWNpYS5jb20wHhcNMTUwN
zAyMDg1MTU3WhcNMjAwNjMwMDg1MTU3WjBsMQswCQYDVQQGEwJLUjEOMAwGA1UECAw zAyMDg1MTU3WhcNMjAwNjMwMDg1MTU3WjBsMQswCQYDVQQGEwJLUjEOMAwGA1UECAw
FU2VvdWwxEjAQBgNVBAcMCUd1cm8tZG9uZzEQMA4GA1UECgwHU29sYWNpYTEQMA4GA FU2VvdWwxEjAQBgNVBAcMCUd1cm8tZG9uZzEQMA4GA1UECgwHU29sYWNpYTEQMA4GA
1UECwwHU29sYWNpYTEVMBMGA1UEAwwMU29sYS1jaWEuY29tMIGfMA0GCSqGSIb3DQE 1UECwwHU29sYWNpYTEVMBMGA1UEAwwMU29sYS1jaWEuY29tMIGfMA0GCSqGSIb3DQE
BAQUAA4GNADCBiQKBgQDYWLrFf2OFMEciwSYsyhaLY4kslaWcXA0hCWJRaFzt5mU- BAQUAA4GNADCBiQKBgQDYWLrFf2OFMEciwSYsyhaLY4kslaWcXA0hCWJRaFzt5mU-
lpSJ4jeu92inBbsXcI8PfRbaItsgW1TD1Wg4gQH4MX_YtaBoOepE-- lpSJ4jeu92inBbsXcI8PfRbaItsgW1TD1Wg4gQH4MX_YtaBoOepE--
3JoZZyPyCWS3AaLYWrDmqFXdbzaO1i8GxB7zz0gWw55bZ9jyzcl5gQzWSqMRpx_dca 3JoZZyPyCWS3AaLYWrDmqFXdbzaO1i8GxB7zz0gWw55bZ9jyzcl5gQzWSqMRpx_dca
d2SP2wIDAQABo4G_MIG8MIGGBgNVHSMEfzB9oXCkbjBsMQswCQYDVQQGEwJLUjEOMA d2SP2wIDAQABo4G_MIG8MIGGBgNVHSMEfzB9oXCkbjBsMQswCQYDVQQGEwJLUjEOMA
wGA1UECAwFU2VvdWwxEjAQBgNVBAcMCUd1cm8tZG9uZzEQMA4GA1UECgwHU29sYWNp wGA1UECAwFU2VvdWwxEjAQBgNVBAcMCUd1cm8tZG9uZzEQMA4GA1UECgwHU29sYWNp
YTEQMA4GA1UECwwHU29sYWNpYTEVMBMGA1UEAwwMU29sYS1jaWEuY29tggkAiTRNq3 YTEQMA4GA1UECwwHU29sYWNpYTEVMBMGA1UEAwwMU29sYS1jaWEuY29tggkAiTRNq3
S2q4MwCQYDVR0TBAIwADAOBgNVHQ8BAf8EBAMCBsAwFgYDVR0lAQH_BAwwCgYIKwYB S2q4MwCQYDVR0TBAIwADAOBgNVHQ8BAf8EBAMCBsAwFgYDVR0lAQH_BAwwCgYIKwYB
BQUHAwMwDQYJKoZIhvcNAQEFBQADgYEAEFMhRwEQ- BQUHAwMwDQYJKoZIhvcNAQEFBQADgYEAEFMhRwEQ-
LDa9O7P1N0mcLORpo6fW3QuJfuXbRQRQGoXddXMKazI4VjbGaXhey7Bzvk6TZYDa- LDa9O7P1N0mcLORpo6fW3QuJfuXbRQRQGoXddXMKazI4VjbGaXhey7Bzvk6TZYDa-
GRiZby1J47UPaDQR3UiDzVvXwCOU6S5yUhNJsW_BeMViYj4lssX28iPpNwLUCVm1QV GRiZby1J47UPaDQR3UiDzVvXwCOU6S5yUhNJsW_BeMViYj4lssX28iPpNwLUCVm1QV
THILI6afLCRWXXclc1L5KGY290OwIdQ", THILI6afLCRWXXclc1L5KGY290OwIdQ",
"tsmid":"tsm_x.acme.com", "tamid":"TAM_x.acme.com",
"did":"zAHkb0-SQh9U_OT8mR5dB-tygcqpUJ9_x07pIiw8WoM" "did":"zAHkb0-SQh9U_OT8mR5dB-tygcqpUJ9_x07pIiw8WoM"
} }
} }
} }
Here is a sample message after the content is encrypted and encoded Below is a sample message after the content is encrypted and encoded
{ {
"CreateSDRequest": { "CreateSDRequest": {
"payload":" "payload":"
eyJDcmVhdGVTRFRCU1JlcXVlc3QiOnsidmVyIjoiMS4wIiwicmlkIjoicmVxLTAxIiwidG eyJDcmVhdGVTRFRCU1JlcXVlc3QiOnsidmVyIjoiMS4wIiwicmlkIjoicmVxLTAxIiwidG
lkIjoidHJhbi0wMSIsInRlZSI6IlNlY3VyaVRFRSIsIm5leHRkc2kiOiJmYWxzZSIsImRz lkIjoidHJhbi0wMSIsInRlZSI6IlNlY3VyaVRFRSIsIm5leHRkc2kiOiJmYWxzZSIsImRz
aWhhc2giOiIyMmVmOWNkM2U3YzZhZTkzMjZjZGI2ZWQ4OTYyMzU1M2NiYmJjMGMyNDRlYz aWhhc2giOiIyMmVmOWNkM2U3YzZhZTkzMjZjZGI2ZWQ4OTYyMzU1M2NiYmJjMGMyNDRlYz
gyYmNjMjQyNjliMTViOWZkYTNiIiwiY29udGVudCI6eyJwcm90ZWN0ZWQiOiJlLUtBbkdW gyYmNjMjQyNjliMTViOWZkYTNiIiwiY29udGVudCI6eyJwcm90ZWN0ZWQiOiJlLUtBbkdW
dVktS0FuVHJpZ0p4Qk1USTRRMEpETFVoVE1qVTI0b0NkZlEiLCJyZWNpcGllbnRzIjpbey dVktS0FuVHJpZ0p4Qk1USTRRMEpETFVoVE1qVTI0b0NkZlEiLCJyZWNpcGllbnRzIjpbey
JoZWFkZXIiOnsiYWxnIjoiUlNBMV81In0sImVuY3J5cHRlZF9rZXkiOiJTUzE2NTl4Q2FJ JoZWFkZXIiOnsiYWxnIjoiUlNBMV81In0sImVuY3J5cHRlZF9rZXkiOiJTUzE2NTl4Q2FJ
skipping to change at page 93, line 42 skipping to change at page 96, line 42
"content":{ "content":{
"did":"zAHkb0-SQh9U_OT8mR5dB-tygcqpUJ9_x07pIiw8WoM", "did":"zAHkb0-SQh9U_OT8mR5dB-tygcqpUJ9_x07pIiw8WoM",
"sdname":"sd.bank.com", "sdname":"sd.bank.com",
"teespaik":"AQABjY9KiwH3hkMmSAAN6CLXot525U85WNlWKAQz5TOdfe_CM8h- "teespaik":"AQABjY9KiwH3hkMmSAAN6CLXot525U85WNlWKAQz5TOdfe_CM8h-
X6_EHX1gOXoyRXaBiKMqWb0YZLCABTw1ytdXy2kWa525imRho8Vqn6HDGsJDZPDru9 X6_EHX1gOXoyRXaBiKMqWb0YZLCABTw1ytdXy2kWa525imRho8Vqn6HDGsJDZPDru9
GnZR8pZX5ge_dWXB_uljMvDttc5iAWEJ8ZgcpLGtBTGLZnQoQbjtn1lIE", GnZR8pZX5ge_dWXB_uljMvDttc5iAWEJ8ZgcpLGtBTGLZnQoQbjtn1lIE",
} }
} }
} }
Here is the response message after the content is encrypted and Below is the response message after the content is encrypted and
encoded. encoded.
{ {
"CreateSDResponse": { "CreateSDResponse": {
"payload":" "payload":"
eyJDcmVhdGVTRFRCU1Jlc3BvbnNlIjp7InZlciI6IjEuMCIsInN0YXR1cyI6InBhc3Mi eyJDcmVhdGVTRFRCU1Jlc3BvbnNlIjp7InZlciI6IjEuMCIsInN0YXR1cyI6InBhc3Mi
LCJyaWQiOiJyZXEtMDEiLCJ0aWQiOiJ0cmFuLTAxIiwiY29udGVudCI6eyJwcm90ZWN0 LCJyaWQiOiJyZXEtMDEiLCJ0aWQiOiJ0cmFuLTAxIiwiY29udGVudCI6eyJwcm90ZWN0
ZWQiOiJlLUtBbkdWdVktS0FuVHJpZ0p4Qk1USTRRMEpETFVoVE1qVTI0b0NkZlEiLCJy ZWQiOiJlLUtBbkdWdVktS0FuVHJpZ0p4Qk1USTRRMEpETFVoVE1qVTI0b0NkZlEiLCJy
ZWNpcGllbnRzIjpbeyJoZWFkZXIiOnsiYWxnIjoiUlNBMV81In0sImVuY3J5cHRlZF9r ZWNpcGllbnRzIjpbeyJoZWFkZXIiOnsiYWxnIjoiUlNBMV81In0sImVuY3J5cHRlZF9r
ZXkiOiJOX0I4R3pldUlfN2hwd0wwTFpHSTkxVWVBbmxJRkJfcndmZU1yZERrWnFGak1s ZXkiOiJOX0I4R3pldUlfN2hwd0wwTFpHSTkxVWVBbmxJRkJfcndmZU1yZERrWnFGak1s
skipping to change at page 95, line 18 skipping to change at page 98, line 18
"ver": "1.0", "ver": "1.0",
"rid": "1222DA7D-8993-41A4-AC02-8A2807B31A3A", "rid": "1222DA7D-8993-41A4-AC02-8A2807B31A3A",
"tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE", "tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE",
"tee": "Primary TEE ABC", "tee": "Primary TEE ABC",
"nextdsi": "false", "nextdsi": "false",
"dsihash": "dsihash":
" "
IsOvwpzDk8Onw4bCrsKTJsONwrbDrcKJYjVTw4vCu8OAw4JEw6zCgsK8w4JCacKxW8Kf IsOvwpzDk8Onw4bCrsKTJsONwrbDrcKJYjVTw4vCu8OAw4JEw6zCgsK8w4JCacKxW8Kf
w5o7", w5o7",
"content": { // NEEDS to BE ENCRYPTED "content": { // NEEDS to BE ENCRYPTED
"tsmid": "id1.tsmxyz.com", "tamid": "id1.TAMxyz.com",
"spid": "com.acmebank.spid1", "spid": "com.acmebank.spid1",
"sdname": "com.acmebank.sdname1", "sdname": "com.acmebank.sdname1",
"changes": { "changes": {
"newsdname": "com.acmebank.sdname2", "newsdname": "com.acmebank.sdname2",
"newspid": "com.acquirer.spid1", "newspid": "com.acquirer.spid1",
"spcert": "spcert":
"MIIDFjCCAn- "MIIDFjCCAn-
gAwIBAgIJAIk0Tat0tquDMA0GCSqGSIb3DQEBBQUAMGwxCzAJBgNVBAYTAktSMQ4 gAwIBAgIJAIk0Tat0tquDMA0GCSqGSIb3DQEBBQUAMGwxCzAJBgNVBAYTAkTAMQ4
wDAYDVQQIDAVTZW91bDESMBAGA1UEBwwJR3Vyby1kb25nMRAwDgYDVQQKDAdTb2x wDAYDVQQIDAVTZW91bDESMBAGA1UEBwwJR3Vyby1kb25nMRAwDgYDVQQKDAdTb2x
hY2lhMRAwDgYDVQQLDAdTb2xhY2lhMRUwEwYDVQQDDAxTb2xhLWNpYS5jb20wHhc hY2lhMRAwDgYDVQQLDAdTb2xhY2lhMRUwEwYDVQQDDAxTb2xhLWNpYS5jb20wHhc
NMTUwNzAyMDg1MTU3WhcNMjAwNjMwMDg1MTU3WjBsMQswCQYDVQQGEwJLUjEOMAw NMTUwNzAyMDg1MTU3WhcNMjAwNjMwMDg1MTU3WjBsMQswCQYDVQQGEwJLUjEOMAw
GA1UECAwFU2VvdWwxEjAQBgNVBAcMCUd1cm8tZG9uZzEQMA4GA1UECgwHU29sYWN GA1UECAwFU2VvdWwxEjAQBgNVBAcMCUd1cm8tZG9uZzEQMA4GA1UECgwHU29sYWN
pYTEQMA4GA1UECwwHU29sYWNpYTEVMBMGA1UEAwwMU29sYS1jaWEuY29tMIGfMA0 pYTEQMA4GA1UECwwHU29sYWNpYTEVMBMGA1UEAwwMU29sYS1jaWEuY29tMIGfMA0
GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDYWLrFf2OFMEciwSYsyhaLY4kslaWcXA0 GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDYWLrFf2OFMEciwSYsyhaLY4kslaWcXA0
hCWJRaFzt5mU- hCWJRaFzt5mU-
lpSJ4jeu92inBbsXcI8PfRbaItsgW1TD1Wg4gQH4MX_YtaBoOepE-- lpSJ4jeu92inBbsXcI8PfRbaItsgW1TD1Wg4gQH4MX_YtaBoOepE--
3JoZZyPyCWS3AaLYWrDmqFXdbzaO1i8GxB7zz0gWw55bZ9jyzcl5gQzWSqMRpx_d 3JoZZyPyCWS3AaLYWrDmqFXdbzaO1i8GxB7zz0gWw55bZ9jyzcl5gQzWSqMRpx_d
cad2SP2wIDAQABo4G_MIG8MIGGBgNVHSMEfzB9oXCkbjBsMQswCQYDVQQGEwJLUj cad2SP2wIDAQABo4G_MIG8MIGGBgNVHSMEfzB9oXCkbjBsMQswCQYDVQQGEwJLUj
skipping to change at page 96, line 27 skipping to change at page 99, line 27
GnZR8pZX5ge_dWXB_uljMvDttc5iAWEJ8ZgcpLGtBTGLZnQoQbjtn1lIE", GnZR8pZX5ge_dWXB_uljMvDttc5iAWEJ8ZgcpLGtBTGLZnQoQbjtn1lIE",
"teespaiktype": "RSA" "teespaiktype": "RSA"
} }
} }
} }
A.1.4. Sample DeleteSD A.1.4. Sample DeleteSD
A.1.4.1. Sample DeleteSDRequest A.1.4.1. Sample DeleteSDRequest
TSM builds message - including data to be encrypted. The TAM builds message - including data to be encrypted.
{ {
"DeleteSDTBSRequest": { "DeleteSDTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}", "rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}",
"tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}", "tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}",
"tee": "Primary TEE", "tee": "Primary TEE",
"nextdsi": "false", "nextdsi": "false",
"dsihash": "AAECAwQFBgcICQoLDA0ODwABAgMEBQYHCAkKCwwNDg8=", "dsihash": "AAECAwQFBgcICQoLDA0ODwABAgMEBQYHCAkKCwwNDg8=",
"content": ENCRYPTED { "content": ENCRYPTED {
"tsmid": "tsm1.com", "tamid": "TAM1.com",
"sdname": "default.acmebank.com", "sdname": "default.acmebank.com",
"deleteta": "1" "deleteta": "1"
} }
} }
} }
TSM encrypts the "content". The TAM encrypts the "content".
{ {
"DeleteSDTBSRequest": { "DeleteSDTBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}", "rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}",
"tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}", "tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}",
"tee": "Primary TEE", "tee": "Primary TEE",
"nextdsi": "false", "nextdsi": "false",
"dsihash": "AAECAwQFBgcICQoLDA0ODwABAgMEBQYHCAkKCwwNDg8=", "dsihash": "AAECAwQFBgcICQoLDA0ODwABAgMEBQYHCAkKCwwNDg8=",
"content": { "content": {
skipping to change at page 97, line 36 skipping to change at page 100, line 36
"iv": "rWO5DVmQX9ogelMLBIogIA", "iv": "rWO5DVmQX9ogelMLBIogIA",
"ciphertext": "ciphertext":
" "
c2FtcGxlIGRzaSBkYXRhIGVuY3J5cHRlZCB3aXRoIEFFUzEyOCBrZXkgZnJvbSByZWNp c2FtcGxlIGRzaSBkYXRhIGVuY3J5cHRlZCB3aXRoIEFFUzEyOCBrZXkgZnJvbSByZWNp
cGllbnRzLmVuY3J5cHRlZF9rZXk", cGllbnRzLmVuY3J5cHRlZF9rZXk",
"tag": "c2FtcGxlIGF1dGhlbnRpY2F0aW9uIHRhZw" "tag": "c2FtcGxlIGF1dGhlbnRpY2F0aW9uIHRhZw"
} }
} }
} }
TSM signs "DeleteSDTBSRequest" to form "DeleteSDRequest" The TAM signs the "DeleteSDTBSRequest" to form a "DeleteSDRequest"
{ {
"DeleteSDRequest": { "DeleteSDRequest": {
"payload":" "payload":"
ewoJIkRlbGV0ZVNEVEJTUmVxdWVzdCI6IHsKCQkidmVyIjogIjEuMCIsCgkJInJp ewoJIkRlbGV0ZVNEVEJTUmVxdWVzdCI6IHsKCQkidmVyIjogIjEuMCIsCgkJInJp
ZCI6ICJ7NzEyNTUxRjUtREZCMy00M2YwLTlBNjMtNjYzNDQwQjkxRDQ5fSIsCgkJ ZCI6ICJ7NzEyNTUxRjUtREZCMy00M2YwLTlBNjMtNjYzNDQwQjkxRDQ5fSIsCgkJ
InRpZCI6ICJ7NEY0NTRBN0YtMDAyRC00MTU3LTg4NEUtQjBERDFBMDZBOEFFfSIs InRpZCI6ICJ7NEY0NTRBN0YtMDAyRC00MTU3LTg4NEUtQjBERDFBMDZBOEFFfSIs
CgkJInRlZSI6ICJQcmltYXJ5IFRFRSIsCgkJIm5leHRkc2kiOiAiZmFsc2UiLAoJ CgkJInRlZSI6ICJQcmltYXJ5IFRFRSIsCgkJIm5leHRkc2kiOiAiZmFsc2UiLAoJ
CSJkc2loYXNoIjogIkFBRUNBd1FGQmdjSUNRb0xEQTBPRHdBQkFnTUVCUVlIQ0Fr CSJkc2loYXNoIjogIkFBRUNBd1FGQmdjSUNRb0xEQTBPRHdBQkFnTUVCUVlIQ0Fr
S0N3d05EZzg9IiwKCQkiY29udGVudCI6IHsKCQkJInByb3RlY3RlZCI6ICJleUps S0N3d05EZzg9IiwKCQkiY29udGVudCI6IHsKCQkJInByb3RlY3RlZCI6ICJleUps
Ym1NaU9pSkJNVEk0UTBKRExVaFRNalUySW4wIiwKCQkJInJlY2lwaWVudHMiOiBb Ym1NaU9pSkJNVEk0UTBKRExVaFRNalUySW4wIiwKCQkJInJlY2lwaWVudHMiOiBb
skipping to change at page 98, line 33 skipping to change at page 101, line 33
"header": { "header": {
"x5c": ["ZXhhbXBsZSBBU04xIHNpZ25lciBjZXJ0aWZpY2F0ZQ==", "x5c": ["ZXhhbXBsZSBBU04xIHNpZ25lciBjZXJ0aWZpY2F0ZQ==",
"ZXhhbXBsZSBBU04xIENBIGNlcnRpZmljYXRl"] "ZXhhbXBsZSBBU04xIENBIGNlcnRpZmljYXRl"]
}, },
"signature":"c2FtcGxlIHNpZ25hdHVyZQ" "signature":"c2FtcGxlIHNpZ25hdHVyZQ"
} }
} }
A.1.4.2. Sample DeleteSDResponse A.1.4.2. Sample DeleteSDResponse
TEE creates "DeleteSDTBSResponse" to respond to the "DeleteSDRequest" The TEE creates a "DeleteSDTBSResponse" to respond to the
message from the TSM, including data to be encrypted. "DeleteSDRequest" message from the TAM, including data to be
encrypted.
{ {
"DeleteSDTBSResponse": { "DeleteSDTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "pass", "status": "pass",
"rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}", "rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}",
"tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}", "tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}",
"content": ENCRYPTED { "content": ENCRYPTED {
"did": "MTZENTE5Qzc0Qzk0NkUxMzYxNzk0NjY4NTc3OTY4NTI=", "did": "MTZENTE5Qzc0Qzk0NkUxMzYxNzk0NjY4NTc3OTY4NTI=",
} }
} }
} }
TEE encrypts the "content" for the TSM. The TEE encrypts the "content" for the TAM.
{ {
"DeleteSDTBSResponse": { "DeleteSDTBSResponse": {
"ver": "1.0", "ver": "1.0",
"status": "pass", "status": "pass",
"rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}", "rid": "{712551F5-DFB3-43f0-9A63-663440B91D49}",
"tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}", "tid": "{4F454A7F-002D-4157-884E-B0DD1A06A8AE}",
"content": { "content": {
"protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0K", "protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0K",
"recipients": [ "recipients": [
skipping to change at page 99, line 34 skipping to change at page 102, line 34
"iv": "ySGmfZ69YlcEilNr5_SGbA", "iv": "ySGmfZ69YlcEilNr5_SGbA",
"ciphertext": "ciphertext":
" "
c2FtcGxlIGRzaSBkYXRhIGVuY3J5cHRlZCB3aXRoIEFFUzEyOCBrZXkgZnJvbSByZW c2FtcGxlIGRzaSBkYXRhIGVuY3J5cHRlZCB3aXRoIEFFUzEyOCBrZXkgZnJvbSByZW
NpcGllbnRzLmVuY3J5cHRlZF9rZXk", NpcGllbnRzLmVuY3J5cHRlZF9rZXk",
"tag": "c2FtcGxlIGF1dGhlbnRpY2F0aW9uIHRhZw" "tag": "c2FtcGxlIGF1dGhlbnRpY2F0aW9uIHRhZw"
} }
} }
} }
TEE signs "DeleteSDTBSResponse" to form "DeleteSDResponse" The TEE signs "DeleteSDTBSResponse" to form a "DeleteSDResponse"
{ {
"DeleteSDResponse": { "DeleteSDResponse": {
"payload":" "payload":"
ewoJIkRlbGV0ZVNEVEJTUmVzcG9uc2UiOiB7CgkJInZlciI6ICIxLjAiLAoJCSJz ewoJIkRlbGV0ZVNEVEJTUmVzcG9uc2UiOiB7CgkJInZlciI6ICIxLjAiLAoJCSJz
dGF0dXMiOiAicGFzcyIsCgkJInJpZCI6ICJ7NzEyNTUxRjUtREZCMy00M2YwLTlB dGF0dXMiOiAicGFzcyIsCgkJInJpZCI6ICJ7NzEyNTUxRjUtREZCMy00M2YwLTlB
NjMtNjYzNDQwQjkxRDQ5fSIsCgkJInRpZCI6ICJ7NEY0NTRBN0YtMDAyRC00MTU3 NjMtNjYzNDQwQjkxRDQ5fSIsCgkJInRpZCI6ICJ7NEY0NTRBN0YtMDAyRC00MTU3
LTg4NEUtQjBERDFBMDZBOEFFfSIsCgkJImNvbnRlbnQiOiB7CgkJCSJwcm90ZWN0 LTg4NEUtQjBERDFBMDZBOEFFfSIsCgkJImNvbnRlbnQiOiB7CgkJCSJwcm90ZWN0
ZWQiOiAiZXlKbGJtTWlPaUpCTVRJNFEwSkRMVWhUTWpVMkluMEsiLAoJCQkicmVj ZWQiOiAiZXlKbGJtTWlPaUpCTVRJNFEwSkRMVWhUTWpVMkluMEsiLAoJCQkicmVj
aXBpZW50cyI6IFt7CgkJCQkiaGVhZGVyIjogewoJCQkJCSJhbGciOiAiUlNBMV81 aXBpZW50cyI6IFt7CgkJCQkiaGVhZGVyIjogewoJCQkJCSJhbGciOiAiUlNBMV81
IgoJCQkJfSwKCQkJCSJlbmNyeXB0ZWRfa2V5IjogIlFVVlRNVEk0SUNoRFJVc3BJ IgoJCQkJfSwKCQkJCSJlbmNyeXB0ZWRfa2V5IjogIlFVVlRNVEk0SUNoRFJVc3BJ
skipping to change at page 100, line 26 skipping to change at page 103, line 26
IjogInlTR21mWjY5WWxjRWlsTnI1X1NHYkEiLAoJCQkiY2lwaGVydGV4dCI6ICJj IjogInlTR21mWjY5WWxjRWlsTnI1X1NHYkEiLAoJCQkiY2lwaGVydGV4dCI6ICJj
MkZ0Y0d4bElHUnphU0JrWVhSaElHVnVZM0o1Y0hSbFpDQjNhWFJvSUVGRlV6RXlP MkZ0Y0d4bElHUnphU0JrWVhSaElHVnVZM0o1Y0hSbFpDQjNhWFJvSUVGRlV6RXlP
Q0JyWlhrZ1puSnZiU0J5WldOcGNHbGxiblJ6TG1WdVkzSjVjSFJsWkY5clpYayIs Q0JyWlhrZ1puSnZiU0J5WldOcGNHbGxiblJ6TG1WdVkzSjVjSFJsWkY5clpYayIs
CgkJCSJ0YWciOiAiYzJGdGNHeGxJR0YxZEdobGJuUnBZMkYwYVc5dUlIUmhadyIK CgkJCSJ0YWciOiAiYzJGdGNHeGxJR0YxZEdobGJuUnBZMkYwYVc5dUlIUmhadyIK
CQl9Cgl9Cn0", CQl9Cgl9Cn0",
"protected":"eyJhbGciOiJSUzI1NiJ9", "protected":"eyJhbGciOiJSUzI1NiJ9",
"signature":"c2FtcGxlIHNpZ25hdHVyZQ" "signature":"c2FtcGxlIHNpZ25hdHVyZQ"
} }
} }
TEE returns "DeleteSDResponse" back to OTrP Agent, which returns The TEE returns "DeleteSDResponse" back to the OTrP Agent, which
message back to TSM. returns the message back to the TAM.
A.2. Sample TA Management Messages A.2. Sample TA Management Messages
A.2.1. Sample InstallTA A.2.1. Sample InstallTA
A.2.1.1. Sample InstallTARequest A.2.1.1. Sample InstallTARequest
{ {
"InstallTATBSRequest": { "InstallTATBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "24BEB059-0AED-42A6-A381-817DFB7A1207", "rid": "24BEB059-0AED-42A6-A381-817DFB7A1207",
"tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE", "tid": "4F454A7F-002D-4157-884E-B0DD1A06A8AE",
"tee": "Primary TEE ABC", "tee": "Primary TEE ABC",
"nextdsi": "true", "nextdsi": "true",
"dsihash": "dsihash":
" "
IsOvwpzDk8Onw4bCrsKTJsONwrbDrcKJYjVTw4vCu8OAw4JEw6zCgsK8w4JCacKxW8Kf IsOvwpzDk8Onw4bCrsKTJsONwrbDrcKJYjVTw4vCu8OAw4JEw6zCgsK8w4JCacKxW8Kf
w5o7", w5o7",
"content": { "content": {
"tsmid": "id1.tsmxyz.com", "tamid": "id1.TAMxyz.com",
"spid": "com.acmebank.spid1", "spid": "com.acmebank.spid1",
"sdname": "com.acmebank.sdname1", "sdname": "com.acmebank.sdname1",
"taid": "com.acmebank.taid.banking" "taid": "com.acmebank.taid.banking"
}, },
"encrypted_ta": { "encrypted_ta": {
"key": "key":
"mLBjodcE4j36y64nC/nEs694P3XrLAOokjisXIGfs0H7lOEmT5FtaNDYEMcg9RnE "mLBjodcE4j36y64nC/nEs694P3XrLAOokjisXIGfs0H7lOEmT5FtaNDYEMcg9RnE
ftlJGHO7N0lgcNcjoXBmeuY9VI8xzrsZM9gzH6VBKtVONSx0aw5IAFkNcyPZwDdZ ftlJGHO7N0lgcNcjoXBmeuY9VI8xzrsZM9gzH6VBKtVONSx0aw5IAFkNcyPZwDdZ
MLwhvrzPJ9Fg+bZtrCoJz18PUz+5aNl/dj8+NM85LCXXcBlZF74btJer1Mw6ffzT MLwhvrzPJ9Fg+bZtrCoJz18PUz+5aNl/dj8+NM85LCXXcBlZF74btJer1Mw6ffzT
/grPiEQTeJ1nEm9F3tyRsvcTInsnPJ3dEXv7sJXMrhRKAeZsqKzGX4eiZ3rEY+FQ /grPiEQTeJ1nEm9F3tyRsvcTInsnPJ3dEXv7sJXMrhRKAeZsqKzGX4eiZ3rEY+FQ
skipping to change at page 103, line 18 skipping to change at page 106, line 18
{ {
"UpdateTATBSRequest": { "UpdateTATBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "req-2", "rid": "req-2",
"tid": "tran-01", "tid": "tran-01",
"tee": "SecuriTEE", "tee": "SecuriTEE",
"nextdsi": " false", "nextdsi": " false",
"dsihash": "gwjul_9MZks3pqUSN1-eL1aViwGXNAxk0AIKW79dn4U", "dsihash": "gwjul_9MZks3pqUSN1-eL1aViwGXNAxk0AIKW79dn4U",
"content": { "content": {
"tsmid": "tsm1.acme.com", "tamid": "TAM1.acme.com",
"spid": "bank.com", "spid": "bank.com",
"sdname": "sd.bank.com", "sdname": "sd.bank.com",
"taid": "sd.bank.com.ta" "taid": "sd.bank.com.ta"
}, },
"encrypted_ta": { "encrypted_ta": {
"key": "key":
" "
XzmAn_RDVk3IozMwNWhiB6fmZlIs1YUvMKlQAv_UDoZ1fvGGsRGo9bT0A440aYMgLt XzmAn_RDVk3IozMwNWhiB6fmZlIs1YUvMKlQAv_UDoZ1fvGGsRGo9bT0A440aYMgLt
GilKypoJjCgijdaHgamaJgRSc4Je2otpnEEagsahvDNoarMCC5nGQdkRxW7Vo2NKgL GilKypoJjCgijdaHgamaJgRSc4Je2otpnEEagsahvDNoarMCC5nGQdkRxW7Vo2NKgL
A892HGeHkJVshYm1cUlFQ-BhiJ4NAykFwlqC_oc", A892HGeHkJVshYm1cUlFQ-BhiJ4NAykFwlqC_oc",
skipping to change at page 107, line 17 skipping to change at page 110, line 17
{ {
"DeleteTATBSRequest": { "DeleteTATBSRequest": {
"ver": "1.0", "ver": "1.0",
"rid": "req-2", "rid": "req-2",
"tid": "tran-01", "tid": "tran-01",
"tee": "SecuriTEE", "tee": "SecuriTEE",
"nextdsi": "false", "nextdsi": "false",
"dsihash": "gwjul_9MZks3pqUSN1-eL1aViwGXNAxk0AIKW79dn4U", "dsihash": "gwjul_9MZks3pqUSN1-eL1aViwGXNAxk0AIKW79dn4U",
"content": { "content": {
"tsmid": "tsm1.acme.com", "tamid": "TAM1.acme.com",
"sdname": "sd.bank.com", "sdname": "sd.bank.com",
"taid": "sd.bank.com.ta" "taid": "sd.bank.com.ta"
} }
} }
} }
{ {
"DeleteTARequest": { "DeleteTARequest": {
"payload": "payload":
" "
skipping to change at page 110, line 20 skipping to change at page 113, line 20
MDEiLA0KCQkiY29udGVudCI6IHsNCgkJCSJwcm90ZWN0ZWQiOnsiZW5jIjoiQTEyOENC MDEiLA0KCQkiY29udGVudCI6IHsNCgkJCSJwcm90ZWN0ZWQiOnsiZW5jIjoiQTEyOENC
Qy1IUzI1NiJ9LA0KCQkJInJlY2lwaWVudHMiOlsNCgkJCQl7DQoJCQkJCSJoZWFkZXIi Qy1IUzI1NiJ9LA0KCQkJInJlY2lwaWVudHMiOlsNCgkJCQl7DQoJCQkJCSJoZWFkZXIi
OnsiYWxnIjoiUlNBMV81In0sDQoJCQkJCSJlbmNyeXB0ZWRfa2V5IjoiTXdtU1ZHaWU2 OnsiYWxnIjoiUlNBMV81In0sDQoJCQkJCSJlbmNyeXB0ZWRfa2V5IjoiTXdtU1ZHaWU2
eHpfQmxTaFlmTFRKRHhKT3oyNWhvYy1HZ2NEM2o5OWFyM2E4X2lYY182ZE44bFRTb1dD eHpfQmxTaFlmTFRKRHhKT3oyNWhvYy1HZ2NEM2o5OWFyM2E4X2lYY182ZE44bFRTb1dD
X19wZEFhaEMyWk5SakdIcTBCZ2JDYTRKalk0eXRkMVBVWDB6M1psbXl1YnRXM291eEpY X19wZEFhaEMyWk5SakdIcTBCZ2JDYTRKalk0eXRkMVBVWDB6M1psbXl1YnRXM291eEpY
el9PMzg1WGM4S3hySndjbElyZGx2WUY2OVZmeERLQkVzUHJCdzlVenVIa1VmSU4xWlFU el9PMzg1WGM4S3hySndjbElyZGx2WUY2OVZmeERLQkVzUHJCdzlVenVIa1VmSU4xWlFU
bWZ0QmVaSlJnIg0KCQkJCX0NCgkJCV0sDQoJCQkiaXYiOiJBeFk4REN0RGFHbHNiR2xq bWZ0QmVaSlJnIg0KCQkJCX0NCgkJCV0sDQoJCQkiaXYiOiJBeFk4REN0RGFHbHNiR2xq
YjNSb1pRIiwNCgkJCSJjaXBoZXJ0ZXh0IjoiamhQTlV5ZkFTel9rVV9GbEM2LUtCME01 YjNSb1pRIiwNCgkJCSJjaXBoZXJ0ZXh0IjoiamhQTlV5ZkFTel9rVV9GbEM2LUtCME01
WDBHNE5MbHc0LWt0bERyajZTWlUteUp6eUFUbC1oY0ZBWWMwLXJMVEF4cF93N1d1WER0 WDBHNE5MbHc0LWt0bERyajZTWlUteUp6eUFUbC1oY0ZBWWMwLXJMVEF4cF93N1d1WER0
Y3N3SzJSSzRjcWciLA0KCQkJInRhZyI6IlBBeGo5N25oT29qVTNIREhxSll4MGZMNWpt Y3N3SzJSSzRjcWciLA0KCQkJInRhZyI6IlBBeGo5N25oT29qVTNIREhxSll4MGZMNWpt
b0xkTlJkTHRtSmIzUTdrYXciDQoJCX0NCgl9DQp9", b0xkTlJkTHRTAMIzUTdrYXciDQoJCX0NCgl9DQp9",
"protected": "eyJhbGciOiJSUzI1NiJ9", "protected": "eyJhbGciOiJSUzI1NiJ9",
"header": { "header": {
"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d", "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d",
"signer":" "signer":"
MIIC3zCCAkigAwIBAgIJAJf2fFkE1BYOMA0GCSqGSIb3DQEBBQUAMFoxCzAJ MIIC3zCCAkigAwIBAgIJAJf2fFkE1BYOMA0GCSqGSIb3DQEBBQUAMFoxCzAJ
BgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRMwEQYDVQQHDApDYWxp BgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRMwEQYDVQQHDApDYWxp
Zm9ybmlhMSEwHwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcN Zm9ybmlhMSEwHwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcN
MTUwNzAyMDkwMTE4WhcNMjAwNjMwMDkwMTE4WjBaMQswCQYDVQQGEwJVUzET MTUwNzAyMDkwMTE4WhcNMjAwNjMwMDkwMTE4WjBaMQswCQYDVQQGEwJVUzET
MBEGA1UECAwKQ2FsaWZvcm5pYTETMBEGA1UEBwwKQ2FsaWZvcm5pYTEhMB8G MBEGA1UECAwKQ2FsaWZvcm5pYTETMBEGA1UEBwwKQ2FsaWZvcm5pYTEhMB8G
A1UECgwYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIGfMA0GCSqGSIb3DQEB A1UECgwYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIGfMA0GCSqGSIb3DQEB
skipping to change at page 111, line 4 skipping to change at page 114, line 4
em4cIckfxzTBBiPHCjrrjB2X8Ktn8GSZ1MdyIZV8fwdEmD90IvtMHgtzK- em4cIckfxzTBBiPHCjrrjB2X8Ktn8GSZ1MdyIZV8fwdEmD90IvtMHgtzK-
9wo6Aibj_rVIpxGb7trP82uzc2X8VwYnQbuqQyzofQvcwZHLYplvi95pZ5fV 9wo6Aibj_rVIpxGb7trP82uzc2X8VwYnQbuqQyzofQvcwZHLYplvi95pZ5fV
rJvnYAUBFyfrdT5GjqL1nqH3a_Y3QPscuCjg" rJvnYAUBFyfrdT5GjqL1nqH3a_Y3QPscuCjg"
}, },
"signature":" "signature":"
DfoBOetNelKsnAe_m4Z9K5UbihgWNYZsp5jVybiI05sOagDzv6R4do9npaAlAvpNK8HJ DfoBOetNelKsnAe_m4Z9K5UbihgWNYZsp5jVybiI05sOagDzv6R4do9npaAlAvpNK8HJ
CxD6D22J8GDUExlIhSR1aDuDCQm6QzmjdkFdxAz5TRYl6zpPCZqgSToN_g1TZxqxEv6V CxD6D22J8GDUExlIhSR1aDuDCQm6QzmjdkFdxAz5TRYl6zpPCZqgSToN_g1TZxqxEv6V
Ob5fies4g6MHvCH-Il_-KbHq5YpwGxEEFdg" Ob5fies4g6MHvCH-Il_-KbHq5YpwGxEEFdg"
} }
} }
A.3. Example OTrP Agent Option
The most popular TEE devices today are Android powered devices. In
an Android device, an OTrP Agent can be a bound service with a
service registration ID that a Client Application can use. This
option allows a Client Application not to depend on any OTrP Agent
SDK or provider.
An OTrP Agent is responsible to detect and work with more than one
TEE if a device has more than one. In this version, there is only
one active TEE such that an OTrP Agent only needs to handle the
active TEE.
Authors' Addresses Authors' Addresses
Mingliang Pei Mingliang Pei
Symantec Symantec
350 Ellis St 350 Ellis St
Mountain View, CA 94043 Mountain View, CA 94043
USA USA
Email: mingliang_pei@symantec.com Email: mingliang_pei@symantec.com
 End of changes. 711 change blocks. 
1491 lines changed or deleted 1595 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/