README
¶
ConfidentialVM Attestation Reverse Proxy
Overview
This application provides a reverse proxy with TLS termination, supporting confidentialVM attestation for both client and server sides. It allows for secure communication between a client and a server, with attestation verification to ensure the integrity of the communication.
Features
- Client-side TLS termination with confidentialVM attestation verification.
- Server-side TLS termination with confidentialVM attestation verification.
- Reverse proxy functionality to forward requests between client and server.
Both the client-side and the server-side TLS termination can be separately configured to provide attestations and verify attestations.
Limitations
- TDX support only, SEV-SNP can be added
- uses edgeless systems constellation codebase to provide attestation on Azure using MAA
Modes of operation
Server
- TCP/HTTP server with regular TLS on the server side, to allow the client to verify the server's TLS certificate.
- TCP/HTTP server with aTLS on the server side, to allow client verify the server measurement.
- TCP/HTTP server that verifies the client (via client-side aTLS certificate). The measurement is passed along to the proxy target as header. Valid for both server-side TLS and aTLS.
- TCP/HTTP server that performs mutual attestation, that is it both provides its own attestation, and verifies the client. The client's measurement is forwarded as a header.
Client
- Client making a request, verifying server's TLS certificate.
- Client making a request, verifying server aTLS certificate (supporting one or multiple whitelisted measurements). The server's measurement is returned as a header.
- Client making a request with a client-side aTLS cert.
- Client making a request mutual attestation, both verifying server aTLS and providing the client-side aTLS handshake. The sever's measurement is returned as a header.
proxy-server
Command line arguments
--listen-addr: address to listen on (default: "127.0.0.1:8080")--target-addr: address to proxy requests to (default: "https://localhost:80")--server-attestation-type: type of attestation to present (none, azure-tdx) (default: "azure-tdx")--tls-certificate-path: Path to certificate (PEM file) to present. Only valid for --server-attestation-type=none and with--tls-private-key-path.--tls-private-key-path: Path to private key file for the certificate (PEM). Only valid with --tls-certificate-path.--client-attestation-type: type of attestation to expect and verify (none, azure-tdx) (default: "none")--client-measurements: optional path to JSON measurements enforced on the client--log-json: log in JSON format (default: false)--log-debug: log debug messages (default: false)--help, -h: show help
Build the server
# Build the binary
make build-proxy-server
# Build the Docker image
make docker-images
Run the server
# Run the binary
sudo ./build/proxy-server --listen-addr=<listen-addr> --target-addr=<target-addr> [--server-attestation-type=<server-attestation-type>] [--client-attestation-type=<client-attestation-type>] [--client-measurements=<client-measurements>]
# Run the Docker image
docker run -p 8080:8080 -e LOG_JSON=1 cvm-proxy-server
By default the server will present Azure TDX attestation, and you can modify that via the --server-attestation-type flag.
The server can be made to present a regular TLS certificate through --tls-certificate-path and --tls-private-key-path flags instead of aTLS one.
By default the server will not verify client attestations, you can change that via --client-attestation-type and --client-measurements flags. Valid for both aTLS and regular TLS.
This repository contains a dummy http server that you can use for testing the server. Simply run go run ./cmd/dummy-server/main.go and point your --target-addr=http://127.0.0.1:8085. You can also use the sample measurements.json.
proxy-client
Command line arguments
--listen-addr: address to listen on (default: "127.0.0.1:8080")--target-addr: address to proxy requests to (default: "https://localhost:80")--server-attestation-type: type of attestation to expect and verify (none, azure-tdx) (default: "azure-tdx")--server-measurements: optional path to JSON measurements enforced on the server--verify-tls: verify server's TLS certificate instead of server's attestation. Only valid for server-attestation-type=none.--tls-ca-certificate: additional CA certificate to verify against (PEM) [default=no additional TLS certs]. Only valid with --verify-tls.--client-attestation-type: type of attestation to present (none, azure-tdx) (default: "none")--log-json: log in JSON format (default: false)--log-debug: log debug messages (default: false)--help, -h: show help
Build the client
make build-proxy-client
Run the client
./build/proxy-client --listen-addr=<listen-addr> --target-addr=<target-addr> [--server-measurements=<server-measurements-file>] [--server-attestation-type=<server-attestation-type>] [--client-attestation-type=<client-attestation-type>]
By default the client will expect the server to present an Azure TDX attestation, and you can modify that via the --server-attestation-type and --server-measurements flags.
The server can also be a regular TLS server, which you can configure with the --verify-tls flag, which is only valid in combination with --server-attestation-type=none. Non-standard CA for the server can also be configured with --tls-ca-certificate.
By default the client will not present client attestations, you can change that via --client-attestation-type flag. Valid for both aTLS and TLS server proxies.
This repository contains a sample measurements.json file that you can use. The client will (correctly) complain about unexpected measurements that you can then correct.
Measurements
Attestation verification requires the expected measurements which you pass through the --{client, server}-measurements flag.
The measurements are expected to be a JSON map, and multiple valid measurements can be provided. The verifier will attempt to verify with each of the provided measurements, and if any succeeds, the attestation is assumed valid.
The (single) validated measurement is json-marshalled and forwarded (returned in the case of client) as "X-Flashbots-Measurement" header, and the type of attestation as "X-Flashbots-Attestation-Type" header. For mapping attestation types to OIDs and issuers, see internal/attestation/variant/variant.go. To only validate and forward the measurement (as opposed to also authorizing the measurement against an expected one), simply provide an empty expected measurements object.
Notes
- Files in
internal/are copied from https://github.com/edgelesssys/constellation
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
Package common contains shared utilities
|
Package common contains shared utilities |
|
internal
|
|
|
api/attestationconfigapi/cli/client
package client contains code to manage CVM versions in Constellation's CDN API.
|
package client contains code to manage CVM versions in Constellation's CDN API. |
|
api/client
Package client provides a client for the versions API.
|
Package client provides a client for the versions API. |
|
api/fetcher
Package fetcher implements a client for the Constellation Resource API.
|
Package fetcher implements a client for the Constellation Resource API. |
|
api/versionsapi/cli
This package provides a CLI tool to interact with the Constellation versions API.
|
This package provides a CLI tool to interact with the Constellation versions API. |
|
atls
aTLS provides config generation functions to bootstrap attested TLS connections.
|
aTLS provides config generation functions to bootstrap attested TLS connections. |
|
attestation
This package deals with the low level attestation and verification logic of Constellation nodes.
|
This package deals with the low level attestation and verification logic of Constellation nodes. |
|
attestation/aws/snp
--------- WARNING! ---------
|
--------- WARNING! --------- |
|
attestation/azure/tdx
package tdx implements attestation for TDX on Azure.
|
package tdx implements attestation for TDX on Azure. |
|
attestation/idkeydigest
Package idkeydigest provides type definitions for the `idkeydigest` value of SEV-SNP attestation.
|
Package idkeydigest provides type definitions for the `idkeydigest` value of SEV-SNP attestation. |
|
attestation/initialize
Package initialize implements functions to mark a node as initialized in the context of cluster attestation.
|
Package initialize implements functions to mark a node as initialized in the context of cluster attestation. |
|
attestation/simulator
TPM2 simulator used for unit tests.
|
TPM2 simulator used for unit tests. |
|
attestation/snp
Package SNP provides types shared by SNP-based attestation implementations.
|
Package SNP provides types shared by SNP-based attestation implementations. |
|
attestation/tdx
Package TDX implements attestation for Intel TDX.
|
Package TDX implements attestation for Intel TDX. |
|
attestation/variant
Package variant defines Attestation variants for different CSPs.
|
Package variant defines Attestation variants for different CSPs. |
|
cloud/aws
Implements interaction with the AWS API.
|
Implements interaction with the AWS API. |
|
cloud/azure
Implements interaction with the Azure API.
|
Implements interaction with the Azure API. |
|
cloud/azureshared
Package gcpshared contains code to parse and define data types relevant for Microsoft Azure.
|
Package gcpshared contains code to parse and define data types relevant for Microsoft Azure. |
|
cloud/gcp
Implements interaction with the GCP API.
|
Implements interaction with the GCP API. |
|
cloud/gcpshared
Package gcpshared contains code to parse and define data types relevant for Google Cloud Platform.
|
Package gcpshared contains code to parse and define data types relevant for Google Cloud Platform. |
|
cloud/qemu
This package provides an interface to fake a CSP API for QEMU instances.
|
This package provides an interface to fake a CSP API for QEMU instances. |
|
compatibility
Package compatibility offers helper functions for comparing and filtering versions.
|
Package compatibility offers helper functions for comparing and filtering versions. |
|
config/imageversion
Package imageversion contains the pinned container images for the config.
|
Package imageversion contains the pinned container images for the config. |
|
config/migration
Package migration contains outdated configuration formats and their migration functions.
|
Package migration contains outdated configuration formats and their migration functions. |
|
constants
Package constants contains the constants used by Constellation.
|
Package constants contains the constants used by Constellation. |
|
containerimage
This package provides container image names, registry info and digests.
|
This package provides container image names, registry info and digests. |
|
crypto
Package crypto provides functions to for cryptography and random numbers.
|
Package crypto provides functions to for cryptography and random numbers. |
|
crypto/testvector
Package testvector provides test vectors for key derivation and crypto functions.
|
Package testvector provides test vectors for key derivation and crypto functions. |
|
cryptsetup
Package cryptsetup provides a wrapper around libcryptsetup.
|
Package cryptsetup provides a wrapper around libcryptsetup. |
|
encoding
Package encoding provides data types and functions for JSON or YAML encoding/decoding.
|
Package encoding provides data types and functions for JSON or YAML encoding/decoding. |
|
file
Package file provides functions that combine file handling, JSON marshaling and file system abstraction.
|
Package file provides functions that combine file handling, JSON marshaling and file system abstraction. |
|
grpc/atlscredentials
Package atlscredentials handles creation of TLS credentials for attested TLS (ATLS).
|
Package atlscredentials handles creation of TLS credentials for attested TLS (ATLS). |
|
grpc/dialer
Package dialer provides a grpc dialer that can be used to create grpc client connections with different levels of ATLS encryption / verification.
|
Package dialer provides a grpc dialer that can be used to create grpc client connections with different levels of ATLS encryption / verification. |
|
grpc/grpclog
grpclog provides a logging utilities for gRPC.
|
grpclog provides a logging utilities for gRPC. |
|
grpc/retry
Package retry provides functions to check if a gRPC error is retryable.
|
Package retry provides functions to check if a gRPC error is retryable. |
|
grpc/testdialer
Package testdialer provides a fake dialer for testing.
|
Package testdialer provides a fake dialer for testing. |
|
imagefetcher
Package imagefetcher provides helping wrappers around a versionsapi fetcher.
|
Package imagefetcher provides helping wrappers around a versionsapi fetcher. |
|
installer
Package installer provides functionality to install binary components of supported kubernetes versions.
|
Package installer provides functionality to install binary components of supported kubernetes versions. |
|
kms/config
Package config provides configuration constants for the KeyService.
|
Package config provides configuration constants for the KeyService. |
|
kms/kms
Package kms provides an abstract interface for Key Management Services.
|
Package kms provides an abstract interface for Key Management Services. |
|
kms/kms/aws
Package aws implements a KMS backend for AWS KMS.
|
Package aws implements a KMS backend for AWS KMS. |
|
kms/kms/azure
Package azure implements KMS backends for Azure Key Vault and Azure managed HSM.
|
Package azure implements KMS backends for Azure Key Vault and Azure managed HSM. |
|
kms/kms/cluster
Package cluster implements a KMS backend for in cluster key management.
|
Package cluster implements a KMS backend for in cluster key management. |
|
kms/kms/gcp
Package gcp implements a KMS backend for Google Cloud KMS.
|
Package gcp implements a KMS backend for Google Cloud KMS. |
|
kms/kms/internal
Package internal implements the CloudKMS interface using go-kms-wrapping.
|
Package internal implements the CloudKMS interface using go-kms-wrapping. |
|
kms/setup
Package setup provides functions to create a KMS and key store from a given URI.
|
Package setup provides functions to create a KMS and key store from a given URI. |
|
kms/storage
Package storage implements storage backends for DEKs.
|
Package storage implements storage backends for DEKs. |
|
kms/storage/awss3
Package awss3 implements a storage backend for the KMS using AWS S3: https://aws.amazon.com/s3/
|
Package awss3 implements a storage backend for the KMS using AWS S3: https://aws.amazon.com/s3/ |
|
kms/storage/azureblob
Package azureblob implements a storage backend for the KMS using Azure Blob Storage.
|
Package azureblob implements a storage backend for the KMS using Azure Blob Storage. |
|
kms/storage/gcs
Package gcs implements a storage backend for the KMS using Google Cloud Storage (GCS).
|
Package gcs implements a storage backend for the KMS using Google Cloud Storage (GCS). |
|
kms/storage/memfs
Package memfs implements a storage backend for the KMS that stores keys in memory only.
|
Package memfs implements a storage backend for the KMS that stores keys in memory only. |
|
kms/uri
Package uri provides URIs and parsing logic for KMS and storage URIs.
|
Package uri provides URIs and parsing logic for KMS and storage URIs. |
|
kubernetes
Package kubernetes provides data types and custom marshalers for Kubernetes API objects.
|
Package kubernetes provides data types and custom marshalers for Kubernetes API objects. |
|
kubernetes/kubectl
Package kubectl provides a kubectl-like interface for Kubernetes.
|
Package kubectl provides a kubectl-like interface for Kubernetes. |
|
license
Package license provides functions to check a user's Constellation license.
|
Package license provides functions to check a user's Constellation license. |
|
logger
Package logger provides helper functions that can be used in combination with slog to increase functionality or make working with slog easier.
|
Package logger provides helper functions that can be used in combination with slog to increase functionality or make working with slog easier. |
|
maa
Package maa provides an interface for interacting with an MAA service on an infrastructure level.
|
Package maa provides an interface for interacting with an MAA service on an infrastructure level. |
|
mpimage
The mpimage package provides utilities for handling CSP marketplace OS images.
|
The mpimage package provides utilities for handling CSP marketplace OS images. |
|
nodestate
Package nodestate is used to persist the state of a Constellation node to disk.
|
Package nodestate is used to persist the state of a Constellation node to disk. |
|
osimage
package osimage is used to handle osimages in the CI (uploading and maintenance).
|
package osimage is used to handle osimages in the CI (uploading and maintenance). |
|
osimage/archive
package archive is used to archive OS images in S3.
|
package archive is used to archive OS images in S3. |
|
osimage/imageinfo
package imageinfo is used to upload image info JSON files to S3.
|
package imageinfo is used to upload image info JSON files to S3. |
|
osimage/measurementsuploader
package measurementsuploader is used to upload measurements (v2) JSON files (and signatures) to S3.
|
package measurementsuploader is used to upload measurements (v2) JSON files (and signatures) to S3. |
|
osimage/nop
package nop implements a no-op for CSPs that don't require custom image upload functionality.
|
package nop implements a no-op for CSPs that don't require custom image upload functionality. |
|
osimage/secureboot
package secureboot holds secure boot configuration for image uploads.
|
package secureboot holds secure boot configuration for image uploads. |
|
osimage/uplosi
package uplosi implements uploading os images using uplosi.
|
package uplosi implements uploading os images using uplosi. |
|
retry
Package retry provides a simple interface for retrying operations.
|
Package retry provides a simple interface for retrying operations. |
|
semver
Package semver provides functionality to parse and process semantic versions, as they are used in multiple components of Constellation.
|
Package semver provides functionality to parse and process semantic versions, as they are used in multiple components of Constellation. |
|
sigstore/keyselect
Package keyselect is used to select the correct public key for signature verification.
|
Package keyselect is used to select the correct public key for signature verification. |
|
staticupload
Package staticupload provides a static file uploader/updater/remover for the CDN / static API.
|
Package staticupload provides a static file uploader/updater/remover for the CDN / static API. |
|
validation
Package validation provides a unified document validation interface for use within the Constellation CLI.
|
Package validation provides a unified document validation interface for use within the Constellation CLI. |
|
verify
Package verify provides the types for the verify report in JSON format.
|
Package verify provides the types for the verify report in JSON format. |
|
versions
Package versions defines the supported versions of Constellation components.
|
Package versions defines the supported versions of Constellation components. |
|
versions/hash-generator
hash-generator updates the binary hashes and kubeadm patches in versions.go in place.
|
hash-generator updates the binary hashes and kubeadm patches in versions.go in place. |
|
Package proxy contains the core proxy functionality and aTLS configuration
|
Package proxy contains the core proxy functionality and aTLS configuration |
Click to show internal directories.
Click to hide internal directories.