atls

README

Attested TLS (aTLS)

In a confidential computing (CC) environment, attested TLS (aTLS) can be used to establish secure connections between two parties utilizing the remote attestation features of the CC components.

aTLS modifies the TLS handshake by embedding an attestation statement into the TLS certificate. Instead of relying on a Certificate Authority, aTLS uses this attestation statement to establish trust in the certificate.

The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).

Client side verification

1. The client sends a ClientHello message, setting ServerName to a random nonce.

2. The server generates an attestation statement using the clients nonce and its CC capabilities.

   • The attestation is embedded in the server certificate using x509 certificate extensions with an object identifier (OID) to identify the CC attestation type. Take a look at the variant package for implementation details.

3. The client verifies the attestation statement.

4. If successful the client can trust the server to be running the expected configuration, and finish the TLS handshake.

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: ClientHello(nonce)
    Server->>Client: ServerCertificate(AttestationStatement), ServerHelloDone
    Note over Client: Verify Attestation
    Client->>Server: ClientKeyExchange
    Client->>Server: ChangeCipherSpec, Finished
    Server->>Client: #

Server side verification

1. The client sends a ClientHello message

2. The server sends back a certificate and a random nonce. The nonce is encoded as the Distinguished Name of an acceptable CA.

3. The client does not verify the servers certificate, but uses the nonce to generate an attestation based on its CC capabilities.

   • The attestation is embedded in the client certificate using x509 certificate extensions with an OID to identify the CC attestation type.

4. The server verifies the client's attestation statement.

5. If successful the server can trust the client to be running the expected configuration, and finish the TLS handshake.

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: ClientHello
    Server->>Client: ServerCertificate, AcceptableCAs(nonce), ServerHelloDone
    Client->>Server: ClientKeyExchange, ClientCertificate(AttestationStatement)
    Client->>Server: ChangeCipherSpec, Finished
    Note over Server: Verify Attestation
    Server->>Client: ChangeCipherSpec, Finished

Mutual aTLS

1. The client sends a ClientHello message, setting ServerName to a random nonce.

2. The server generates an attestation statement using the clients nonce and its CC capabilities.

   • The attestation is embedded in the server certificate using x509 certificate extensions with an OID to identify the attestation type.
   • A nonce is encoded as the Distinguished Name of an acceptable CA.

3. The client verifies the attestation statement.

4. The client uses the nonce to generate an attestation based on its CC capabilities.

   • The attestation is embedded in the client certificate using x509 certificate extensions with an OID to identify the CC attestation type.

5. The server verifies the client's attestation statement.

6. If all verifications were successful, mutual trust in each others configuration is established, and the TLS handshake can be finished.

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: ClientHello(nonce)
    Server->>Client: ServerCertificate(AttestationStatement), AcceptableCAs(nonce), ServerHelloDone
    Note over Client: Verify Attestation
    Client->>Server: ClientKeyExchange, ClientCertificate(AttestationStatement)
    Client->>Server: ChangeCipherSpec, Finished
    Note over Server: Verify Attestation
    Server->>Client: ChangeCipherSpec, Finished

Documentation

Overview

aTLS provides config generation functions to bootstrap attested TLS connections.

Index

• func CreateAttestationClientTLSConfig(issuer Issuer, validators []Validator) (*tls.Config, error)
• func CreateAttestationServerTLSConfig(issuer Issuer, validators []Validator) (*tls.Config, error)
• type FakeAttestationDoc
• type FakeIssuer
  • func NewFakeIssuer(oid variant.Getter) *FakeIssuer
  • func (FakeIssuer) Issue(_ context.Context, userData []byte, nonce []byte) ([]byte, error)
• type FakeValidator
  • func NewFakeValidator(oid variant.Getter) *FakeValidator
  • func (v FakeValidator) Validate(_ context.Context, attDoc []byte, nonce []byte) ([]byte, error)
• type Issuer
• type Validator
  • func NewFakeValidators(oid variant.Getter) []Validator

Functions

func CreateAttestationClientTLSConfig

func CreateAttestationClientTLSConfig(issuer Issuer, validators []Validator) (*tls.Config, error)

CreateAttestationClientTLSConfig creates a tls.Config object that verifies a certificate with an embedded attestation document.

ATTENTION: The tls.Config ensures freshness of the server's attestation only for the first connection it is used for. If freshness is required, you must create a new tls.Config for each connection or ensure freshness on the protocol level. If freshness is not required, you can reuse this tls.Config.

If no validators are set, the server's attestation document will not be verified. If issuer is nil, the client will be unable to perform mutual aTLS.

func CreateAttestationServerTLSConfig

func CreateAttestationServerTLSConfig(issuer Issuer, validators []Validator) (*tls.Config, error)

CreateAttestationServerTLSConfig creates a tls.Config object with a self-signed certificate and an embedded attestation document. Pass a list of validators to enable mutual aTLS. If issuer is nil, no attestation will be embedded.

Types

type FakeAttestationDoc

type FakeAttestationDoc struct {
	UserData []byte
	Nonce    []byte
}

FakeAttestationDoc is a fake attestation document used for testing.

type FakeIssuer

type FakeIssuer struct {
	variant.Getter
}

FakeIssuer fakes an issuer and can be used for tests.

func NewFakeIssuer

func NewFakeIssuer(oid variant.Getter) *FakeIssuer

NewFakeIssuer creates a new FakeIssuer with the given OID.

func (FakeIssuer) Issue

func (FakeIssuer) Issue(_ context.Context, userData []byte, nonce []byte) ([]byte, error)

Issue marshals the user data and returns it.

type FakeValidator

type FakeValidator struct {
	variant.Getter
	// contains filtered or unexported fields
}

FakeValidator fakes a validator and can be used for tests.

func NewFakeValidator

func NewFakeValidator(oid variant.Getter) *FakeValidator

NewFakeValidator creates a new FakeValidator with the given OID.

func (FakeValidator) Validate

func (v FakeValidator) Validate(_ context.Context, attDoc []byte, nonce []byte) ([]byte, error)

Validate unmarshals the attestation document and verifies the nonce.

type Issuer

type Issuer interface {
	variant.Getter
	Issue(ctx context.Context, userData []byte, nonce []byte) (quote []byte, err error)
}

Issuer issues an attestation document.

type Validator

type Validator interface {
	variant.Getter
	Validate(ctx context.Context, attDoc []byte, nonce []byte) ([]byte, error)
}

Validator is able to validate an attestation document.

func NewFakeValidators

func NewFakeValidators(oid variant.Getter) []Validator

NewFakeValidators returns a slice with a single FakeValidator.