keymaster/4.1/IKeymasterDevice.hal

/*
 * 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);
};