Evolution-x/hardware_interfaces
1
0
Fork 0
mirror of https://github.com/Evolution-X/hardware_interfaces synced 2026-02-01 11:36:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Introduce Secretkeeper HAL interface am: 18cafa0a11 am: 5d668c50ec

Browse Source 
Original change: https://android-review.googlesource.com/c/platform/hardware/interfaces/+/2695089

Change-Id: I0580a55379c34c1954da9758d86bbc594c835f55
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
This commit is contained in:
Shikha Panwar
2023-11-21 18:23:20 +00:00
committed by Automerger Merge Worker
parent 053f772e9b 5d668c50ec
commit 2898897930
4 changed files with 264 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
security/secretkeeper/aidl/Android.bp Normal file
View File

@@ -0,0 +1,36 @@
// Copyright (C) 2023 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 {
default_applicable_licenses: ["Android-Apache-2.0"],
}
aidl_interface {
name: "android.hardware.security.secretkeeper",
vendor_available: true,
srcs: ["android/hardware/security/secretkeeper/*.aidl"],
stability: "vintf",
backend: {
ndk: {
enabled: true,
},
rust: {
enabled: true,
apex_available: [
"//apex_available:platform",
"com.android.virt",
],
},
},
}

38
security/secretkeeper/aidl/aidl_api/android.hardware.security.secretkeeper/current/android/hardware/security/secretkeeper/ISecretkeeper.aidl Normal file
View File

@@ -0,0 +1,38 @@
/*
* Copyright (C) 2023 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.
*/
///////////////////////////////////////////////////////////////////////////////
// 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.secretkeeper;
@VintfStability
interface ISecretkeeper {
byte[] processSecretManagementRequest(in byte[] request);
}

74
security/secretkeeper/aidl/android/hardware/security/secretkeeper/ISecretkeeper.aidl Normal file
View File

@@ -0,0 +1,74 @@
/*
* Copyright (C) 2023 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.secretkeeper;
@VintfStability
/**
* Secretkeeper service definition.
*
* An ISecretkeeper instance provides secure storage of secrets on behalf of other components in
* Android, in particular for protected virtual machine instances. From the perspective of security
* privilege, Secretkeeper must be implemented in an environment with privilege higher than any of
* its clients. Since AVF based protected Virtual Machines are one set of its clients, the
* implementation of ISecretkeeper should live in a secure environment, such as:
* - A trusted execution environment such as ARM TrustZone.
* - A completely separate, purpose-built and certified secure CPU.
*
* TODO(b/291224769): Extend the HAL interface to include:
* 1. Session setup api: This is used to perform cryptographic operations that allow shared keys to
* be exchanged between session participants, typically (but not necessarily) a pVM instance and
* Secretkeeper. This session setup is based on public key cryptography.
* 2. Dice policy operation - These allow sealing of the secrets with a class of Dice chains.
* Typical operations are (securely) updating the dice policy sealing the Secrets above. These
* operations are core to AntiRollback protected secrets - ie, ensuring secrets of a pVM are only
* accessible to same or higher versions of the images.
* 3. Maintenance api: This is required for removing the Secretkeeper entries for obsolete pvMs.
*/
interface ISecretkeeper {
/**
* processSecretManagementRequest method is used for interacting with the Secret Management API
*
* Secret Management API: The clients can use this API to store (& get) 32 bytes of data.
* The API is a CBOR based protocol, which follows request/response model.
* See SecretManagement.cddl for the API spec.
*
* Further, the requests (from client) & responses (from service) must be encrypted into
* ProtectedRequestPacket & ProtectedResponsePacket using symmetric keys agreed between
* the client & service. This cryptographic protection is required because the messages are
* ferried via Android, which is allowed to be outside the TCB of clients (for example protected
* Virtual Machines). For this, service (& client) must implement a key exchange protocol, which
* is critical for establishing the secure channel.
*
* Secretkeeper database should guarantee the following properties:
* 1. Confidentiality: No entity (of security privilege lower than Secretkeeper) should
* be able to get a client's data in clear.
*
* 2. Integrity: The data is protected against malicious Android OS tampering with database.
* ie, if Android (userspace & kernel) tampers with the client's secret, the Secretkeeper
* service must be able to detect it & return error when clients requests for their secrets.
* Note: the integrity requirements also include Antirollback protection ie, reverting the
* database into an old state should be detected.
*
* 3. The data is persistent across device boot.
* Note: Denial of service is not in scope. A malicious Android may be able to delete data,
* but for ideal Android, the data should be persistent.
*
* @param CBOR-encoded ProtectedRequestPacket. See SecretManagement.cddl for its definition.
* @return CBOR-encoded ProtectedResponsePacket. See SecretManagement.cddl for its definition
*/
byte[] processSecretManagementRequest(in byte[] request);
}

116
security/secretkeeper/aidl/android/hardware/security/secretkeeper/SecretManagement.cddl Normal file
View File

@@ -0,0 +1,116 @@
; CDDL for the Secret Management API.
; Also see processSecretManagementRequest method in ISecretkeeper.aidl
; ProtectedRequestPacket is used by client for accessing Secret Management API
; in Secretkeeper service. The service returns ProtectedResponsePacket of the corresponding type.
; ProtectedRequestPacket & ProtectedResponsePacket are encrypted wrappers
; on RequestPacket & ResponsePacket using symmetric keys agreed between Secretkeeper & clients
; (these are referred to as KeySourceToSink & KeySinkToSource)
;
; The API operation required is encoded using 'Opcode', the arguments using 'Params'
; and returned values as 'Result'.
ProtectedRequestPacket =
ProtectedGetVersionRequest / ProtectedStoreSecretRequest / ProtectedGetSecretRequest
ProtectedResponsePacket =
ProtectedGetVersionResponse / ProtectedStoreSecretResponse / ProtectedGetSecretResponse
ProtectedGetVersionRequest = ProtectedRequestPacket<GetVersionRequestPacket>
ProtectedGetVersionResponse = ProtectedResponsePacket<GetVersionResponsePacket>
ProtectedStoreSecretRequest = ProtectedRequestPacket<StoreSecretRequestPacket>
ProtectedStoreSecretResponse = ProtectedResponsePacket<StoreSecretResponsePacket>
ProtectedGetSecretRequest = ProtectedRequestPacket<GetSecretRequestPacket>
ProtectedGetSecretResponse = ProtectedResponsePacket<GetSecretResponsePacket>
GetVersionRequestPacket = RequestPacket<GetVersionOpcode, GetVersionParams>
GetVersionResponsePacket = ResponsePacket<GetVersionResult>
StoreSecretRequestPacket = RequestPacket<StoreSecretOpcode, StoreSecretParams>
StoreSecretResponsePacket = ResponsePacket<StoreSecretResult>
GetSecretRequestPacket = RequestPacket<GetOpcode, GetSecretParams>
GetSecretResponsePacket = ResponsePacket<GetSecretResult>
RequestPacket<Opcode, Params> = [
Opcode,
Params
]
ResponsePacket<Result> = ResponsePacketError / ResponsePacketSuccess<Result>
ResponsePacketSuccess = [
0, ; Indicates successful Response
result : Result
]
ResponsePacketError = [
error_code: ErrorCode, ; Indicate the error
error_message: tstr ; Additional human-readable context
]
Opcode = &(
GetVersionOpcode: 1, ; Get version of the SecretManagement API
StoreSecretOpcode: 2, ; Store a secret
GetSecretOpcode: 3, ; Get the secret
)
GetVersionParams = ()
GetVersionResult = (version : uint)
StoreSecretParams = (
id : bstr .size 64 ; Unique identifier of the secret
secret : bstr .size 32,
sealing_policy : bstr .cbor DicePolicy, ; See DicePolicy.cddl for definition of DicePolicy
)
StoreSecretResult = ()
GetSecretParams = (
id : bstr .size 64 ; Unique identifier of the secret
; Use this to update the sealing policy associated with a secret during GetSecret operation.
updated_sealing_policy : bstr .cbor DicePolicy / nil,
)
GetSecretResult = (secret : bstr .size 32)
ProtectedRequestPacket<Payload, Key> = CryptoPayload<Payload, KeySourceToSink>
ProtectedResponsePacket<Payload, Key> = ProtectedResponseError
/ ProtectedResponseSuccess<Payload>
ProtectedResponseSuccess<Payload> = [
0, ; Indicates successful crypto operations. Note: Payload
; may contain Error from functional layer.
message: CryptoPayload<Payload, KeySinkToSource> ; message is the encrypted payload
]
ProtectedResponseError = [
error_code: CryptoErrorCode, ; Indicates the error. This is in cleartext & will be
; visible to Android. These are errors from crypto
; layer & indicates the request could not even be read
message: tstr ; Additional human-readable context
]
CryptoPayload<Payload, Key> = [ ; COSE_Encrypt0 (untagged), [RFC 9052 s5.2]
protected: bstr .cbor {
1 : 3, ; Algorithm: AES-GCM mode w/ 256-bit key, 128-bit tag
4 : bstr ; key identifier, uniquely identifies the session
; TODO(b/291228560): Refer to the Key Exchange spec.
},
unprotected: {
5 : bstr .size 12 ; IV
},
ciphertext : bstr ; AES-GCM-256(Key, bstr .cbor Payload)
; AAD for the encryption is CBOR-serialized
; Enc_structure (RFC 9052 s5.3) with empty external_aad.
]
; TODO(b/291224769): Create a more exhaustive set of CryptoErrorCode
CryptoErrorCode = &(
CryptoErrorCode_SessionExpired: 1,
)
; TODO(b/291224769): Create a more exhaustive set of ErrorCodes
ErrorCode = &(
; Use this as if no other error code can be used.
ErrorCode_UnexpectedServerError: 1,
; Indicate the Request was malformed & hence couldnt be served.
ErrorCode_RequestMalformed: 2,
)
; INCLUDE DicePolicy.cddl for: DicePolicy