Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit be151802 authored by Chirag Pathak's avatar Chirag Pathak Committed by Janis Danisevskis
Browse files

The aidl definition for Shared Secret functionality.

Test: N/A
Bug: b/171844725
Change-Id: I5f6217d487df89e8ceab92eb2bea55de5bace141
parent 2570af6b
Loading
Loading
Loading
Loading
+21 −0
Original line number Diff line number Diff line
aidl_interface {
    name: "android.hardware.security.sharedsecret",
    vendor_available: true,
    srcs: [
        "android/hardware/security/sharedsecret/*.aidl",
    ],
    stability: "vintf",
    backend: {
        java: {
            sdk_version: "module_current",
        },
        ndk: {
            vndk: {
                enabled: true,
            },
        },
        rust: {
            enabled: true,
        },
    },
}
+26 −0
Original line number Diff line number Diff line
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //
///////////////////////////////////////////////////////////////////////////////

// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
//     the interface (from the latest frozen version), the build system will
//     prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.

package android.hardware.security.sharedsecret;
@VintfStability
interface ISharedSecret {
  android.hardware.security.sharedsecret.SharedSecretParameters getSharedSecretParameters();
  byte[] computeSharedSecret(in android.hardware.security.sharedsecret.SharedSecretParameters[] params);
  const String KEY_AGREEMENT_LABEL = "KeymasterSharedMac";
  const String KEY_CHECK_LABEL = "Keymaster HMAC Verification";
}
+24 −0
Original line number Diff line number Diff line
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //
///////////////////////////////////////////////////////////////////////////////

// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
//     the interface (from the latest frozen version), the build system will
//     prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.

package android.hardware.security.sharedsecret;
@VintfStability
parcelable SharedSecretParameters {
  byte[] seed;
  byte[] nonce;
}
+114 −0
Original line number Diff line number Diff line
/*
 * Copyright (C) 2020 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.
 * limitations under the License.
 */

package android.hardware.security.sharedsecret;
import android.hardware.security.sharedsecret.SharedSecretParameters;

/**
 * Shared Secret definition.
 *
 * An ISharedSecret enables any service that implements this interface to establish a shared secret
 * with one or more other services such as ISecureClock, TEE IKeymintDevice, StrongBox
 * IKeymintDevice, etc. The shared secret is a 256-bit HMAC key and it is further used to generate
 * secure tokens with integrity protection. There are two steps to establish a shared secret between
 * the collaborating services:
 *
 * Step 1: During Android startup the system calls each service that implements this interface to
 * get the shared secret parameters. This is done using getSharedSecretParameters method defined
 * below.
 * Step 2: The system lexicographically sorts the shared secret parameters received from each
 * service and then sends these sorted parameter list to each service in a computeSharedSecret
 * method defined below. The services individually computes the shared secret and returns back
 * the 32 byte sharing check hash value generated by using the computed shared secret.
 * Step 3: The system collects sharing check hash values from each service and evaluates them. If
 * they are all equal, then the shared secret generation is considered to be successful else it is
 * considered to have failed.
 */

@VintfStability
interface ISharedSecret {
    /**
     * String used as label in the shared key derivation. See computeSharedSecret below.
     */
    const String KEY_AGREEMENT_LABEL = "KeymasterSharedMac";

    /**
     * String used as context in the computation of the sharingCheck. See computeSharedSecret
     * below.
     */
    const String KEY_CHECK_LABEL = "Keymaster HMAC Verification";

    /**
     * This method is the first step in the process for agreeing on a shared key.  It is called by
     * Android during startup.  The system calls it on each of the HAL instances and collects the
     * results in preparation for the second step.
     *
     * @return The SharedSecretParameters to use.  As specified in the SharedSecretParameters
     *         documentation, the seed must contain the same value in every invocation
     *         of the method on a given device, and the nonce must return the same value for every
     *         invocation during a boot session.
     */
    SharedSecretParameters getSharedSecretParameters();

    /**
     * This method is the second and final step in the process for agreeing on a shared key.  It is
     * called by Android during startup.  The system calls it on each of the keymint services, and
     * sends to it all of the SharedSecretParameters returned by all keymint services.
     *
     * This method computes the shared 32-byte HMAC key ``H'' as follows (all keymint services
     * instances perform the same computation to arrive at the same result):
     *
     *     H = CKDF(key = K,
     *              context = P1 || P2 || ... || Pn,
     *              label = KEY_AGREEMENT_LABEL)
     *
     * where:
     *
     *     ``CKDF'' is the standard AES-CMAC KDF from NIST SP 800-108 in counter mode (see Section
     *           5.1 of the referenced publication).  ``key'', ``context'', and ``label'' are
     *           defined in the standard.  The counter is prefixed and length L appended, as shown
     *           in the construction on page 12 of the standard.  The label string is UTF-8 encoded.
     *
     *     ``K'' is a pre-established shared secret, set up during factory reset.  The mechanism for
     *           establishing this shared secret is implementation-defined.Any method of securely
     *           establishing K that ensures that an attacker cannot obtain or derive its value is
     *           acceptable.
     *
     *           CRITICAL SECURITY REQUIREMENT: All keys created by a IKeymintDevice instance must
     *           be cryptographically bound to the value of K, such that establishing a new K
     *           permanently destroys them.
     *
     *     ``||'' represents concatenation.
     *
     *     ``Pi'' is the i'th SharedSecretParameters value in the params vector. Encoding of an
     *           SharedSecretParameters is the concatenation of its two fields, i.e. seed || nonce.
     *
     * Note that the label "KeymasterSharedMac" is the 18-byte UTF-8 encoding of the string.
     *
     * @param params is an array of SharedSecretParameters The lexicographically sorted
     * SharedSecretParameters data returned by all keymint services when getSharedSecretParameters
     * was called.
     *
     * @return sharingCheck A 32-byte value used to verify that all the keymint services have
     *         computed the same shared HMAC key.  The sharingCheck value is computed as follows:
     *
     *             sharingCheck = HMAC(H, KEY_CHECK_LABEL)
     *
     *         The string is UTF-8 encoded, 27 bytes in length.  If the returned values of all
     *         keymint services don't match, clients must assume that HMAC agreement
     *         failed.
     */
    byte[] computeSharedSecret(in SharedSecretParameters[] params);
}
+40 −0
Original line number Diff line number Diff line
/*
 * Copyright (C) 2020 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.security.sharedsecret;

/**
 * SharedSecretParameters holds the data used in the process of establishing a shared secret i.e.
 * HMAC key between multiple keymint services.  These parameters are returned in by
 * getSharedSecretParameters() and send to computeShareSecret().  See the named methods in
 * ISharedSecret for details of usage.
 */

@VintfStability
parcelable SharedSecretParameters {
    /**
     * Either empty or contains a non zero persistent value that is associated with the pre-shared
     * HMAC agreement key.  It is either empty or 32 bytes in length.
     */
    byte[] seed;

    /**
     * A 32-byte value which is guaranteed to be different each time
     * getSharedSecretParameters() is called.  Probabilistic uniqueness (i.e. random) is acceptable,
     * though a stronger uniqueness guarantee (e.g. counter) is recommended where possible.
     */
    byte[] nonce;
}