-
Notifications
You must be signed in to change notification settings - Fork 1
/
draft-ietf-teep-opentrustprotocol-02.xml
5552 lines (5119 loc) · 228 KB
/
draft-ietf-teep-opentrustprotocol-02.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC7515 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7515.xml">
<!ENTITY RFC7516 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7516.xml">
<!ENTITY RFC7517 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7517.xml">
<!ENTITY RFC7518 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7518.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<!-- <?rfc compact="yes" ?> -->
<?rfc subcompact="no" ?>
<rfc category="info" docName="draft-ietf-teep-opentrustprotocol-02.txt" ipr="trust200902"
submissionType="IETF">
<front>
<title abbrev="OTrP">The Open Trust Protocol (OTrP)</title>
<author fullname="Mingliang Pei" initials="M." surname="Pei">
<organization>Symantec</organization>
<address>
<postal>
<street>350 Ellis St</street>
<city>Mountain View</city>
<region>CA</region>
<code>94043</code>
<country>USA</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname="Andrew Atyeo" initials="A." surname="Atyeo">
<organization>Intercede</organization>
<address>
<postal>
<street>St. Mary's Road, Lutterworth</street>
<city>Leicestershire</city>
<region>LE17</region>
<code>4PS</code>
<country>Great Britain</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname="Nick Cook" initials="N." surname="Cook">
<organization>ARM Ltd.</organization>
<address>
<postal>
<street>110 Fulbourn Rd</street>
<city>Cambridge</city>
<region>CB1</region>
<code>9NJ</code>
<country>Great Britain</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname="Minho Yoo" initials="M." surname="Yoo">
<organization>IoTrust</organization>
<address>
<postal>
<street>Suite 501, Gasanbusiness Center,165, Gasan digital1-ro</street>
<city>Seoul</city>
<code>08503</code>
<country>Korea</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname="Hannes Tschofenig" initials="H." surname="Tschofenig">
<organization>ARM Ltd.</organization>
<address>
<postal>
<street>110 Fulbourn Rd</street>
<city>Cambridge</city>
<region>CB1</region>
<code>9NJ</code>
<country>Great Britain</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<date month="October" year="2018" />
<area>Security</area>
<workgroup>TEEP</workgroup>
<keyword>Trusted Execution Environment</keyword>
<abstract>
<t>This document specifies the Open Trust Protocol (OTrP), a
protocol that follows the Trust Execution Environment Provisioning (TEEP)
architecture and provides a message protocol that provisions and manages
Trusted Applications into a device with a Trusted Execution Environment
(TEE).
</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The Trusted Execution Environment (TEE) concept has been designed to
separate a regular operating system, also referred as a Rich Execution
Environment (REE), from security-sensitive applications. In an TEE
ecosystem, different device vendors may use different TEE implementations.
Different application providers or device administrators may choose to
use different TAM providers. There calls for an interoperable
protocol for managing TAs running in different TEEs of various devices
is needed.
</t>
<t>The Trusted Execution Environment Provisioning (TEEP) architecture
document <xref target="TEEPArch"/> has set to provide a design guidance
for such an interoperable protocol. This document specifies an Open Trust
Protocol (OTrP) that follows the architecture guidance.
</t>
<t>OTrP defines a mutual trust message protocol between a TAM and a TEE and
relies on IETF-defined end-to-end security
mechanisms, namely JSON Web Encryption (JWE), JSON Web Signature (JWS),
and JSON Web Key (JWK). Other message encoding methods may be supported.</t>
<t>This specification defines message payloads exchanged between devices
and a TAM. The messages are designed in anticipation of the use of the
most common transport methods such as HTTPS.
</t>
<t>Each TA binary and configuration data can be from either of two sources:
<list hangIndent="2" style="numbers">
<t>A TAM supplies the signed and encrypted TA binary and any
required configuration data</t>
<t>A Client Application supplies the TA binary</t>
</list>
</t>
<t>
This specification considers the first case where TA binary and
configuration data are encrypted by recipient's public key that
TAM has to be involved. The second case will also be addressed
separately.
</t>
</section>
<section title="Requirements Language">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
<xref target="RFC2119"/>.
</t>
</section>
<section anchor="terms" title="Terminology">
<section anchor="Subsection-Definitions" title="Definitions">
<t>The definitions provided below are defined as used in this
document. All the terms defined in the TEEP Architecture document
<xref target="TEEPArch" /> will be used, which are not repeated
in this document.
</t>
<t>
<list hangIndent="4" style="hanging">
<t hangText="OTrP Broker:">
It is the Broker as defined in the TEEP Architecture document
<xref target="TEEPArch" />.
</t>
</list>
</t>
</section>
<section title="Abbreviations">
<t>
<list hangIndent="8" style="hanging">
<t hangText="CA">Certificate Authority</t>
<t hangText="OTrP">Open Trust Protocol</t>
<t hangText="REE">Rich Execution Environment</t>
<t hangText="SD">Security Domain</t>
<t hangText="SP">Service Provider</t>
<t hangText="TA">Trusted Application</t>
<t hangText="TEE">Trusted Execution Environment</t>
<t hangText="TFW">Trusted Firmware</t>
<t hangText="TAM">Trusted Application Manager</t>
</list>
</t>
</section>
</section>
<section anchor="model" title="OTrP Entities and Trust Model">
<section anchor="components" title="System Components">
<t>The same system components as defined in the TEEP Architecture document
<xref target="TEEPArch" /> are used in OTrP, including TAM, CA, TEE, REE,
and OTrP Broker (a.k.a Broker).</t>
<t>Secure boot (for the purposes of OTrP) is optional in enabling
authenticity checking of TEEs by the TAM. A TAM provider can choose
it policy whether it trusts a TEE if the underlying firmware attestation
information is not included.
</t>
<t>OTrP uses trust anchors to establish trust between TEEs and TAMs and
verifies that they communicate in a trusted way when performing
lifecycle management transactions.
</t>
</section>
<section anchor="teeanchors" title="Trust Anchors in TEE">
<t>This assumes the Trust Anchor specification defined in the
TEEP Architecture document <xref target="TEEPArch" />.
</t>
<t>Each TEE comes with a trust store that contains a
whitelist of root CA certificates that are used to validate a TAM's
certificate. A TEE will accept a TAM to create new Security Domains and
install new TAs on behalf of a SP only if the TAM's certificate is
chained to one of the root CA certificates in the TEE's trust
store.
</t>
</section>
<section anchor="TAManchors" title="Trust Anchors in TAM">
<t>The Trust Anchor set in a TAM consists of a list of Certificate
Authority certificates that signs various device TEE certificates.
A TAM decides what TEE and optionally TFW it will trust when TFW
signature data is present in an attestation.
</t>
</section>
<section anchor="keytypes" title="Keys and Certificate Types">
<t>OTrP leverages the following list of trust anchors and
identities in generating signed and encrypted command messages that
are exchanged between a device's TEE and a TAM. With these
security artifacts, OTrP Messages are able to deliver end-to-end
security without relying on any transport security.
</t>
<texttable anchor="keytypelist" title="Key and Certificate Types">
<ttcol align='left'>Key Entity Name</ttcol>
<ttcol align='left'>Location</ttcol>
<ttcol align='left'>Issuer</ttcol>
<ttcol align='left'>Trust Implication</ttcol>
<ttcol align='left'>Cardinality</ttcol>
<c>1. TFW key pair and certificate</c>
<c>Device secure storage</c>
<c>FW CA</c>
<c>A whitelist of FW root CA trusted by TAMs</c>
<c>1 per device</c>
<c>2. TEE key pair and certificate</c>
<c>Device TEE</c>
<c>TEE CA under a root CA</c>
<c>A whitelist of TEE root CA trusted by TAMs</c>
<c>1 per device</c>
<c>3. TAM key pair and certificate</c>
<c>TAM provider</c>
<c>TAM CA under a root CA</c>
<c>A whitelist of TAM root CA embedded in TEE</c>
<c>1 or multiple can be used by a TAM</c>
<c>4. SP key pair and certificate</c>
<c>SP</c>
<c>SP signer CA</c>
<c>TAM manages SP. TA trust is delegated to TAM. TEE trusts TAM to
ensure that a TA is trustworthy.
</c>
<c>1 or multiple can be used by a TAM</c>
</texttable>
<t>
<list hangIndent="4" style="hanging">
<t hangText="1. TFW key pair and certificate:">
A key pair and certificate for
evidence of trustworthy firmware in a device. This key pair is
optional. Some TEE may present its
trusted attributes to a TAM using signed attestation with a
TFW key. For example, a platform that uses a hardware based TEE
can have attestation data signed by a hardware protected TFW key.
<list hangIndent="2" style="hanging">
<t hangText="Location: ">Device secure storage</t>
<t hangText="Supported Key Type: ">RSA and ECC</t>
<t hangText="Issuer: ">OEM CA</t>
<t hangText="Trust Implication: ">A whitelist of FW root CA trusted
by TAMs
</t>
<t hangText="Cardinality: ">One per device</t>
</list>
</t>
<t hangText="2. TEE key pair and certificate:">It is used for device
attestation to a remote TAM and SP.
</t>
<t>This key pair is burned into the device at device manufacturer.
The key pair and its certificate are valid for the expected
lifetime of the device.
<list hangIndent="2" style="hanging">
<t hangText="Location: ">Device TEE</t>
<t hangText="Supported Key Type: ">RSA and ECC</t>
<t hangText="Issuer: ">A CA that chains to a TEE root CA</t>
<t hangText="Trust Implication: ">A whitelist of TEE root CA
trusted by TAMs
</t>
<t hangText="Cardinality: ">One per device</t>
</list>
</t>
<t hangText="3. TAM key pair and certificate:">A TAM provider acquires
a certificate from a CA that a TEE trusts.
<list hangIndent="2" style="hanging">
<t hangText="Location: ">TAM provider</t>
<t hangText="Supported Key Type: ">RSA and ECC.</t>
<t hangText="Supported Key Size: ">RSA 2048-bit, ECC P-256
and P-384. Other sizes should be anticipated in future.
</t>
<t hangText="Issuer: ">TAM CA that chains to a root CA</t>
<t hangText="Trust Implication: ">A whitelist of TAM root CA
embedded in TEE
</t>
<t hangText="Cardinality: ">One or multiple can be used by a TAM</t>
</list>
</t>
<t hangText="4. SP key pair and certificate:">an SP uses its own key pair
and certificate to sign a TA.
<list hangIndent="2" style="hanging">
<t hangText="Location: ">SP</t>
<t hangText="Supported Key Type: ">RSA and ECC</t>
<t hangText="Supported Key Size: ">RSA 2048-bit, ECC P-256
and P-384. Other sizes should be anticipated in future.
</t>
<t hangText="Issuer: ">an SP signer CA that chains to a root CA</t>
<t hangText="Trust Implication: ">TAM manages SP. TA trusts an SP
by validating trust against a TAM that the SP uses. A TEE
trusts TAM to ensure that a TA from the TAM is trustworthy.
</t>
<t hangText="Cardinality: ">One or multiple can be used by an SP</t>
</list>
</t>
</list>
</t>
</section>
</section>
<section anchor="overview" title="Protocol Scope and Entity Relations">
<t>This document specifies messages and key properties that can
establish mutual trust between a TEE and a TAM. The
protocol provides specifications for the following three entities:
</t>
<t>
<list style="numbers">
<t>Key and certificate types required for device firmware, TEEs, TAs,
SPs, and TAMs
</t>
<t>Data message formats that should be exchanged between a TEE in a
device and a TAM
</t>
<t>An OTrP Broker in the REE that can relay
messages between a Client Application and TEE
</t>
</list>
</t>
<t>Figure 1: Protocol Scope and Entity Relationship</t>
<t>
<figure>
<preamble></preamble>
<artwork align="left"><![CDATA[
PKI CA -- CA CA --
| | |
| | |
| | |
Device | | --- OTrP Broker / Client App --- |
SW | | | | |
| | | | |
| | | | |
OTrP | -- TEE TAM-------
|
|
FW
]]></artwork>
</figure>
</t>
<t>Figure 2: OTrP System Diagram</t>
<t>
<figure>
<preamble></preamble>
<artwork align="left"><![CDATA[
-------OTrP Message Protocol---
| |
| |
-------------------- --------------- ----------
| REE | TEE | | TAM | | SP |
| --- | --- | | --- | | -- |
| | | | | | |
| Client | SD (TAs)| | SD / TA | | TA |
| Apps | | | Mgmt | | |
| | | | | | | |
| | | List of | | List of | | |
| OTrP | Trusted | | Trusted | | |
| Broker | TAM/SP | | FW/TEE | | |
| | CAs | | CAs | | |
| | | | | | |
| |TEE Key/ | | TAM Key/ | | SP Key/|
| | Cert | | Cert | | Cert |
| | FW Key/ | | | | |
| | Cert | | | | |
-------------------- --------------- ----------
| | |
| | |
------------- ---------- ---------
| TEE CA | | TAM CA | | SP CA |
------------- ---------- ---------
]]></artwork>
</figure>
</t>
<t>In the previous diagram, different Certificate Authorities can be used
respectively for different types of certificates. OTrP Messages are
always signed, where the signer keys is the message creator's private
key such as a FW's private key, a TEE's private key, or a TAM's
private key.
</t>
<t>The main OTrP component consists of a set of standard JSON messages
created by a TAM to deliver device SD and TA management commands to a
device, and device attestation and response messages created by a TEE
that responds to a TAM's OTrP message.
</t>
<t>The communication method of OTrP Messages between a TAM and TEE in a
device may vary between TAM and TEE providers. A mandatory
transport protocol is specified for a compliant TAM and a device TEE.
</t>
<t>An OTrP Broker is used to bridge communication between a TAM
and a TEE. The OTrP Broker doesn't need to know the actual content of OTrP
Messages except for the TEE routing information.
</t>
<section anchor="setupflow" title="A Sample Device Setup Flow">
<t>Step 1: Prepare Images for Devices
<list hangIndent="2" style="numbers">
<t>[TEE vendor] Deliver TEE Image (CODE Binary) to device OEM</t>
<t>[CA] Deliver root CA Whitelist</t>
<t>[Soc] Deliver TFW Image</t>
</list>
</t>
<t></t>
<t>Step 2: Inject Key Pairs and Images to Devices
<list hangIndent="2" style="numbers">
<t>[OEM] Generate Secure Boot Key Pair
(May be shared among multiple devices)</t>
<t>[OEM] Flash signed TFW Image and signed TEE Image
onto devices (signed by Secure Boot Key)</t>
</list>
</t>
<t></t>
<t>Step 3: Setup attestation key pairs in devices
<list hangIndent="2" style="numbers">
<t>[OEM] Flash TFW Public Key and a bootloader key.</t>
<t>[TFW/TEE] Generate a unique attestation key pair and
get a certificate for the device.</t>
</list>
</t>
<t></t>
<t>Step 4: Setup trust anchors in devices
<list hangIndent="2" style="numbers">
<t>[TFW/TEE] Store the key and certificate encrypted
with the eFuse key</t>
<t>[TEE vendor or OEM] Store trusted CA certificate list
into devices</t>
</list>
</t>
</section>
<section anchor="derivedkeys" title="Derived Keys in The Protocol">
<t>
The protocol generates one key pair in run time to
assist message communication and anonymous verification between
a TAM and a TEE.
</t>
<t>
TEE SP Anonymous Key (AIK): one derived key pair per SP in a device
</t>
<t>
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. This key pair is generated in the first SD
creation for an SP. It is deleted when all SDs are removed for a
SP in a device.
The public 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 is also used by a TAM to encrypt TA
binary data and personalization data when it sends a TA to a
device for installation.
</t>
</section>
<section anchor="sdtree" title="Security Domain Hierarchy and Ownership">
<t>
The primary job of a TAM is to help an SP to manage its trusted
application components. A TA is typically installed in an SD.
An SD is commonly created for an SP.
</t>
<t>
When an SP delegates its SD and TA management to a TAM, an SD is
created on behalf of a TAM in a TEE and the owner of the SD is
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.
</t>
<t>
Each SD for an SP is associated with only one TAM. When an SP changes
TAM, a new SP SD must be created to associate with the new TAM. The
TEE will maintain a registry of TAM ID and SP SD ID mapping.
</t>
<t>
From an SD ownership perspective, the SD tree is flat and there is
only one level. An SD is associated with its owner. It is up to TEE
implementation how it maintains SD binding information for a TAM and
different SPs under the same TAM.
</t>
<t>
It is an important decision in this protocol specification that a TEE
doesn't need to know whether a TAM is authorized to manage the SD for
an SP. This authorization is implicitly triggered by an SP Client
Application, which instructs what TAM it wants to use. An SD is 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 another TAM.
</t>
<t>
Since a TAM may support multiple SPs, sharing the same SD name for
different SPs creates a dependency in deleting an SD. An SD can be
deleted only after all TAs associated with this SD is deleted. An SP
cannot delete a Security Domain on its own with a TAM if a TAM
decides to introduce such sharing. There are cases where multiple
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 TAM
implementation and out of scope of this specification.
</t>
</section>
<section anchor="sdownerid"
title="SD Owner Identification and TAM Certificate Requirements">
<t>
There is a need of cryptographically binding proof about the owner of
an SD in a device. When an SD is created on behalf of a TAM, a future
request from the TAM must present itself as a way that the TEE can
verify it is the true owner. The certificate itself cannot reliably
used as the owner because TAM may change its certificate.
</t>
<t>
To this end, each TAM will be associated with a trusted identifier
defined as an attribute in the TAM certificate. This field is kept
the same when the TAM renew its certificates. A TAM CA is responsible
to vet the requested TAM attribute value.
</t>
<t>
This identifier value must not collide among different TAM providers,
and one TAM shouldn't be able to claim the identifier used by another
TAM provider.
</t>
<t>
The certificate extension name to carry the identifier can initially
use SubjectAltName:registeredID. A dedicated new extension name may
be registered later.
</t>
<t>
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 TAM in the
certificate enrollment process.
</t>
<t>
A TEE can assign this certificate attribute value as the TAM owner ID
for the SDs that are created for the TAM.
</t>
<t>
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 TAM is
able to produce a Proof-of-Possession (POP) data with the secret.
</t>
</section>
<section anchor="spcontainer" title="Service Provider Container">
<t>A sample Security Domain hierarchy for the TEE is shown below.
</t>
<t>
<figure>
<artwork><![CDATA[
----------
| TEE |
----------
|
| ----------
|----------| SP1 SD1 |
| ----------
| ----------
|----------| SP1 SD2 |
| ----------
| ----------
|----------| SP2 SD1 |
----------
]]></artwork>
</figure>
</t>
<t>OTrP segregates SDs and TAs such that a TAM can only manage or
retrieve data for SDs and TAs that it previously created for the
SPs it represents.
</t>
</section>
</section>
<section anchor="otrpbroker" title="OTrP Broker">
<t>A TEE and TAs that run inside the TEE don't generally have capability
to communicate to the outside of the hosting device, for example,
the TEE specified by Global Platform groups <xref target="GPTEE"/>.
This calls for a 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.
</t>
<t>A shared OTrP Broker comes to meed this need. An OTrP Broker 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.
</t>
<t>
This interface for Client Applications may be commonly an Android
service call for an Android powered device. A Client Application
interacts with a TAM, and turns around to pass messages received
from TAM to OTrP Broker.
</t>
<t>In all cases, a Client Application needs to be able to identify an
OTrP Broker that it can use.
</t>
<section anchor="brokerrole" title="Role of OTrP Broker">
<t> An OTrP Broker abstracts the message exchanges
with the TEE in a device. The input data is originated from a TAM
that a Client Application connects. A Client Application may also
directly call OTrP Broker for some TA query functions.
</t>
<t>
OTrP Broker may internally process a request from TAM. At least, it
needs to know where to route a message, e.g. TEE instance. It doesn't
need to process or verify message content.
</t>
<t>
OTrP Broker returns TEE / TFW generated response messages to the
caller. OTrP Broker isn't expected to handle any network connection
with an application or TAM.
</t>
<t>
OTrP Broker only needs to return an OTrP Broker error message if the
TEE is not reachable for some reason. Other errors are represented
as response messages returned from the TEE which will then be
passed to the TAM.
</t>
</section>
<section anchor="brokergp" title="OTrP Broker and Global Platform TEE Client API">
<t>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 to OTrP implementation that converts given messages from
TAM. More details can be found at <xref target="GPTEECLAPI"/>.
</t>
</section>
<section anchor="brokerimpl" title="OTrP Broker Implementation Consideration">
<t>A Provider should consider methods of distribution, scope and
concurrency on device and runtime options when implementing an OTrP
Broker. Several non-exhaustive options are discussed below. Providers
are encouraged to take advantage of the latest communication and
platform capabilities to offer the best user experience.
</t>
<section title="OTrP Broker Distribution">
<t>
OTrP Broker installation is commonly carried out at OEM time. A
user can
dynamically download and install an OTrP Broker on-demand.
</t>
<t>
It is important to ensure a legitimate OTrP Broker is installed and
used. If an OTrP Broker is compromised it may send rogue messages to
TAM and TEE and introduce additional risks.
</t>
</section>
<section title="Number of OTrP Broker">
<t>
We anticipate only one shared OTrP Broker instance in a device. The
device's TEE vendor will most probably supply one OTrP Broker.
Potentially we expect some open source.
</t>
<t>
With one shared OTrP Broker, the OTrP Broker provider is responsible
to allow multiple TAMs and TEE providers to achieve
interoperability. With a standard OTrP Broker interface, TAM can
implement its own SDK for its SP Client Applications to work with
this OTrP Broker.
</t>
<t>
Multiple independent OTrP Broker providers can be used as long as
they have standard interface to a Client Application or TAM SDK.
Only one OTrP Broker is expected in a device.
</t>
<t>
TAM providers are generally expected to provide SDK for SP
applications to interact with an OTrP Broker for the TAM and TEE
interaction.
</t>
</section>
</section>
<section anchor="brokerapi" title="OTrP Broker Interfaces for Client Applications">
<t>A Client Application shall be responsible for relaying
messages between the OTrP Broker and the TAM.
</t>
<t>
If a failure occurs during calling OTrP Broker, an error message
described in "Common Errors" section (see <xref target="commerr"></xref>)
will be returned.
</t>
<section anchor="brokerproc" title="ProcessOTrPMessage call">
<t>
Description
<list hangIndent="4" style="empty">
<t>
A Client Application will use this method of the OTrP Broker in
a device to pass OTrP messages from a TAM. The method is
responsible for interacting with the TEE and for forwarding the
input message to the TEE. It also returns TEE generated response
message back to the Client Application.
</t>
</list>
</t>
<t>
Inputs:
<list hangIndent="4" style="empty">
<t>TAMInMsg - OTrP message generated in a TAM that is passed to
this method from a Client Application.
</t>
</list>
</t>
<t>
Outputs:
<list hangIndent="4" style="empty">
<t>A TEE-generated OTrP response message (which may be a
successful response or be a response message containing
an error raised within the TEE) for the client application
to forward to the TAM. In the event of the OTrP Broker not
being able to communicate with the TEE, a
OTrPBrokerException shall be thrown.
</t>
</list>
</t>
</section>
<section anchor="brokertaapi" title="GetTAInformation call">
<t>
Description
<list hangIndent="4" style="empty">
<t>
A Client Application may quickly query local TEE about a
previously installed TA without requiring TAM each time if it
has had the TA's identifier and previously saved TEE SP AIK
public key for TA information integrity verification.
</t>
</list>
</t>
<t>
Inputs:
<figure>
<artwork><![CDATA[
{
"TAQuery": {
"spid": "<SP identifier value of the TA>",
"taid": "<The identifier value of the TA>"
}
}
]]></artwork>
</figure>
</t>
<t>
Outputs:
<list hangIndent="4" style="empty">
<t>
The OTrP Broker is expected to return TA signer and TAM
signer 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.
</t>
<t>
The output is a JSON message that is generated by the TEE. It
contains the following information:
<list hangIndent="2" style="symbols">
<t>tamid</t>
<t>SP ID</t>
<t>TA signer certificate</t>
<t>TAM certificate</t>
</list>
The message is signed with TEE SP AIK private key.
</t>
<t>
The Client Application is expected to consume the response as
follows.
</t>
<t>
The Client Application gets signed TA metadata, in
particular, the TA signer certificate. It is able to verify
that the result is from device by checking signer against TEE
SP AIK public key it gets in some earlier interaction with TAM.
</t>
<t>
If this is a new Client Application in the device that hasn't
had TEE SP AIK public key for the response verification, the
application can contact the TAM first to do GetDeviceState, and
TAM will return TEE SP AIK public key to the app for this
operation to proceed.
</t>
<t>
Output Message:
<figure>
<artwork><![CDATA[
{
"TAInformationTBS": {
"taid": "<TA Identifier from the input>",
"tamid": "<TAM ID for the Security Domain where this TA
resides>",
"spid": "<The service provider identifier of this TA>",
"signercert": "<The BASE64 encoded certificate data of the
TA binary application's signer certificate>",
"signercacerts": [ < The full list of CA certificate chain
including the root CA>
],
"cacert": "<The BASE64 encoded CA certificate data of the TA
binary application's signer certificate>"
],
"tamcert": "<The BASE64 encoded certificate data of the TAM
that manages this TA.>",
"tamcacerts": [ < The full list of CA certificate chain
including the root CA>
],
"cacert":"<The BASE64 encoded CA certificate data of the TAM
that manages this TA>"
]
}
}
{
"TAInformation": {
"payload": "<The BASE64URL encoding of the TAInformationTBS
JSON above>",
"protected": "<BASE64URL encoded signing algorithm>",
"header": {
"signer": {"<JWK definition of the TEE SP AIK public
key>"}
},
"signature": "<signature contents signed by TEE SP AIK
private key BASE64URL encoded>"
}
}
]]></artwork>
</figure>
where the definitions of BASE64 and BASE64URL refer to
<xref target="RFC4648"/>.
</t>
<t>
A sample JWK public key representation refers to an example in
<xref target="RFC7517"/>.
</t>
</list>
</t>
</section>
</section>
<section anchor="brokeruse" title="Sample End-to-End Client Application Flow">
<section title="Case 1: A New Client Application Uses a TA">
<t>
<list style="numbers">
<t>
During the Client Application installation time, the Client
Application calls TAM to initialize the device preparation step.
<list style="letters">
<t>The Client Application knows it wants to use a Trusted
Application TA1 but the application doesn't know whether
TA1 has been installed or not. It can use
<xref target="GPTEECLAPI">GP TEE Client API </xref> to
check the existence of TA1 first. If it detects
that TA1 doesn't exist, it will contact TAM to initiate
the installation of TA1. Note that TA1 could have been
previously installed by other Client Applications from
the same service provider in the device.
</t>
<t>The Client Application sends the TAM the TA list that it
depends on. The TAM will query a device for the Security
Domains and TAs that have been installed, and instructs
the device to install any dependent TAs that have not been
installed.
</t>
<t>In general, the TAM has the latest TA list and
their status in a device because all operations are
instructed by TAM. TAM has such visibility because all
Security Domain deletion and TA deletion are managed by
the TAM; the TAM could have stored the state when a TA is
installed, updated and deleted. There is also the
possibility that an update
command is carried out inside TEE but a response is never
received in TAM. There is also possibility that some manual
local reset is done in a device that the TAM isn't aware of
the changes.
</t>
</list>
</t>
<t>The TAM generates message: GetDeviceStateRequest
</t>
<t>The Client Application passes the JSON message GetDeviceStateRequest
to OTrP Broker call ProcessOTrPMessage. The communication between a
Client Application and an OTrP Broker is up to the implementation
of the OTrP Broker.
</t>
<t>The OTrP Broker routes the message to the active TEE.
Multiple TEE case: it is up to OTrP Broker to figure this out.
This specification limits the support to only one active TEE,
which is the typical case today.
</t>
<t>The target active TEE processes the received OTrP message, and
returns a JSON message GetDeviceStateResponse.
</t>
<t>The OTrP Broker passes the GetDeviceStateResponse to the Client
Application.
</t>
<t>The Client Application sends GetDeviceStateResponse to the TAM.
</t>
<t>
The TAM processes the GetDeviceStateResponse.
<list style="letters">
<t>Extract TEEspaik for the SP, signs TEEspaik with TAM
signer key
</t>
<t>Examine SD list and TA list</t>
</list>
</t>
<t>
The TAM continues to carry out other actions based on the need.
The next call could be instructing the device to install a
dependent TA.
<list style="letters">
<t>Assume a dependent TA isn't in the device yet, the TAM
may do the following: (1) create an SD in which to install
the TA by sending a CreateSDRequest message. The message
is sent back to the Client Application, and then
the OTrP Broker and TEE to process; (2) install a TA with
an InstallTARequest message.
</t>
<t>If a Client Application depends on multiple TAs, the Client
Application should expect multiple round trips of the TA
installation message exchanges.
</t>
</list>
</t>
<t>At the last TAM and TEE operation, the TAM returns the signed
TEE SP AIK public key to the application.
</t>
<t>The Client Application stores the TEEspaik for future
loaded TA trust check.
</t>