Help us shape the future of Go! Take the 2026 Go Developer Survey

kes

package module
v0.24.0-lgcorzo.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 10, 2026 License: AGPL-3.0 Imports: 34 Imported by: 0

README

[!NOTE] UPSTREAM STATUS & FORK PURPOSE: While upstream MinIO has archived the open-source KES (Key Encryption Service) in favor of proprietary MinKMS AiStor Key Manager, this repository is actively maintained and hardened as the cryptographic key management backbone of the Dark Gravity Autonomous CA/CD Factory. Ongoing security patches, envelope encryption hardening, and supply-chain integrity checks are continuously integrated to protect the autonomous software delivery lifecycle.

🛡️ Dark Gravity Factory: Security Maintenance & System Integrity Rationale

1. Why Security Maintenance Continues on this Repository

In the Dark Gravity Autonomous CA/CD Software Factory (V7.2 / V7.3), KES is not merely a utility—it is the critical Key Management Service (KMS) proxy that governs all envelope encryption operations, data-at-rest protection, and cryptographic key lifecycle management for the entire autonomous engineering system.

Upstream MinIO's deprecation of KES open-source leaves unaddressed security vulnerabilities (CVEs) and orphaned cryptographic primitives. In a zero-trust, autonomous multi-agent factory where AI agents autonomously synthesize, compile, and deploy software:

  • Envelope Encryption Integrity: KES mediates all Data Encryption Key (DEK) derivation between MinIO Object Storage and the root KMS (HashiCorp Vault, AWS KMS, GCP KMS, Azure Key Vault). Unpatched vulnerabilities in the key proxy would compromise every encrypted object in the factory.
  • Cryptographic Provenance Chain: Every artifact produced by the Dark Gravity factory—compiled binaries, AST mutations, causal lineage snapshots—relies on KES-derived keys for at-rest encryption. A broken KES link invalidates the entire cryptographic proof chain.
  • Air-Gapped Data Sovereignty: Dark Gravity operates on sovereign, air-gapped infrastructure. Key material must never escape the private network perimeter, and the KMS proxy must remain fully auditable and patchable without commercial dependencies.
  • Continuous Compliance & Auditability: Under regulations like the EU AI Act (Art. 12 & 14), SOC 2 Type II, and ISO/IEC 25059, any weakness in key management voids the factory's compliance posture.

Therefore, this repository is actively maintained to remediate security flaws, patch cryptographic vulnerabilities, and provide robust CI/CD builds tailored for production Kubernetes and MicroK8s environments.

2. Integration Architecture within Dark Gravity

KES is the central cryptographic gateway bridging MinIO Object Storage with enterprise Key Management Systems:

graph TD
    subgraph "MicroK8s Cluster (storage namespace)"
        MINIO["MinIO Tenant S3 Storage<br/>(mlflow-minio-pool-0)"]
    end

    subgraph "KES Key Encryption Service"
        KES_NODE["KES Server<br/>(Stateless, Horizontally Scalable)"]
    end

    subgraph "Root Key Management Systems"
        VAULT["HashiCorp Vault"]
        AWS_KMS["AWS KMS / Secrets Manager"]
        GCP_KMS["GCP Secret Manager"]
        AZURE_KV["Azure Key Vault"]
        FORTANIX["Fortanix SDKMS"]
        ENTRUST["Entrust KeyControl"]
        GEMALTO["Gemalto KeySecure"]
    end

    subgraph "Dark Gravity Factory Core"
        HATCHET["Hatchet DAG Engine<br/>(Crash Resilience)"] -->|Encrypted BridgeState Checkpoints| MINIO
        ZERO_CLAW["ZeroClaw / Rustant<br/>(Code Execution)"] -->|Encrypted Spec-Kit & Code Artifacts| MINIO
        SEMANTICA["Semantica-AGI<br/>(Causal Graph)"] -->|Encrypted Ontological Lineage Snapshots| MINIO
        MLFLOW["MLflow Tracking Server"] -->|Encrypted Model Weights & Partitions| MINIO
    end

    MINIO -->|DEK Request / Envelope Encryption| KES_NODE
    KES_NODE -->|Root Key Operations| VAULT
    KES_NODE -.->|Alternative KMS| AWS_KMS
    KES_NODE -.->|Alternative KMS| GCP_KMS
    KES_NODE -.->|Alternative KMS| AZURE_KV
    KES_NODE -.->|Alternative KMS| FORTANIX
    KES_NODE -.->|Alternative KMS| ENTRUST
    KES_NODE -.->|Alternative KMS| GEMALTO
  • Cluster Topology & Service Endpoints: KES is deployed as a stateless service in the storage Kubernetes namespace, fronting MinIO's Server-Side Encryption (SSE-S3/SSE-KMS) with horizontal auto-scaling.
  • Envelope Encryption Flow: MinIO requests Data Encryption Keys (DEKs) from KES. KES derives DEKs using root keys stored in the configured KMS backend (Vault, AWS, GCP, Azure, etc.), returning both the plaintext DEK (for encryption) and the sealed DEK (for storage alongside encrypted data).
  • Stateless Architecture: KES nodes maintain no persistent state—all key material is derived on-demand from the root KMS, enabling seamless scaling and zero-downtime upgrades.

3. Critical Security Mechanisms Enforced

To protect the factory's cryptographic infrastructure against compromise, the following defenses are strictly enforced:

  • mTLS Identity Verification: All KES API access requires mutual TLS authentication. Client certificates are mapped to KES identities with policy-based access control.
  • Policy-Based Key Access Control: Fine-grained policies restrict which identities can create, derive, decrypt, or list keys, preventing unauthorized key operations.
  • Audit Logging: Every cryptographic operation (key creation, DEK derivation, decryption) is logged with full identity context for compliance audit trails.
  • Prometheus Metrics & Monitoring: KES exposes /v1/metrics for real-time observability of cryptographic operations, error rates, and latency.
  • Cryptographic Provenance (NHI Verifiable Credentials): Every artifact and code modification is cryptographically signed by Non-Human Identities (NHI) using W3C Verifiable Credentials with Ed25519 keys and deterministic BLAKE3/SHA-256 hashes.

KES Quickstart Guide

license

KES is a cloud-native distributed key management and encryption server designed to secure modern applications at scale.

What is KES?

KES (Key Encryption Service) is a distributed key management server that scales horizontally. It can either be run as edge server close to the applications reducing latency to and load on a central key management system (KMS) or as central key management service. KES nodes are self-contained stateless instances that can be scaled up and down automatically.

KES is Open Source Software

We designed KES as Open Source software for the Open Source software community. We encourage the community to remix, redesign, and reshare KES under the terms of the AGPLv3 license.

All usage of KES in your application stack requires validation against AGPLv3 obligations, which include but are not limited to the release of modified code to the community from which you have benefited.

The AGPLv3 provides no obligation by any party to support, maintain, or warranty the original or any modified work. All support is provided on a best-effort basis through GitHub, and any member of the community is welcome to contribute and assist others in their usage of the software.

Install

The KES server and CLI is available as a single binary, container image or can be built from source.

Docker

Pull the latest release via:

docker pull lgcorzo/kes
Binary Releases
OS ARCH Binary
linux amd64 linux-amd64
linux arm64 linux-arm64
darwin arm64 darwin-arm64
windows amd64 windows-amd64

Download the binary via curl but replace <OS> and <ARCH> with your operating system and CPU architecture.

curl -sSL --tlsv1.2 'https://github.com/lgcorzo/kes/releases/latest/download/kes-<OS>-<ARCH>' -o ./kes

chmod +x ./kes

You can also verify the binary with minisign by downloading the corresponding .minisig signature file. Run:

curl -sSL --tlsv1.2 'https://github.com/lgcorzo/kes/releases/latest/download/kes-<OS>-<ARCH>.minisig' -o ./kes.minisig

minisign -Vm ./kes -P RWTx5Zr1tiHQLwG9keckT0c45M3AGeHD6IvimQHpyRywVWGbP1aVSGav
Build from source

Download and install the binary via your Go toolchain:

go install github.com/lgcorzo/kes/cmd/kes@latest

Quick Start

We run a public KES instance at https://play.min.io:7373 as playground. You can interact with our play instance either via the KES CLI or cURL. Alternatively, you can get started by setting up your own KES server in less than five minutes.

First steps
1. Configure CLI

Point the KES CLI to the KES server at https://play.min.io:7373 and use the following API key:

export KES_SERVER=https://play.min.io:7373
export KES_API_KEY=kes:v1:AD9E7FSYWrMD+VjhI6q545cYT9YOyFxZb7UnjEepYDRc
3. Create a Key

Create a new root encryption key - e.g. my-key.

kes key create my-key

Note that creating a new key will fail with key already exist if it already exist.

4. Generate a DEK

Derive a new data encryption keys (DEK).

kes key dek my-key

The plaintext part of the DEK would be used by an application to encrypt some data. The ciphertext part of the DEK would be stored alongside the encrypted data for future decryption.

Docs

If you want to learn more about KES checkout our documentation.

Monitoring

KES servers provide an API endpoint /v1/metrics that observability tools, like Prometheus, can scrape.
Refer to the monitoring documentation for how to setup and capture KES metrics.

For a graphical Grafana dashboard refer to the following example.

FAQs

I have received an insufficient permissions error

This means that you are using a KES identity that is not allowed to perform a specific operation, like creating or listing keys.

The KES admin identity can perform any general purpose API operation. You should never experience a not authorized: insufficient permissions error when performing general purpose API operations using the admin identity.

In addition to the admin identity, KES supports a policy-based access control model. You will receive a not authorized: insufficient permissions error in the following two cases:

  1. You are using a KES identity that is not assigned to any policy. KES rejects requests issued by unknown identities.

    This can be fixed by assigning a policy to the identity. Checkout the examples.

  2. You are using a KES identity that is assigned to a policy but the policy either not allows or even denies the API call.

    In this case, you have to grant the API permission in the policy assigned to the identity. Checkout the list of APIs. For example, when you want to create a key you should allow the /v1/key/create/<key-name>. The <key-name> can either be a specific key name, like my-key-1 or a pattern allowing arbitrary key names, like my-key*.

    Also note that deny rules take precedence over allow rules. Hence, you have to make sure that any deny pattern does not accidentally matches your API request.

4. Sovereign MinIO Ecosystem: Maintained Repositories in @lgcorzo

To guarantee long-term sovereign support, full supply-chain independence, and continuous security patching for the Dark Gravity factory and production environments, the complete MinIO ecosystem of 38 servers, clients, storage drivers, acceleration libraries, and core dependencies has been preserved and actively maintained under @lgcorzo:

Category Repository Description Key Capabilities
Core Storage & Server lgcorzo/minio High-performance Object Storage Server Multi-tenant S3-compatible engine, Erasure Coding, Tiering, Decommissioning
lgcorzo/mc MinIO Client CLI Tool High-speed mirror, diff, administration, encryption management, batch processing
lgcorzo/kes Key Encryption Server (KES) High-performance KMS proxy (Vault, AWS-KMS, GCP-KMS, Azure Key Vault, Dev KMS)
lgcorzo/console Graphical Web Administration Interface Visual bucket policy management, IAM administration, observability metrics dashboard
lgcorzo/operator Kubernetes Operator Declarative MinIO Tenant orchestration, CRD management, and cluster automation
lgcorzo/directpv Kubernetes CSI Direct Storage Driver High-throughput direct-attached NVMe/SSD volume provisioner for Kubernetes
lgcorzo/sidekick High-Performance S3 Proxy Low-latency client-side load balancing and failover sidecar proxy
lgcorzo/docs Documentation Source & Engine Sphinx-based documentation build system and architecture references
SDKs & APIs lgcorzo/minio-go Official Go Client SDK Idiomatic Go SDK for object storage operations, multipart uploads, STS, and presigned URLs
lgcorzo/madmin-go MinIO Admin Go Library Administrative APIs for server configuration, user management, healing, and decommissioning
lgcorzo/kms-go Cryptographic KMS Client Library Go client primitives for key creation, DEK derivation, and envelope encryption via KES
lgcorzo/pkg Common Go Utility Packages Cryptographic certificates, hashing routines, and shared helper primitives
lgcorzo/mtls Mutual TLS Utilities Zero-trust inter-node cryptographic identity verification and mTLS configuration
Hardware & SIMD Acceleration lgcorzo/sha256-simd SIMD-Accelerated SHA256 AVX-512 and ARMv8 Crypto Extensions SHA256 acceleration (up to 100x speedup)
lgcorzo/md5-simd SIMD-Accelerated MD5 Parallel AVX-512 and AVX2 MD5 calculation (up to 8x acceleration)
lgcorzo/blake2b-simd SIMD-Accelerated BLAKE2b Pure Go cryptographic hashing leveraging AVX2/AVX512/SSSE3 vector instructions
lgcorzo/highwayhash SIMD HighwayHash High-speed native hashing (>10 GB/s per core on Intel & ARM assembly)
lgcorzo/crc64nvme NVMe CRC64 SIMD Acceleration Fast carryless-multiplication CRC64 checksums for NVMe storage devices
lgcorzo/simdjson-go High-Throughput SIMD JSON Parser Gigabytes/sec JSON parsing leveraging vector instructions for event & metadata processing
lgcorzo/sio Data At Rest Encryption (DARE) Streaming authenticated encryption format for secure on-disk persistence
lgcorzo/asm2plan9s Assembly Bytecode Converter Converts AVX512/AVX2/ARM assembly instructions into Go Plan9 bytecode
Networking & Routing lgcorzo/mux High-Performance Request Router Matcher and multiplexer for incoming S3 REST and STS API routes
lgcorzo/websocket Low-Latency WebSocket Engine High-throughput duplex communication for real-time console and bucket notifications
lgcorzo/dnscache DNS Lookup Caching In-memory DNS cache minimizing latency on distributed multi-cluster lookups
Data Formats & Helpers lgcorzo/zipindex Fast ZIP Archive Indexer Compressed index lookup enabling direct random reads of files inside ZIP archives
lgcorzo/xxml Extended XML 1.0 Parser Robust XML namespace and control character support for strict S3 API compliance
lgcorzo/colorjson Colorized JSON Encoder Human-readable terminal logging and JSON inspection
lgcorzo/csvparser High-Performance CSV Parser Streaming CSV parsing engine for S3 Select query execution
lgcorzo/filepath Lexically Sorted Flat Path Walker High-efficiency directory walking and flat object key enumeration
lgcorzo/selfupdate Binary Self-Updating Library Secure signature-verified self-upgrades for CLI binaries
lgcorzo/cli Minimalist CLI Framework Lightweight command-line argument parser for distributed helper utilities
Testing & Tooling lgcorzo/mint Integration Test & Verification Suite End-to-end multi-language test suite certifying S3 protocol and functional compliance
lgcorzo/warp S3 Benchmarking Tool High-throughput synthetic benchmark suite measuring IOPS and latency
lgcorzo/dperf Distributed Performance Benchmark Stress-testing network bandwidth, disk I/O, and CPU throughput across storage nodes
lgcorzo/certgen TLS Certificate Generator Standalone zero-dependency x.509 TLS certificate generation utility
lgcorzo/pkger Binary Packaging Utility Multi-architecture DEB, RPM, and APK packaging automation tool
lgcorzo/multipart-debug S3 Multipart Upload Diagnostic Tool Low-level multipart upload debugging, part alignment, and encryption validation
lgcorzo/minio-cf Cloud Foundry Integration Support for deploying and orchestrating MinIO within Cloud Foundry estates

5. Sovereign Maintenance & Long-Term Support Plan in GitHub

To preserve long-term operational resilience, supply-chain autonomy, and enterprise security compliance (EU AI Act, SOC 2 Type II, ISO 25059) without upstream commercial lock-in, all 38 repositories are managed under a structured maintenance protocol:

flowchart TD
    subgraph "1. Upstream & Vulnerability Tracking"
        UPSTREAM["Upstream Git Repositories"] -->|Weekly Cron Poll| SYNC_WF["GitHub Actions: Upstream Sync"]
        VULN_DB["OSV / NIST NVD / VulnCheck"] -->|Daily Security Scan| SEC_SCAN["Trivy & CodeQL SAST"]
    end

    subgraph "2. Autonomous Remediation (Dark Gravity Factory)"
        SYNC_WF -->|New Commits / Upstream Tags| MERGE_GATE{"Conflict Check"}
        SEC_SCAN -->|CVE Alert Detected| ISSUE_DISPATCH["Dispatch Mission to Hatchet DAG"]
        ISSUE_DISPATCH --> RUSTANT["Rustant Planner Agent"]
        RUSTANT --> ZERO_CLAW["ZeroClaw Dev Agent"]
        ZERO_CLAW -->|AST Surgical Fix| BRANCH_PR["Create Hardened PR"]
    end

    subgraph "3. Automated Verification Matrix"
        MERGE_GATE -->|Fast-Forward / Non-Conflicting| RUN_MATRIX["Comprehensive CI Matrix"]
        BRANCH_PR --> RUN_MATRIX
        RUN_MATRIX --> TEST_BUILD["Build & Vet (Go 1.25)"]
        RUN_MATRIX --> TEST_LINT["golangci-lint v2"]
        RUN_MATRIX --> TEST_MULTI["Test Matrix (Linux, Windows, macOS)"]
        RUN_MATRIX --> TEST_VULN["govulncheck Security Scan"]
        RUN_MATRIX --> TEST_RELEASE["GoReleaser Snapshot Build"]
    end

    subgraph "4. Supply Chain Artifact Publishing"
        RUN_MATRIX -->|Green Verification| BUILD_ARTIFACTS["Multi-Arch Build (AMD64 / ARM64)"]
        BUILD_ARTIFACTS --> DOCKER_REG["GHCR (ghcr.io/lgcorzo/kes)"]
        BUILD_ARTIFACTS --> QUAY_REG["Quay.io (quay.io/lgcorzo/kes)"]
        BUILD_ARTIFACTS --> GH_RELEASES["GitHub Releases + Minisign Signatures"]
    end
5.1 Automated Upstream Synchronization
  • Scheduled Synchronization Workflows: Each repository runs a weekly GitHub Actions workflow fetching upstream tags and release commits.
  • Protected Branch Non-Destructive Merges: Upstream changes are fetched into dedicated tracking branches and merged into master via pull requests to ensure custom factory hardening and Dark Gravity patches are never overwritten.
5.2 Vulnerability Ingestion & Autonomous Remediation
  • Continuous CVE Scanning: Daily VulnCheck, CodeQL, and govulncheck inspections are executed across all repositories.
  • Autonomous Repair via Dark Gravity Agents:
    1. High/Critical CVEs trigger an issue labeled autonomous-mission in rust_CACD_autonomous_factory.
    2. The Hatchet orchestrator assigns the remediation mission to ZeroClaw (developer agent).
    3. Surgical AST mutations are applied, tested in gVisor sandboxes against the standardized verification suite, and presented for Human-in-the-Loop (HITL) review.
5.3 Multi-Architecture Container CI/CD & Local Registries
  • GoReleaser Multi-Arch Builds: KES produces linux/amd64 and linux/arm64 binaries and container images via GoReleaser.
  • Dual Registry Target:
    • Global Container Distribution: ghcr.io/lgcorzo/kes:latest and quay.io/lgcorzo/kes:latest.
    • Air-Gapped MicroK8s Deployments: In-cluster private registry at localhost:32000.
5.4 Signature-Verified Binary Releases
  • Every published binary (kes) is cryptographically signed using Minisign, generating signature files for supply-chain provenance verification.
  • Downstream container images verify checksums before packaging to enforce strict supply-chain provenance.
5.5 Go Module Dependency Resolution Policy

To import sovereign libraries across the Dark Gravity factory without namespace conflicts, projects declare Go module replace directives in their go.mod:

module my-factory-service

go 1.25

require (
    github.com/minio/kes v0.0.0
    github.com/minio/kms-go/kes v0.3.1
)

replace (
    github.com/minio/kes => github.com/lgcorzo/kes master
    github.com/minio/kms-go => github.com/lgcorzo/kms-go master
)

Contribute to KES Project

Please follow KES Contributor's Guide for guidance on making new contributions to the repository.

License

  • KES source is licensed under the GNU AGPLv3.
  • Use of KES is governed by the AGPLv3 license that can be found in the LICENSE file.

Documentation

Index

Examples

Constants

View Source 
const ServerShutdownTimeout = 1 * time.Second

ServerShutdownTimeout is the default time period the server waits while trying to shutdown gracefully before forcefully closing connections.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditHandler 

type AuditHandler interface {
	// Enabled reports whether the handler handles records at
	// the given level. The handler ignores records whose level
	// is lower. It is called early, before an audit record is
	// created, to safe effort if the audit event should be
	// discarded.
	//
	// The Server will pass the request context as the first
	// argument, or context.Background() if no context is
	// available. Enabled may use the context to make a
	// decision.
	Enabled(context.Context, slog.Level) bool

	// Handle handles the AuditRecord. It will only be called when
	// Enabled returns true.
	//
	// The context is present for providing AuditHandlers access
	// to the context's values and to potentially pass it to an
	// underlying slog.Handler. Canceling the context should not
	// affect record processing.
	Handle(context.Context, AuditRecord) error
}

An AuditHandler handles audit records produced by a Server.

A typical handler may print audit records to standard error, or write them to a file or database.

Any of the AuditHandler's methods may be called concurrently with itself or with other methods. It is the responsibility of the Handler to manage this concurrency.

type AuditLogHandler 

type AuditLogHandler struct {
	Handler slog.Handler
}

AuditLogHandler is an AuditHandler adapter that wraps an slog.Handler. It converts AuditRecords to slog.Records and passes them to the slog.Handler. An AuditLogHandler acts as a bridge between AuditHandlers and slog.Handlers.

Example

This example shows how to connect an AuditHandler to any slog.Handler, here an TextHandler writing to stdout. 

package main

import (
	"context"
	"log/slog"
	"net/http"
	"net/netip"
	"os"
	"time"

	"github.com/lgcorzo/kes"
)

func main() {
	audit := &kes.AuditLogHandler{
		Handler: slog.NewTextHandler(os.Stdout, nil),
	}
	conf := &kes.Config{
		AuditLog: audit,
	}
	_ = conf

	// Handle will be called by the KES server internally
	audit.Handle(context.Background(), kes.AuditRecord{
		Time:         time.Date(2023, time.October, 19, 8, 44, 0, 0, time.UTC),
		Method:       http.MethodPut,
		Path:         "/v1/key/create/my-key",
		Identity:     "2ecb8804e7702a6b768e89b7bba5933044c9d071e4f4035235269b919e56e691",
		RemoteIP:     netip.MustParseAddr("10.1.2.3"),
		StatusCode:   http.StatusOK,
		ResponseTime: 200 * time.Millisecond,
		Level:        slog.LevelInfo,
		Message:      "secret key 'my-key' created",
	})
}

Output:
time=2023-10-19T08:44:00.000Z level=INFO msg="secret key 'my-key' created" req.method=PUT req.path=/v1/key/create/my-key req.ip=10.1.2.3 req.identity=2ecb8804e7702a6b768e89b7bba5933044c9d071e4f4035235269b919e56e691 res.code=200 res.time=200ms

func (*AuditLogHandler) Enabled 

func (a *AuditLogHandler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether the AuditLogHandler handles records at the given level. It returns true if the underlying handler returns true.

func (*AuditLogHandler) Handle 

func (a *AuditLogHandler) Handle(ctx context.Context, r AuditRecord) error

Handle converts the AuditRecord to an slog.Record and passes it to the underlying handler.

type AuditRecord 

type AuditRecord struct {
	// Point in time when the audit event happened.
	Time time.Time

	// The request HTTP method. (GET, PUT, ...)
	Method string

	// Request URL path. Always starts with a '/'.
	Path string

	// Identity that send the request.
	Identity kes.Identity

	// IP address of the client that sent the request.
	RemoteIP netip.Addr

	// Status code the KES server responded with.
	StatusCode int

	// Amount of time the server took to process the
	// request and generate a response.
	ResponseTime time.Duration

	// The log level of this event.
	Level slog.Level

	// The log message describing the event.
	Message string
}

AuditRecord describes an audit event logged by a KES server.

type CacheConfig 

type CacheConfig struct {
	// Expiry controls how long a particular key resides
	// in the cache. If zero or negative, keys remain in
	// the cache as long as the KES server has sufficient
	// memory.
	Expiry time.Duration

	// ExpiryUnused is the interval in which a particular
	// key must be accessed to remain in the cache. Keys
	// that haven't been accessed get evicted from the
	// cache. The general cache expiry still applies.
	//
	// ExpiryUnused does nothing if <= 0 or greater than
	// Expiry.
	ExpiryUnused time.Duration

	// ExpiryOffline controls how long a particular key
	// resides in the cache once the key store becomes
	// unavailable. It overwrites Expiry and ExpiryUnused
	// if the key store is not available. Once the key
	// store is available again, Expiry and ExpiryUnused,
	// if set, apply.
	//
	// A common use of ExpiryOffline is reducing the impact
	// of a key store outage, and therefore, improving
	// availability.
	//
	// Offline caching is disabled if ExpiryOffline <= 0.
	ExpiryOffline time.Duration
}

CacheConfig is a structure containing the KES server key store cache configuration.

type Config 

type Config struct {
	// Admin is the KES server admin identity. It must not be empty.
	// To disable admin access set it to a non-hex value. For example,
	// "disabled".
	Admin kes.Identity

	// TLS contains the KES server's TLS configuration.
	//
	// A KES server requires a TLS certificate. Therefore, either
	// Config.Certificates, Config.GetCertificate or
	// Config.GetConfigForClient must be set.
	//
	// Further, the KES server has to request client certificates
	// for mTLS authentication. Hence, Config.ClientAuth must be
	// at least tls.RequestClientCert.
	TLS *tls.Config

	// Cache specifies how long the KES server caches keys from the
	// KeyStore. If nil, caching is disabled.
	Cache *CacheConfig

	// Policies is a set of policies and identities. Each identity
	// must be assigned to a policy only once.
	Policies map[string]Policy

	// Predefined Keys to be added to KeyStore before server starts.
	PredefinedKeys []Key

	// Keys is the KeyStore the KES server fetches keys from.
	Keys KeyStore

	// Routes allows customization of the KES server API routes. It
	// contains a set of API route paths, for example "/v1/status",
	// and the corresponding route configuration.
	//
	// The KES server uses sane defaults for all its API routes.
	Routes map[string]RouteConfig

	// ErrorLog is an optional handler for handling the server's
	// error log events. If nil, defaults to a slog.TextHandler
	// writing to os.Stderr. The server's error log level is
	// controlled by Server.ErrLevel.
	ErrorLog slog.Handler

	// AuditLog is an optional handler for handling the server's
	// audit log events. If nil, defaults to a slog.TextHandler
	// writing to os.Stdout. The server's audit log level is
	// controlled by Server.AuditLevel.
	AuditLog AuditHandler
}

Config is a structure that holds configuration for a KES server.

type Identity 

type Identity = kes.Identity

An Identity should uniquely identify a client and is computed from the X.509 certificate presented by the client during the TLS handshake.

type Key 

type Key struct {
	Name string // Name of cryptographic key
}

Key define a cryptographic key

type KeyStore 

type KeyStore interface {
	// Closes the key store and releases associated resources,
	// like background go routines, if any.
	io.Closer

	// Status returns the current state of the KeyStore.
	Status(context.Context) (KeyStoreState, error)

	// Create creates a new entry with the given name if and only
	// if no such entry exists.
	// Otherwise, Create returns kes.ErrKeyExists.
	Create(ctx context.Context, name string, value []byte) error

	// Delete removes the entry. It may return either no error or
	// kes.ErrKeyNotFound if no such entry exists.
	Delete(ctx context.Context, name string) error

	// Get returns the value for the given name. It returns
	// kes.ErrKeyNotFound if no such entry exits.
	Get(ctx context.Context, name string) ([]byte, error)

	// List returns the first n key names, that start with the given
	// prefix, and the next prefix from which the listing should
	// continue.
	//
	// It returns all keys with the prefix if n < 0 and less than n
	// names if n is greater than the number of keys with the prefix.
	//
	// An empty prefix matches any key name. At the end of the listing
	// or when there are no (more) keys starting with the prefix, the
	// returned prefix is empty.
	List(ctx context.Context, prefix string, n int) ([]string, string, error)
}

A KeyStore stores key-value pairs. It provides durable storage for a KES server to persist and access keys. A KeyStore may be modified concurrently by different go routines.

type KeyStoreState 

type KeyStoreState struct {
	Latency time.Duration
}

KeyStoreState is a structure containing information about the current state of a KeyStore.

type MemKeyStore 

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

MemKeyStore is a volatile KeyStore that stores key-value pairs in memory. Its zero value is ready and safe to be used concurrently from different go routines. It is optimized for reads but not well-suited for many writes/deletes.

func (*MemKeyStore) Close 

func (ks *MemKeyStore) Close() error

Close does nothing and returns no error.

It is implemented to satisfy the KeyStore interface.

func (*MemKeyStore) Create 

func (ks *MemKeyStore) Create(_ context.Context, name string, value []byte) error

Create creates a new entry with the given name if and only if no such entry exists. Otherwise, Create returns kes.ErrKeyExists.

func (*MemKeyStore) Delete 

func (ks *MemKeyStore) Delete(_ context.Context, name string) error

Delete removes the entry. It may return either no error or kes.ErrKeyNotFound if no such entry exists.

func (*MemKeyStore) Get 

func (ks *MemKeyStore) Get(_ context.Context, name string) ([]byte, error)

Get returns the value for the given name. It returns kes.ErrKeyNotFound if no such entry exits.

func (*MemKeyStore) List 

func (ks *MemKeyStore) List(_ context.Context, prefix string, n int) ([]string, string, error)

List returns the first n key names that start with the given prefix and the next prefix from which to continue the listing.

It returns all keys with the prefix if n < 0 and less than n names if n is grater than the number of keys with the prefix.

An empty prefix matches any key name. At the end of the listing or when there are no (more) keys starting with the prefix, the returned prefix is empty.

List never returns an error.

func (*MemKeyStore) Status 

func (ks *MemKeyStore) Status(context.Context) (KeyStoreState, error)

Status returns the current state of the MemKeyStore. It never returns an error.

func (*MemKeyStore) String 

func (ks *MemKeyStore) String() string

type Policy 

type Policy struct {
	Allow map[string]kes.Rule // Set of allow rules

	Deny map[string]kes.Rule // Set of deny rules

	Identities []kes.Identity
}

Policy is a KES policy with associated identities.

A policy contains a set of allow and deny rules.

type RouteConfig 

type RouteConfig struct {
	// Timeout specifies when the API handler times out.
	//
	// A handler times out when it fails to send the
	// *entire* response body to the client within the
	// given time period.
	//
	// If <= 0, timeouts are disabled for the API route.
	//
	// Disabling timeouts may leave client/server connections
	// hung or allow certain types of denial-of-service (DOS)
	// attacks.
	Timeout time.Duration

	// InsecureSkipAuth, if set, disables authentication for the
	// API route. It allows anyone that can send HTTPS requests
	// to the KES server to invoke the API.
	//
	// For example the KES readiness API authentication may be
	// disabled when the probing clients do not support mTLS
	// client authentication
	//
	// If setting InsecureSkipAuth for any API then clients that
	// do not send a client certificate during the TLS handshake
	// no longer encounter a TLS handshake error but receive a
	// HTTP error instead. In particular, when the server's TLS
	// client auth type has been set  tls.RequireAnyClientCert
	// or tls.RequireAndVerifyClientCert.
	InsecureSkipAuth bool
}

RouteConfig is a structure holding API route configuration.

type Server 

type Server struct {
	// ShutdownTimeout controls how long Server.Close
	// tries to shutdown the server gracefully without
	// interrupting any active connections.
	//
	// If 0, defaults to ServerShutdownTimeout. If
	// negative, Server.Close waits indefinitely for
	// connections to return to idle and then shut down.
	ShutdownTimeout time.Duration

	// ErrLevel controls which errors are logged by the server.
	// It may be adjusted after the server has been started to
	// change its logging behavior.
	//
	// Log records are passed to the Config.ErrorLog handler
	// if and only if their log level is equal or greater than
	// ErrLevel. A custom Config.ErrorLog may handle records
	// independently from this ErrLevel.
	//
	// Defaults to slog.LevelInfo which includes TLS and HTTP
	// errors when handling requests.
	ErrLevel slog.LevelVar

	// AuditLevel controls which audit events are logged by
	// the server. It may be adjusted after the server has
	// been started to change its logging behavior.
	//
	// Log records are passed to the Config.AuditLog handler
	// if and only if their log level is equal or greater than
	// AuditLevel. A custom Config.AuditLog may handle records
	// independently from this AuditLevel.
	//
	// Defaults to slog.LevelInfo.
	AuditLevel slog.LevelVar
	// contains filtered or unexported fields
}

Server is a KES server.

func (*Server) Addr 

func (s *Server) Addr() string

Addr returns the server's listener address, or the empty string if the server hasn't been started.

func (*Server) Close 

func (s *Server) Close() error

Close closes the server and underlying listener. It first tries to shutdown the server gracefully by waiting for requests to finish before closing the server forcefully.

func (*Server) ListenAndStart 

func (s *Server) ListenAndStart(ctx context.Context, addr string, conf *Config) error

ListenAndStart listens on the TCP network address addr and then calls Start to start the server using the given config. Accepted connections are configured to enable TCP keep-alives.

HTTP/2 support is only enabled if conf.TLS is configured with "h2" in the TLS Config.NextProtos.

ListenAndStart returns once the server is closed or ctx.Done returns, whatever happens first. It returns the first error encountered while shutting down the HTTPS server and closing the listener, if any. It attempts to shutdown the server gracefully by waiting for requests to finish before closing the server forcefully.

func (*Server) Start 

func (s *Server) Start(ctx context.Context, ln net.Listener, conf *Config) error

Start starts the server using the given config and accepts incoming HTTPS connections on the listener ln, creating a new service goroutine for each.

HTTP/2 support is only enabled if conf.TLS is configured with "h2" in the TLS Config.NextProtos.

Start returns once the server is closed or ctx.Done returns, whatever happens first. It returns the first error encountered while shutting down the HTTPS server and closing the listener, if any. It attempts to shutdown the server gracefully by waiting for requests to finish before closing the server forcefully.

func (*Server) Update 

func (s *Server) Update(conf *Config) (io.Closer, error)

Update changes the server's configuration. Callers should close the returned io.Closer once they want to releases any resources allocated by the previous configuration, like open file handles or background go routines.

For only changing the server's admin identity, TLS configuration or policies use Server.UpdateAdmin, Server.UpdateTLS or Server.UpdatePolicies. These more specific methods are usually simpler to use and more efficient.

func (*Server) UpdateAdmin 

func (s *Server) UpdateAdmin(admin kes.Identity) error

UpdateAdmin updates the server's admin identity. All other server configuration options remain unchanged. It returns an error if the server has not been started or has been closed.

func (*Server) UpdatePolicies 

func (s *Server) UpdatePolicies(policies map[string]Policy) error

UpdatePolicies updates the server policies. All other server configuration options remain unchanged. It returns an error if the server has not been started or has been closed.

func (*Server) UpdateTLS 

func (s *Server) UpdateTLS(conf *tls.Config) error

UpdateTLS updates the server's TLS configuration. All other server configuration options remain unchanged. It returns an error if the server has not been started or has been closed.

Source Files

View all Source files

Directories

Path Synopsis
cmd
kes command
internal
api
cache
cli
cpu
crypto
fips
headers
Package headers defines common HTTP headers.
 Package headers defines common HTTP headers.
http
https
keystore
keystore/aws
keystore/azure
keystore/entrust
keystore/fortanix
keystore/fs
Package fs implements a key-value store that stores keys as file names and values as file content.
 Package fs implements a key-value store that stores keys as file names and values as file content.
keystore/gcp
keystore/gemalto
Package gemalto implements a key store that fetches/stores cryptographic keys on a Gemalto KeySecure instance.
 Package gemalto implements a key store that fetches/stores cryptographic keys on a Gemalto KeySecure instance.
keystore/vault
Package vault implements a secret key store that stores secret keys as key-value entries on the Hashicorp Vault K/V secret backend.
 Package vault implements a secret key store that stores secret keys as key-value entries on the Hashicorp Vault K/V secret backend.
metric
protobuf
sys

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.