security

package
v0.1.0-alpha.1 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 0 Imported by: 0

Documentation

Overview

Package security provides platform-wide security configuration types

Package security provides platform-wide security configuration types.

Overview

The security package defines configuration structures for TLS, mTLS, and ACME across the platform. It provides a unified way to configure secure communications for HTTP servers, WebSocket servers, and HTTP clients.

Key features:

  • Server TLS configuration (manual or ACME-managed certificates)
  • Client TLS configuration (CA trust, certificate verification)
  • Mutual TLS (mTLS) for both client and server
  • ACME integration for automatic certificate management

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        security.Config                              │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                        TLSConfig                                    │
├─────────────────────────────┬───────────────────────────────────────┤
│       ServerTLSConfig       │          ClientTLSConfig              │
│  - Enabled                  │  - Mode (manual/acme)                 │
│  - Mode (manual/acme)       │  - CAFiles                            │
│  - CertFile, KeyFile        │  - InsecureSkipVerify                 │
│  - MinVersion               │  - MinVersion                         │
│  - ACMEConfig               │  - ACMEConfig                         │
│  - ServerMTLSConfig         │  - ClientMTLSConfig                   │
└─────────────────────────────┴───────────────────────────────────────┘

Usage

Basic server TLS configuration:

cfg := security.ServerTLSConfig{
    Enabled:    true,
    Mode:       "manual",
    CertFile:   "/etc/ssl/server.crt",
    KeyFile:    "/etc/ssl/server.key",
    MinVersion: "1.2",
}

Client TLS with additional CAs:

cfg := security.ClientTLSConfig{
    CAFiles:    []string{"/etc/ssl/internal-ca.pem"},
    MinVersion: "1.3",
}

Server with mTLS (client certificate validation):

cfg := security.ServerTLSConfig{
    Enabled:  true,
    CertFile: "/etc/ssl/server.crt",
    KeyFile:  "/etc/ssl/server.key",
    MTLS: security.ServerMTLSConfig{
        Enabled:           true,
        ClientCAFiles:     []string{"/etc/ssl/client-ca.pem"},
        AllowedClientCNs:  []string{"service-a", "service-b"},
    },
}

ACME-managed certificates:

cfg := security.ServerTLSConfig{
    Enabled: true,
    Mode:    "acme",
    ACME: security.ACMEConfig{
        Enabled:       true,
        DirectoryURL:  "https://acme-v02.api.letsencrypt.org/directory",
        Email:         "admin@example.com",
        Domains:       []string{"example.com"},
        ChallengeType: "http-01",
        StoragePath:   "/etc/ssl/acme",
    },
}

Configuration Types

ServerTLSConfig - Server-side TLS:

  • Enabled: Enable TLS for the server
  • Mode: "manual" (provide certs) or "acme" (automatic)
  • CertFile/KeyFile: Certificate and key paths (manual mode)
  • MinVersion: "1.2" or "1.3"

ClientTLSConfig - Client-side TLS:

  • CAFiles: Additional CAs to trust (system CAs always included)
  • InsecureSkipVerify: Skip verification (DEV/TEST ONLY)
  • MinVersion: "1.2" or "1.3"

ServerMTLSConfig - Server mTLS (validate client certs):

  • ClientCAFiles: CAs to trust for client certs
  • ClientCertOptional: Admit clients without a certificate (default: required)
  • AllowedClientCNs: Optional CN whitelist

ClientMTLSConfig - Client mTLS (present client cert):

  • CertFile/KeyFile: Client certificate and key

ACMEConfig - ACME certificate automation:

  • DirectoryURL: ACME server URL
  • Email: Contact email
  • Domains: Certificate domains
  • ChallengeType: "http-01" or "tls-alpn-01"
  • RenewBefore: Renewal lead time (e.g., "24h")

Validation

These types carry no validation of their own. internal/tlsutil checks a configuration when it builds a tls.Config: it reads the certificate, key and CA files, and refuses a MinVersion other than "1.2", "1.3" or empty.

Security Defaults

The zero value of each type provides these defaults:

  • TLS disabled by default (explicit opt-in)
  • TLS 1.2 minimum version
  • InsecureSkipVerify false
  • Manual mode (no ACME by default)

Thread Safety

Config types are value types and safe to copy.

See Also

Related packages:

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ACMEConfig

type ACMEConfig struct {
	Enabled       bool     `json:"enabled" schema:"type:boolean,description:Enable ACME certificate management,default:false,category:security"`
	DirectoryURL  string   `json:"directory_url,omitempty" schema:"type:string,description:ACME directory URL (e.g. step-ca),category:security"`
	Email         string   `json:"email,omitempty" schema:"type:string,description:Contact email for ACME account,category:security"`
	Domains       []string `json:"domains,omitempty" schema:"type:array,description:Domains for certificate,category:security"`
	ChallengeType string   `` /* 138-byte string literal not displayed */
	RenewBefore   string   `` /* 134-byte string literal not displayed */
	StoragePath   string   `json:"storage_path,omitempty" schema:"type:string,description:Certificate storage path,category:security"`
	CABundle      string   `json:"ca_bundle,omitempty" schema:"type:string,description:CA bundle for step-ca validation,category:security"`
}

ACMEConfig holds ACME client configuration for automated certificate management.

type ClientMTLSConfig

type ClientMTLSConfig struct {
	Enabled  bool   `json:"enabled" schema:"type:boolean,description:Enable mTLS client certificate,default:false,category:security"`
	CertFile string `json:"cert_file,omitempty" schema:"type:string,description:Path to client certificate file,category:security"`
	KeyFile  string `json:"key_file,omitempty" schema:"type:string,description:Path to client private key file,category:security"`
}

ClientMTLSConfig holds mTLS configuration for clients (client certificate provision).

type ClientTLSConfig

type ClientTLSConfig struct {
	Mode               string   `json:"mode,omitempty" schema:"type:string,description:TLS mode (manual or acme),default:manual,category:security"`
	CAFiles            []string `json:"ca_files,omitempty" schema:"type:array,description:Additional CA certificates to trust,category:security"`
	InsecureSkipVerify bool     `` /* 149-byte string literal not displayed */
	MinVersion         string   `json:"min_version,omitempty" schema:"type:string,description:Minimum TLS version (1.2 or 1.3),default:1.2,category:security"`

	// ACME mode (Tier 3)
	ACME ACMEConfig `json:"acme,omitempty" schema:"type:object,description:ACME configuration for automatic client certificates,category:security"`

	// mTLS support (both modes)
	MTLS ClientMTLSConfig `json:"mtls,omitempty" schema:"type:object,description:mTLS configuration for client certificate provision,category:security"`
}

ClientTLSConfig holds TLS configuration for HTTP/WebSocket clients. Always uses system CA bundle first, CAFiles are ADDITIONAL trusted CAs.

type Config

type Config struct {
	TLS TLSConfig `json:"tls,omitempty" schema:"type:object,description:TLS configuration for servers and clients,category:security"`
}

Config holds platform-wide security configuration.

type ServerMTLSConfig

type ServerMTLSConfig struct {
	Enabled            bool     `json:"enabled" schema:"type:boolean,description:Enable mTLS client certificate validation,default:false,category:security"`
	ClientCAFiles      []string `` /* 129-byte string literal not displayed */
	ClientCertOptional bool     `` /* 159-byte string literal not displayed */
	AllowedClientCNs   []string `` /* 137-byte string literal not displayed */
}

ServerMTLSConfig holds mTLS configuration for servers (client certificate validation).

type ServerTLSConfig

type ServerTLSConfig struct {
	Enabled    bool   `json:"enabled" schema:"type:boolean,description:Enable TLS for server,default:false,category:security"`
	Mode       string `json:"mode,omitempty" schema:"type:string,description:TLS mode (manual or acme),default:manual,category:security"`
	CertFile   string `json:"cert_file,omitempty" schema:"type:string,description:Path to server certificate file,category:security"`
	KeyFile    string `json:"key_file,omitempty" schema:"type:string,description:Path to server private key file,category:security"`
	MinVersion string `json:"min_version,omitempty" schema:"type:string,description:Minimum TLS version (1.2 or 1.3),default:1.2,category:security"`

	// ACME mode (Tier 3)
	ACME ACMEConfig `json:"acme,omitempty" schema:"type:object,description:ACME configuration for automatic certificates,category:security"`

	// mTLS support (both modes)
	MTLS ServerMTLSConfig `json:"mtls,omitempty" schema:"type:object,description:mTLS configuration for client certificate validation,category:security"`
}

ServerTLSConfig holds TLS configuration for HTTP/WebSocket servers.

type TLSConfig

type TLSConfig struct {
	Server ServerTLSConfig `json:"server,omitempty" schema:"type:object,description:Server TLS configuration,category:security"`
	Client ClientTLSConfig `json:"client,omitempty" schema:"type:object,description:Client TLS configuration,category:security"`
}

TLSConfig holds TLS configuration for HTTP/WebSocket servers and clients.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL