Document protocol details in READMEs by ameba23 · Pull Request #37 · flashbots/attested-tls

ameba23 · 2026-04-27T09:13:36Z

This adds more details to the top-level and crate-level readme files, covering the implementation, intended use and the protocol at a high level.

This also addresses #23 by documenting that particular crates expect a tokio runtime.

* main: doc: qualify the `build()` method description chore: switch to single-threaded tests chore: switch to blocking verifier feat: implement allow-lists of leaf cert pubkeys feat: implement builder for cert resolver/verifier fix: be explicit w.r.t attestation types fix: make `AttestedCertificateResolver::new()` non-async fix: re-export `ra_tls::rcgen` feat: allow using custom key-pairs chore: rename primary_name to subject chore: make detect() non-async Attested certificate verifier should require client authentication Bump rustls-webpki from 0.103.12 to 0.103.13

0x416e746f6e

great docs!

0x416e746f6e · 2026-05-18T07:59:29Z

+PCCS enabled and calling verification APIs, including
+`verify_attestation_sync()`, is expected to happen from within a Tokio runtime,
+and will panic if called outside of one.
+
+Note that the synchronous verification API is synchronous in its return type,
+but it still relies on Tokio-backed background tasks for PCCS pre-warm
+and cache refresh.


rephrase:

Suggested change

PCCS enabled and calling verification APIs, including

`verify_attestation_sync()`, is expected to happen from within a Tokio runtime,

and will panic if called outside of one.

Note that the synchronous verification API is synchronous in its return type,

but it still relies on Tokio-backed background tasks for PCCS pre-warm

and cache refresh.

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.

0x416e746f6e · 2026-05-18T08:06:46Z

+- `AttestedCertificateResolver`: issues TLS certificates which contain an
+  embedded attestation and handles renewal. 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 certificate and the embedded
+  attestation 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).


rephrase:

Suggested change

- `AttestedCertificateResolver`: issues TLS certificates which contain an

embedded attestation and handles renewal. 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 certificate and the embedded

attestation 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).

- `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).

0x416e746f6e · 2026-05-18T08:16:47Z

+
+## Protocol details
+
+The resolver issues a short-lived X.509 leaf certificate whose attestation is


grammar:

Suggested change

The resolver issues a short-lived X.509 leaf certificate whose attestation is

The resolver issues a short-lived X.509 leaf certificate which attestation is

(certificate is a thing, not a person)

0x416e746f6e · 2026-05-18T08:21:12Z

+- Issues either a self-signed leaf certificate or a leaf signed by a provided
+  private CA


rephrase:

Suggested change

- Issues either a self-signed leaf certificate or a leaf signed by a provided

private CA

- Issues either a self-signed certificate or a leaf certificate signed by a

provided (private) CA

0x416e746f6e · 2026-05-18T08:23:53Z

+The attestation is embedded using the `ra-tls` certificate extension format.
+When verifying a certificate, this crate first tries to parse the `ra-tls`


provide hyperlinks:

Suggested change

The attestation is embedded using the `ra-tls` certificate extension format.

When verifying a certificate, this crate first tries to parse the `ra-tls`

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)

0x416e746f6e · 2026-05-18T08:28:59Z

+
+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:


nit:

Suggested change

It can:

It can:

0x416e746f6e · 2026-05-18T08:29:22Z

+That applies even when calling synchronous-looking APIs such as
+`get_collateral_sync()`: cache miss repair, proactive refresh, and startup
+pre-warm are all driven by Tokio background tasks.


rephrase:

Suggested change

That applies even when calling synchronous-looking APIs such as

`get_collateral_sync()`: cache miss repair, proactive refresh, and startup

pre-warm are all driven by Tokio background tasks.

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.

0x416e746f6e · 2026-05-18T08:32:51Z

+Primitives for attested TLS channels.

-Provided crates:
+This workspace contains components for a protocol which binds confidential


grammar:

Suggested change

This workspace contains components for a protocol which binds confidential

This workspace contains components for a protocol that binds confidential

("binds confidential computing attestation evidence" is definitive property of the protocol, also called "restrictive")

0x416e746f6e · 2026-05-18T08:35:04Z

+- An inner TLS session which uses a certificate with attestation
+  evidence embedded in an extension.


rephrase:

Suggested change

- An inner TLS session which uses a certificate with attestation

evidence embedded in an extension.

- An inner TLS session uses a certificate with attestation evidence embedded in

an extension.

0x416e746f6e · 2026-05-18T08:39:14Z

+The inner identity should not be persistent and represents a particular CVM
+instance and particular OS image build.


rephrase:

Suggested change

The inner identity should not be persistent and represents a particular CVM

instance and particular OS image build.

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).

ameba23 added 3 commits April 27, 2026 10:25

Document protocol details in README

e4e8bff

Add more explanation to top-level readme

34a3e10

Add more explanation to nested-tls readme

72114e2

ameba23 requested a review from 0x416e746f6e May 6, 2026 06:47

ameba23 added 2 commits May 8, 2026 08:45

Update documentation to match implementation following latest changes

fc24c8a

0x416e746f6e approved these changes May 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document protocol details in READMEs#37

Document protocol details in READMEs#37
ameba23 wants to merge 5 commits into
mainfrom
peg/document-protocol-details

ameba23 commented Apr 27, 2026 •

edited

Loading

Uh oh!

0x416e746f6e left a comment

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

0x416e746f6e May 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Protocol details

		The resolver issues a short-lived X.509 leaf certificate whose attestation is

		- Issues either a self-signed leaf certificate or a leaf signed by a provided
		private CA

		The attestation is embedded using the `ra-tls` certificate extension format.
		When verifying a certificate, this crate first tries to parse the `ra-tls`

-The attestation is embedded using the `ra-tls` certificate extension format.
-When verifying a certificate, this crate first tries to parse the `ra-tls`
+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)

	This workspace contains components for a protocol which binds confidential
	This workspace contains components for a protocol that binds confidential

		- An inner TLS session which uses a certificate with attestation
		evidence embedded in an extension.

		The inner identity should not be persistent and represents a particular CVM
		instance and particular OS image build.

-The inner identity should not be persistent and represents a particular CVM
-instance and particular OS image build.
+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).

Conversation

ameba23 commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

0x416e746f6e left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ameba23 commented Apr 27, 2026 •

edited

Loading