Add Keymaster 4.1
Note that CL is missing complete tests (what's included is just a
stub, really) and support library code. All of that will come in
near-future CLs. This CL omits them because they'll take time and
there's a need to unblock Keymaster 4.1 implementers now.
Bug: 140193672
Bug: 140192237
Bug: 140824829
Test: Will be in a future CL
Change-Id: I0e6e3a38356f0517158a10604b549415641ad1b9
diff --git a/keymaster/4.1/IKeymasterDevice.hal b/keymaster/4.1/IKeymasterDevice.hal
new file mode 100644
index 0000000..64d2c9f
--- /dev/null
+++ b/keymaster/4.1/IKeymasterDevice.hal
@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.keymaster@4.1;
+
+import @4.0::ErrorCode;
+import @4.0::HardwareAuthToken;
+import @4.0::IKeymasterDevice;
+import @4.0::KeyParameter;
+import @4.0::KeyPurpose;
+import @4.0::OperationHandle;
+import IOperation;
+
+/**
+ * @4.1::IKeymasterDevice is a minor extension to @4.0::IKeymasterDevice. It adds support for
+ *
+ * - Partial hardware enforcment of UNLOCKED_DEVICE_REQUIRED keys;
+ * - Device-unique attestaion;
+ * - Early boot only keys;
+ * - Better cleanup of operations when clients die without completing or aborting them.
+ */
+interface IKeymasterDevice extends @4.0::IKeymasterDevice {
+ /**
+ * Called by client to notify the IKeymasterDevice that the device is now locked, and keys with
+ * the UNLOCKED_DEVICE_REQUIRED tag should no longer be usable. When this function is called,
+ * the IKeymasterDevice should note the current timestamp, and attempts to use
+ * UNLOCKED_DEVICE_REQUIRED keys must be rejected with Error::DEVICE_LOCKED until an
+ * authentication token with a later timestamp is presented. If the `passwordOnly' argument is
+ * set to true the sufficiently-recent authentication token must indicate that the user
+ * authenticated with a password, not a biometric.
+ *
+ * @param passwordOnly specifies whether the device must be unlocked with a password, rather
+ * than a biometric, before UNLOCKED_DEVICE_REQUIRED keys can be used.
+ */
+ deviceLocked(bool passwordOnly) generates (ErrorCode error);
+
+ /**
+ * Called by client to notify the IKeymasterDevice that the device has left the early boot
+ * state, and that keys with the EARLY_BOOT_ONLY tag may no longer be used. All attempts to use
+ * an EARLY_BOOT_ONLY key after this method is called must fail with Error::INVALID_KEY_BLOB.
+ */
+ earlyBootEnded() generates (ErrorCode error);
+
+ /**
+ * Begins a cryptographic operation. beginOp() is a variation on begin(). beginOp() has
+ * identical functionality to begin, but instead of an OperationHandle it returns an IOperation
+ * object. An IKeymasterDevice HAL service must call linkToDeath() on the Operation before
+ * returning it, and the provided hidl_death_recipient, if called, must abort() the operation.
+ * This is to ensure that in the event a client crashes while an operation is in progress, the
+ * operation slot is freed and available for use by other clients.
+ *
+ * @4.1::IKeymasterDevices must implement both beginOp() and begin().
+ */
+ beginOp(KeyPurpose purpose, vec<uint8_t> keyBlob, vec<KeyParameter> inParams,
+ HardwareAuthToken authToken)
+ generates (ErrorCode error, vec<KeyParameter> outParam, IOperation operation);
+};