Secretkeeper provides secure storage of secrets on behalf of other components in Android. It is specified as a HAL and must be implemented in an environment with privilege higher than any of its clients. Typically this will be a trusted execution environment such as ARM TrustZone.
The core SecretManagement API is a CBOR based protocol and can be used to store (& get) 32 bytes of secret data. Secretkeeper supports establishing a secure channel with clients as well as deletion of some or all data.
The requests (from the client) & responses (from Secretkeeper) must be encrypted using symmetric keys agreed between the client & service. For this, Secretkeeper (& client) must implement the AuthGraph key exchange protocol to establish a secure channel between them.
In the key exchange protocol, the client acts as P1 (source) and Secretkeeper as P2 (sink). The interface returned by getAuthGraphKe() can be used to invoke methods on the sink.
The storage layer of Secretkeeper, in addition to conventional storage, provides DICE policy based access control. A client can restrict the access to its stored entry.
The underlying storage of Secretkeeper should offer the following security guarantees:
Secretkeeper uses DICE policy based access control. Each secret is associated with a sealing policy, which is a DICE policy. This is a required input while storing a secret. Further access to this secret is restricted to clients whose DICE chain adheres to the corresponding sealing policy.
Android provides a reference implementation of Secretkeeper as well as the required AuthGraph Key exchange HAL. The implementation is modular and easily configurable. For example, partners can plug in their implementation of AES-GCM, RNG instead of using the BoringSSL implementations.
Navigating this project:
Outside this directory:
To use the Rust reference implementation on an Android device, device-specific implementations of various abstractions must be provided. This section describes the different areas of functionality that are required.
Using the reference implementation requires a Rust toolchain that can target the secure environment. This toolchain (and any associated system libraries) must also support heap allocation (or an approximation thereof) via the alloc
sysroot crate.
If the BoringSSL-based implementation of cryptographic functionality is used (see below), then some parts of the Rust std
library must also be provided, in order to support the compilation of the openssl
wrapper crate.
Checklist:
alloc
.Secretkeeper appears as a HAL service in userspace, and so an executable that registers for and services the Secretkeeper HAL must be provided.
The implementation of this service is mostly provided by the secretkeeper_hal
crate (and by the associated authgraph_hal
crate), but a driver program must be provided that:
The Secretkeeper HAL service (which runs in userspace) must communicate with the Secretkeeper TA (which runs in the secure environment). The reference implementation assumes the existence of two reliable, message-oriented, bi-directional communication channels for this (one for Secretkeeper, one for AuthGraph), as encapsulated in the authgraph_hal::channel::SerializedChannel
trait.
This trait has a single method execute()
, which takes as input a request message (as bytes), and returns a response message (as bytes) or an error.
Two instances of this trait must be provided to the secretkeeper_hal::SecretkeeperService
type, which allows it to service Binder requests by forwarding the requests to the TA as request/response pairs.
Checklist:
init.rc
configuration for the HAL service.SerializedChannel
trait, for reliable HAL <-> TA communication.The Trusty implementation of the Secretkeeper HAL provides an example of all of the above.
The secretkeeper_core::ta
module provides the majority of the implementation of the Secretkeeper TA, but needs a driver program that:
authgraph_core::ta::AuthGraphTa
instance.secretkeeper_core_ta::SecretkeeperTa
instance.SecretkeeperTa::process()
or AuthGraphTa::process()
, receiving a responseChecklist:
main
equivalent for TA, handling scheduling of incoming requests.The Trusty implementation of the Secretkeeper TA provides an example of all of the above.
If Secretkeeper is used to store secrets on behalf of protected virtual machines (pVMs), then the bootloader is required to retrieve the identity of Secretkeeper (expressed as a public key) at boot time so that the identity can be (securely) provided to pVM instances, as described below. The bootloader should use the secretkeeper_core::ta::bootloader::GetIdentityKey
message to do this.
Checklist:
GetIdentityKey
request at boot time.The Secretkeeper TA requires implementations for low-level cryptographic primitives to be provided, in the form of implementations of the various Rust traits held in authgraph_core::traits
.
Note that some of these traits include methods that have default implementations, which means that an external implementation is not required (but can be provided if desired).
Checklist:
BoringSSL-based implementations are available for all of the above.
The Secretkeeper requires an implementation of the secretkeeper_core::store::KeyValueStore
trait that abstracts away access to secure storage.
The Trusty implementation of the Secretkeeper TA includes an example implementation.
Checklist:
KeyValueStore
implementation.Microdroid instances use Secretkeeper to store their secrets while protecting against the Rollback attacks on the boot images & packages. Such secrets (and data protected by the secrets) are accessible on updates but not on downgrades of boot images and apks.
As described above, Microdroid as a Secretkeeper client establishes a secure channel with the Secretkeeper implementation using the AuthGraph key exchange protocol. As part of this Microdroid needs to verify that it is communicating with the real Secretkeeper.
To achieve this the Secretkeeper implementation should generate a per-boot key pair and use that as its identity in the AuthGraph protocol. The public key from the pair then needs to be securely communicated to the Microdroid VM which uses it to verify the identity of Secretkeeper.
The public key is transported as a CBOR-encoded COSE_key, as a PubKeyEd25519 / PubKeyECDSA256 / PubKeyECDSA384 as defined in generateCertificateRequestV2.cddl.
Microdroid expects the public key to be present in the Linux device tree as the value of the secretkeeper_public_key
property of the /avf
node - exposed to userspace at /proc/device-tree/avf/secretkeeper_public_key
.
When a protected VM is started, AVF populates this property in the VM DT /avf
node from the corresponding property in the /avf/reference/avf
node in the host DT. pvmfw verifies that the value is correct using the VM reference DT that is included in the pvmfw configuration data.
The Android bootloader should request the public key from the Secretkeeper implementation at boot time and populate it in both the host Android DT and the VM Reference DT for pvmfw.
The reference code for Secretkeeper defines a protocol that can be used by the bootloader to retrieve the public key; see core/src/ta/bootloader.rs.