blob: 9c8c619d2d44ca40262acc8919b46cee23027838 [file] [log] [blame]
Bert McMeendaa11372015-09-17 16:35:18 -07001page.title=Implementer's Reference
2@jd:body
3
4<!--
5 Copyright 2015 The Android Open Source Project
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18-->
19
20<p>This page provides details to assist implementers of <a href="keymaster.html">Keymaster</a> HALs. It
21covers each tag and each function in the API.</p>
22
23<h2 id=authorization_tags>Authorization tags</h2>
24
25<p>Except as noted in the tag descriptions, all of the tags below are used during
26key generation to specify key characteristics.</p>
27
28<h3 id=km_tag_purpose>KM_TAG_PURPOSE</h3>
29
30<p>Specifies the set of purposes for which the key may be used.</p>
31
32<p>Possible values are defined by the following enumeration:</p>
33
34<pre>
35typedef enum {
36 KM_PURPOSE_ENCRYPT = 0,
37 KM_PURPOSE_DECRYPT = 1,
38 KM_PURPOSE_SIGN = 2,
39 KM_PURPOSE_VERIFY = 3,
40} keymaster_purpose_t;
41</pre>
42
43<p>This tag is repeatable; keys may be generated with multiple values, although an
44operation has a single purpose. When the <a href="#begin">begin</a> function is called to
45start an operation, the purpose of the operation is
46specified. If the purpose specified to the operation is not authorized by the
47key, the operation must fail with <code>KM_ERROR_INCOMPATIBLE_PURPOSE</code>.</p>
48
49<h3 id=km_tag_algorithm>KM_TAG_ALGORITHM</h3>
50
51<p>Specifies the cryptographic algorithm with which the key is used.</p>
52
53<p>Possible values are defined by the following enumeration:</p>
54
55<pre>
56typedef enum {
57 KM_ALGORITHM_RSA = 1,
58 KM_ALGORITHM_EC = 3,
59 KM_ALGORITHM_AES = 32,
60 KM_ALGORITHM_HMAC = 128,
61} keymaster_algorithm_t;
62</pre>
63
64<p>This tag is not repeatable.</p>
65
66<h3 id=km_tag_key_size>KM_TAG_KEY_SIZE</h3>
67
68<p>Specifies the size, in bits, of the key, measuring in the normal way for the
69key's algorithm. For example, for RSA keys, <code>KM_TAG_KEY_SIZE</code> specifies
70the size of the public modulus. For AES keys it specifies the length
71of the secret key material.</p>
72
73<p>This tag is not repeatable.</p>
74
75<h3 id=km_tag_block_mode>KM_TAG_BLOCK_MODE</h3>
76
77<p>Specifies the block cipher mode(s) with which the key may be used. This tag is
78only relevant to AES keys.</p>
79
80<p>Possible values are defined by the following enumeration:</p>
81
82<pre>
83typedef enum {
84 KM_MODE_ECB = 1,
85 KM_MODE_CBC = 2,
86 KM_MODE_CTR = 3,
87 KM_MODE_GCM = 32,
88} keymaster_block_mode_t;
89</pre>
90
91<p>This tag is repeatable, and for AES key operations a mode must be specified in
92the <code>additional_params</code> argument of <a href="#begin">begin</a>. If the specified
93mode is not in the modes associated with the key, the
94operation must fail with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
95
96<h3 id=km_tag_digest>KM_TAG_DIGEST</h3>
97
98<p>Specifies the digest algorithms which may be used with the key to perform
99signing and verification operations. This tag is relevant to RSA, ECDSA and
100HMAC keys.</p>
101
102<p>Possible values are defined by the following enumeration:</p>
103
104<pre>
105typedef enum {
106 KM_DIGEST_NONE = 0,
107 KM_DIGEST_MD5 = 1,
108 KM_DIGEST_SHA1 = 2,
109 KM_DIGEST_SHA_2_224 = 3,
110 KM_DIGEST_SHA_2_256 = 4,
111 KM_DIGEST_SHA_2_384 = 5,
112 KM_DIGEST_SHA_2_512 = 6,
113}
114keymaster_digest_t;
115</pre>
116
117<p>This tag is repeatable. For signing and verification operations a digest must
118be specified in the <code>additional_params</code> argument of <a href="#begin">begin</a>.
119If the specified digest is not in the digests associated with the key, the
120operation must fail with <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.</p>
121
122<h3 id=km_tag_padding>KM_TAG_PADDING</h3>
123
124<p>Specifies the padding modes which may be used with the key. This tag is
125relevant to RSA and AES keys.</p>
126
127<p>Possible values are defined by the following enumeration:</p>
128
129<pre>
130typedef enum {
131 KM_PAD_NONE = 1,
132 KM_PAD_RSA_OAEP = 2,
133 KM_PAD_RSA_PSS = 3,
134 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
135 KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
136 KM_PAD_PKCS7 = 64,
137} keymaster_padding_t;
138</pre>
139
140<p><code>KM_PAD_RSA_OAEP</code> and <code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code> are used
141only for RSA encryption/decryption keys and specify RSA PKCS#1v2 OAEP
142padding and RSA PKCS#1 v1.5 randomized padding, respectively. <code>KM_PAD_RSA_PSS</code> and
143<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> are used only for RSA signing/verification keys and
144specify RSA PKCS#1v2 PSS
145padding and RSA PKCS#1 v1.5 deterministic padding, respectively. Note also that
146the RSA PSS padding mode is incompatible with <a href="#km_tag_digest">KM_DIGEST_NONE</a>.</p>
147
148<p><code>KM_PAD_NONE</code> may be used with either RSA or AES keys. For AES keys,
149if <code>KM_PAD_NONE</code> is used with block mode ECB or CBC and the data to be encrypted
150or decrypted
151is not a multiple of the AES block size in length, the call to finish must fail
152with <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
153
154<p><code>KM_PAD_PKCS7</code> may only be used with AES keys, and only with ECB and CBC modes.</p>
155
156<p>This tag is repeatable. A padding mode must be specified in the call to
157<a href="#begin">begin</a>. If the specified mode is not authorized for the key,
158the operation must fail
159with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
160
161<h3 id=km_tag_caller_nonce>KM_TAG_CALLER_NONCE</h3>
162
163<p>Specifies that the caller is allowed to provide a nonce for nonce-requiring
164operations.</p>
165
166<p>This tag is boolean, so the possible values are true (if the tag is present)
167and false (if the tag is not present).</p>
168
169<p>This tag is used only for AES keys, and is only relevant for CBC, CTR and GCM
170block modes. If the tag is not present, implementations should reject any
171operation which provides <a href="#km_tag_nonce">KM_TAG_NONCE</a> to <a href="#begin">begin</a>
172with <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>.</p>
173
174<p>This tag is not repeatable.</p>
175
176<h3 id=km_tag_min_mac_length>KM_TAG_MIN_MAC_LENGTH</h3>
177
178<p>Required for HMAC keys and AES keys that support GCM mode, this tag specifies
179the minimum length of MAC that can be requested or verified with this key.</p>
180
181<p>This value is the minimum MAC length, in bits. It must be a multiple of 8. For
182HMAC keys, the value must be at least 64. For GCM keys it must be at least 96
183and must not exceed 128.</p>
184
185<h3 id=km_tag_rsa_public_exponent>KM_TAG_RSA_PUBLIC_EXPONENT</h3>
186
187<p>Specifies the value of the public exponent for an RSA key pair. This tag is
188relevant only to RSA keys, and required for all RSA keys.</p>
189
190<p>The value is a 64-bit unsigned integer that must satisfy the requirements of an
191RSA public exponent. Because it is specified by the caller and therefore cannot
192be chosen by the implementation, it must be a prime number. Trustlets are
193required to support the value 2^16+1. It is recommended that other reasonable
194values be supported, in particular the value 3. If no exponent is specified or
195if the specified exponent is not supported, key generation must fail
196with <code>KM_ERROR_INVALID_ARGUMENT</code>.</p>
197
198<p>This tag is not repeatable.</p>
199
200<h3 id=km_tag_blob_usage_requirements>KM_TAG_BLOB_USAGE_REQUIREMENTS</h3>
201
202<p>Specifies the system environment conditions which must hold for the generated
203key to be used.</p>
204
205<p>Possible values are defined by the following enumeration:</p>
206
207<pre>
208typedef enum {
209 KM_BLOB_STANDALONE = 0,
210 KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
211} keymaster_key_blob_usage_requirements_t;
212</pre>
213
214<p>This tag may be specified during key generation to require that the key be
215usable in the specified condition, and must be returned with the key
216characteristics (from <a href="#generate_key">generate_key</a> and
217<a href="#get_key_characteristics">get_key_characteristics</a>). If
218the caller specifies <code>KM_TAG_BLOB_USAGE_REQUIREMENTS</code> with
219value <code>KM_BLOB_STANDALONE</code> the trustlet must return a key blob
220which can be used without file system
221support. This is critical for devices with encrypted disks, where the file
222system may not be available until after a Keymaster key is used to decrypt the
223disk.</p>
224
225<p>This tag is not repeatable.</p>
226
227<h3 id=km_tag_bootloader_only>KM_TAG_BOOTLOADER_ONLY</h3>
228
229<p>Specifies that the key may only be used by the bootloader.</p>
230
231<p>This tag is boolean, so the possible values are true (if the tag is present)
232and false (if the tag is not present).</p>
233
234<p>Any attempt to use a key with <code>KM_TAG_BOOTLOADER_ONLY</code> from the
235Android system must fail with <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
236
237<p>This tag is not repeatable.</p>
238
239<h3 id=km_tag_active_datetime>KM_TAG_ACTIVE_DATETIME</h3>
240
241<p>Specifies the date and time at which the key becomes active. Prior to this
242time, any attempt to use the key must fail with <code>KM_ERROR_KEY_NOT_YET_VALID</code>.</p>
243
244<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
245
246<p>This tag is not repeatable.</p>
247
248<h3 id=km_tag_origination_expire_datetime>KM_TAG_ORIGINATION_EXPIRE_DATETIME</h3>
249
250<p>Specifies the date and time at which the key expires for signing and encryption
251purposes. After this time, any attempt to use a key
252with <a href="#km_tag_purpose">KM_PURPOSE_SIGN</a> or
253<a href="#km_tag_purpose">KM_PURPOSE_ENCRYPT</a> provided
254to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
255
256<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
257
258<p>This tag is not repeatable.</p>
259
260<h3 id=km_tag_usage_expire_datetime>KM_TAG_USAGE_EXPIRE_DATETIME</h3>
261
262<p>Specifies the date and time at which the key expires for verification and
263decryption purposes. After this time, any attempt to use a key with
264<a href="#km_tag_purpose">KM_PURPOSE_VERIFY</a> or <a href="#km_tag_purpose">KM_PURPOSE DECRYPT</a>
265provided to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
266
267<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
268
269<p>This tag is not repeatable.</p>
270
271<h3 id=km_tag_min_seconds_between_ops>KM_TAG_MIN_SECONDS_BETWEEN_OPS</h3>
272
273<p>Specifies the minimum amount of time that must elapse between allowed
274operations using a key. This can be used to rate-limit uses of keys in contexts
275where unlimited use may enable brute force attacks.</p>
276
277<p>The value is a 32-bit integer representing seconds between allowed operations.</p>
278
279<p>When a key with this tag is used in an operation, a timer should be started
280during the <a href="#finish">finish</a> or <a href="#abort">abort</a> call. Any
281call to <a href="#begin">begin</a> that is received before the timer indicates
282that the interval specified by <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> has
283elapsed must fail with <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. This
284requirement implies that a trustlet must keep a table of timers for keys
285with this tag. Because Keymaster memory is often limited, it is acceptable for
286this table to have a fixed maximum size and for Keymaster to fail operations
287which attempt to use keys with this tag when the table is full. At least 32
288in-use keys must be accommodated, and table slots must be aggressively reused
289when key minimum-usage intervals expire. If an operation fails because the
290table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
291
292<p>This tag is not repeatable.</p>
293
294<h3 id=km_tag_max_uses_per_boot>KM_TAG_MAX_USES_PER_BOOT</h3>
295
296<p>Specifies the maximum number of times that a key may be used between system
297reboots. This is another mechanism to rate-limit key use.</p>
298
299<p>The value is a 32-bit integer representing uses per boot.</p>
300
301<p>When a key with this tag is used in an operation, a key-associated counter
302should be incremented during the <a href="#begin">begin</a> call. After the key counter
303has exceeded this value, all subsequent attempts
304to use the key must fail with <code>KM_ERROR_MAX_OPS_EXCEEDED</code>, until the device is
305restarted. This requirement implies that a trustlet must
306keep a table of use counters for keys with this tag. Because Keymaster memory
307is often limited, it is acceptable for this table to have a fixed maximum size
308and for Keymaster to fail operations that attempt to use keys with this tag
309when the table is full. At least 16 keys must be accommodated. If an operation
310fails because the table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
311
312<p>This tag is not repeatable.</p>
313
314<h3 id=km_tag_user_secure_id>KM_TAG_USER_SECURE_ID</h3>
315
316<p>Specifies that a key may only be used under a particular secure user
317authentication state. This tag is mutually exclusive
318with <a href="#km_tag_no_auth_required">KM_TAG_NO_AUTH_REQUIRED</a>.</p>
319
320<p>The value is a 64-bit integer specifying the authentication policy state value
321which must be present in an authentication token (provided to <a href="#begin">begin</a> with
322the <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a>) to authorize use of the key. Any
323call to <a href="#begin">begin</a> with a key with this tag that does not provide an
324authentication token, or provides an
325authentication token without a matching policy state value, must fail.</p>
326
327<p>This tag is repeatable. If any of the provided values matches any policy state
328value in the authentication token, the key is authorized for use. Otherwise the operation
329must fail with <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
330
331<h3 id=km_tag_no_auth_required>KM_TAG_NO_AUTH_REQUIRED</h3>
332
333<p>Specifies that no authentication is required to use this key. This tag is
334mutually exclusive with <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>.</p>
335
336<p>This tag is boolean, so the possible values are true (if the tag is present)
337and false (if the tag is not present).</p>
338
339<p>This tag is not repeatable.</p>
340
341<h3 id=km_tag_user_auth_type>KM_TAG_USER_AUTH_TYPE</h3>
342
343<p>Specifies the types of user authenticators that may be used to authorize this
344key.</p>
345
346<p>The value is a 32-bit integer bitmask of values from the enumeration:</p>
347
348<pre>
349typedef enum {
350 HW_AUTH_NONE = 0,
351 HW_AUTH_PASSWORD = 1 &lt;&lt; 0,
352 HW_AUTH_FINGERPRINT = 1 &lt;&lt; 1,
353 // Additional entries should be powers of 2.
354 HW_AUTH_ANY = UINT32_MAX,
355} hw_authenticator_type_t;
356</pre>
357
358<p>This tag is not repeatable.</p>
359
360<h3 id=km_tag_auth_timeout>KM_TAG_AUTH_TIMEOUT</h3>
361
362<p>Specifies the time in seconds for which the key is authorized for use, after
363authentication. If <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is present and this tag
364is not, then the key requires authentication for every
365usage (see <a href="#begin">begin</a> for the details of the authentication-per-operation flow).</p>
366
367<p>The value is a 32-bit integer specifying the time in seconds after a successful
368authentication of the user specified by <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> with
369the authentication method specified
370by <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> that the key can be used.</p>
371
372<p>This tag is not repeatable.</p>
373
374<h3 id=km_tag_all_applications>KM_TAG_ALL_APPLICATIONS</h3>
375
376<p>Reserved for future use.</p>
377
378<p>This tag is not repeatable.</p>
379
380<h3 id=km_tag_application_id>KM_TAG_APPLICATION_ID</h3>
381
382<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
383this tag specifies data that must be provided during all uses of the key. In
384particular, calls to <a href="#export_key">export_key</a> and
385<a href="#get_key_characteristics">get_key_characteristics</a> must
386provide the same value in the <code>client_id</code> parameter, and
387calls to <a href="#begin">begin</a> must provide this tag and the
388same associated data as part of the <code>in_params</code> set. If the correct
389data is not provided the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
390
391<p>The value is a blob, an arbitrary-length array of bytes.</p>
392
393<p>This tag is not repeatable.</p>
394
395<h3 id=km_tag_application_data>KM_TAG_APPLICATION_DATA</h3>
396
397<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
398this tag specifies data that must be provided during all uses of the key. In
399particular, calls to <a href="#export_key">export_key</a> and
400<a href="#get_key_characteristics">get_key_characteristics</a> must
401provide the same value to the <code>client_id</code> parameter, and calls
402to <a href="#begin">begin</a> must provide this tag and the same associated
403data as part of the <code>in_params</code> set. If the correct data is not
404provided, the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
405
406<p>This tag is not repeatable.</p>
407
408<h3 id=km_tag_creation_datetime>KM_TAG_CREATION_DATETIME</h3>
409
410<p>Specifies the date and time the key was created, in milliseconds since January
4111, 1970. This tag is optional and informational only.</p>
412
413<p>This tag is not repeatable.</p>
414
415<h3 id=km_tag_origin>KM_TAG_ORIGIN</h3>
416
417<p>Specifies where the key was created, if known. This tag may not be specified
418during key generation or import, and must be added to the key characteristics
419by the trustlet.</p>
420
421<p>The possible values are defined in <code>keymaster_origin_t</code>:</p>
422
423<pre>
424typedef enum {
425 KM_ORIGIN_GENERATED = 0,
426 KM_ORIGIN_IMPORTED = 2,
427 KM_ORIGIN_UNKNOWN = 3,
428} keymaster_key_origin_t
429</pre>
430
431<p>The full meaning of the value depends not only on the value but on whether it's
432found in the hardware-enforced or software-enforced characteristics list.</p>
433
434<p><code>KM_ORIGIN_GENERATED</code> indicates that Keymaster generated the key.
435If in the hardware-enforced list,
436the key was generated in secure hardware and is permanently hardware-bound. If
437in the software-enforced list, the key was generated in SoftKeymaster and is
438not hardware-bound.</p>
439
440<p><code>KM_ORIGIN_IMPORTED</code> indicates that the key was generated outside
441of Keymaster and imported into
442Keymaster. If in the hardware-enforced list, it is permanently hardware-bound,
443although copies outside of secure hardware may exist. If in the
444software-enforces list, the key was imported into SoftKeymaster and is not
445hardware-bound.</p>
446
447<p><code>KM_ORIGIN_UNKNOWN</code> should only appear in the hardware-enforced list.
448It indicates that the key is
449hardware-bound, but it is not known whether the key was originally generated in
450secure hardware or was imported. This only occurs when keymaster0 hardware is
451being used to emulate keymaster1 services.</p>
452
453<p>This tag is not repeatable.</p>
454
455<h3 id=km_tag_rollback_resistant>KM_TAG_ROLLBACK_RESISTANT</h3>
456
457<p>Indicates that the key is rollback-resistant, meaning that when deleted
458by <a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
459the key is guaranteed to be permanently deleted and unusable. It's possible
460that keys without this tag could be deleted and then restored from backup.</p>
461
462<p>This tag is boolean, so the possible values are true (if the tag is present)
463and false (if the tag is not present).</p>
464
465<p>This tag is not repeatable.</p>
466
467<h3 id=km_tag_root_of_trust>KM_TAG_ROOT_OF_TRUST</h3>
468
469<p>Specifies the "root of trust," the key used by verified boot to validate the
470operating system booted (if any). This tag is never provided to or returned
471from Keymaster in the key characteristics.</p>
472
473<h3 id=km_tag_associated_data>KM_TAG_ASSOCIATED_DATA</h3>
474
475<p>Provides "associated data" for AES-GCM encryption or decryption. This tag is
476provided to <a href="#update">update</a> and specifies data that is not
477encrypted/decrypted but is used in computing
478the GCM tag.</p>
479
480<p>The value is a blob, an arbitrary-length array of bytes.</p>
481
482<p>This tag is not repeatable.</p>
483
484<h3 id=km_tag_nonce>KM_TAG_NONCE</h3>
485
486<p>Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC or
487CTR encryption or decryption. This tag is provided to <a href="#begin">begin</a>
488during encryption and decryption operations. It may only be provided to <a href="#begin">begin</a>
489if the key has <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>. If not provided,
490an appropriate nonce or IV will be randomly generated by
491Keymaster and returned from begin.</p>
492
493<p>The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend
494on the mode: GCM nonces are 12 bytes in length; CBC and CTR IVs are 16 bytes in
495length.</p>
496
497<p>This tag is not repeatable.</p>
498
499<h3 id=km_tag_auth_token>KM_TAG_AUTH_TOKEN</h3>
500
501<p>Provides an authentication token (see the Authentication page) to
502<a href="#begin">begin</a>, <a href="#update">update</a> or <a href="#finish">finish</a>,
503to prove user authentication for a key operation that requires
504it (key has <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>).</p>
505
506<p>The value is a blob which contains a <code>hw_auth_token_t</code> structure.</p>
507
508<p>This tag is not repeatable.</p>
509
510<h3 id=km_tag_mac_length>KM_TAG_MAC_LENGTH</h3>
511
512<p>Provides the requested length of a MAC or GCM authentication tag, in bits.</p>
513
514<p>The value is the MAC length in bits. It must be a multiple of 8 and must be at
515least as large as the value of <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
516associated with the key.</p>
517
518<h2 id=functions>Functions</h2>
519
520<h3 id=deprecated_functions>Deprecated functions</h3>
521
522<p>The following functions are in the <code>keymaster1_device_t</code> definition but
523should not be implemented. The function pointers should be set
524to <code>NULL</code>:</p>
525
526<ul>
527 <li><code>generate_keypair</code>
528 <li><code>import_keypair</code>
529 <li><code>get_keypair_public</code>
530 <li><code>delete_keypair</code>
531 <li><code>delete_all</code>
532 <li><code>sign_data</code>
533 <li><code>verify_data</code>
534</ul>
535
536<h3 id=general_implementation_guidelines>General implementation guidelines</h3>
537
538<p>The following guidelines apply to all functions in the API.</p>
539
540<h4 id=input_pointer_parameters>Input pointer parameters</h4>
541
542<p>Input pointer parameters that are not used for a given call may be <code>NULL</code>.
543The caller is not required to provide placeholders. For example, some key
544types and modes may not use any values from the <code>in_params</code> argument
545to <a href="#begin">begin</a>, so the caller may set <code>in_params</code>
546to <code>NULL</code> or provide an empty parameter set. It is also acceptable for the caller to
547provide unused parameters, and Keymaster methods should not issue errors.</p>
548
549<p>If a required input parameter is NULL, Keymaster methods should return
550<code>KM_ERROR_UNEXPECTED_NULL_POINTER</code>.</p>
551
552<h4 id=output_pointer_parameters>Output pointer parameters</h4>
553
554<p>Similar to input pointer parameters, unused output pointer parameters
555may be <code>NULL</code>. If a method needs to return data in an output
556parameter found to be <code>NULL</code>, it should return <code>KM_ERROR_OUTPUT_PARAMETER_NULL</code>.</p>
557
558<h4 id=api_misuse>API misuse</h4>
559
560<p>There are many ways that callers can make requests that don't make sense or are
561foolish but not technically wrong. Keymaster1 implementations are not required
562to fail in such cases or issue a diagnostic. Use of too-small keys,
563specification of irrelevant input parameters, reuse of IVs or nonces,
564generation of keys with no purposes (hence useless) and the like should not be
565diagnosed by implementations. Omission of required parameters, specification of
566invalid required parameters, and similar errors must be diagnosed.</p>
567
568<p>It is the responsibility of apps, the framework, and Android keystore to ensure
569that the calls to Keymaster modules are sensible and useful.</p>
570
571<h3 id=get_supported_algorithms>get_supported_algorithms</h3>
572
573<p>Returns the list of algorithms supported by the Keymaster hardware
574implementation. A software implementation must return an empty list; a hybrid
575implementation must return a list containing only the algorithms that are
576supported by hardware.</p>
577
578<p>Keymaster1 implementations must support RSA, EC, AES and HMAC.</p>
579
580<h3 id=get_supported_block_modes>get_supported_block_modes</h3>
581
582<p>Returns the list of AES block modes supported by the Keymaster hardware
583implementation for a specified algorithm and purpose.</p>
584
585<p>For RSA, EC and HMAC, which are not block ciphers, the method must return an
586empty list for all valid purposes. Invalid purposes should cause the method to
587return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
588
589<p>Keymaster1 implementations must support ECB, CBC, CTR and GCM for AES
590encryption and decryption.</p>
591
592<h3 id=get_supported_padding_modes>get_supported_padding_modes</h3>
593
594<p>Returns the list of padding modes supported by the Keymaster hardware
595implementation for a specified algorithm and purpose.</p>
596
597<p>HMAC and EC have no notion of padding so the method must return an empty list
598for all valid purposes. Invalid purposes should cause the method to return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
599
600<p>For RSA, keymaster1 implementations must support:</p>
601
602<ul>
603 <li>Unpadded encryption, decryption, signing and verification. For unpadded
604encryption and signing, if the message is shorter than the public modulus,
605implementations must left-pad it with zeros. For unpadded decryption and
606verification, the input length must match the public modulus size.
607 <li>PKCS#1 v1.5 encryption and signing padding modes
608 <li>PSS with a minimum salt length of 20
609 <li>OAEP
610</ul>
611
612<p>For AES in ECB and CBC modes, keymaster1 implementations must support no
613padding and PKCS#7-padding. CTR and GCM modes must support only no padding.</p>
614
615<h3 id=get_supported_digests>get_supported_digests</h3>
616
617<p>Returns the list of digest modes supported by the Keymaster hardware
618implementation for a specified algorithm and purpose.</p>
619
620<p>No AES modes support or require digesting, so the method must return an empty
621list for valid purposes.</p>
622
623<p>Keymaster1 implementations are allowed to implement a subset of the defined
624digests, but must provide SHA-256. It is strongly recommended that keymaster1
625implementations provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the
626full set of defined digests).</p>
627
628<h3 id=get_supported_import_formats>get_supported_import_formats</h3>
629
630<p>Returns the list of import formats supported by the Keymaster hardware
631implementation of a specified algorithm.</p>
632
633<p>Keymaster1 implementations must support the PKCS#8 format (without password
634protection) for importing RSA and EC key pairs, and must support RAW import of
635AES and HMAC key material.</p>
636
637<h3 id=get_supported_export_formats>get_supported_export_formats</h3>
638
639<p>Returns the list of export formats supported by the Keymaster hardware
640implementation of a specified algorithm.</p>
641
642<p>Keymaster1 implementations must support the X.509 format for exporting RSA and
643EC public keys. Export of private keys or asymmetric keys must not be
644supported.</p>
645
646<h3 id=add_rng_entropy>add_rng_entropy</h3>
647
648<p>Adds caller-provided entropy to the pool used by the Keymaster1 implementation
649for generating random numbers, for keys, IVs, etc.</p>
650
651<p>Keymaster1 implementations must <strong>securely</strong> mix the provided
652entropy into their pool, which must also contain
653internally-generated entropy from a hardware random number generator. Mixing
654must have the property that an attacker with complete control of either
655the <code>add_rng_entropy</code>-provided bits or the hardware-generated bits, but not both, cannot predict
656bits generated from the entropy pool with probability greater than ½.</p>
657
658<p>Keymaster1 implementations that attempt to estimate the entropy in their
659internal pool must assume that data provided by <code>add_rng_entropy</code> contains no entropy.</p>
660
661<h3 id=generate_key>generate_key</h3>
662
663<p>Generates a new cryptographic key, specifying associated authorizations, which
664will be permanently bound to the key. Keymaster1 implementations must make it
665impossible to use a key in any way inconsistent with the authorizations
666specified at generation time. With respect to authorizations that the secure
667hardware cannot enforce, the secure hardware's obligation is limited to
668ensuring that the unenforceable authorizations associated with the key cannot
669be modified, so that every call to <a href="#get_key_characteristics">get_key_characteristics</a>
670will return the original value. In addition, the characteristics returned by <code>generate_key</code>
671must allocate authorizations correctly between the hardware-enforced and
672software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
673for more details.</p>
674
675<p>The parameters that must be provided to <code>generate_key</code> depend on the type of key
676being generated. This section will summarize the
677required and allowed tags for each type of key. <a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>
678is always required, to specify the type.</p>
679
680<h4 id=rsa_keys>RSA keys</h4>
681
682<p>The following parameters are required when generating an RSA key.</p>
683
684<ul>
685 <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the size of the public
686 modulus, in bits. If omitted, the method must
687return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>. Values that must be supported are
6881024, 2048, 3072 and 4096. It is
689recommended to support all key sizes that are a multiple of 8.
690 <li><a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> specifies
691 the RSA public exponent value. If omitted, the method must
692 return <code>KM_ERROR_INVALID_ARGUMENT</code>.
693 Implementations must support the values 3 and 65537. It is recommended to
694support all prime values up to 2^64.
695</ul>
696
697<p>The following parameters are not required to generate an RSA key, but creating
698an RSA key without them will produce a key that is unusable.
699The <code>generate_key</code> function should not return an error if these parameters are omitted.</p>
700
701<ul>
702 <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> specifies allowed purposes.
703 All purposes must be supported for RSA keys, in
704any combination.
705 <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies digest algorithms that
706 may be used with the new key. Implementations
707that do not support all digest algorithms must accept key generation requests
708that include unsupported digests. The unsupported digests should be placed in
709the "software-enforced" list in the returned key characteristics. This is
710because the key will be usable with those other digests, but digesting will be
711performed in software. Then hardware will be called to perform the operation
712with <code>KM_DIGEST_NONE</code>.
713 <li><a href="#km_tag_padding">KM_TAG_PADDING</a> specifies the padding modes
714 that may be used with the new key. Implementations
715that do not support all digest algorithms must place <code>KM_PAD_RSA_PSS</code>
716and <code>KM_PAD_RSA_OAEP</code> in the software-enforced list of the key
717characteristics if any unsupported
718digest algorithms are specified.
719</ul>
720
721<h4 id=ecdsa_keys>ECDSA keys</h4>
722
723<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required to generate an
724ECDSA key. It is used to select the EC group.
725Implementations must support values 224, 256, 384 and 521, which indicate the
726NIST p-224, p-256, p-384 and p521 curves, respectively.</p>
727
728<p><a href="#km_tag_digest">KM_TAG_DIGEST</a> is also needed for a useful ECDSA key,
729but is not required for generation.</p>
730
731<h4 id=aes_keys>AES keys</h4>
732
733<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required when
734generating an AES key. If omitted, the method must return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>.
735Values that must be supported are 128 and 256. It is recommended to support
736192-bit AES keys.</p>
737
738<p>The following parameters are particularly relevant for AES keys, but not
739required to generate one:</p>
740
741<ul>
742 <li><code>KM_TAG_BLOCK_MODE</code> specifies the block modes with which the new key may be used.
743 <li><code>KM_TAG_PADDING</code> specifies the padding modes that may be used. This is only relevant for ECB
744and CBC modes.
745</ul>
746
747<p>If the GCM block mode is specified, then <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
748must be provided. If omitted, the method must return
749<code>KM_ERROR_MISSING_MIN_MAC_LENGTH</code>. The value of the tag must be a multiple of 8 and must
750be at least 96 and no more than 128.</p>
751
752<h4 id=hmac_keys>HMAC keys</h4>
753
754<p>The following parameters are required for HMAC key generation:</p>
755
756<ul>
757 <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the key size in bits. Values
758 smaller than 64 and values that are not
759multiples of 8 must not be supported. All multiples of 8, from 64 to 512, must
760be supported. Larger values may be supported.
761 <li><a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a> specifies the minimum length of
762 MACs that can be generated or verified with
763this key. The value must be a multiple of 8 and must be at least 64.
764 <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies the digest algorithm for the key. Exactly
765 one digest must be
766specified, otherwise return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>. If the digest is not supported
767by the trustlet, return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.
768</ul>
769
770<h4 id=key_characteristics>Key characteristics</h4>
771
772<p>If the characteristics argument is non-NULL, <code>generate_key</code> must return the newly-generated
773key's characteristics divided appropriately
774into hardware-enforced and software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
775for a description of which characteristics go in which list. The returned
776characteristics must include all of the parameters specified to key generation,
777except <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> and
778<a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>.
779If these tags were included in the key parameters, they must be removed from
780the returned characteristics; it must not be possible to find their values by
781examining the returned key blob. However, they must be cryptographically bound
782to the key blob, so that if the correct values are not provided when the key is
783used, usage will fail. Similarly, <a href="#km_tag_root_of_trust">KM_TAG_ROOT_OF_TRUST</a> must
784be cryptographically bound to the key, but it may not be specified during
785key creation or import and must never be returned.</p>
786
787<p>In addition to the provided tags, the trustlet must also
788add <a href="#km_tag_origin">KM_TAG_ORIGIN</a>, with the value <code>KM_ORIGIN_GENERATED</code>,
789and if the key is rollback resistant, <a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a>.</p>
790
791<h4 id=rollback_resistance>Rollback resistance </h4>
792
793<p>Rollback resistance means that once a key is deleted with
794<a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
795it is guaranteed by secure hardware never to be usable again. Implementations
796without rollback resistance will typically return generated or imported key
797material to the caller as a key blob, an encrypted and authenticated form. When
798keystore deletes the key blob, the key is gone, but an attacker who has
799previously managed to retrieve the key material can potentially restore it to
800the device.</p>
801
802<p>A key is rollback resistant if the secure hardware guarantees that deleted keys
803cannot be restored later. This is generally done by storing additional key
804metadata in a trusted location that cannot be manipulated by an attacker. On
805mobile devices, the mechanism used for this is usually Replay Protected Memory
806Blocks (RPMB). Because the number of keys that may be created is essentially
807unbounded and the trusted storage used for rollback resistance may be limited
808in size, it is required that this method succeed even if rollback resistance
809cannot be provided for the new key. In that case,
810<a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a> should not be
811added to the key characteristics.</p>
812
813<h3 id=get_key_characteristics>get_key_characteristics</h3>
814
815<p>Returns parameters and authorizations associated with the provided key, divided
816into two sets: hardware-enforced and software-enforced. The description here
817applies equally to the key characteristics lists returned
818by <a href="#generate_key">generate_key</a> and <a href="#import_key">import_key</a>.</p>
819
820<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation
821or import, the same value must provided to
822this method in the <code>client_id</code> argument. Otherwise, the
823method must return <code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly,
824if <code>KM_TAG_APPLICATION_DATA </code>was provided during generation
825or import, the same value must be provided to
826this method in the <code>app_data</code> argument.</p>
827
828<p>The characteristics returned by this method completely describe the type and
829usage of the specified key.</p>
830
831<p>The general rule for deciding whether a given tag belongs in the
832hardware-enforced or software-enforced list is that if the meaning of the tag
833is fully assured by secure hardware, it is hardware-enforced. Otherwise, it's
834software enforced. Below is a list of specific tags whose correct allocation
835may be unclear:</p>
836
837<ul>
838 <li><a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>, <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a>,
839 and <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> are
840 intrinsic properties of the key. For any key that is secured by hardware,
841these will be in the hardware-enforced list, because the statement that, for
842example, "This RSA key material is only used as an RSA key" is enforced by
843hardware because the hardware will use it in no other way and software has no
844access to the key material and cannot use it at all.
845 <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> values that are supported by the
846 secure hardware are to be placed in the
847hardware-supported list. Unsupported digests go in the software-supported list.
848 <li><a href="#km_tag_padding">KM_TAG_PADDING</a> values generally go in the
849 hardware-supported list, but if there is a
850possibility that a specific padding mode may have to be performed by software,
851they go in the software-enforced list. Such a possibility arises for RSA keys
852that permit PSS or OAEP padding with digest algorithms that are not supported
853by the secure hardware.
854 <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> and
855 <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> are hardware-enforced
856 only if user authentication is hardware enforced. For
857that to be true, the Keymaster trustlet and the relevant authentication
858trustlet must both be secure and must share a secret HMAC key used to sign and
859validate authentication tokens. See the Authentication page for details.
860 <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a>,
861 <a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a>,
862 and <a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> tags
863 require access to a verifiably correct wall clock. Most secure hardware
864will only have access to time information provided by the non-secure OS, which
865means the tags are software-enforced.
866 <li><a href="#km_tag_origin">KM_TAG_ORIGIN</a> is always in the hardware list for
867 hardware-bound keys. Its presence in that
868list is the way higher layers determine that a key is hardware-backed.
869</ul>
870
871<h3 id=import_key>import_key</h3>
872
873<p>Imports key material into Keymaster hardware. Key definition parameters and
874output characteristics are handled the same as for <code>generate_key</code>,
875with the following exceptions:</p>
876
877<ul>
878 <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> and
879 <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> (for RSA keys only)
880 are not required in the input parameters. If not provided,
881the trustlet must deduce the values from the provided key material and add
882appropriate tags and values to the key characteristics. If the parameters are
883provided, the trustlet must validate them against the key material. In the
884event of a mismatch, the method must return <code>KM_ERROR_IMPORT_PARAMETER_MISMATCH</code>.
885 <li>The returned <a href="#km_tag_origin">KM_TAG_ORIGIN</a> must have the
886 value <code>KM_ORIGIN_IMPORTED</code>.
887</ul>
888
889<h3 id=export_key>export_key</h3>
890
891<p>Exports a public key from a Keymaster RSA or EC key pair.</p>
892
893<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation or import,
894the same value must provided to
895this method in the <code>client_id</code> argument. Otherwise, the method must return
896<code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly, if <code>KM_TAG_APPLICATION_DATA</code>
897was provided during generation or import, the same value must be provided to
898this method in the <code>app_data</code> argument.</p>
899
900<h3 id=delete_key>delete_key</h3>
901
902<p>Deletes the provided key. This method is optional, and will likely be
903implemented only by Keymaster modules that provide rollback resistance.</p>
904
905<h3 id=delete_all_keys>delete_all_keys</h3>
906
907<p>Deletes all keys. This method is optional, and will likely be implemented only
908by Keymaster modules that provide rollback resistance.</p>
909
910<h3 id=begin>begin</h3>
911
912<p>Begins a cryptographic operation, using the specified key, for the specified
913purpose, with the specified parameters (as appropriate), and returns an
914operation handle which is used with <a href="#update">update</a> and <a href="#finish">finish</a> to complete the operation.</p>
915
916<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>
917were specified during key generation or import, calls to begin must include
918those tags with the originally-specified values in the <code>in_params</code> argument to this method.</p>
919
920<h4 id=authorization_enforcement>Authorization enforcement</h4>
921
922<p>During this method, the following key authorizations must be enforced by the
923trustlet if the implementation placed them in the "hardware-enforced"
924characteristics and if the operation is not a public key operation. Public key
925operations, meaning <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>,
926with RSA or EC keys, must be allowed to succeed even if authorization
927requirements are not met.</p>
928
929<ul>
930 <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> requires that the purpose specified
931 for this method match one of the purposes
932in the key authorizations, unless the requested operation is a public key
933operation, meaning that the key is RSA or EC and the purpose is <code>KM_PURPOSE_ENCRYPT</code>
934or <code>KM_PURPOSE_VERIFY</code>. Note that <code>KM_PURPOSE_ENCRYPT</code> is not valid for EC keys.
935Begin should return <code>KM_ERROR_UNSUPPORTED_PURPOSE</code> in that case.
936 <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a> requires comparison with a trusted
937 UTC time source. If the current date and
938time is prior to the tag value, the method must return <code>KM_ERROR_KEY_NOT_YET_VALID</code>.
939 <li><a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a> requires
940 comparison with a trusted UTC time source. If the current date and
941time is later than the tag value and the purpose is <code>KM_PURPOSE_ENCRYPT</code> or <code>KM_PURPOSE_SIGN</code>,
942the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
943 <li><a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> requires comparison with a
944 trusted UTC time source. If the current date and
945time is later than the tag value and the purpose is <code>KM_PURPOSE_DECRYPT</code> or <code>KM_PURPOSE_VERIFY</code>,
946the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
947 <li><a href="#km_tag_min_seconds_between_ops">KM_TAG_MIN_SECONDS_BETWEEN_OPS</a> requires comparison with a
948 trusted relative timer indicating the last use of
949the key. If the last use time plus the tag value is less than the current time,
950the method must return <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. See the tag description for
951important implementation requirements.
952 <li><a href="#km_tag_max_uses_per_boot">KM_TAG_MAX_USES_PER_BOOT</a> requires comparison against a
953 secure counter that tracks the uses of the key
954since boot time. If the count of previous uses exceeds the tag value, the
955method must return <code>KM_ERROR_KEY_MAX_OPS_EXCEEDED</code>.
956 <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is enforced by this method only
957 if the key also has <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>. If the key has both,
958 then this method must have received a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in
959 <code>in_params</code> and that token must be valid, meaning that the HMAC field validates correctly.
960In addition, at least one of the <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>
961values from the key must match at least one of the secure ID values in the
962token. Finally, the key must also have a <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> and
963it must match the auth type in the token. If any of these requirements is
964not met, the method must return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.
965 <li><a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> allows the caller to specify a nonce
966 or initialization vector (IV). If the key
967does not have this tag but the caller provided <a href="#km_tag_nonce">KM_TAG_NONCE</a> to this method,
968<code>KM_ERROR_CALLER_NONCE_PROHIBITED</code> must be returned.
969 <li><a href="#km_tag_bootloader_only">KM_TAG_BOOTLOADER_ONLY</a> specifies that the key may only be
970 used by the bootloader. If this method is
971called with a bootloader-only key after the bootloader has finished executing,
972it must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.
973</ul>
974
975<h4 id=rsa_keys>RSA keys</h4>
976
977<p>All RSA key operations must specify exactly one padding mode in <code>in_params</code>. If
978unspecified or specified more than once, the method must return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
979
980<p>RSA signing and verification operations require a digest, as do RSA encryption
981and decryption operations with OAEP padding mode. For those cases, the caller
982must specify exactly one digest in <code>in_params</code>. If unspecified or specified more than once,
983the method must return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.</p>
984
985<p>Private key operations (<code>KM_PURPOSE_DECYPT</code> and <code>KM_PURPOSE_SIGN</code>) require
986authorization of digest and padding, which means that the specified
987values must be in the key authorizations. If not, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>
988or <code>KM_ERROR_INCOMPATIBLE_PADDING</code>, as appropriate. Public key operations
989(<code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>) are permitted with
990unauthorized digest or padding.</p>
991
992<p>With the exception of <code>KM_PAD_NONE</code>, all RSA padding modes are applicable only to
993certain purposes. Specifically, <code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> and <code>KM_PAD_RSA_PSS</code>
994only support signing and verification, while <code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> and
995<code>KM_PAD_RSA_OAEP</code> only support encryption and decryption. The method must return
996<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code> if the specified mode does not support the specified purpose.</p>
997
998<p>There are some important interactions between padding modes and digests:</p>
999
1000<ul>
1001 <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be performed. If signing or
1002verifying, <code>KM_DIGEST_NONE </code>must be specified for the digest. No digest is required for unpadded encryption
1003or decryption.
1004 <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest, which may be <code>KM_DIGEST_NONE.</code>
1005 <li><code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> padding does not require a digest.
1006 <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
1007 If <code>KM_DIGEST_NONE</code> is specified, the method must return
1008 <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>. In addition, the
1009 size of the RSA key must be at least 22 bytes larger than
1010the output size of the digest. Otherwise, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
1011 <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
1012 If <code>KM_DIGEST_NONE</code> is specified, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
1013</ul>
1014
1015<h4 id=ec_keys>EC keys</h4>
1016
1017<p>EC key operations must specify exactly one padding mode in <code>in_params</code>.
1018If unspecified or specified more than once,
1019return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
1020
1021<p>Private key operations (<code>KM_PURPOSE_SIGN</code>) require authorization of the
1022digest, which means that the specified value must be in the key authorizations.
1023If not, return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
1024Public key operations (<code>KM_PURPOSE_VERIFY</code>) are permitted with unauthorized digest or padding.</p>
1025
1026<h4 id=aes_keys>AES keys</h4>
1027
1028<p>AES key operations must specify exactly one block mode and one padding mode in <code>in_params</code>.
1029If either value is unspecified or specified more than once, return <code>KM_ERROR_UNSUPPORTED_BLOCK_MODE</code> or
1030<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>. The specified modes must be authorized by the key.
1031Otherwise, the method must
1032return <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code> or <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
1033
1034<p>If the block mode is <code>KM_MODE_GCM</code>, <code>in_params</code> must specify <code>KM_TAG_MAC_LENGTH</code>, and the
1035specified value must be a multiple of 8 and must not be greater than
1036128, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations. For MAC lengths greater than 128 or non-multiples of
10378, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
1038
1039<p>If the block mode is <code>KM_MODE_GCM</code> or <code>KM_MODE_CTR</code>, the specified padding mode must
1040be <code>KM_PAD_NONE</code>. For <code>KM_MODE_ECB</code> or <code>KM_MODE_CBC</code>, the mode may
1041be <code>KM_PAD_NONE</code> or <code>KM_PAD_PKCS7</code>. If the padding mode doesn't meet these
1042requirements, return <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
1043
1044<p>If the block mode is <code>KM_MODE_CBC</code>, <code>KM_MODE_CTR</code>, or <code>KM_MODE_GCM</code>, an initialization vector or nonce is needed.
1045In most cases, callers should not
1046provide an IV or nonce and the Keymaster implementation must generate a random
1047IV or nonce and return it via <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>out_params</code>. CBC
1048and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
1049authorizations contain <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>, then the caller may
1050provide an IV/nonce with <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>in_params</code>. If a
1051nonce is provided when <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is not authorized,
1052return <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>. If a nonce is not provided when
1053<a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is authorized, generate a random IV/nonce.</p>
1054
1055<h4 id=hmac_keys>HMAC keys</h4>
1056
1057<p>HMAC key operations must specify <code>KM_TAG_MAC_LENGTH</code> in <code>in_params</code>.
1058The specified value must be a multiple of 8 and must not be greater than the
1059digest length, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations.
1060For MAC lengths greater than the digest length or
1061non-multiples of 8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than
1062the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
1063
1064<h3 id=update>update</h3>
1065
1066<p>Provides data to process in an ongoing operation started with <a href="#begin">begin</a>.
1067The operation is specified by the <code>operation_handle</code> parameter.</p>
1068
1069<p>To provide more flexibility for buffer handling, implementations of this method
1070have the option of consuming less data than was provided. The caller is
1071responsible for looping to feed the rest of the data in subsequent calls. The
1072amount of input consumed must be returned in the <code>input_consumed</code> parameter.
1073Implementations must always consume at least one byte, unless the
1074operation cannot accept any more; if more than zero bytes are provided and zero
1075bytes are consumed, callers will consider this an error and abort the
1076operation.</p>
1077
1078<p>Implementations may also choose how much data to return, as a result of the
1079update. This is only relevant for encryption and decryption operations, since
1080signing and verification return no data until <a href="#finish">finish</a>. It is recommended
1081to return data as early as possible, rather than buffer it.</p>
1082
1083<h4 id=error_handling>Error handling</h4>
1084
1085<p>If this method returns an error code other than <code>KM_ERROR_OK</code>, the operation is
1086aborted and the operation handle must be invalidated. Any
1087future use of the handle, with this method or <a href="#finish">finish</a> or <a href="#abort">abort</a>,
1088must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
1089
1090<h4 id=authorization_enforcement>Authorization enforcement</h4>
1091
1092<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception
1093is the case where the key has:</p>
1094
1095<ul>
1096 <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
1097 <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
1098</ul>
1099
1100<p>In this case, the key requires an authorization per operation, and the update
1101method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
1102The token must be valid (HMAC must verify) and it must contain a
1103matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
1104contain the operation handle of the current operation in the
1105challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
1106
1107<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and
1108<a href="#finish">finish</a>. The implementation need only validate the token once if it prefers.</p>
1109
1110<h4 id=rsa_keys>RSA keys</h4>
1111
1112<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept
1113the entire block to be signed or verified in a single
1114update. It may not consume only a portion of the block. It still must accept
1115the data in multiple updates if the caller chooses to provide it that way,
1116however. If the caller provides more data to sign than can be used (length of
1117data exceeds RSA key size), return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
1118
1119<h4 id=ecdsa_keys>ECDSA keys</h4>
1120
1121<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept the
1122entire block to be signed or verified in a single
1123update. This method may not consume only a portion of the block.</p>
1124
1125<p>However, this method still must accept the data in multiple updates if the
1126caller chooses to provide it that way. If the caller provides more data to sign
1127than can be used, the data should be silently truncated. (This differs from the
1128handling of excess data provided in similar RSA operations. The reason for this
1129is compatibility with legacy clients.)</p>
1130
1131<h4 id=aes_keys>AES keys</h4>
1132
1133<p>AES GCM mode supports "associated authentication data," provided via the
1134<a href="#km_tag_associated_data">KM_TAG_ASSOCIATED_DATA</a> tag in the <code>in_params</code> argument.
1135The associated data may be provided in repeated calls (important if
1136the data is too large to send in a single block) but must always precede data
1137to be encrypted or decrypted. An update call may receive both associated data
1138and data to encrypt/decrypt, but subsequent updates may not include associated
1139data. If the caller provides associated data to an update call after a call
1140that includes data to encrypt/decrypt, return <code>KM_ERROR_INVALID_TAG</code>.</p>
1141
1142<p>For GCM encryption, the tag is appended to the ciphertext by <a href="#finish">finish</a>.
1143During decryption, the last <code>KM_TAG_MAC_LENGTH</code> bytes of the data provided to the last
1144update call is the tag. Since a given
1145invocation of <a href="#update">update</a> cannot know if it's the last invocation, it must process all but the tag
1146length and buffer the possible tag data for processing during <a href="#finish">finish</a>.</p>
1147
1148<h3 id=finish>finish</h3>
1149
1150<p>Finished an ongoing operation started with <a href="#begin">begin</a>, processing all of the
1151as-yet-unprocessed data provided by <a href="#update">update</a>(s).</p>
1152
1153<p>This method is the last one called in an operation, so all processed data must
1154be returned.</p>
1155
1156<p>Whether it completes successfully or returns an error, this method finalizes
1157the operation and therefore invalidates the provided operation handle. Any
1158future use of the handle, with this method or <a href="#update">update</a> or
1159<a href="#abort">abort</a>, must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
1160
1161<p>Signing operations return the signature as the output. Verification operations
1162accept the signature in the <code>signature</code> parameter, and return no output.</p>
1163
1164<h4 id=authorization_enforcement>Authorization enforcement</h4>
1165
1166<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception is the case where the key has:</p>
1167
1168<ul>
1169 <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
1170 <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
1171</ul>
1172
1173<p>In this case, the key requires an authorization per operation, and the update
1174method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
1175The token must be valid (HMAC must verify) and it must contain a
1176matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
1177contain the operation handle of the current operation in the
1178challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
1179
1180<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and <a href="#finish">finish</a>.
1181The implementation need only validate the token once if it prefers.</p>
1182
1183<h4 id=rsa_keys>RSA keys</h4>
1184
1185<p>Some additional requirements, depending on the padding mode:</p>
1186
1187<ul>
1188 <li><strong>KM_PAD_NONE</strong>. For unpadded signing and encryption operations, if the provided data is
1189shorter than the key, the data must be zero-padded on the left before
1190signing/encryption. If the data is the same length as the key but numerically
1191larger, return <code>KM_ERROR_INVALID_ARGUMENT</code>. For verification and decryption operations, the data must be exactly as long
1192as the key. Otherwise, return <code>KM_ERROR_INVALID_INPUT_LENGTH.</code>
1193 <li><strong>KM_PAD_RSA_PSS</strong>. For PSS-padded signature operations, the PSS salt must be at least 20 bytes
1194in length and randomly-generated. The salt may be longer; the reference
1195implementation uses maximally-sized salt. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
1196<code>input_params</code> on <a href="#begin">begin</a> is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest
1197algorithm.
1198 <li><strong>KM_PAD_RSA_OAEP</strong>. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
1199 <code>input_params</code> on <a href="#begin">begin</a> is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest
1200algorithm.
1201</ul>
1202
1203<h4 id=ecdsa_keys>ECDSA keys</h4>
1204
1205<p>If the data provided for unpadded signing or verification is too long, truncate
1206it.</p>
1207
1208<h4 id=aes_keys>AES keys</h4>
1209
1210<p>Some additional requirements, depending on block mode:</p>
1211
1212<ul>
1213 <li><strong>KM_MODE_ECB</strong> or <strong>KM_MODE_CBC</strong>. If padding is <code>KM_PAD_NONE</code> and the
1214 data length is not a multiple of the AES block size, return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>. If
1215 padding is <code>KM_PAD_PKCS7</code>, pad the data per the PKCS#7 specification. Note that PKCS#7 requires that if
1216the data is a multiple of the block length, an additional padding block must be
1217added.
1218 <li><strong>KM_MODE_GCM</strong>. During encryption, after processing all plaintext, compute the
1219 tag (<a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes) and append it to the returned ciphertext.
1220 During decryption, process
1221the last <a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes as the tag. If tag verification fails,
1222return <code>KM_ERROR_VERIFICATION_FAILED</code>.
1223</ul>
1224
1225<h3 id=abort>abort</h3>
1226
1227<p>Aborts the in-progress operation. After the call to abort, return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code> for
1228any subsequent use of the provided operation handle with <a href="#update">update</a>,
1229<a href="#finish">finish</a>, or <a href="#abort">abort</a>.</p>