kmshandler

Documentation

Overview

Package kmshandler implements an HTTP server and client for interacting with an onchain-governed Trusted Execution Environment (TEE) Key Management System (KMS).

This package provides handlers and clients for secure TEE instance authentication, cryptographic material distribution, and onboarding of new KMS instances. It integrates with blockchain-based governance to verify instance identity and operator authorization before providing cryptographic materials.

Key components:

• Handler: Processes HTTP requests for secrets and onboarding with attestation verification
• Client: Communicates with KMS to obtain instance secrets and handle onboarding

The handler implements a secure workflow for TEE instance provisioning:

1. Verifies attestation evidence against onchain registry
2. Validates optional operator signatures for additional authorization
3. Provides application private keys, signed TLS certificates, and identity information
4. Supports secure KMS onboarding through onchain governance

Index

• Variables
• func ParseWorkloadAndOperatorIdentity(r *http.Request, registry interfaces.OnchainRegistry, csr interfaces.TLSCSR) ([32]byte, [20]byte, error)
• type Handler
  • func NewHandler(kms HandlerKMS, kmsGovernance interfaces.KMSGovernance, ...) *Handler
  • func (h *Handler) HandleOnboard(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) HandleSecrets(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) RegisterRoutes(r chi.Router)
• type HandlerKMS
• type SecretsProvider
  • func (p *SecretsProvider) AppSecrets(url string, contractAddr interfaces.ContractAddress, csr interfaces.TLSCSR) (*interfaces.AppSecrets, error)
  • func (p *SecretsProvider) OnboardKMS(url string, onboardHash [32]byte, kms *simplekms.SimpleKMS, ...) ([]byte, error)
• type SimpleHandlerKMS
  • func NewSimpleHandlerKMS(kms *simplekms.SimpleKMS, addr interfaces.ContractAddress) *SimpleHandlerKMS
  • func (k *SimpleHandlerKMS) VerifyOnboardRequest(onboardRequest interfaces.OnboardRequest) (map[int]string, error)

Variables

var DefaultSecretsProvider = &SecretsProvider{
	Client: http.DefaultClient,
}

DefaultSecretsProvider is a pre-configured SecretsProvider instance with default HTTP client. It can be used directly for most applications without additional configuration.

Functions

func ParseWorkloadAndOperatorIdentity

func ParseWorkloadAndOperatorIdentity(r *http.Request, registry interfaces.OnchainRegistry, csr interfaces.TLSCSR) ([32]byte, [20]byte, error)

ParseWorkloadAndOperatorIdentity extracts and verifies the TEE instance identity and operator information from attestation evidence and CSR.

It performs the following verification steps: 1. Extracts attestation type and measurements from headers 2. Computes the workload identity through the onchain governance contract 3. Parses the CSR to extract any operator signature extensions 4. If an operator signature is present, recovers the operator's Ethereum address

This implements a critical security verification step ensuring that only properly attested instances with authorized operators can receive cryptographic materials.

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler processes HTTP requests for the onchain-governed TEE Key Management Service. It integrates with blockchain-based governance contracts to verify identity, authenticate operators, and provide cryptographic materials to authorized instances.

The handler is responsible for critical security operations such as: - Verifying TEE instance attestation evidence against onchain allowlist - Validating operator signatures with onchain authorization checks - Providing private keys for application-wide secret decryption - Issuing signed TLS certificates for secure communication - Supporting secure KMS onboarding through attestation verification

All operations are performed only after verifying both the instance's identity and operator authorization through the onchain governance contracts, implementing a robust two-factor authorization model (attestation + operator signature).

func NewHandler

func NewHandler(kms HandlerKMS, kmsGovernance interfaces.KMSGovernance, registryFactory interfaces.RegistryFactory, log *slog.Logger) *Handler

NewHandler creates a new HTTP request handler with the specified dependencies.

func (*Handler) HandleOnboard

func (h *Handler) HandleOnboard(w http.ResponseWriter, r *http.Request)

HandleOnboard processes KMS onboarding requests for new TEE instances. It retrieves onchain onboarding requests, verifies attestation, and provides encrypted KMS seed material for authorized instances.

URL format: GET /api/attested/onboard/{onboard_id} The onboard_id is a 32-byte hex-encoded hash that identifies the onboarding request previously registered in the onchain governance contract.

This allows secure distributed KMS deployment where new instances can receive encrypted master key material through attestation verification and onchain governance.

Response: Raw encrypted seed material for KMS initialization

func (*Handler) HandleSecrets

func (h *Handler) HandleSecrets(w http.ResponseWriter, r *http.Request)

HandleSecrets processes TEE instance secrets requests with onchain authorization. It verifies both the instance's identity and operator authorization against the governance contract, then provides cryptographic materials if authorized.

URL format: POST /api/attested/secrets/{contract_address} Required headers:

• X-Flashbots-Attestation-Type: Type of attestation (azure-tdx, qemu-tdx)
• X-Flashbots-Measurement: JSON-encoded measurement values

Request body: TLS Certificate Signing Request (CSR) in PEM format The CSR may optionally include an operator signature as an X.509 extension with OID cryptoutils.OIDOperatorSignature. This signature provides additional authorization through onchain governance verification.

Response: JSON-encoded AppSecrets containing:

• Application private key for decrypting secrets
• Signed TLS certificate for secure communication
• Operator's Ethereum address (if provided)
• Attestation evidence

func (*Handler) RegisterRoutes

func (h *Handler) RegisterRoutes(r chi.Router)

type HandlerKMS

type HandlerKMS interface {
	interfaces.KMS
	VerifyOnboardRequest(interfaces.OnboardRequest) (map[int]string, error)
	OnboardRemote(interfaces.AppPubkey) ([]byte, error)
}

type SecretsProvider

type SecretsProvider struct {
	Client *http.Client

	// DebugAttestationTypeHeader allows manually setting the attestation type header.
	// This is primarily for testing and development, and should not be used in production.
	DebugAttestationTypeHeader string

	// DebugMeasurementsHeader allows manually setting the measurements header.
	// This is primarily for testing and development, and should not be used in production.
	DebugMeasurementsHeader string
}

SecretsProvider implements a client for retrieving cryptographic materials from the onchain-governed KMS. It handles secure communication with the KMS server including the attestation headers required for TEE identity verification.

The client supports: - Retrieving application secrets (private keys and certificates) - Onboarding new KMS instances through onchain governance - Debug options for attestation headers in development environments

func (*SecretsProvider) AppSecrets

func (p *SecretsProvider) AppSecrets(url string, contractAddr interfaces.ContractAddress, csr interfaces.TLSCSR) (*interfaces.AppSecrets, error)

AppSecrets sends a request to the KMS server to obtain cryptographic materials for a TEE instance. It submits the CSR and attestation evidence, and returns the application private key, signed certificate, and other identity materials.

Parameters:

• url: The KMS server URL
• contractAddr: The contract address identifying the application
• csr: Certificate Signing Request in PEM format

The client automatically includes attestation evidence headers for production environments. For development and testing, attestation headers can be manually set using the DebugAttestationTypeHeader and DebugMeasurementsHeader fields.

Returns:

• AppSecrets containing private key, TLS certificate, operator address, and attestation evidence
• Error if the request fails or authorization is denied

func (*SecretsProvider) OnboardKMS

func (p *SecretsProvider) OnboardKMS(url string, onboardHash [32]byte, kms *simplekms.SimpleKMS, privkey interfaces.AppPrivkey) ([]byte, error)

OnboardKMS retrieves KMS seed material for a new KMS instance through onchain governance. This method is used during KMS bootstrapping to securely distribute master key material to authorized instances.

Parameters:

• url: The KMS server URL
• onboardHash: The hash identifying the onchain onboarding request
• kms: The local KMS instance that will receive the seed
• privkey: The application private key for authentication

The onboard request must be previously registered and approved on the blockchain before calling this method.

Returns:

• Encrypted seed material that can be used to initialize the KMS
• Error if onboarding fails

type SimpleHandlerKMS

type SimpleHandlerKMS struct {
	*simplekms.SimpleKMS
	// contains filtered or unexported fields
}

func NewSimpleHandlerKMS

func NewSimpleHandlerKMS(kms *simplekms.SimpleKMS, addr interfaces.ContractAddress) *SimpleHandlerKMS

func (*SimpleHandlerKMS) VerifyOnboardRequest

func (k *SimpleHandlerKMS) VerifyOnboardRequest(onboardRequest interfaces.OnboardRequest) (map[int]string, error)