# Trusty AuthMgr-FE

This directory contains the source for the AuthMgr-FE TA. This TA was built for situations in
which trusty is a VM guest, most often running as a protected VM. The TA is designed to be the
only user space entity in a trusty VM that has access to the [DICE handover from pvmfw], which is
presented to the trusty kernel in a `reserved-memory` node by pvmfw. As the user space owner of the
VM's DICE chain and associated CDIs, the TA serves two functions:

1. AuthMgr-FE is the hwbcc server for protected VMs
2. AuthMgr-FE facilitates authorized connections to trusted HALs via the authmgr protocol.

[Dice handover from pvmfw]: https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:packages/modules/Virtualization/guest/pvmfw/README.md

## Useful AuthMgr references

- [The AuthMgr protocol documentation](https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/see/authmgr/aidl/README.md)
- [The core AuthMgr-FE and AuthMgr-BE library source](https://cs.android.com/android/platform/superproject/main/+/main:system/see/authmgr/)

## hwbcc server

In trusty, the [hwbcc interface] allows user space TAs like Keymint to obtain DICE cert chains
describing the current pVM and perform signing operations using keys derived from CDIs associated
with that cert chain.

The implementation of the server is in the [pvmdice] library. Not all `hwbcc` operations are
currently supported, since we didn't initially add support for operations that had no existing
use cases. The currently supported operations are:

1. `HWBCC_GET_BCC`
2. `HWBCC_SIGN_DATA`

The server is compatible with both the [C client lib][hwbcc-c-client] and [Rust client lib][hwbcc-rust-client].

[hwbcc-c-client]: https://cs.android.com/android/platform/superproject/main/+/main:trusty/user/base/lib/hwbcc/client/
[hwbcc-rust-client]: https://cs.android.com/android/platform/superproject/main/+/main:trusty/user/base/lib/hwbcc/rust/src/lib.rs
[hwbcc interface]: https://cs.android.com/android/platform/superproject/main/+/main:trusty/user/base/interface/hwbcc/
[pvmdice]: https://cs.android.com/android/platform/superproject/main/+/main:trusty/user/base/lib/pvmdice/

## AuthMgr protocol implementation

The AuthMgr-FE TA implementation of the AuthMgr protocol allows a pVM to
authenticate to an AuthMgr-BE in a secure partition and retrieve authenticated and authorized
connections to trusted hal services in the form of Binder objects. The core traits and
phase 1 of the protocol are implemented in [src/authorization.rs](src/authorization.rs)
and phase 2 of the protocol is implemented in [src/accessor.rs](src/accessor.rs) .

### Authenticating the pVM - AuthMgr Phase 1

On TA startup, the AuthMgr-FE will use the pVM's DICE handover to authenticate itself to the
AuthMgr-BE. Failure to authenticate will result in the TA exiting. Successful authentication
of the VM is crucial, since this step provides rollback protection of the OS image.

Rollback protection is provided via the DICE policy that AuthMgr-FE constructs. That policy
ensures that once a given version, `N`, of the VM is authenticated by the AuthMgr-BE, an older
version `(<N)` of the VM cannot be successfully authenticated by the AuthMgr-BE.

### The trusty service_manager lib

All Binder interfaces in trusty can be retrieved via the trusty [service_manager] library.
We don't aim to give comprehensive documentation of that library here, but give an overview
to explain how AuthMgr-FE interacts with it.

The `service_manager` library implements an API surface as close as possible to the upstream
Binder `ServiceManager` interface, so it may be familiar if you've worked with Binder in
Android. To retrieve a Binder object via BinderRpc, one calls `wait_for_interface` with a
service name:

```
let my_binder = service_manager::wait_for_interface("foo.bar.MyInterface/default");
```

`wait_for_interface` connects to the port serving the requested service name and expects to find
either:

1. The requested Binder interface, in which case it returns to the caller.
2. An `ITrustyAccessor` Binder.

The [ITrustyAccessor] interface allows a client to delegate connection establishment for a Binder
object via BinderRpc to a different process. We rely on this to execute the AuthMgr protocol to
retrieve authorized connections to trusted HALs. The fact that this interface is identical
to the upstream Binder `IAccessor` interface is an implementation detail that should never
be relied upon.

[service_manager]: https://cs.android.com/android/platform/superproject/main/+/main:trusty/user/base/lib/service_manager/
[ITrustyAccessor]: https://cs.android.com/android/platform/superproject/main/+/main:trusty/user/base/interface/binder_accessor/trusty/os/ITrustyAccessor.aidl

### AuthMgr-FE ITrustyAccessor implementation

The AuthMgr-FE exposes an `ITrustyAccessor` for every trusted HAL interface it supports.
Practically, this means it creates a port for each Trusted HAL and starts a BinderRpc server
handling requests on that port. When a client uses `service_manager` to request a Trusted HAL
Binder, `AuthMgrFeAccessor::addConnection()` will attempt to execute phase 2 of the AuthMgr
protocol and create an authorized connection to the requested Trusted HAL service. If
successful, it returns a ParcelFileDescriptor (implemented as a Handle in trusty) to the client.
`service_manager::wait_for_interface` takes care of setting up a BinderRpc session on that file
descriptor before it returns.

### Flow Diagram

The following is a sequence diagram, which can be rendered with [js-sequence-diagrams](https://bramp.github.io/js-sequence-diagrams/).
This is automatically supported when viewing in Android code search.

NOTE: This diagram is intended to show a high-level flow of how the AuthMgr-FE interacts with client
TAs and the AuthMgr-BE. It glosses over some specifics of the AuthMgr protocol and does not show
any detail about the implementation of the AuthMgr-BE or how it hands authorized connection
requests over to trusted HAL implementations.

```sequence-diagram
Note over Client TA: Client calls service_manager::wait_for_interface("foo.bar.MyTrustedHal/default")
Client TA->AuthMgrFE TA: ITrustyAccessor::addConnection()
AuthMgrFE TA->AuthMgrFE TA: Derive client DICE cert
AuthMgrFE TA->AuthMgrFE TA: Derive client DICE policy
AuthMgrFE TA-->AuthMgrBE: Create TrustyConnectionToAuthorize
AuthMgrFE TA->AuthMgrBE: AuthMgrFe::authorize_connection(...)
AuthMgrBE->AuthMgrFE TA: Ok(...)
AuthMgrFE TA->Client TA: return fd from TrustyConnectionToAuthorize
Note over Client TA: service_manager::wait_for_interface sets\nup Binder with setupPreconnectedClient\nand returns
Note over Client TA: Client uses Binder, now served\n by BinderRpc to MyTrustedHal
```

## Configuration Options

### AUTHMGRFE_LAZY_PHASE_1
Setting this to `true` instructs the AuthMgr-FE TA to defer phase 1 of the AuthMgr protocol until
it receives its first request for an authorized connection. The default behavior (`false`) is to
attempt to authenticate the pVM early on TA startup.

## Insecure Configuration Options
The following build-time configs can be useful for testing.

### AUTHMGRFE_FAKE_DICE_CHAIN
Setting this to `true` instructs the AuthMgr-FE TA to use a hard-coded fake DICE handover
directly from user space. It will not attempt to use the DICE handover provided to the trusty
kernel. This fake DICE handover will also be used to initialize `PvmDice`. This config is only
allowed if `TEST_BUILD` is also set to `true`.