Lines Matching full:must
39 * Protocol elements, such as purpose, mode and padding, as well as access control constraints, must
40 * be specified by the caller when keys are generated or imported and must be permanently bound to
43 * In addition to the list above, IKeymasterDevice implementations must provide one more service
45 * generator must be high-quality and must be used for generation of keys, initialization vectors,
50 * All of the operations and storage of key material must occur in a secure environment. Secure
55 * must provide complete separation from the Android kernel and user space (collectively called
63 * qualify as a StrongBox, a device must meet the requirements specified in CDD 9.11.2.
67 * All IKeymasterDevice implementations must provide support for the following:
71 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support 2048, 3072 and 4096-bit keys.
72 * STRONGBOX IKeymasterDevices must support 2048-bit keys.
75 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD5, SHA1, SHA-2 224, SHA-2 256, SHA-2
76 * 384 and SHA-2 512 digest modes for RSA signing. STRONGBOX IKeymasterDevices must support
82 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support NIST curves P-224, P-256, P-384 and
83 * P-521. STRONGBOX IKeymasterDevices must support NIST curve P-256.
84 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support SHA1, SHA-2 224, SHA-2 256, SHA-2
85 * 384 and SHA-2 512 digest modes. STRONGBOX IKeymasterDevices must support SHA-2 256.
90 * - CBC, CTR, ECB and GCM modes. The GCM mode must not allow the use of tags smaller than 96
92 * - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and
93 * ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
94 * multiple of the AES block size. With PKCS7 padding, GCM and CTR operations must fail with
102 * - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and
103 * ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
108 * - Any key size that is between 64 and 512 bits (inclusive) and a multiple of 8 must be
109 * supported. STRONGBOX IKeymasterDevices must not support keys larger than 512 bits.
110 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD-5, SHA1, SHA-2-224, SHA-2-256,
111 * SHA-2-384 and SHA-2-512. STRONGBOX IKeymasterDevices must support SHA-2-256.
117 * exfiltrated). Therefore, IKeymasterDevice must enforce access controls.
123 * or imported, the caller specifies an authorization list. The IKeymasterDevice must divide the
126 * the KeyCharacteristics struct. The IKeymasterDevice must also add the following authorizations
129 * o Tag::OS_VERSION, must be hardware-enforced.
130 * o Tag::OS_PATCHLEVEL, must be hardware-enforced.
131 * o Tag::VENDOR_PATCHLEVEL, must be hardware-enforced.
132 * o Tag::BOOT_PATCHLEVEL, must be hardware-enforced.
133 * o Tag::CREATION_DATETIME, must be software-enforced, unless the IKeymasterDevice has access to
135 * o Tag::ORIGIN, must be hardware-enforced.
137 * The IKeymasterDevice must accept arbitrary, unknown tags and return them in the softwareEnforced
141 * unknown tags, must be cryptographically bound to the private/secret key material such that any
148 * IKeymasterDevice implementations must place any tags they cannot fully and completely enforce in
158 * list. The IKeymasterDevice caller must enforce them, and it is unnecessary to enforce them
161 * Some tags must be enforced by the IKeymasterDevice. See the detailed documentation on each Tag
166 * IKeymasterDevice keys must be bound to a root of trust, which is a bitstring that must be
168 * startup, preferably by the bootloader. This bitstring must be cryptographically bound to every
173 * The root of trust consists of a bitstring that must be derived from the public key used by
177 * state must be unusable, unless the previous state is restored. The goal is to increase the value
183 * All keys must also be bound to the operating system and patch level of the system image and the
188 * must be upgraded (See IKeymasterDevice::upgradeKey()) before it can be used, and the previous
189 * version of the key must be invalidated. In this way, as the device is upgraded, the keys will
193 * This version information must be associated with every key as a set of tag/value pairs in the
195 * Tag::VENDOR_PATCHLEVEL, and Tag::BOOT_PATCHLEVEL must be cryptographically bound to every
217 * must be a TEE Keymaster as well. The HMAC key used to MAC and verify authentication tokens
218 * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be
225 * implemented (note that all 4.0::IKeymasterDevice HALS must implement HMAC agreement,
230 * documentation in types.hal, the seed must contain the same value in every invocation
231 * of the method on a given device, and the nonce must return the same value for every
239 * there must be a TEE IKeymasterDevice as well. The HMAC key used to MAC and verify
240 * authentication tokens must be shared between TEE and StrongBox so they can each validate
246 * To ensure consistent ordering of the HmacSharingParameters, the caller must sort the
269 * CRITICAL SECURITY REQUIREMENT: All keys created by a IKeymasterDevice instance must
327 * IKeymasterDevice instances don't match, clients must assume that HMAC agreement
341 * returned by StrongBox begin(). The TEE IKeymasterDevice must validate all of the
343 * verify any, the parametersVerified field of the VerificationToken must be empty. Keystore
344 * must then pass the VerificationToken to the subsequent invocations of StrongBox update() and
347 * StrongBox implementations must return ErrorCode::UNIMPLEMENTED.
358 * parametersToVerify it must not return an error code, but just omit the unverified
369 * Adds entropy to the RNG used by Keymaster. Entropy added through this method must not be the
370 * only source of entropy used, and a secure mixing function must be used to mix the entropy
371 * provided by this method with internally-generated entropy. The mixing function must be
374 * indistinguishable from random. Thus, if the entropy from any source is good, the output must
377 * @param data Bytes to be mixed into the CRNG seed. The caller must not provide more than 2
386 * Generates a new cryptographic key, specifying associated parameters, which must be
387 * cryptographically bound to the key. IKeymasterDevice implementations must disallow any use
396 * In addition to the parameters provided, generateKey must add the following to the returned
406 * software-enforced list. It must be cryptographically bound to the key, like all tags.
420 * must return ErrorCode::UNSUPPORTED_KEY_SIZE. Required values for TEE IKeymasterDevice
422 * must support 2048.
425 * must return ErrorCode::INVALID_ARGUMENT. The values 3 and 65537 must be supported. It is
427 * generateKey must return ErrorCode::INVALID_ARGUMENT.
429 * The following parameters are not necessary to generate a usable RSA key, but generateKey must
432 * o Tag::PURPOSE specifies allowed purposes. All KeyPurpose values (see types.hal) must be
436 * IKeymasterDevice implementations must support all Digest values (see types.hal) for RSA
437 * keys. StrongBox IKeymasterDevice implementations must support SHA_2_256.
440 * key. IKeymasterDevice implementations must support PaddingMode::NONE,
446 * Either Tag::KEY_SIZE or Tag::EC_CURVE must be provided to generate an ECDSA key. If neither
447 * is provided, generateKey must return ErrorCode::UNSUPPORTED_KEY_SIZE. If Tag::KEY_SIZE is
448 * provided, the possible values are 224, 256, 384 and 521, and must be mapped to Tag::EC_CURVE
450 * must support all curves. StrongBox implementations must support P_256.
454 * Only Tag::KEY_SIZE is required to generate an AES key. If omitted, generateKey must return
455 * ErrorCode::UNSUPPORTED_KEY_SIZE. 128 and 256-bit key sizes must be supported.
457 * If Tag::BLOCK_MODE is specified with value BlockMode::GCM, then the caller must also provide
458 * Tag::MIN_MAC_LENGTH. If omitted, generateKey must return ErrorCode::MISSING_MIN_MAC_LENGTH.
480 * IKeymasterDevice must deduce the value from the provided key material and add the tag and
481 * value to the key characteristics. If Tag::KEY_SIZE is provided, the IKeymasterDevice must
482 * validate it against the key material. In the event of a mismatch, importKey must return
486 * not provided, the IKeymasterDevice must deduce the value from the provided key material and
488 * the IKeymasterDevice must validate it against the key material. In the event of a
489 * mismatch, importKey must return ErrorCode::IMPORT_PARAMETER_MISMATCH.
491 * o Tag::ORIGIN (returned in keyCharacteristics) must have the value KeyOrigin::IMPORTED.
536 * importKey). If the secure import is successful, these characteristics must be
563 * This key must have been created with Purpose::WRAP_KEY.
568 * @param unwrappingParams must contain any parameters needed to perform the unwrapping
570 * must be specified in this argument.
575 * key must be bound to the SID value provided by this argument. If the wrappedKeyData
576 * does not contain such a tag and value, this argument must be ignored.
581 * bit set, the constructed key must be bound to the SID value provided by this argument.
582 * If the wrappedKeyData does not contain such a tag and value, this argument must be
600 * The rule that IKeymasterDevice implementations must use for deciding whether a given tag
608 * @param clientId An opaque byte string identifying the client. This value must match the
610 * value, it must be computationally infeasible for the secure hardware to obtain the key
613 * @param appData An opaque byte string provided by the application. This value must match the
615 * value, it must be computationally infeasible for the secure hardware to obtain the key
627 * @parm keyFormat The format used for export. Must be KeyFormat::X509.
630 * referenced key must be asymmetric.
632 * @param clientId An opaque byte string identifying the client. This value must match the
634 * value, it must be computationally infeasible for the secure hardware to obtain the key
637 * @param appData An opaque byte string provided by the application. This value must match the
639 * value, it must be computationally infeasible for the secure hardware to obtain the key
651 * The certificates in the chain must be ordered such that each certificate is signed by the
652 * subsequent one, up to the root which must be self-signed. The first certificate in the chain
653 * signs the public key info of the attested key and must contain the following entries (see RFC
660 * o signature -- contains an the AlgorithmIdentifier of the algorithm used to sign, must be
663 * o issuer -- must contain the same value as the Subject field of the next certificate.
668 * present in the key, the IKeymasterDevice must use the value of Tag::CREATION_DATETIME. If
669 * Tag::USAGE_EXPIRE_DATETIME is not present, the IKeymasterDevice must use the expiration
676 * o Key Usage extension -- digitalSignature bit must be set iff the attested key has
677 * KeyPurpose::SIGN. dataEncipherment bit must be set iff the attested key has
678 * KeyPurpose::DECRYPT. keyEncipherment bit must be set iff the attested key has
679 * KeyPurpose::KEY_WRAP. All other bits must be clear.
681 * In addition to the above, the attestation certificate must contain an extension with OID
705 * # verifiedBootHash must contain 32-byte value that represents the state of all binaries
707 * # component must cause this value to change.
776 * The attestation certificate must be signed by a "batch" key, which must be securely
778 * access or extraction. The batch key must be used only for signing attestation certificates.
779 * The batch attestation certificate must be signed by a chain or zero or more intermediates
780 * leading to a self-signed roots. The intermediate and root certificate signing keys must not
789 * referenced key must be asymmetric.
791 * @param attestParams Parameters for the attestation. Must contain Tag::ATTESTATION_CHALLENGE,
792 * the value of which must be put in the attestationChallenge field of the KeyDescription
797 * The certificates must be DER-encoded.
808 * with a minor version extension to define validatable patch levels for other images; tags must
810 * use an old key blob with getKeyCharacteristics(), exportKey(), attestKey() or begin() must
811 * result in IKeymasterDevice returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must use
814 * The upgradeKey method must examine each version or patch level associated with the key. If
815 * any one of them is higher than the corresponding current device value upgradeKey() must
820 * upgrades to 0 are always allowed. If the system version were 080000, however, keymaster must
822 * than OS_VERSION must never be downgraded.
841 * with Tag::ROLLBACK_RESISTANCE in its hardware-enforced authorization list must render the key
852 * authorization lists must be rendered permanently unusable. Keys without
861 * future. The destruction must be permanent so that not even a factory reset will restore the
866 * must never attest any device ids.
873 * Begins a cryptographic operation using the specified key. If all is well, begin() must
874 * return ErrorCode::OK and create an operation handle which must be passed to subsequent calls
883 * must return ErrorCode::INVALID_OPERATION_HANDLE if called). IKeymasterDevice implementations
884 * must support 16 concurrent operations.
887 * import, calls to begin must include those tags with the originally-specified values in the
888 * inParams argument to this method. If not, begin() must return ErrorCode::INVALID_KEY_BLOB.
892 * The following key authorization parameters must be enforced by the IKeymasterDevice secure
895 * KeyPurpose::VERIFY must be allowed to succeed even if authorization requirements are not met.
902 * o Tag::PURPOSE: The purpose specified in the begin() call must match one of the purposes in
903 * the key authorizations. If the specified purpose does not match, begin() must return
907 * the current date and time is prior to the tag value, begin() must return
912 * KeyPurpose::ENCRYPT or KeyPurpose::SIGN, begin() must return ErrorCode::KEY_EXPIRED.
916 * KeyPurpose::DECRYPT or KeyPurpose::VERIFY, begin() must return ErrorCode::KEY_EXPIRED.
918 * o Tag::MIN_SECONDS_BETWEEN_OPS must be compared with a trusted relative timer indicating the
920 * time, begin() must return ErrorCode::KEY_RATE_LIMIT_EXCEEDED. See the tag description for
923 * o Tag::MAX_USES_PER_BOOT must be compared against a secure counter that tracks the uses of
924 * the key since boot time. If the count of previous uses exceeds the tag value, begin() must
927 * o Tag::USER_SECURE_ID must be enforced by this method if and only if the key also has
929 * requirement must be enforced by update() and finish()). If the key has both, then this
930 * method must receive a non-empty HardwareAuthToken in the authToken argument. For the auth
933 * o The HMAC field must validate correctly.
935 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
938 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
940 * o The timestamp in the auth token plus the value of the Tag::AUTH_TIMEOUT must be less than
944 * If any of these conditions are not met, begin() must return
949 * ErrorCode::CALLER_NONCE_PROHIBITED must be returned.
952 * called with a bootloader-only key after the bootloader has finished executing, it must
958 * All RSA key operations must specify exactly one padding mode in inParams. If unspecified or
959 * specified more than once, the begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE.
962 * operations with OAEP padding mode. For those cases, the caller must specify exactly one
963 * digest in inParams. If unspecified or specified more than once, begin() must return
968 * values. If not, begin() must return ErrorCode::INCOMPATIBLE_DIGEST or
975 * PaddingMode::RSA_OAEP only support encryption and decryption. begin() must return
988 * must construct 0x00 || 0x01 || PS || 0x00 || M, where M is the provided message and PS is a
990 * least 11 bytes larger than the message, otherwise begin() must return
996 * Digest::NONE is specified, the begin() must return ErrorCode::INCOMPATIBLE_DIGEST. In
997 * addition, the size of the RSA key must be at least 2 + D bytes larger than the output size
998 * of the digest, where D is the size of the digest, in bytes. Otherwise begin() must
999 * return ErrorCode::INCOMPATIBLE_DIGEST. The salt size must be D.
1002 * Digest::NONE is specified, begin() must return ErrorCode::INCOMPATIBLE_DIGEST. The OAEP
1003 * mask generation function must be MGF1 and the MGF1 digest must be SHA1, regardless of the
1008 * EC private key operations must specify exactly one digest in inParams. If unspecified or
1009 * specified more than once, begin() must return ErrorCode::UNSUPPORTED_DIGEST. For private key
1011 * list, begin() must return ErrorCode::INCOMPATIBLE_DIGEST. Public key operations
1016 * AES key operations must specify exactly one block mode (Tag::BLOCK_MODE) and one padding mode
1018 * begin() must return ErrorCode::UNSUPPORTED_BLOCK_MODE or
1019 * ErrorCode::UNSUPPORTED_PADDING_MODE. The specified modes must be authorized by the key,
1020 * otherwise begin() must return ErrorCode::INCOMPATIBLE_BLOCK_MODE or
1023 * If the block mode is BlockMode::GCM, inParams must specify Tag::MAC_LENGTH, and the specified
1024 * value must be a multiple of 8 that is not greater than 128 or less than the value of
1026 * non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For values less
1027 * than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
1029 * If the block mode is BlockMode::GCM or BlockMode::CTR, the specified padding mode must be
1031 * or PaddingMode::PKCS7. If the padding mode doesn't meet these conditions, begin() must
1036 * IKeymasterDevice implementation must generate a random IV or nonce and return it via
1040 * begin() must return ErrorCode::CALLER_NONCE_PROHIBITED. If a nonce is not provided when
1041 * Tag::CALLER_NONCE is authorized, IKeymasterDevice must generate a random IV/nonce.
1045 * HMAC key operations must specify Tag::MAC_LENGTH in inParams. The specified value must be a
1048 * length or non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For
1049 * values less than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
1053 * decryption imply signing and verification, respectively, but must be specified as
1057 * must have a purpose compatible with purpose and all of its usage requirements must be
1058 * satisfied, or begin() must return an appropriate error code (see above).
1061 * Tag::APPLICATION_DATA were provided during generation, they must be provided here, or
1062 * the operation must fail with ErrorCode::INVALID_KEY_BLOB. For operations that require
1065 * Tag:CALLER_NONCE, ErrorCode::CALLER_NONCE_PROHIBITED must be returned.
1067 * @param authToken Authentication token. Callers that provide no token must set all numeric
1068 * fields to zero and the MAC must be an empty vector.
1074 * @return operationHandle The newly-created operation handle which must be passed to update(),
1085 * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE.
1089 * feed the rest of the data in subsequent calls. The amount of input consumed must be returned
1090 … * in the inputConsumed parameter. Implementations must always consume at least one byte, unless
1092 * consumed, callers must consider this an error and abort the operation.
1100 * the operation handle must be invalidated. Any future use of the handle, with this method,
1101 * finish, or abort, must return ErrorCode::INVALID_OPERATION_HANDLE.
1112 * In this case, the key requires an authorization per operation, and the update method must
1116 * o The HMAC field must validate correctly.
1118 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
1121 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
1123 * o The challenge field in the auth token must contain the operationHandle
1125 * If any of these conditions are not met, update() must return
1128 * The caller must provide the auth token on every call to update() and finish().
1132 * For signing and verification operations with Digest::NONE, this method must accept the entire
1135 * and update() must accept the data this way as well. If the caller provides more data to sign
1136 * than can be used (length of data exceeds RSA key size), update() must return
1141 * For signing and verification operations with Digest::NONE, this method must accept the entire
1144 * and update() must accept the data this way as well. If the caller provides more data to sign
1153 * (important if the data is too large to send in a single block) but must always precede data
1155 * encrypt/decrypt, but subsequent updates must not include associated data. If the caller
1157 * encrypt/decrypt, update() must return ErrorCode::INVALID_TAG.
1159 * For GCM encryption, the AEAD tag must be appended to the ciphertext by finish(). During
1160 * decryption, the last Tag::MAC_LENGTH bytes of the data provided to the last update call must
1162 * it must process all but the tag length and buffer the possible tag data for processing during
1174 * @param authToken Authentication token. Callers that provide no token must set all numeric
1175 * fields to zero and the MAC must be an empty vector.
1179 * needed. If not provided, all fields must be initialized to zero and vectors must be
1186 * update() or finish(). Every call to update must consume at least one byte, unless
1202 * This method is the last one called in an operation, so all processed data must be returned.
1205 * and therefore must invalidate the provided operation handle. Any future use of the handle,
1206 * with finish(), update(), or abort(), must return ErrorCode::INVALID_OPERATION_HANDLE.
1218 * an authorization per operation, and the finish method must receive a non-empty and valid
1221 * o The HMAC field must validate correctly.
1223 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
1226 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
1228 * o The challenge field in the auth token must contain the operationHandle
1230 * If any of these conditions are not met, update() must return
1233 * The caller must provide the auth token on every call to update() and finish().
1237 * caller must pass a KeyParameter Tag::CONFIRMATION_TOKEN to finish(). Implementations must
1240 * the computed value does not match the Tag::CONFIRMATION_TOKEN parameter, finish() must not
1241 * produce a signature and must return ErrorCode::NO_USER_CONFIRMATION.
1248 * shorter than the key, the data must be zero-padded on the left before
1250 * finish() must return ErrorCode::INVALID_ARGUMENT. For verification and decryption
1251 * operations, the data must be exactly as long as the key. Otherwise, return
1254 * o PaddingMode::RSA_PSS. For PSS-padded signature operations, the PSS salt length must match
1256 * on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask
1257 * generation function and the digest specified with Tag:DIGEST in inputParams must also be
1261 * used as the OAEP digest algorithm, MGF1 must be used as the mask generation function and
1262 * and SHA1 must be used as the MGF1 digest algorithm.
1273 * not a multiple of the AES block size, finish() must return
1281 * must return ErrorCode::VERIFICATION_FAILED.
1283 * @param operationHandle The operation handle returned by begin(). This handle must be invalid
1290 * finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH.
1295 * @param authToken Authentication token. Callers that provide no token must set all numeric
1296 * fields to zero and the MAC must be an empty vector.
1300 * needed. If not provided, all fields must be initialized to zero and vectors empty.
1314 * @param operationHandle The operation handle returned by begin(). This handle must be