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:
- github.com/c360studio/semengine/internal/tlsutil: Build tls.Config from these types
- github.com/c360studio/semengine/pkg/acme: ACME client implementation
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.