Documentation
¶
Overview ¶
Package tlsutil provides TLS configuration utilities for secure connections.
Overview ¶
The tlsutil package bridges security configuration types (pkg/security) and Go's crypto/tls package. It creates properly configured tls.Config values for both server and client use cases, with support for mTLS.
Key features:
- Server TLS configuration
- Client TLS configuration (with system CA integration)
- Mutual TLS (mTLS) for client certificate validation/provision
Architecture ¶
┌─────────────────────────────────────────────────────────────────────┐
│ security.Config │
│ (Platform-wide security configuration) │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ tlsutil │
│ LoadServerTLSConfig() │ LoadClientTLSConfig() │
│ LoadServerTLSConfigWithMTLS() │ LoadClientTLSConfigWithMTLS() │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ *tls.Config │
│ (Ready to use with http.Server, tls.Dial, etc.) │
└─────────────────────────────────────────────────────────────────────┘
Usage ¶
Basic server TLS:
cfg := security.ServerTLSConfig{
Enabled: true,
CertFile: "/etc/ssl/server.crt",
KeyFile: "/etc/ssl/server.key",
}
tlsConfig, err := tlsutil.LoadServerTLSConfig(cfg)
if err != nil {
log.Fatal(err)
}
server := &http.Server{
Addr: ":443",
TLSConfig: tlsConfig,
}
Server with mTLS (require client certificates):
tlsConfig, err := tlsutil.LoadServerTLSConfigWithMTLS(
cfg,
security.ServerMTLSConfig{
Enabled: true,
ClientCAFiles: []string{"/etc/ssl/client-ca.pem"},
AllowedClientCNs: []string{"service-a"},
},
)
Client TLS (uses system CAs plus additional):
cfg := security.ClientTLSConfig{
CAFiles: []string{"/etc/ssl/internal-ca.pem"},
}
tlsConfig, err := tlsutil.LoadClientTLSConfig(cfg)
if err != nil {
log.Fatal(err)
}
client := &http.Client{
Transport: &http.Transport{TLSClientConfig: tlsConfig},
}
Client with mTLS (present client certificate):
tlsConfig, err := tlsutil.LoadClientTLSConfigWithMTLS(
cfg,
security.ClientMTLSConfig{
Enabled: true,
CertFile: "/etc/ssl/client.crt",
KeyFile: "/etc/ssl/client.key",
},
)
Client Certificate Verification ¶
For mTLS servers, optional CN whitelist:
mtlsCfg := security.ServerMTLSConfig{
Enabled: true,
ClientCAFiles: []string{"/etc/ssl/client-ca.pem"},
AllowedClientCNs: []string{"service-a", "service-b"},
}
Only certificates with matching Common Names are accepted.
TLS Version Configuration ¶
Supported MinVersion values:
- "1.2" - TLS 1.2 (default, widely compatible)
- "1.3" - TLS 1.3 (more secure, modern clients only)
If unspecified, defaults to TLS 1.2. Any other value is refused with an invalid-configuration error.
Error Handling ¶
Errors are classified using the errs package:
- Fatal errors: File not found, invalid PEM data
- Invalid errors: a MinVersion other than "1.2", "1.3" or empty
Thread Safety ¶
All Load* functions are safe for concurrent use. The returned tls.Config is thread-safe for concurrent reads.
See Also ¶
Related packages:
- github.com/c360studio/semengine/pkg/security: Configuration types
- crypto/tls: Go standard library TLS package
Package tlsutil provides TLS configuration utilities for secure connections.
Index ¶
- func LoadClientTLSConfig(cfg security.ClientTLSConfig) (*tls.Config, error)
- func LoadClientTLSConfigWithMTLS(cfg security.ClientTLSConfig, mtlsCfg security.ClientMTLSConfig) (*tls.Config, error)
- func LoadServerTLSConfig(cfg security.ServerTLSConfig) (*tls.Config, error)
- func LoadServerTLSConfigWithMTLS(cfg security.ServerTLSConfig, mtlsCfg security.ServerMTLSConfig) (*tls.Config, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadClientTLSConfig ¶
func LoadClientTLSConfig(cfg security.ClientTLSConfig) (*tls.Config, error)
LoadClientTLSConfig creates a tls.Config for HTTP/WebSocket clients from platform config Always uses system CA bundle first, CAFiles are additional trusted CAs
func LoadClientTLSConfigWithMTLS ¶
func LoadClientTLSConfigWithMTLS(cfg security.ClientTLSConfig, mtlsCfg security.ClientMTLSConfig) (*tls.Config, error)
LoadClientTLSConfigWithMTLS creates a tls.Config for HTTP/WebSocket clients with optional mTLS support
func LoadServerTLSConfig ¶
func LoadServerTLSConfig(cfg security.ServerTLSConfig) (*tls.Config, error)
LoadServerTLSConfig creates a tls.Config for HTTP/WebSocket servers from platform config
func LoadServerTLSConfigWithMTLS ¶
func LoadServerTLSConfigWithMTLS(cfg security.ServerTLSConfig, mtlsCfg security.ServerMTLSConfig) (*tls.Config, error)
LoadServerTLSConfigWithMTLS creates a tls.Config for HTTP/WebSocket servers with optional mTLS support. Enabling mTLS while server TLS is disabled is refused with errs.ErrInvalidConfig: a plain HTTP server cannot verify a client certificate, so there is no config that honours both.
Types ¶
This section is empty.