From 4faf8b63a49ff24140d3658cb5c2ab2d1156188e Mon Sep 17 00:00:00 2001 From: Joel Galenson Date: Thu, 10 Dec 2020 10:28:53 -0800 Subject: [PATCH 1/4] Add Secure Clock to the compatibility matrix. Test: Build Change-Id: I570f7535add92d98b4e129ec5478859d648db23a --- compatibility_matrices/compatibility_matrix.current.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/compatibility_matrices/compatibility_matrix.current.xml b/compatibility_matrices/compatibility_matrix.current.xml index 910f051750..e897c071f5 100644 --- a/compatibility_matrices/compatibility_matrix.current.xml +++ b/compatibility_matrices/compatibility_matrix.current.xml @@ -458,6 +458,13 @@ SIM[1-9][0-9]* + + android.hardware.security.secureclock + + ISecureClock + default + + android.hardware.sensors 1.0 From c160ae682edb6a7bfde040d426b6abaf462c28dd Mon Sep 17 00:00:00 2001 From: Chirag Pathak Date: Mon, 7 Dec 2020 22:14:34 +0000 Subject: [PATCH 2/4] The aidl definition for Secure Clock keymint service. Test: N/A Bug: b/168673523 Change-Id: I6134d8b4ce620ecceccc0ea88a234f01e6915798 --- security/secureclock/aidl/Android.bp | 24 ++++++++ .../security/secureclock/ISecureClock.aidl | 24 ++++++++ .../security/secureclock/TimeStampToken.aidl | 26 ++++++++ .../security/secureclock/ISecureClock.aidl | 48 +++++++++++++++ .../security/secureclock/TimeStampToken.aidl | 61 +++++++++++++++++++ 5 files changed, 183 insertions(+) create mode 100644 security/secureclock/aidl/Android.bp create mode 100644 security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/ISecureClock.aidl create mode 100644 security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/TimeStampToken.aidl create mode 100644 security/secureclock/aidl/android/hardware/security/secureclock/ISecureClock.aidl create mode 100644 security/secureclock/aidl/android/hardware/security/secureclock/TimeStampToken.aidl diff --git a/security/secureclock/aidl/Android.bp b/security/secureclock/aidl/Android.bp new file mode 100644 index 0000000000..7d26a9bd58 --- /dev/null +++ b/security/secureclock/aidl/Android.bp @@ -0,0 +1,24 @@ +aidl_interface { + name: "android.hardware.security.secureclock", + vendor_available: true, + srcs: [ + "android/hardware/security/secureclock/*.aidl", + ], + stability: "vintf", + imports: [ + "android.hardware.security.keymint", + ], + backend: { + java: { + sdk_version: "module_current", + }, + ndk: { + vndk: { + enabled: true, + }, + }, + rust: { + enabled: true, + }, + }, +} diff --git a/security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/ISecureClock.aidl b/security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/ISecureClock.aidl new file mode 100644 index 0000000000..c16b312cda --- /dev/null +++ b/security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/ISecureClock.aidl @@ -0,0 +1,24 @@ +/////////////////////////////////////////////////////////////////////////////// +// 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 -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.secureclock; +@VintfStability +interface ISecureClock { + android.hardware.security.secureclock.TimeStampToken generateTimeStamp(in long challenge); + const String TIME_STAMP_MAC_LABEL = "Time Verification"; +} diff --git a/security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/TimeStampToken.aidl b/security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/TimeStampToken.aidl new file mode 100644 index 0000000000..c23ddca2c9 --- /dev/null +++ b/security/secureclock/aidl/aidl_api/android.hardware.security.secureclock/current/android/hardware/security/secureclock/TimeStampToken.aidl @@ -0,0 +1,26 @@ +/////////////////////////////////////////////////////////////////////////////// +// 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 -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.secureclock; +@VintfStability +parcelable TimeStampToken { + long challenge; + android.hardware.security.keymint.Timestamp timestamp; + android.hardware.security.keymint.SecurityLevel securityLevel; + byte[] mac; +} diff --git a/security/secureclock/aidl/android/hardware/security/secureclock/ISecureClock.aidl b/security/secureclock/aidl/android/hardware/security/secureclock/ISecureClock.aidl new file mode 100644 index 0000000000..7d416dda7a --- /dev/null +++ b/security/secureclock/aidl/android/hardware/security/secureclock/ISecureClock.aidl @@ -0,0 +1,48 @@ +/* + * 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.secureclock; +import android.hardware.security.secureclock.TimeStampToken; + +/** + * Secure Clock definition. + * + * An ISecureClock provides a keymint service to generate secure timestamp using a secure platform. + * The secure time stamp contains time in milliseconds. This time stamp also contains a 256-bit MAC + * which provides integrity protection. The MAC is generated using HMAC-SHA-256 and a shared + * secret. The shared secret must be available to secure clock service by implementing + * ISharedSecret aidl. Note: ISecureClock depends on the shared secret, without which the secure + * time stamp token cannot be generated. + */ + +@VintfStability +interface ISecureClock { + /** + * String used as context in the HMAC computation signing the generated time stamp. + * See TimeStampToken.mac for details. + */ + const String TIME_STAMP_MAC_LABEL = "Time Verification"; + + /** + * Generates an authenticated timestamp. + * + * @param A challenge value provided by the relying party. It will be included in the generated + * TimeStampToken to ensure freshness. The relying service must ensure that the + * challenge cannot be specified or predicted by an attacker. + * + * @return the TimeStampToken, see the definition for details. + */ + TimeStampToken generateTimeStamp(in long challenge); +} diff --git a/security/secureclock/aidl/android/hardware/security/secureclock/TimeStampToken.aidl b/security/secureclock/aidl/android/hardware/security/secureclock/TimeStampToken.aidl new file mode 100644 index 0000000000..76a2d28780 --- /dev/null +++ b/security/secureclock/aidl/android/hardware/security/secureclock/TimeStampToken.aidl @@ -0,0 +1,61 @@ +/* + * 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.secureclock; + +import android.hardware.security.keymint.SecurityLevel; +import android.hardware.security.keymint.Timestamp; + +/** + * TimeStampToken instances are used for secure environments that requires secure time information. + */ + +@VintfStability +parcelable TimeStampToken { + /** + * The challenge that was provided as argument to ISecureClock.generateTimeStamp by the client. + */ + long challenge; + + /** + * The current time of the secure environment that generates the TimeStampToken. + */ + Timestamp timestamp; + + /** + * SecurityLevel of the secure environment that generated the token. + */ + SecurityLevel securityLevel; + + /** + * 32-byte HMAC-SHA256 of the above values, computed as: + * + * HMAC(H, + * ISecureClock.TIME_STAMP_MAC_LABEL || challenge || timestamp) + * + * where: + * + * ``ISecureClock.TIME_STAMP_MAC_LABEL'' is a sting constant defined in ISecureClock.aidl. + * + * ``H'' is the shared HMAC key (see computeSharedHmac() in ISharedHmacSecret). + * + * ``||'' represents concatenation + * + * The representation of challenge and timestamp is as 64-bit unsigned integers in big-endian + * order. securityLevel is represented as a 32-bit unsigned integer in big-endian order. + */ + byte[] mac; +} From 2570af6b96002917292b11182d433fbc51e1cce4 Mon Sep 17 00:00:00 2001 From: Joel Galenson Date: Thu, 10 Dec 2020 10:29:19 -0800 Subject: [PATCH 3/4] Add Shared Secret to the compatibility matrix. Test: Build Change-Id: Iadac3b304a9b8eba69f6fb2fe7aec41f7200a613 --- compatibility_matrices/compatibility_matrix.current.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/compatibility_matrices/compatibility_matrix.current.xml b/compatibility_matrices/compatibility_matrix.current.xml index e897c071f5..d39e339e79 100644 --- a/compatibility_matrices/compatibility_matrix.current.xml +++ b/compatibility_matrices/compatibility_matrix.current.xml @@ -465,6 +465,13 @@ default + + android.hardware.security.sharedsecret + + ISharedSecret + default + + android.hardware.sensors 1.0 From be15180242fb4b536bd3572c30aae4d48aaaefde Mon Sep 17 00:00:00 2001 From: Chirag Pathak Date: Mon, 7 Dec 2020 22:16:10 +0000 Subject: [PATCH 4/4] The aidl definition for Shared Secret functionality. Test: N/A Bug: b/171844725 Change-Id: I5f6217d487df89e8ceab92eb2bea55de5bace141 --- security/sharedsecret/aidl/Android.bp | 21 ++++ .../security/sharedsecret/ISharedSecret.aidl | 26 ++++ .../sharedsecret/SharedSecretParameters.aidl | 24 ++++ .../security/sharedsecret/ISharedSecret.aidl | 114 ++++++++++++++++++ .../sharedsecret/SharedSecretParameters.aidl | 40 ++++++ 5 files changed, 225 insertions(+) create mode 100644 security/sharedsecret/aidl/Android.bp create mode 100644 security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/ISharedSecret.aidl create mode 100644 security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/SharedSecretParameters.aidl create mode 100644 security/sharedsecret/aidl/android/hardware/security/sharedsecret/ISharedSecret.aidl create mode 100644 security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl diff --git a/security/sharedsecret/aidl/Android.bp b/security/sharedsecret/aidl/Android.bp new file mode 100644 index 0000000000..ab441106f7 --- /dev/null +++ b/security/sharedsecret/aidl/Android.bp @@ -0,0 +1,21 @@ +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, + }, + }, +} diff --git a/security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/ISharedSecret.aidl b/security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/ISharedSecret.aidl new file mode 100644 index 0000000000..2509936d99 --- /dev/null +++ b/security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/ISharedSecret.aidl @@ -0,0 +1,26 @@ +/////////////////////////////////////////////////////////////////////////////// +// 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 -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"; +} diff --git a/security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/SharedSecretParameters.aidl b/security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/SharedSecretParameters.aidl new file mode 100644 index 0000000000..9b65046060 --- /dev/null +++ b/security/sharedsecret/aidl/aidl_api/android.hardware.security.sharedsecret/current/android/hardware/security/sharedsecret/SharedSecretParameters.aidl @@ -0,0 +1,24 @@ +/////////////////////////////////////////////////////////////////////////////// +// 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 -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; +} diff --git a/security/sharedsecret/aidl/android/hardware/security/sharedsecret/ISharedSecret.aidl b/security/sharedsecret/aidl/android/hardware/security/sharedsecret/ISharedSecret.aidl new file mode 100644 index 0000000000..906303f15b --- /dev/null +++ b/security/sharedsecret/aidl/android/hardware/security/sharedsecret/ISharedSecret.aidl @@ -0,0 +1,114 @@ +/* + * 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); +} diff --git a/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl b/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl new file mode 100644 index 0000000000..691b3f1386 --- /dev/null +++ b/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl @@ -0,0 +1,40 @@ +/* + * 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; +}