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
|
<html devsite><head>
<title>Keymaster 授权标记</title>
<meta name="project_path" value="/_project.yaml"/>
<meta name="book_path" value="/_book.yaml"/>
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>本页提供了一些对 Keymaster HAL 实现人员很有帮助的详细信息。
其中介绍了 HAL 中的每个标记、提供相应标记的 Keymaster 版本以及相应标记是否可重复使用。除非标记说明中另有注明，否则以下所有标记都会在密钥生成期间用于指定密钥特性。</p>
<p>对于 Keymaster 4，标记是在 <code>platform/hardware/interfaces/keymaster/<var>keymaster-version</var>/types.hal</code> 中定义的；例如，如果是 Keymaster 3，则在 <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/3.0/types.hal" class="external">3.0/types.hal</a> 中定义，如果是 Keymaster 4，则在 <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/4.0/types.hal" class="external">4.0/types.hal</a> 中定义。对于 Keymaster 2 及更低版本，标记是在 <code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware" class="external">
platform/hardware/libhardware/include/hardware/keymaster_defs.h</a></code> 中定义的。</p>
<p>要了解具体函数，请参阅 <a href="/security/keystore/implementer-ref">Keymaster 函数</a>页面。</p>
<p class="note">为了支持 Keymaster 3 从旧式 C 结构 HAL 转换到根据新的硬件接口定义语言 (HIDL) 定义生成的 C++ HAL 接口，Android 8.0 中的标记名称已更改。如同所有其他 keymaster 枚举一样，标记现在被定义为范围限定为 C++ 的枚举。例如，标记的前缀从之前的 <code>KM_TAG_</code> 改为现在的 <code>Tag::</code>。</p>
<h2 id="active_datetime">Tag::ACTIVE_DATETIME</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定相应密钥变为有效状态的日期和时间。在此之前，尝试使用相应密钥时，操作会失败并显示 <code>ErrorCode::KEY_NOT_YET_VALID</code>。</p>
<p>此标记的值是一个 64 位的整数，表示距 1970 年 1 月 1 日的毫秒数。</p>
<h2 id="algorithm">Tag::ALGORITHM</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定与相应密钥配合使用的加密算法。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
</pre>
<h2 id="all_applications">Tag::ALL_APPLICATIONS</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>预留以供日后使用。</p>
<h2 id="allow_while_on_body">Tag::ALLOW_WHILE_ON_BODY</h2>
<p><strong>版本</strong>：2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>此标记仅适用于配备贴身传感器的 Android Wear 设备。目前，TEE 并不能提供对贴身传感器的安全访问，贴身传感器也不是非常安全，因此这应该是一项完全由软件强制执行的功能。</p>
<h2 id="all_users">Tag::ALL_USERS</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>预留以供日后使用。</p>
<h2 id="application_data">Tag::APPLICATION_DATA</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>将此标记提供给 <a href="/security/keystore/implementer-ref#generate_key">generateKey</a> 或 <a href="/security/keystore/implementer-ref#import_key">importKey</a> 时，此标记可用于指定使用相应密钥时均须提供的数据。具体来说就是，调用 <a href="/security/keystore/implementer-ref#export_key">exportKey</a> 和 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a> 时需要为 <code>clientId</code> 参数提供相同的值，而调用 <a href="/security/keystore/implementer-ref#begin">begin</a> 时则需要提供此标记以及相同的相关数据（作为 <code>inParams</code> 集合的一部分）。如果未收到正确的数据，则该函数会返回 <code>ErrorCode::INVALID_KEY_BLOB</code>。</p>
<p>此标记的内容以加密形式绑定到相应密钥，这意味着，如果有不轨人士有权访问安全域的所有机密内容，但无权访问此标记的内容，必须要确保他们在不对此标记的内容进行暴力破解攻击的情况下无法解密相应密钥，应用可通过指定足够的高熵内容来防范这一行为。<em></em></p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="application_id">Tag::APPLICATION_ID</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>将此标记提供给 <a href="/security/keystore/implementer-ref#generate_key">generateKey</a> 或 <a href="/security/keystore/implementer-ref#import_key">importKey</a> 时，此标记可用于指定使用相应密钥时均须提供的数据。具体来说就是，调用 <a href="/security/keystore/implementer-ref#export_key">exportKey</a> 和 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a> 时需要为 <code>clientId</code> 参数提供相同的值，而调用 <a href="/security/keystore/implementer-ref#begin">begin</a> 时则需要提供此标记以及相同的相关数据（作为 <code>inParams</code> 集合的一部分）。如果未收到正确的数据，则该函数会返回 <code>ErrorCode::INVALID_KEY_BLOB</code>。</p>
<p>此标记的内容以加密形式绑定到相应密钥，这意味着，即使有不轨人士有权访问安全域的所有机密内容，也应无权访问此标记的内容，必须要确保他们无法解密相应密钥（在不对此标记的内容进行暴力破解攻击的情况下）。<em></em></p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="associated_data">Tag::ASSOCIATED_DATA</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于提供进行 AES-GCM 加密或解密时使用的“相关数据”。可以将此标记提供给 <a href="/security/keystore/implementer-ref#update">update</a>，以便指定在计算 GCM 标记时使用的未加密/解密的数据。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_application_id">Tag::ATTESTATION_APPLICATION_ID</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于识别已发起密钥认证的可能的应用集。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_challenge">Tag::ATTESTATION_CHALLENGE</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于在认证时提供质询。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_brand">Tag::ATTESTATION_ID_BRAND</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>提供设备的品牌名称（由 Android 中的 <code>Build.BRAND</code> 返回）。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_device">Tag::ATTESTATION_ID_DEVICE</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>提供设备的设备名称（由 Android 中的 <code>Build.DEVICE</code> 返回）。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_imei">Tag::ATTESTATION_ID_IMEI</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？是</p>
<p>为设备上的所有无线装置提供 IMEI。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_manufacturer">Tag::ATTESTATION_ID_MANUFACTURER</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>提供设备的制造商名称（由 Android 中的 <code>Build.MANUFACTURER</code> 返回）。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_meid">Tag::ATTESTATION_ID_MEID</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？是</p>
<p>为设备上的所有无线装置提供 MEID。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_model">Tag::ATTESTATION_ID_MODEL</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>提供设备的型号名称（由 Android 中的 <code>Build.MODEL</code> 返回）。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_product">Tag::ATTESTATION_ID_PRODUCT</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>提供设备的产品名称（由 Android 中的 <code>Build.PRODUCT</code> 返回）。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="attestation_id_serial">Tag::ATTESTATION_ID_SERIAL</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>提供设备的序列号。仅在请求认证该设备的标识符时才会设置此字段。</p>
<p>如果该设备不支持 ID 认证（或者之前已调用 <code>destroyAttestationIds()</code> 且该设备无法再证明其 ID），则任何包含该标记的密钥认证请求都会失败并显示 <code>ErrorCode::CANNOT_ATTEST_IDS</code>。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="auth_timeout">Tag::AUTH_TIMEOUT</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定授权在多长时间内使用相应密钥（以秒数计，从通过身份验证开始算起）。如果 <a href="#user_secure_id">Tag::USER_SECURE_ID</a> 存在而此标记不存在，那么每次使用相应密钥时都需要进行身份验证（要详细了解按操作进行身份验证的流程，请参阅 <a href="/security/keystore/implementer-ref#begin">begin</a>）。</p>
<p>此标记的值是一个 32 位的整数，用于指定可在多长时间内使用相应密钥（以秒计，从使用由 <a href="#mac_length">Tag::USER_AUTH_TYPE</a> 指定的身份验证方法对由 <a href="#user_secure_id">Tag::USER_SECURE_ID</a> 指定的用户成功进行身份验证后开始算起）。</p>
<h2 id="auth_token">Tag::AUTH_TOKEN</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于向 <a href="/security/keystore/implementer-ref#begin">begin</a>、<a href="/security/keystore/implementer-ref#update">update</a> 或 <a href="/security/keystore/implementer-ref#finish">finish</a> 提供<a href="/security/keystore/authentication/#authentication_token_format">身份验证令牌</a>，以便向要求用户通过身份验证的密钥操作（密钥带有 <a href="#user_secure_id">Tag::USER_SECURE_ID</a>）证明相应用户已通过身份验证。</p>
<p>此标记的值是一个包含 <code>hw_auth_token_t</code> 结构的 Blob。</p>
<h2 id="blob_usage_requirements">Tag::BLOB_USAGE_REQUIREMENTS</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定要使用生成的密钥所必需的系统环境条件。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
KM_BLOB_STANDALONE = 0,
KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;
</pre>
<p>可以在密钥生成期间指定此标记，以便要求在指定条件下才可以使用生成的密钥。此标记需要和密钥特性一起从 <a href="/security/keystore/implementer-ref#generate_key">generateKey</a> 和 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a> 返回。
如果调用程序指定了值为 <code>KeyBlobUsageRequirements::STANDALONE</code> 的 <code>Tag::BLOB_USAGE_REQUIREMENTS</code>，则 Trustlet 会返回一个可在没有文件系统支持的情况下使用的密钥 Blob。这对于具有已加密磁盘的设备至关重要：在使用 Keymaster 密钥解密磁盘之前，此类设备的文件系统可能一直无法使用。</p>
<h2 id="block_mode">Tag::BLOCK_MODE</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？是</p>
<p>用于指定可与相应密钥配合使用的分块加密模式。
此标记仅与 AES 密钥有关。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
KM_MODE_ECB = 1,
KM_MODE_CBC = 2,
KM_MODE_CTR = 3,
KM_MODE_GCM = 32,
} keymaster_block_mode_t;
</pre>
<p>此标记可重复使用；对于 AES 密钥操作，请在 <a href="/security/keystore/implementer-ref#begin">begin</a> 的 <code>additionalParams</code> 参数中指定模式。
如果指定的模式不在相应密钥的关联模式之列，操作会失败并显示 <code>ErrorCode::INCOMPATIBLE_BLOCK_MODE</code>。</p>
<h2 id="boot_patchlevel">Tag::BOOT_PATCHLEVEL</h2>
<p><strong>版本</strong>：4</p>
<p>Tag::BOOT_PATCHLEVEL 用于指定可与秘钥配合使用的启动映像（内核）安全补丁程序级别。该标记一定不会发送至 keymaster TA，而是由 TA 添加到由硬件强制执行的授权列表中。任何试图将秘钥与不同于当前运行的系统补丁程序级别的 <code>Tag::BOOT_PATCHLEVEL</code> 配合使用的行为，都会导致 <code>begin()</code>、<code>getKeyCharacteristics()</code> 或 <code>exportKey()</code> 返回 <code>ErrorCode::KEY_REQUIRES_UPGRADE</code>。如需了解详情，请参阅 <code>upgradeKey()</code>。
</p>
<p>该标记的值是形式为 YYYYMMDD 的整数，其中 YYYY 表示上次更新时间的四位数年份，MM 表示上次更新时间的两位数月份，DD 表示上次更新时间的两位数日期。例如，对于上次更新时间为 2018 年 6 月 5 日的 Android 设备上生成的密钥，其值将表示为 20180605。如果日期未知，则可以替换为 00。
</p>
<p>在每次启动期间，引导加载程序都必须将启动映像的补丁程序级别提供给安全环境（相应机制是由实现定义的）。
</p>
<p>
必须由硬件强制执行。
</p>
<h2 id="bootloader_only">Tag::BOOTLOADER_ONLY</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定仅引导加载程序可以使用该密钥。</p>
<p>此标记为布尔值，因此可能的值为 true（如果此标记存在）和 false（如果此标记不存在）。</p>
<p>尝试从 Android 系统使用带有 <code>Tag::BOOTLOADER_ONLY</code> 标记的密钥时，操作会失败并显示 <code>ErrorCode::INVALID_KEY_BLOB</code>。</p>
<h2 id="caller_nonce">Tag::CALLER_NONCE</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定调用程序可以为需要随机数的操作提供随机数。</p>
<p>此标记为布尔值，因此可能的值为 true（如果此标记存在）和 false（如果此标记不存在）。</p>
<p>此标记仅用于 AES 密钥，并且仅与 CBC、CTR 和 GCM 分块模式有关。如果此标记不存在，则实现应拒绝执行任何向 <a href="/security/keystore/implementer-ref#begin">begin</a> 提供 <a href="#nonce">Tag::NONCE</a> 的操作并显示 <code>ErrorCode::CALLER_NONCE_PROHIBITED</code>。</p>
<h2 id="creation_datetime">Tag::CREATION_DATETIME</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定相应密钥的创建日期和时间（以距 1970 年 1 月 1 日的毫秒数计）。此标记为可选标记，仅供参考。</p>
<h2 id="digest">Tag::DIGEST</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？是</p>
<p>用于指定可与相应密钥配合使用以执行签名和验证操作的摘要算法。此标记与 RSA 密钥、ECDSA 密钥和 HMAC 密钥有关。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class Digest : uint32_t {
NONE = 0,
MD5 = 1,
SHA1 = 2,
SHA_2_224 = 3,
SHA_2_256 = 4,
SHA_2_384 = 5,
SHA_2_512 = 6,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
KM_DIGEST_NONE = 0,
KM_DIGEST_MD5 = 1,
KM_DIGEST_SHA1 = 2,
KM_DIGEST_SHA_2_224 = 3,
KM_DIGEST_SHA_2_256 = 4,
KM_DIGEST_SHA_2_384 = 5,
KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;
</pre>
<p>此标记可重复使用。要执行签名和验证操作，请在 <a href="/security/keystore/implementer-ref#begin">begin</a> 的 <code>additionalParams</code> 参数中指定摘要。
如果指定的摘要不在相应密钥的关联摘要之列，操作会失败并显示 <code>ErrorCode::INCOMPATIBLE_DIGEST</code>。</p>
<h2 id="ec_curve">Tag::EC_CURVE</h2>
<p><strong>版本</strong>：2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>在 Keymaster 1 中，用于 EC 密钥的曲线从指定密钥的大小推测而来。为了在今后提高灵活性，Keymaster 2 引入了一种明确的方法来指定曲线。EC 密钥生成请求可包含 <code>Tag::EC_CURVE</code> 和/或 <code>Tag::KEY_SIZE</code>。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
</pre>
<p>如果某个生成请求仅包含 <code>Tag::KEY_SIZE</code>，则回退到 Keymaster 1 逻辑，以选择相应的 NIST 曲线。</p>
<p>如果请求仅包含 <code>Tag::EC_CURVE</code>，则使用指定的曲线。对于 Keymaster 3 及更高版本，曲线在 <code>EcCurve</code> 中定义。对于 Keymaster 2 及更早版本，曲线在 <code>keymaster_ec_curve_t</code> 中定义。</p>
<p>如果请求同时包含两者，则使用 <code>Tag::EC_CURVE</code> 指定的曲线，并验证指定密钥的大小是否适合该曲线。如果不适合，则返回 <code>ErrorCode::INVALID_ARGUMENT</code>。</p>
<h2 id="include_unique_id">Tag::INCLUDE_UNIQUE_ID</h2>
<p><strong>版本</strong>：2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>在密钥生成期间指定此标记，以指示所生成密钥的认证证书应包含一个范围限定于应用且受时间限制的设备唯一 ID（由 <a href="#unique_id">Tag::UNIQUE_ID</a> 指定）。</p>
<p>此标记为布尔值，因此可能的值为 true（如果此标记存在）和 false（如果此标记不存在）。</p>
<h2 id="key_size">Tag::KEY_SIZE</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定相应密钥的大小（以位数计，按适用于相应密钥算法的一般方式衡量）。例如，对于 RSA 密钥，<code>Tag::KEY_SIZE</code> 用于指定公开模数的大小。对于 AES 密钥，此标记用于指定密钥私密材料的长度。</p>
<p class="note">在 Keymaster 2 及更高版本中，<code>Tag::KEY_SIZE</code> 不再是选择 ECC（椭圆曲线加密）曲线的首选机制。虽然对于其他密钥类型而言，该标记没有任何变化，但 ECC 曲线是使用标记 <a href="#ec_curve"><code>Tag::EC_CURVE</code></a> 选择的。</p>
<h2 id="mac_length">Tag::MAC_LENGTH</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于提供 MAC 或 GCM 身份验证标记的请求长度（以位数计）。</p>
<p>此标记的值是 MAC 长度（以位数计）。这个值是 8 的倍数，并且不小于与相应密钥关联的 <a href="#min_mac_length">Tag::MIN_MAC_LENGTH</a> 的值。</p>
<h2 id="max_uses_per_boot">Tag::MAX_USES_PER_BOOT</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定在两次系统重启之间可以使用相应密钥的最大次数。这是另一种限制密钥使用次数的机制。</p>
<p>此标记的值是一个 32 位的整数，表示在每次系统启动后可以使用相应密钥的次数。</p>
<p>当有操作使用带有此标记的某个密钥时，与该密钥关联的计数器应在 <a href="/security/keystore/implementer-ref#begin">begin</a> 调用期间递增。当密钥计数器超出此标记的值后，所有尝试使用该密钥的后续操作都会失败并显示 <code>ErrorCode::MAX_OPS_EXCEEDED</code>，直到设备重启为止。这意味着 Trustlet 会为带有此标记的密钥维护一份使用次数计数器表格。
由于 Keymaster 内存的大小通常有限制，因此该表格可以具有固定的最大大小，并且当该表格被占满时，如果有操作尝试使用带有此标记的密钥，Keymaster 可以使这些操作失败。此表格需要容纳至少 16 个密钥。如果某项操作因该表格已被占满而失败，则 Keymaster 会返回 <code>ErrorCode::TOO_MANY_OPERATIONS</code>。</p>
<h2 id="min_mac_length">Tag::MIN_MAC_LENGTH</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>此标记适用于支持 GCM 模式的 HMAC 密钥和 AES 密钥，用于指定可通过相应密钥请求或验证的 MAC 的最小长度。</p>
<p>此标记的值是 MAC 的最小长度（以位数计）。这个值是 8 的倍数。对于 HMAC 密钥，这个值至少为 64。对于 GCM 密钥，这个值介于 96 到 128 之间。</p>
<h2 id="min_seconds_between_ops">Tag::MIN_SECONDS_BETWEEN_OPS</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定至少间隔多长时间才能再次将密钥用于允许的操作。在不限制密钥使用次数可能会给暴力破解攻击以可乘之机的环境中，可以使用此标记来限制密钥的使用次数。</p>
<p>此标记的值是一个 32 位的整数，表示允许的操作之间间隔的秒数。</p>
<p>当有操作使用某个带有此标记的密钥时，请在 <a href="/security/keystore/implementer-ref#finish">finish</a> 或 <a href="/security/keystore/implementer-ref#abort">abort</a> 调用期间启动计时器。在计时器表明由 <code>Tag::MIN_SECONDS_BETWEEN_OPS</code> 指定的间隔时间已过去之前收到的所有 <a href="/security/keystore/implementer-ref#begin">begin</a> 调用都会失败并显示 <code>ErrorCode::KEY_RATE_LIMIT_EXCEEDED</code>。这意味着 Trustlet 会为带有此标记的密钥维护一份使用次数计数器表格。由于 Keymaster 内存的大小通常有限制，因此该表格可以具有固定的最大大小，并且当该表格被占满时，如果有操作尝试使用带有此标记的密钥，Keymaster 可以使这些操作失败。该表格需要容纳至少 32 个使用中的密钥，而且当密钥最小使用间隔到期时，需要主动重复使用该表格中的位置。如果某项操作因该表格已被占满而失败，则 Keymaster 会返回 <code>ErrorCode::TOO_MANY_OPERATIONS</code>。</p>
<h2 id="no_auth_required">Tag::NO_AUTH_REQUIRED</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定无需进行身份验证即可使用相应密钥。此标记与 <a href="#user_secure_id">Tag::USER_SECURE_ID</a> 互斥。</p>
<p>此标记为布尔值，因此可能的值为 true（如果此标记存在）和 false（如果此标记不存在）。</p>
<h2 id="nonce">Tag::NONCE</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于提供或返回进行 AES GCM、CBC 或 CTR 加密/解密时使用的随机数或初始化矢量 (IV)。在加密和解密操作期间，可以将此标记提供给 <a href="/security/keystore/implementer-ref#begin">begin</a>。仅当相应密钥带有 <a href="#caller_nonce">Tag::CALLER_NONCE</a> 时，此标记才会提供给 <a href="/security/keystore/implementer-ref#begin">begin</a>。如果未提供此标记，Keymaster 将会随机生成并通过 begin 返回一个适当的随机数或 IV。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。所允许的长度取决于模式：GCM 随机数的长度为 12 个字节；CBC IV 和 CTR IV 的长度为 16 个字节。</p>
<h2 id="origin">Tag::ORIGIN</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定相应密钥是在哪里创建的（如果知道）。在生成或导入密钥期间可以不指定此标记，但此标记必须要由 Trustlet 添加到密钥特性中。</p>
<strong>Keymaster 3</strong>
<p>可能的值是在 <code>android::hardware::keymaster::v3_0::KeyOrigin</code> 中定义的：</p>
<pre class="devsite-click-to-copy">
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<p>可能的值是在 <code>keymaster_origin_t</code> 中定义的：</p>
<pre class="devsite-click-to-copy">
typedef enum {
KM_ORIGIN_GENERATED = 0,
KM_ORIGIN_IMPORTED = 2,
KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t
</pre>
<p>此标记的值的完整含义不仅取决于值本身，还取决于值是位于由硬件强制执行的特性列表中，还是位于由软件强制执行的特性列表中。</p>
<p><code>GENERATED</code> 表示相应密钥是由 Keymaster 生成的。
如果它位于由硬件强制执行的列表中，那么相应密钥是在安全硬件中生成的，并且已永久绑定到硬件。如果它位于由软件强制执行的列表中，那么相应密钥是在 SoftKeymaster 中生成的，并且没有绑定到硬件。</p>
<p><code>DERIVED</code> 表示相应密钥是在 Keymaster 内部派生的。
很可能存在于设备之外。</p>
<p><code>IMPORTED</code> 表示相应密钥是在 Keymaster 之外生成的，并且导入到了 Keymaster 中。如果它位于由硬件强制执行的列表中，那么相应密钥已永久绑定到硬件，不过可能存在位于安全硬件之外的副本。如果它位于由软件强制执行的列表中，那么相应密钥已导入到 SoftKeymaster 中，并且没有绑定到硬件。</p>
<p><code>UNKNOWN</code> 应当仅出现在由硬件强制执行的列表中。
它表示相应密钥已绑定到硬件，但不知道相应密钥原本就是在安全硬件中生成的，还是导入的。只有在使用 keymaster0 硬件模拟 keymaster1 服务时，才会出现这种情况。</p>
<h2 id="origination_expire_datetime">Tag::ORIGINATION_EXPIRE_DATETIME</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定相应密钥无法再用于签名和加密目的的过期日期和时间。在此之后，如果尝试使用向 <a href="/security/keystore/implementer-ref#begin">begin</a> 提供 <a href="#purpose">KeyPurpose::SIGN</a> 或 <a href="#purpose">KeyPurpose::ENCRYPT</a> 的密钥，操作都会失败并显示 <code>ErrorCode::KEY_EXPIRED</code>。</p>
<p>此标记的值是一个 64 位的整数，表示距 1970 年 1 月 1 日的毫秒数。</p>
<h2 id="os_patchlevel">Tag::OS_PATCHLEVEL</h2>
<p><strong>版本</strong>：2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>该标记一定不会发送至 keymaster TA，而是由 TA 添加到由硬件强制执行的授权列表中。</p>
<p>该标记的值是形式为 YYYYMM 的整数，其中 YYYY 表示上次更新时间的四位数年份，MM 表示上次更新时间的两位数月份。例如，对于上次更新时间为 2015 年 12 月的 Android 设备上生成的密钥，其值将表示为 201512。</p>
<p>如果密钥的补丁程序级别与当前补丁程序级别不同，则该密钥不可用。尝试使用此类密钥会导致 <a href="/security/keystore/implementer-ref#begin">begin</a>、<a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a> 或 <a href="/security/keystore/implementer-ref#export_key">exportKey</a> 返回 <code>ErrorCode::KEY_REQUIRES_UPGRADE</code>。如需了解更多详情，请参阅<a href="/security/keystore/version-binding">版本绑定</a>。</p>
<h2 id="os_version">Tag::OS_VERSION</h2>
<p><strong>版本</strong>：2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>该标记一定不会发送至 keymaster TA，而是由 TA 添加到由硬件强制执行的授权列表中。</p>
<p>该标记的值是形式为 MMmmss 的整数，其中 MM 表示主要版本号，mm 表示次要版本号，ss 表示子次要版本号。例如，对于在 Android 4.0.3 版本上生成的密钥，其值将表示为 040003。</p>
<h2 id="padding">Tag::PADDING</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？是</p>
<p>用于指定可与相应密钥配合使用的填充模式。此标记与 RSA 密钥和 AES 密钥有关。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class PaddingMode : uint32_t {
NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
RSA_PKCS1_1_5_SIGN = 5,
PKCS7 = 64,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
KM_PAD_NONE = 1,
KM_PAD_RSA_OAEP = 2,
KM_PAD_RSA_PSS = 3,
KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
KM_PAD_PKCS7 = 64,
} keymaster_padding_t;
</pre>
<p><code>PaddingMode::RSA_OAEP</code> 和 <code>PaddingMode::RSA_PKCS1_1_5_ENCRYPT</code> 仅用于 RSA 加密/解密密钥，分别用来指定 RSA PKCS#1v2 OAEP 填充和 RSA PKCS#1 v1.5 随机填充。
<code>PaddingMode::RSA_PSS</code> 和 <code>PaddingMode::RSA_PKCS1_1_5_SIGN</code> 仅用于 RSA 签名/验证密钥，分别用来指定 RSA PKCS#1v2 PSS 填充和 RSA PKCS#1 v1.5 确定性填充。</p>
<p class="note"><strong>注意</strong>：RSA PSS 填充模式与 <a href="#digest">Digest::NONE</a> 不兼容。</p>
<p><code>PaddingMode::NONE</code> 可与 RSA 密钥或 AES 密钥配合使用。对于 AES 密钥，如果将 <code>PaddingMode::NONE</code> 与分块模式 ECB 或 CBC 配合使用，并且要加密或解密的数据的长度不是 AES 分块大小的倍数，调用 finish 会失败并显示 <code>ErrorCode::INVALID_INPUT_LENGTH</code>。</p>
<p><code>PaddingMode::PKCS7</code> 只能与 AES 密钥以及 ECB 和 CBC 模式配合使用。</p>
<p>此标记可重复使用。在调用 <a href="/security/keystore/implementer-ref#begin">begin</a> 时必须指定填充模式。
如果指定的模式未针对相应密钥获得授权，操作会失败并显示 <code>ErrorCode::INCOMPATIBLE_BLOCK_MODE</code>。</p>
<h2 id="purpose">Tag::PURPOSE</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？是</p>
<p>用于指定相应密钥可用于哪些目的。</p>
<p>可能的值是通过以下枚举定义的：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class KeyPurpose : uint32_t {
ENCRYPT = 0,
DECRYPT = 1,
SIGN = 2,
VERIFY = 3,
DERIVE_KEY = 4, // since 3.0
WRAP_KEY = 5, // since 3.0
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
</pre>
<p>此标记可重复使用。可以生成具有多个值的密钥，不过一项操作只有一个目的。当调用 <a href="/security/keystore/implementer-ref#begin">begin</a> 函数来启动某项操作时，要指定操作的目的。如果为操作指定的目的未通过相应密钥授权，操作会失败并显示 <code>ErrorCode::INCOMPATIBLE_PURPOSE</code>。</p>
<h2 id="reset_since_id_rotation">Tag::RESET_SINCE_ID_ROTATION</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定设备自上次唯一 ID 旋转以来是否恢复出厂设置。用于密钥认证。</p>
<p>此标记为布尔值，因此可能的值为 true（如果此标记存在）和 false（如果此标记不存在）。</p>
<h2 id="rollback_resistant">Tag::ROLLBACK_RESISTANT</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于表明密钥可抗回滚，也就是说，当通过 <a href="/security/keystore/implementer-ref#delete_key">deleteKey</a> 或 <a href="/security/keystore/implementer-ref#delete_all_keys">deleteAllKeys</a> 删除密钥后，可保证该密钥已被永久删除且无法再使用。如果密钥不带此标记，那么在被删除后，可能能够从备份中恢复。</p>
<p>此标记为布尔值，因此可能的值为 true（如果此标记存在）和 false（如果此标记不存在）。</p>
<h2 id="root_of_trust">Tag::ROOT_OF_TRUST</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定“信任根”，即经过验证的启动程序在验证操作系统是否已启动时使用的密钥（如果有）。<em></em>在任何情况下，都不可以通过密钥特性将此标记提供给 Keymaster，也不可以通过密钥特性从 Keymaster 返回此标记。</p>
<h2 id="rsa_public_exponent">Tag::RSA_PUBLIC_EXPONENT</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于为 RSA 密钥对指定公开指数的值。此标记仅与 RSA 密钥有关，而且是所有 RSA 密钥都必需的标记。</p>
<p>此标记的值是一个 64 位的未签名整数，并且符合 RSA 公开指数方面的要求。该值必须是质数。Trustlet 支持 2^16+1 这个值，并且可以支持其他合理的值，尤其是 3。如果未指定指数或指定的指数不受支持，密钥生成操作会失败并显示 <code>ErrorCode::INVALID_ARGUMENT</code>。</p>
<h2 id="unique_id">Tag::UNIQUE_ID</h2>
<p><strong>版本</strong>：3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于在认证时提供唯一 ID。</p>
<p>此标记的值是一个 Blob（任意长度的字节数数组）。</p>
<h2 id="usage_expire_datetime">Tag::USAGE_EXPIRE_DATETIME</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定相应密钥无法再用于验证和解密目的的过期日期和时间。在此之后，如果尝试使用向 <a href="/security/keystore/implementer-ref#begin">begin</a> 提供 <a href="#purpose">KeyPurpose::VERIFY</a> 或 <a href="#purpose">KeyPurpose::DECRYPT</a> 的密钥，操作都会失败并显示 <code>ErrorCode::KEY_EXPIRED</code>。</p>
<p>此标记的值是一个 64 位的整数，表示距 1970 年 1 月 1 日的毫秒数。</p>
<h2 id="user_auth_type">Tag::USER_AUTH_TYPE</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定可以使用哪些类型的用户身份验证程序来授权使用相应密钥。请求 Keymaster 执行所用密钥带有此标记的操作时，要为 Keymaster 提供一个身份验证令牌，并且该令牌的 <code>authenticator_type</code> 字段需与此标记中的值一致。例如，<code>(ntoh(token.authenticator_type) & auth_type_tag_value) != 0</code>，其中 <code>ntoh</code> 是一个函数，用于将按网络字节序保存的整数转换成按主机字节序保存的整数，<code>auth_type_tag_value</code> 是此标记的值。</p>
<p>此标记的值是以下枚举值的位掩码（32 位整数）：</p>
<strong>Keymaster 3</strong>
<pre class="devsite-click-to-copy">
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
</pre>
<strong>Keymaster 2 及更早版本</strong>
<pre class="devsite-click-to-copy">
typedef enum {
HW_AUTH_NONE = 0,
HW_AUTH_PASSWORD = 1 << 0,
HW_AUTH_FINGERPRINT = 1 << 1,
// Additional entries should be powers of 2.
HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;
</pre>
<h2 id="user_secure_id">Tag::USER_SECURE_ID</h2>
<p><strong>版本</strong>：1、2、3、4</p>
<p><strong>是否可重复使用</strong>？否</p>
<p>用于指定只能在某个安全的用户身份验证状态下使用相应密钥。此标记与 <a href="#no_auth_required">Tag::NO_AUTH_REQUIRED</a> 互斥。</p>
<p>此标记的值是一个 64 位的整数，用于指定在通过 <a href="#auth_token">Tag::AUTH_TOKEN</a> 向 <a href="/security/keystore/implementer-ref#begin">begin</a> 提供的身份验证令牌中必须存在哪个身份验证政策状态值，身份验证程序才会授权使用相应密钥。如果在调用 <a href="/security/keystore/implementer-ref#begin">begin</a> 时未提供身份验证令牌，或提供的身份验证令牌没有匹配的政策状态值，但所用密钥带有此标记，则该调用失败。</p>
<p>此标记可重复使用。如果提供的值中有任何一个与身份验证令牌中的任何政策状态值一致，身份验证程序即会授权使用相应密钥。否则，操作会失败并显示 <code>ErrorCode::KEY_USER_NOT_AUTHENTICATED</code>。</p>
<h2 id="vendor_patchlevel">Tag::VENDOR_PATCHLEVEL</h2>
<p><strong>版本</strong>：4</p>
<p>此标记用于指定可与秘钥配合使用的供应商映像安全补丁程序级别。该标记一定不会发送至 keymaster TA，而是由 TA 添加到由硬件强制执行的授权列表中。任何试图将秘钥与不同于当前运行的系统补丁程序级别的 <code>Tag::VENDOR_PATCHLEVEL</code> 配合使用的行为，一定会导致 <code>begin()</code>、<code>getKeyCharacteristics()</code> 或 <code>exportKey()</code> 返回 <code>ErrorCode::KEY_REQUIRES_UPGRADE</code>。如需了解详情，请参阅 <code>upgradeKey()</code>。
</p>
<p>该标记的值是形式为 YYYYMMDD 的整数，其中 YYYY 表示上次更新时间的四位数年份，MM 表示上次更新时间的两位数月份，DD 表示上次更新时间的两位数日期。例如，对于上次更新时间为 2018 年 6 月 5 日的 Android 设备上生成的密钥，其值将表示为 20180605。</p>
<p>IKeymasterDevice HAL 必须从系统属性 <code>ro.vendor.build.security_patch</code> 读取当前供应商补丁程序级别，并在 HAL 首次加载时将其传递给安全环境（相应机制是由实现定义的）。在下次启动完成前，安全环境不得接受其他补丁程序级别。
</p>
<p>
必须由硬件强制执行。
</p>
</body></html>
|
