# The Case for EAR and CoCo

## EAR (EAT Attestation Result)

[EAR](https://datatracker.ietf.org/doc/draft-fv-rats-ear/) is a format for carrying attestation results, i.e., the output of an appraisal over attester-produced evidence.

EAR is an [EAT](https://datatracker.ietf.org/doc/draft-ietf-rats-eat/) token that can be serialised as [JWT](https://www.rfc-editor.org/rfc/rfc7519) or [CWT](https://www.rfc-editor.org/rfc/rfc8392).

The EAR claims set can be split in three main parts:

* Some top-level metadata,
* One or more attester-specific appraisal records based on the [AR4SI](https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/) information model, and
* An extensible block allocated for application-specific needs.

### Implementation status

Currently, there are two open-source implementations we know of, both under the Veraison project:

* [`veraison/ear`](https://github.com/veraison/ear): complete producer and consumer in Go
* [`veraison/c-ear`](https://github.com/veraison/c-ear): partial consumer in C

## Attestation Results in the KBS Attestation Protocol Flows

A KBC (Key Broker Client) that has authenticated successfully receives an attestation result from the KBS (Key Broker Server) in the response to `POST /kbs/v0/attest`. The result uses a JWT envelope and the claims set looks like this:

{
    "exp": 1568187398,
    "iat": 1568158598,
    "iss": "<URL of the issuing service>",

    "tee-pubkey": "<TEE public key>",
    /* Custom Claims */
}

A CoCo attester can use the attestation result token as a ["passport"](https://www.rfc-editor.org/rfc/rfc9334.html#name-passport-model) (with the cryptographic identity defined by `tee-pubkey` and an explicit validity period provided by the `iat` and `exp` claims) to make (strongly) authenticated requests for resources from external services.

The "Custom Claims" set must include the attestation result from the attestation service, which carries the CoCo attester's TCB status and measurements.

> **Note:** For further details see the [KBS Attestation Protocol](https://github.com/confidential-containers/kbs/blob/main/docs/kbs_attestation_protocol.md#attestation-results-token) documentation.

## Discussion

As described above, the attestation service sends an attestation result to the
KBS containing the appraisal of the CoCo attester.
A further attestation result (in fact, a passport) wraps the original
attestation result produced by the attestation service alongside the identity
key of the CoCo attester. The bundle is then sent back by KBS to KBC where it is processed and used.

The EAR / AR4SI data and info models seem well suited for encoding the core appraisal.
Potentially, it could also be employed for the wrapping passport, although this is not strictly necessary.

flowchart LR
    KBC -- "EAR{TEE passport} (?)"  --- KBS
    KBS -- "EAR{CoCo appraisal}" --- AS["attestation service"]

There seems to be value adopting a standardised format like EAR / AR4SI for at least the following reasons:

1. Interoperability outside the CoCo flows - for example to reuse the AR computed by CoCo in subsequent TLS exchanges involving the CoCo attester,
1. Ease the task of defining and computing authorization policies by relying parties due to the reliance on AR4SI's "trustworthiness vector" to present a normalized view of the evaluation results. An example that uses [OPA](https://www.openpolicyagent.org) to evaluate a EAR can be found [here](https://play.openpolicyagent.org/p/fBydqNm0G0) (click on the _Evaluate_ button.)
1. Code reuse via existing open-source libraries,
1. Normalised and attester-agnostic result format, which allows to accommodate all currently supported formats as well as any other kinds of attester / CC technologies in the future.

### Some Closing Remarks

Feel free to ask any question you might have. We are also keen to assist you with the integration of EAR into CoCo. I hope you find it worthwhile.