The aidl definition for Shared Secret functionality.

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,

        },

    },

}

///////////////////////////////////////////////////////////////////////////////

// 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";

}

///////////////////////////////////////////////////////////////////////////////

// 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;

}

/*

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

}

/*

 * 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;

}