Document protocol details in READMEs

crates/attestation/README.md

@@ -10,6 +10,17 @@ This crate provides:
 - Attestation generation and verification for DCAP and (optionally) Azure
 - Parsing and evaluation of measurement policies
 
+## Runtime Requirements
+
+Verification uses the [`pccs`](../pccs) crate for collateral caching and
+background refresh. As a result, constructing an `AttestationVerifier` with
+PCCS enabled and calling verification APIs is expected to happen from within a
+Tokio runtime and might panic if called outside of one.
+
+Note that although some of the verification API methods are synchronous (for
+example `verify_attestation_sync`), still their functionality depends on
+Tokio-backed background tasks such as PCCS pre-warm and cache refresh.
+
 ## Feature flags
 
 ### `azure`

crates/attested-tls/readme.md

@@ -1,3 +1,91 @@
 # attested-tls
 
-Attested TLS primitives.
+Attested TLS primitives built on `rustls`.
+
+This crate provides two components:
+
+- `AttestedCertificateResolver`: issues and renews TLS certificates with
+  attestations embedded in their extensions.
+
+  It implements [`rustls::server::ResolvesServerCert`](https://docs.rs/rustls/latest/rustls/server/trait.ResolvesServerCert.html)
+  and [`rustls::client::ResolvesClientCert`](https://docs.rs/rustls/latest/rustls/client/trait.ResolvesClientCert.html).
+
+- `AttestedCertificateVerifier`: verifies the TLS certificates and their
+  embedded attestations during TLS handshake.
+
+  It implements [`rustls::client::danger::ServerCertVerifier`](https://docs.rs/rustls/latest/rustls/client/danger/trait.ServerCertVerifier.html)
+  and [`rustls::server::danger::ClientCertVerifier`](https://docs.rs/rustls/latest/rustls/server/danger/trait.ClientCertVerifier.html).
+
+The crate supports both server and client TLS authentication, and can be used as
+the inner attested session inside [`nested-tls`](../nested-tls).
+
+## Protocol details
+
+The resolver issues a short-lived X.509 leaf certificate which attestation is
+bound to:
+
+- The certificate public key
+- The certificate validity window (`not_before`, `not_after`)
+- The certificate primary hostname (common name)
+
+The binding is encoded as:
+
+`SHA-512(public_key_der || not_before_unix_secs || not_after_unix_secs || common_name)`
+
+That 64-byte hash is used as the attestation report data. The embedded
+attestation is verified against the same recomputed value during certificate
+verification.
+
+The certificate resolver:
+
+- Uses one keypair per resolver instance; by default it generates an
+  ECDSA P-256 keypair, but callers can provide a compatible keypair
+- Issues either a self-signed certificate or a leaf certificate signed by a
+  provided (private) CA
+- Embeds attestation evidence into the certificate using the
+  [`ra-tls`](https://github.com/Dstack-TEE/dstack/tree/master/ra-tls) crate
+- Renews the certificate after two-thirds of its validity period has passed
+- Reuses the same keypair for renewed certificates created by the same
+  resolver instance
+
+The certificate verifier:
+
+- Optionally verifies the certificate chain against a provided `RootCertStore`
+- For self-signed server certificates, verifies server name and certificate
+  validity
+- For self-signed client certificates, verifies certificate validity
+- Extracts the embedded attestation from the certificate
+- Recomputes the expected report data from the certificate contents
+- Verifies the attestation through [`attestation`](../attestation)
+- Caches successful attestation verifications until the certificate expires
+  so repeated handshakes with the same certificate avoid repeating quote
+  verification.
+
+Both server-side and client-side attested certificates are supported.
+
+## Certificate format
+
+Certificates are issued with:
+
+- Subject common name set to the configured primary hostname
+- Subject alternative names containing the primary hostname plus any extra SANs
+- Usable for both server and client auth
+
+The attestation is embedded using the [`ra-tls`](https://github.com/Dstack-TEE/dstack/tree/master/ra-tls)
+certificate extension format. When verifying a certificate, this crate first
+tries to parse the [`ra-tls`](https://github.com/Dstack-TEE/dstack/tree/master/ra-tls)
+attestation payload directly. If that fails, it falls back to reading the
+custom attestation extension OID and parsing the JSON payload stored there.
+
+## Relationship to `nested-tls`
+
+This crate does not implement an outer TLS session or any stream nesting by
+itself.
+
+If you want a standard CA-signed outer TLS session plus an inner attested
+TLS session, use this crate together with [`nested-tls`](../nested-tls).
+This is demonstrated in [tests/nested_tls.rs](./tests/nested_tls.rs).
+
+## Runtime requirements
+
+This crate expects to run in a Tokio runtime.

crates/nested-tls/readme.md

@@ -1,3 +1,33 @@
 # nested-tls
 
 Nested TLS primitives.
+
+This crate provides wrappers around `rustls`'s `Acceptor` and `Connector` for
+running one TLS session inside another.
+
+At a high level:
+
+1. The client and server complete an outer TLS handshake over the underlying
+   transport.
+2. A second TLS handshake is then performed over the encrypted outer TLS
+   stream.
+3. The resulting stream can be used like a normal TLS stream.
+
+The main types are:
+
+- `client::NestingTlsConnector`, which performs the outer handshake and then
+  the inner handshake on the client side
+- `server::NestingTlsAcceptor`, which accepts the outer handshake and then the
+  inner handshake on the server side
+
+The crate also includes [Actix](https://actix.rs/) integration for both client
+and server.
+
+This crate does not define the authentication policy of either layer. It only
+composes two `rustls` sessions. In this workspace, the proposed pattern is:
+
+- outer TLS for conventional CA-signed certificates
+- inner TLS for attested certificates via [`attested-tls`](../attested-tls)
+
+After both handshakes complete, callers interact with the returned stream as a
+single nested TLS connection.

crates/pccs/README.md

@@ -0,0 +1,28 @@
+# pccs
+
+An internal Provisioning Certificate Caching Service implementation for DCAP
+collateral fetching and caching.
+
+This crate is used by attestation verification code that needs Intel TDX/SGX
+collateral such as TCB info, QE identity, and certificate revocation lists.
+
+It can:
+
+- Fetch collateral from Intel PCS or a configured PCCS endpoint
+- Cache collateral in-process
+- Pre-warm the cache at startup
+- Refresh cached collateral in the background before expiry
+
+This is an alternative to Intel's reference PCCS server implementation which
+can be embedded in Rust services that verify quotes.
+
+For Intel's terminology and architecture, see the Intel documentation for the
+[Provisioning Certificate Caching Service (PCCS)](https://cc-enabling.trustedservices.intel.com/intel-sgx-tdx-pccs/01/introduction/).
+
+## Runtime Requirements
+
+This crate expects to be used from within a Tokio runtime.
+
+The above applies even when calling synchronous-looking APIs such as
+`get_collateral_sync()` because cache miss repair, proactive refresh, and
+startup pre-warm are all driven by Tokio background tasks.

readme.md

@@ -1,21 +1,53 @@
 # attested-tls
 
-Primitives for attested tls channels.
+Primitives for attested TLS channels.
 
-Provided crates:
+This workspace contains components for a protocol that binds confidential
+computing attestation evidence to TLS certificates.
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant S as Server
+
+  opt Outer TLS
+    Note over C,S: TLS handshake with CA-signed cert
+  end
+
+  Note over C,S: TLS handshake with attestation verification
+  C<<->>S: Application traffic
+```
+
+- An outer TLS session authenticates the service using a standard CA-signed
+  certificate.  This is optional.
+- An inner TLS session uses a certificate with attestation evidence embedded in
+  an extension.
+- The attestation is verified during the inner TLS handshake and is bound to
+  the details of the certificate.
+
+The idea is that the outer identity proves ownership of the domain and can
+potentially persist across CVM re-starts to avoid relying on the CA at boot.
+
+The inner identity represents particular CVM lifetime (for example, it can
+persist across service restarts, but must not persist across CVM reboots, let
+alone CVM image updates).
+
+More details in the individual READMEs of the provided crates:
 
 - [`attested-tls`](./crates/attested-tls) - provides attested TLS via X509
   Certificate extensions and a custom certificate verifier.
 - [`nested-tls`](./crates/nested-tls) - provides two TLS sessions, such that
-  that outer session can be used for a CA signed certificate and the inner
+  the outer session can be used for a CA signed certificate and the inner
   session for attestation.
 - [`attestation`](./crates/attestation) - provides attestation generation,
   verification and measurement handling.
+- [`pccs`](./crates/pccs) provides collateral fetching and caching for DCAP
+  verification.
 - [`mock-tdx`](./crates/mock-tdx) - generates deterministic mock TDX DCAP
   quotes, collateral, and trust roots for tests and development on non-TDX
   hardware.
 
 The included `shell.nix` file can be used with `nix-shell`, `direnv`, or `nix
 develop` to add the dependencies needed by the optional `azure` feature of the
-`attestation` crate on Linux.  See the 
+`attestation` crate on Linux.  See the
 [`attestation` crate readme](./crates/attestation) for details.