Bert McMeen | daa1137 | 2015-09-17 16:35:18 -0700 | [diff] [blame] | 1 | page.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 |
| 21 | covers 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 |
| 26 | key 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> |
| 35 | typedef 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 |
| 44 | operation has a single purpose. When the <a href="#begin">begin</a> function is called to |
| 45 | start an operation, the purpose of the operation is |
| 46 | specified. If the purpose specified to the operation is not authorized by the |
| 47 | key, 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> |
| 56 | typedef 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 |
| 69 | key's algorithm. For example, for RSA keys, <code>KM_TAG_KEY_SIZE</code> specifies |
| 70 | the size of the public modulus. For AES keys it specifies the length |
| 71 | of 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 |
| 78 | only relevant to AES keys.</p> |
| 79 | |
| 80 | <p>Possible values are defined by the following enumeration:</p> |
| 81 | |
| 82 | <pre> |
| 83 | typedef 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 |
| 92 | the <code>additional_params</code> argument of <a href="#begin">begin</a>. If the specified |
| 93 | mode is not in the modes associated with the key, the |
| 94 | operation 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 |
| 99 | signing and verification operations. This tag is relevant to RSA, ECDSA and |
| 100 | HMAC keys.</p> |
| 101 | |
| 102 | <p>Possible values are defined by the following enumeration:</p> |
| 103 | |
| 104 | <pre> |
| 105 | typedef 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 | } |
| 114 | keymaster_digest_t; |
| 115 | </pre> |
| 116 | |
| 117 | <p>This tag is repeatable. For signing and verification operations a digest must |
| 118 | be specified in the <code>additional_params</code> argument of <a href="#begin">begin</a>. |
| 119 | If the specified digest is not in the digests associated with the key, the |
| 120 | operation 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 |
| 125 | relevant to RSA and AES keys.</p> |
| 126 | |
| 127 | <p>Possible values are defined by the following enumeration:</p> |
| 128 | |
| 129 | <pre> |
| 130 | typedef 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 |
| 141 | only for RSA encryption/decryption keys and specify RSA PKCS#1v2 OAEP |
| 142 | padding 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 |
| 144 | specify RSA PKCS#1v2 PSS |
| 145 | padding and RSA PKCS#1 v1.5 deterministic padding, respectively. Note also that |
| 146 | the 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, |
| 149 | if <code>KM_PAD_NONE</code> is used with block mode ECB or CBC and the data to be encrypted |
| 150 | or decrypted |
| 151 | is not a multiple of the AES block size in length, the call to finish must fail |
| 152 | with <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, |
| 158 | the operation must fail |
| 159 | with <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 |
| 164 | operations.</p> |
| 165 | |
| 166 | <p>This tag is boolean, so the possible values are true (if the tag is present) |
| 167 | and 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 |
| 170 | block modes. If the tag is not present, implementations should reject any |
| 171 | operation which provides <a href="#km_tag_nonce">KM_TAG_NONCE</a> to <a href="#begin">begin</a> |
| 172 | with <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 |
| 179 | the 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 |
| 182 | HMAC keys, the value must be at least 64. For GCM keys it must be at least 96 |
| 183 | and 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 |
| 188 | relevant 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 |
| 191 | RSA public exponent. Because it is specified by the caller and therefore cannot |
| 192 | be chosen by the implementation, it must be a prime number. Trustlets are |
| 193 | required to support the value 2^16+1. It is recommended that other reasonable |
| 194 | values be supported, in particular the value 3. If no exponent is specified or |
| 195 | if the specified exponent is not supported, key generation must fail |
| 196 | with <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 |
| 203 | key to be used.</p> |
| 204 | |
| 205 | <p>Possible values are defined by the following enumeration:</p> |
| 206 | |
| 207 | <pre> |
| 208 | typedef 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 |
| 215 | usable in the specified condition, and must be returned with the key |
| 216 | characteristics (from <a href="#generate_key">generate_key</a> and |
| 217 | <a href="#get_key_characteristics">get_key_characteristics</a>). If |
| 218 | the caller specifies <code>KM_TAG_BLOB_USAGE_REQUIREMENTS</code> with |
| 219 | value <code>KM_BLOB_STANDALONE</code> the trustlet must return a key blob |
| 220 | which can be used without file system |
| 221 | support. This is critical for devices with encrypted disks, where the file |
| 222 | system may not be available until after a Keymaster key is used to decrypt the |
| 223 | disk.</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) |
| 232 | and 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 |
| 235 | Android 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 |
| 242 | time, 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 |
| 251 | purposes. After this time, any attempt to use a key |
| 252 | with <a href="#km_tag_purpose">KM_PURPOSE_SIGN</a> or |
| 253 | <a href="#km_tag_purpose">KM_PURPOSE_ENCRYPT</a> provided |
| 254 | to <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 |
| 263 | decryption 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> |
| 265 | provided 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 |
| 274 | operations using a key. This can be used to rate-limit uses of keys in contexts |
| 275 | where 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 |
| 280 | during the <a href="#finish">finish</a> or <a href="#abort">abort</a> call. Any |
| 281 | call to <a href="#begin">begin</a> that is received before the timer indicates |
| 282 | that the interval specified by <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> has |
| 283 | elapsed must fail with <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. This |
| 284 | requirement implies that a trustlet must keep a table of timers for keys |
| 285 | with this tag. Because Keymaster memory is often limited, it is acceptable for |
| 286 | this table to have a fixed maximum size and for Keymaster to fail operations |
| 287 | which attempt to use keys with this tag when the table is full. At least 32 |
| 288 | in-use keys must be accommodated, and table slots must be aggressively reused |
| 289 | when key minimum-usage intervals expire. If an operation fails because the |
| 290 | table 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 |
| 297 | reboots. 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 |
| 302 | should be incremented during the <a href="#begin">begin</a> call. After the key counter |
| 303 | has exceeded this value, all subsequent attempts |
| 304 | to use the key must fail with <code>KM_ERROR_MAX_OPS_EXCEEDED</code>, until the device is |
| 305 | restarted. This requirement implies that a trustlet must |
| 306 | keep a table of use counters for keys with this tag. Because Keymaster memory |
| 307 | is often limited, it is acceptable for this table to have a fixed maximum size |
| 308 | and for Keymaster to fail operations that attempt to use keys with this tag |
| 309 | when the table is full. At least 16 keys must be accommodated. If an operation |
| 310 | fails 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 |
| 317 | authentication state. This tag is mutually exclusive |
| 318 | with <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 |
| 321 | which must be present in an authentication token (provided to <a href="#begin">begin</a> with |
| 322 | the <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a>) to authorize use of the key. Any |
| 323 | call to <a href="#begin">begin</a> with a key with this tag that does not provide an |
| 324 | authentication token, or provides an |
| 325 | authentication 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 |
| 328 | value in the authentication token, the key is authorized for use. Otherwise the operation |
| 329 | must 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 |
| 334 | mutually 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) |
| 337 | and 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 |
| 344 | key.</p> |
| 345 | |
| 346 | <p>The value is a 32-bit integer bitmask of values from the enumeration:</p> |
| 347 | |
| 348 | <pre> |
| 349 | typedef enum { |
| 350 | HW_AUTH_NONE = 0, |
| 351 | HW_AUTH_PASSWORD = 1 << 0, |
| 352 | HW_AUTH_FINGERPRINT = 1 << 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 |
| 363 | authentication. If <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is present and this tag |
| 364 | is not, then the key requires authentication for every |
| 365 | usage (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 |
| 368 | authentication of the user specified by <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> with |
| 369 | the authentication method specified |
| 370 | by <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>, |
| 383 | this tag specifies data that must be provided during all uses of the key. In |
| 384 | particular, calls to <a href="#export_key">export_key</a> and |
| 385 | <a href="#get_key_characteristics">get_key_characteristics</a> must |
| 386 | provide the same value in the <code>client_id</code> parameter, and |
| 387 | calls to <a href="#begin">begin</a> must provide this tag and the |
| 388 | same associated data as part of the <code>in_params</code> set. If the correct |
| 389 | data 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>, |
| 398 | this tag specifies data that must be provided during all uses of the key. In |
| 399 | particular, calls to <a href="#export_key">export_key</a> and |
| 400 | <a href="#get_key_characteristics">get_key_characteristics</a> must |
| 401 | provide the same value to the <code>client_id</code> parameter, and calls |
| 402 | to <a href="#begin">begin</a> must provide this tag and the same associated |
| 403 | data as part of the <code>in_params</code> set. If the correct data is not |
| 404 | provided, 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 |
| 411 | 1, 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 |
| 418 | during key generation or import, and must be added to the key characteristics |
| 419 | by the trustlet.</p> |
| 420 | |
| 421 | <p>The possible values are defined in <code>keymaster_origin_t</code>:</p> |
| 422 | |
| 423 | <pre> |
| 424 | typedef 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 |
| 432 | found in the hardware-enforced or software-enforced characteristics list.</p> |
| 433 | |
| 434 | <p><code>KM_ORIGIN_GENERATED</code> indicates that Keymaster generated the key. |
| 435 | If in the hardware-enforced list, |
| 436 | the key was generated in secure hardware and is permanently hardware-bound. If |
| 437 | in the software-enforced list, the key was generated in SoftKeymaster and is |
| 438 | not hardware-bound.</p> |
| 439 | |
| 440 | <p><code>KM_ORIGIN_IMPORTED</code> indicates that the key was generated outside |
| 441 | of Keymaster and imported into |
| 442 | Keymaster. If in the hardware-enforced list, it is permanently hardware-bound, |
| 443 | although copies outside of secure hardware may exist. If in the |
| 444 | software-enforces list, the key was imported into SoftKeymaster and is not |
| 445 | hardware-bound.</p> |
| 446 | |
| 447 | <p><code>KM_ORIGIN_UNKNOWN</code> should only appear in the hardware-enforced list. |
| 448 | It indicates that the key is |
| 449 | hardware-bound, but it is not known whether the key was originally generated in |
| 450 | secure hardware or was imported. This only occurs when keymaster0 hardware is |
| 451 | being 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 |
| 458 | by <a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>, |
| 459 | the key is guaranteed to be permanently deleted and unusable. It's possible |
| 460 | that 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) |
| 463 | and 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 |
| 470 | operating system booted (if any). This tag is never provided to or returned |
| 471 | from 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 |
| 476 | provided to <a href="#update">update</a> and specifies data that is not |
| 477 | encrypted/decrypted but is used in computing |
| 478 | the 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 |
| 487 | CTR encryption or decryption. This tag is provided to <a href="#begin">begin</a> |
| 488 | during encryption and decryption operations. It may only be provided to <a href="#begin">begin</a> |
| 489 | if the key has <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>. If not provided, |
| 490 | an appropriate nonce or IV will be randomly generated by |
| 491 | Keymaster and returned from begin.</p> |
| 492 | |
| 493 | <p>The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend |
| 494 | on the mode: GCM nonces are 12 bytes in length; CBC and CTR IVs are 16 bytes in |
| 495 | length.</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>, |
| 503 | to prove user authentication for a key operation that requires |
| 504 | it (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 |
| 515 | least as large as the value of <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a> |
| 516 | associated 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 |
| 523 | should not be implemented. The function pointers should be set |
| 524 | to <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>. |
| 543 | The caller is not required to provide placeholders. For example, some key |
| 544 | types and modes may not use any values from the <code>in_params</code> argument |
| 545 | to <a href="#begin">begin</a>, so the caller may set <code>in_params</code> |
| 546 | to <code>NULL</code> or provide an empty parameter set. It is also acceptable for the caller to |
| 547 | provide 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 |
| 555 | may be <code>NULL</code>. If a method needs to return data in an output |
| 556 | parameter 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 |
| 561 | foolish but not technically wrong. Keymaster1 implementations are not required |
| 562 | to fail in such cases or issue a diagnostic. Use of too-small keys, |
| 563 | specification of irrelevant input parameters, reuse of IVs or nonces, |
| 564 | generation of keys with no purposes (hence useless) and the like should not be |
| 565 | diagnosed by implementations. Omission of required parameters, specification of |
| 566 | invalid 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 |
| 569 | that 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 |
| 574 | implementation. A software implementation must return an empty list; a hybrid |
| 575 | implementation must return a list containing only the algorithms that are |
| 576 | supported 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 |
| 583 | implementation 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 |
| 586 | empty list for all valid purposes. Invalid purposes should cause the method to |
| 587 | return <code>KM_ERROR_INVALID_PURPOSE</code>.</p> |
| 588 | |
| 589 | <p>Keymaster1 implementations must support ECB, CBC, CTR and GCM for AES |
| 590 | encryption 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 |
| 595 | implementation 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 |
| 598 | for 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 |
| 604 | encryption and signing, if the message is shorter than the public modulus, |
| 605 | implementations must left-pad it with zeros. For unpadded decryption and |
| 606 | verification, 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 |
| 613 | padding 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 |
| 618 | implementation for a specified algorithm and purpose.</p> |
| 619 | |
| 620 | <p>No AES modes support or require digesting, so the method must return an empty |
| 621 | list for valid purposes.</p> |
| 622 | |
| 623 | <p>Keymaster1 implementations are allowed to implement a subset of the defined |
| 624 | digests, but must provide SHA-256. It is strongly recommended that keymaster1 |
| 625 | implementations provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the |
| 626 | full 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 |
| 631 | implementation of a specified algorithm.</p> |
| 632 | |
| 633 | <p>Keymaster1 implementations must support the PKCS#8 format (without password |
| 634 | protection) for importing RSA and EC key pairs, and must support RAW import of |
| 635 | AES 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 |
| 640 | implementation of a specified algorithm.</p> |
| 641 | |
| 642 | <p>Keymaster1 implementations must support the X.509 format for exporting RSA and |
| 643 | EC public keys. Export of private keys or asymmetric keys must not be |
| 644 | supported.</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 |
| 649 | for generating random numbers, for keys, IVs, etc.</p> |
| 650 | |
| 651 | <p>Keymaster1 implementations must <strong>securely</strong> mix the provided |
| 652 | entropy into their pool, which must also contain |
| 653 | internally-generated entropy from a hardware random number generator. Mixing |
| 654 | must have the property that an attacker with complete control of either |
| 655 | the <code>add_rng_entropy</code>-provided bits or the hardware-generated bits, but not both, cannot predict |
| 656 | bits generated from the entropy pool with probability greater than ½.</p> |
| 657 | |
| 658 | <p>Keymaster1 implementations that attempt to estimate the entropy in their |
| 659 | internal 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 |
| 664 | will be permanently bound to the key. Keymaster1 implementations must make it |
| 665 | impossible to use a key in any way inconsistent with the authorizations |
| 666 | specified at generation time. With respect to authorizations that the secure |
| 667 | hardware cannot enforce, the secure hardware's obligation is limited to |
| 668 | ensuring that the unenforceable authorizations associated with the key cannot |
| 669 | be modified, so that every call to <a href="#get_key_characteristics">get_key_characteristics</a> |
| 670 | will return the original value. In addition, the characteristics returned by <code>generate_key</code> |
| 671 | must allocate authorizations correctly between the hardware-enforced and |
| 672 | software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a> |
| 673 | for more details.</p> |
| 674 | |
| 675 | <p>The parameters that must be provided to <code>generate_key</code> depend on the type of key |
| 676 | being generated. This section will summarize the |
| 677 | required and allowed tags for each type of key. <a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a> |
| 678 | is 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 |
| 687 | return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>. Values that must be supported are |
| 688 | 1024, 2048, 3072 and 4096. It is |
| 689 | recommended 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 |
| 694 | support 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 |
| 698 | an RSA key without them will produce a key that is unusable. |
| 699 | The <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 |
| 704 | any 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 |
| 707 | that do not support all digest algorithms must accept key generation requests |
| 708 | that include unsupported digests. The unsupported digests should be placed in |
| 709 | the "software-enforced" list in the returned key characteristics. This is |
| 710 | because the key will be usable with those other digests, but digesting will be |
| 711 | performed in software. Then hardware will be called to perform the operation |
| 712 | with <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 |
| 715 | that do not support all digest algorithms must place <code>KM_PAD_RSA_PSS</code> |
| 716 | and <code>KM_PAD_RSA_OAEP</code> in the software-enforced list of the key |
| 717 | characteristics if any unsupported |
| 718 | digest 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 |
| 724 | ECDSA key. It is used to select the EC group. |
| 725 | Implementations must support values 224, 256, 384 and 521, which indicate the |
| 726 | NIST 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, |
| 729 | but 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 |
| 734 | generating an AES key. If omitted, the method must return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>. |
| 735 | Values that must be supported are 128 and 256. It is recommended to support |
| 736 | 192-bit AES keys.</p> |
| 737 | |
| 738 | <p>The following parameters are particularly relevant for AES keys, but not |
| 739 | required 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 |
| 744 | and 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> |
| 748 | must 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 |
| 750 | be 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 |
| 759 | multiples of 8 must not be supported. All multiples of 8, from 64 to 512, must |
| 760 | be 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 |
| 763 | this 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 |
| 766 | specified, otherwise return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>. If the digest is not supported |
| 767 | by 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 |
| 773 | key's characteristics divided appropriately |
| 774 | into hardware-enforced and software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a> |
| 775 | for a description of which characteristics go in which list. The returned |
| 776 | characteristics must include all of the parameters specified to key generation, |
| 777 | except <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> and |
| 778 | <a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>. |
| 779 | If these tags were included in the key parameters, they must be removed from |
| 780 | the returned characteristics; it must not be possible to find their values by |
| 781 | examining the returned key blob. However, they must be cryptographically bound |
| 782 | to the key blob, so that if the correct values are not provided when the key is |
| 783 | used, usage will fail. Similarly, <a href="#km_tag_root_of_trust">KM_TAG_ROOT_OF_TRUST</a> must |
| 784 | be cryptographically bound to the key, but it may not be specified during |
| 785 | key creation or import and must never be returned.</p> |
| 786 | |
| 787 | <p>In addition to the provided tags, the trustlet must also |
| 788 | add <a href="#km_tag_origin">KM_TAG_ORIGIN</a>, with the value <code>KM_ORIGIN_GENERATED</code>, |
| 789 | and 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>, |
| 795 | it is guaranteed by secure hardware never to be usable again. Implementations |
| 796 | without rollback resistance will typically return generated or imported key |
| 797 | material to the caller as a key blob, an encrypted and authenticated form. When |
| 798 | keystore deletes the key blob, the key is gone, but an attacker who has |
| 799 | previously managed to retrieve the key material can potentially restore it to |
| 800 | the device.</p> |
| 801 | |
| 802 | <p>A key is rollback resistant if the secure hardware guarantees that deleted keys |
| 803 | cannot be restored later. This is generally done by storing additional key |
| 804 | metadata in a trusted location that cannot be manipulated by an attacker. On |
| 805 | mobile devices, the mechanism used for this is usually Replay Protected Memory |
| 806 | Blocks (RPMB). Because the number of keys that may be created is essentially |
| 807 | unbounded and the trusted storage used for rollback resistance may be limited |
| 808 | in size, it is required that this method succeed even if rollback resistance |
| 809 | cannot be provided for the new key. In that case, |
| 810 | <a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a> should not be |
| 811 | added 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 |
| 816 | into two sets: hardware-enforced and software-enforced. The description here |
| 817 | applies equally to the key characteristics lists returned |
| 818 | by <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 |
| 821 | or import, the same value must provided to |
| 822 | this method in the <code>client_id</code> argument. Otherwise, the |
| 823 | method must return <code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly, |
| 824 | if <code>KM_TAG_APPLICATION_DATA </code>was provided during generation |
| 825 | or import, the same value must be provided to |
| 826 | this method in the <code>app_data</code> argument.</p> |
| 827 | |
| 828 | <p>The characteristics returned by this method completely describe the type and |
| 829 | usage of the specified key.</p> |
| 830 | |
| 831 | <p>The general rule for deciding whether a given tag belongs in the |
| 832 | hardware-enforced or software-enforced list is that if the meaning of the tag |
| 833 | is fully assured by secure hardware, it is hardware-enforced. Otherwise, it's |
| 834 | software enforced. Below is a list of specific tags whose correct allocation |
| 835 | may 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, |
| 841 | these will be in the hardware-enforced list, because the statement that, for |
| 842 | example, "This RSA key material is only used as an RSA key" is enforced by |
| 843 | hardware because the hardware will use it in no other way and software has no |
| 844 | access 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 |
| 847 | hardware-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 |
| 850 | possibility that a specific padding mode may have to be performed by software, |
| 851 | they go in the software-enforced list. Such a possibility arises for RSA keys |
| 852 | that permit PSS or OAEP padding with digest algorithms that are not supported |
| 853 | by 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 |
| 857 | that to be true, the Keymaster trustlet and the relevant authentication |
| 858 | trustlet must both be secure and must share a secret HMAC key used to sign and |
| 859 | validate 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 |
| 864 | will only have access to time information provided by the non-secure OS, which |
| 865 | means 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 |
| 868 | list 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 |
| 874 | output characteristics are handled the same as for <code>generate_key</code>, |
| 875 | with 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, |
| 881 | the trustlet must deduce the values from the provided key material and add |
| 882 | appropriate tags and values to the key characteristics. If the parameters are |
| 883 | provided, the trustlet must validate them against the key material. In the |
| 884 | event 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, |
| 894 | the same value must provided to |
| 895 | this 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> |
| 897 | was provided during generation or import, the same value must be provided to |
| 898 | this 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 |
| 903 | implemented 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 |
| 908 | by 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 |
| 913 | purpose, with the specified parameters (as appropriate), and returns an |
| 914 | operation 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> |
| 917 | were specified during key generation or import, calls to begin must include |
| 918 | those 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 |
| 923 | trustlet if the implementation placed them in the "hardware-enforced" |
| 924 | characteristics and if the operation is not a public key operation. Public key |
| 925 | operations, meaning <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>, |
| 926 | with RSA or EC keys, must be allowed to succeed even if authorization |
| 927 | requirements 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 |
| 932 | in the key authorizations, unless the requested operation is a public key |
| 933 | operation, meaning that the key is RSA or EC and the purpose is <code>KM_PURPOSE_ENCRYPT</code> |
| 934 | or <code>KM_PURPOSE_VERIFY</code>. Note that <code>KM_PURPOSE_ENCRYPT</code> is not valid for EC keys. |
| 935 | Begin 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 |
| 938 | time 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 |
| 941 | time is later than the tag value and the purpose is <code>KM_PURPOSE_ENCRYPT</code> or <code>KM_PURPOSE_SIGN</code>, |
| 942 | the 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 |
| 945 | time is later than the tag value and the purpose is <code>KM_PURPOSE_DECRYPT</code> or <code>KM_PURPOSE_VERIFY</code>, |
| 946 | the 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 |
| 949 | the key. If the last use time plus the tag value is less than the current time, |
| 950 | the method must return <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. See the tag description for |
| 951 | important 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 |
| 954 | since boot time. If the count of previous uses exceeds the tag value, the |
| 955 | method 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. |
| 960 | In addition, at least one of the <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> |
| 961 | values from the key must match at least one of the secure ID values in the |
| 962 | token. Finally, the key must also have a <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> and |
| 963 | it must match the auth type in the token. If any of these requirements is |
| 964 | not 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 |
| 967 | does 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 |
| 971 | called with a bootloader-only key after the bootloader has finished executing, |
| 972 | it 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 |
| 978 | unspecified 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 |
| 981 | and decryption operations with OAEP padding mode. For those cases, the caller |
| 982 | must specify exactly one digest in <code>in_params</code>. If unspecified or specified more than once, |
| 983 | the 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 |
| 986 | authorization of digest and padding, which means that the specified |
| 987 | values must be in the key authorizations. If not, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code> |
| 988 | or <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 |
| 990 | unauthorized digest or padding.</p> |
| 991 | |
| 992 | <p>With the exception of <code>KM_PAD_NONE</code>, all RSA padding modes are applicable only to |
| 993 | certain purposes. Specifically, <code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> and <code>KM_PAD_RSA_PSS</code> |
| 994 | only 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 |
| 1002 | verifying, <code>KM_DIGEST_NONE </code>must be specified for the digest. No digest is required for unpadded encryption |
| 1003 | or 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 |
| 1010 | the 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>. |
| 1018 | If unspecified or specified more than once, |
| 1019 | return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p> |
| 1020 | |
| 1021 | <p>Private key operations (<code>KM_PURPOSE_SIGN</code>) require authorization of the |
| 1022 | digest, which means that the specified value must be in the key authorizations. |
| 1023 | If not, return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>. |
| 1024 | Public 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>. |
| 1029 | If 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. |
| 1031 | Otherwise, the method must |
| 1032 | return <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 |
| 1035 | specified value must be a multiple of 8 and must not be greater than |
| 1036 | 128, 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 |
| 1037 | 8, 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 |
| 1040 | be <code>KM_PAD_NONE</code>. For <code>KM_MODE_ECB</code> or <code>KM_MODE_CBC</code>, the mode may |
| 1041 | be <code>KM_PAD_NONE</code> or <code>KM_PAD_PKCS7</code>. If the padding mode doesn't meet these |
| 1042 | requirements, 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. |
| 1045 | In most cases, callers should not |
| 1046 | provide an IV or nonce and the Keymaster implementation must generate a random |
| 1047 | IV or nonce and return it via <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>out_params</code>. CBC |
| 1048 | and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key |
| 1049 | authorizations contain <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>, then the caller may |
| 1050 | provide an IV/nonce with <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>in_params</code>. If a |
| 1051 | nonce is provided when <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is not authorized, |
| 1052 | return <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>. |
| 1058 | The specified value must be a multiple of 8 and must not be greater than the |
| 1059 | digest length, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations. |
| 1060 | For MAC lengths greater than the digest length or |
| 1061 | non-multiples of 8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than |
| 1062 | the 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>. |
| 1067 | The 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 |
| 1070 | have the option of consuming less data than was provided. The caller is |
| 1071 | responsible for looping to feed the rest of the data in subsequent calls. The |
| 1072 | amount of input consumed must be returned in the <code>input_consumed</code> parameter. |
| 1073 | Implementations must always consume at least one byte, unless the |
| 1074 | operation cannot accept any more; if more than zero bytes are provided and zero |
| 1075 | bytes are consumed, callers will consider this an error and abort the |
| 1076 | operation.</p> |
| 1077 | |
| 1078 | <p>Implementations may also choose how much data to return, as a result of the |
| 1079 | update. This is only relevant for encryption and decryption operations, since |
| 1080 | signing and verification return no data until <a href="#finish">finish</a>. It is recommended |
| 1081 | to 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 |
| 1086 | aborted and the operation handle must be invalidated. Any |
| 1087 | future use of the handle, with this method or <a href="#finish">finish</a> or <a href="#abort">abort</a>, |
| 1088 | must 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 |
| 1093 | is 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 |
| 1101 | method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument. |
| 1102 | The token must be valid (HMAC must verify) and it must contain a |
| 1103 | matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must |
| 1104 | contain the operation handle of the current operation in the |
| 1105 | challenge 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 |
| 1113 | the entire block to be signed or verified in a single |
| 1114 | update. It may not consume only a portion of the block. It still must accept |
| 1115 | the data in multiple updates if the caller chooses to provide it that way, |
| 1116 | however. If the caller provides more data to sign than can be used (length of |
| 1117 | data 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 |
| 1122 | entire block to be signed or verified in a single |
| 1123 | update. 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 |
| 1126 | caller chooses to provide it that way. If the caller provides more data to sign |
| 1127 | than can be used, the data should be silently truncated. (This differs from the |
| 1128 | handling of excess data provided in similar RSA operations. The reason for this |
| 1129 | is 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. |
| 1135 | The associated data may be provided in repeated calls (important if |
| 1136 | the data is too large to send in a single block) but must always precede data |
| 1137 | to be encrypted or decrypted. An update call may receive both associated data |
| 1138 | and data to encrypt/decrypt, but subsequent updates may not include associated |
| 1139 | data. If the caller provides associated data to an update call after a call |
| 1140 | that 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>. |
| 1143 | During decryption, the last <code>KM_TAG_MAC_LENGTH</code> bytes of the data provided to the last |
| 1144 | update call is the tag. Since a given |
| 1145 | invocation of <a href="#update">update</a> cannot know if it's the last invocation, it must process all but the tag |
| 1146 | length 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 |
| 1151 | as-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 |
| 1154 | be returned.</p> |
| 1155 | |
| 1156 | <p>Whether it completes successfully or returns an error, this method finalizes |
| 1157 | the operation and therefore invalidates the provided operation handle. Any |
| 1158 | future 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 |
| 1162 | accept 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 |
| 1174 | method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument. |
| 1175 | The token must be valid (HMAC must verify) and it must contain a |
| 1176 | matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must |
| 1177 | contain the operation handle of the current operation in the |
| 1178 | challenge 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>. |
| 1181 | The 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 |
| 1189 | shorter than the key, the data must be zero-padded on the left before |
| 1190 | signing/encryption. If the data is the same length as the key but numerically |
| 1191 | larger, return <code>KM_ERROR_INVALID_ARGUMENT</code>. For verification and decryption operations, the data must be exactly as long |
| 1192 | as 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 |
| 1194 | in length and randomly-generated. The salt may be longer; the reference |
| 1195 | implementation 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 |
| 1197 | algorithm. |
| 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 |
| 1200 | algorithm. |
| 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 |
| 1206 | it.</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 |
| 1216 | the data is a multiple of the block length, an additional padding block must be |
| 1217 | added. |
| 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 |
| 1221 | the last <a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes as the tag. If tag verification fails, |
| 1222 | return <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 |
| 1228 | any 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> |