Documentation
¶
Overview ¶
Package mtls 提供 mTLS 双向认证配置和管理功能
Package mtls 提供 gRPC 服务端和客户端的 mTLS 凭证配置 ¶
Package mtls 提供 mTLS 双向认证配置和管理功能 ¶
此包提供通用的 mTLS 配置和证书管理能力,适用于任何 gRPC 服务。 设计为可提取到 component-base 的独立模块。
功能特性:
- 服务端和客户端 TLS 配置构建
- 证书自动重载和热更新
- 客户端证书验证(CN/OU/SAN 白名单)
- 服务身份提取
使用示例:
cfg := mtls.DefaultConfig()
cfg.CertFile = "/path/to/server.crt"
cfg.KeyFile = "/path/to/server.key"
cfg.CAFile = "/path/to/ca.crt"
creds, err := mtls.NewServerCredentials(cfg)
if err != nil {
log.Fatal(err)
}
server := grpc.NewServer(creds.GRPCServerOption())
Package mtls 提供 mTLS 客户端身份信息提取和上下文管理
Index ¶
- Constants
- func ContextWithServiceIdentity(ctx context.Context, identity *ServiceIdentity) context.Context
- func GetServiceName(ctx context.Context) string
- func GetServiceNamespace(ctx context.Context) string
- func IsEnvironment(s string) bool
- func MatchDNSSAN(actual, pattern string) bool
- func NewClientTLSConfig(certFile, keyFile, caFile, serverName string) (*tls.Config, error)
- func NewMutualTLSConfig(certFile, keyFile, caFile string) (*tls.Config, error)
- func ParseServiceFromCN(cn string) (serviceName, namespace string)
- func ParseServiceFromDNS(dns string) (serviceName, namespace string)
- type ClientCredentials
- type ClientCredentialsConfig
- type Config
- type ServerCredentials
- type ServiceIdentity
- type TLSConfigBuilder
Constants ¶
const ( // ServiceIdentityKey 服务身份上下文键 ServiceIdentityKey contextKey = "grpc_service_identity" // PeerCertificateKey 对端证书上下文键 PeerCertificateKey contextKey = "grpc_peer_certificate" )
Variables ¶
This section is empty.
Functions ¶
func ContextWithServiceIdentity ¶
func ContextWithServiceIdentity(ctx context.Context, identity *ServiceIdentity) context.Context
ContextWithServiceIdentity 将服务身份注入上下文
func GetServiceNamespace ¶
GetServiceNamespace 快速获取服务命名空间
func NewClientTLSConfig ¶
NewClientTLSConfig 快速创建客户端 TLS 配置
func NewMutualTLSConfig ¶
NewMutualTLSConfig 快速创建双向 TLS 配置(用于服务端)
func ParseServiceFromCN ¶
ParseServiceFromCN 从 CN 解析服务名称
func ParseServiceFromDNS ¶
ParseServiceFromDNS 从 DNS SAN 解析服务名称
Types ¶
type ClientCredentials ¶
type ClientCredentials struct {
// contains filtered or unexported fields
}
ClientCredentials 客户端 mTLS 凭证
func NewClientCredentials ¶
func NewClientCredentials(cfg *ClientCredentialsConfig) (*ClientCredentials, error)
NewClientCredentials 创建客户端 mTLS 凭证
func (*ClientCredentials) GRPCDialOption ¶
func (c *ClientCredentials) GRPCDialOption() grpc.DialOption
GRPCDialOption 返回 gRPC Dial 选项
func (*ClientCredentials) TransportCredentials ¶
func (c *ClientCredentials) TransportCredentials() credentials.TransportCredentials
TransportCredentials 返回 gRPC 传输凭证
type ClientCredentialsConfig ¶
type ClientCredentialsConfig struct {
// 客户端证书
CertFile string `json:"cert_file" mapstructure:"cert-file"` // 客户端证书文件
KeyFile string `json:"key_file" mapstructure:"key-file"` // 客户端私钥文件
// CA 证书(用于验证服务端)
CAFile string `json:"ca_file" mapstructure:"ca-file"` // Root CA 证书文件
// 服务端名称(用于 SNI)
ServerName string `json:"server_name" mapstructure:"server-name"` // 服务端主机名
// TLS 配置
InsecureSkipVerify bool `json:"insecure_skip_verify" mapstructure:"insecure-skip-verify"` // 跳过服务端证书验证(仅用于测试)
}
ClientCredentialsConfig 客户端 mTLS 凭证配置
func (*ClientCredentialsConfig) Validate ¶
func (c *ClientCredentialsConfig) Validate() error
Validate 验证客户端凭证配置
type Config ¶
type Config struct {
// 服务端证书配置
CertFile string `json:"cert_file" mapstructure:"cert-file"` // 服务端证书文件
KeyFile string `json:"key_file" mapstructure:"key-file"` // 服务端私钥文件
// CA 证书配置
CAFile string `json:"ca_file" mapstructure:"ca-file"` // 根 CA 证书文件
CADir string `json:"ca_dir" mapstructure:"ca-dir"` // CA 证书目录(支持多级 CA)
// 客户端证书验证配置
RequireClientCert bool `json:"require_client_cert" mapstructure:"require-client-cert"` // 是否要求客户端证书
AllowedCNs []string `json:"allowed_cns" mapstructure:"allowed-cns"` // 允许的客户端证书 CN 列表
AllowedOUs []string `json:"allowed_ous" mapstructure:"allowed-ous"` // 允许的客户端证书 OU 列表
AllowedDNSSANs []string `json:"allowed_dns_sans" mapstructure:"allowed-dns-sans"` // 允许的 DNS SAN 列表
// TLS 版本控制
MinVersion uint16 `json:"min_version" mapstructure:"min-version"` // 最低 TLS 版本 (默认 TLS 1.2)
MaxVersion uint16 `json:"max_version" mapstructure:"max-version"` // 最高 TLS 版本 (默认 TLS 1.3)
// 证书轮换配置
EnableAutoReload bool `json:"enable_auto_reload" mapstructure:"enable-auto-reload"` // 启用证书自动重载
ReloadInterval time.Duration `json:"reload_interval" mapstructure:"reload-interval"` // 证书重载检查间隔
CertExpiryThreshold time.Duration `json:"cert_expiry_threshold" mapstructure:"cert-expiry-threshold"` // 证书过期预警阈值
}
Config mTLS 配置
type ServerCredentials ¶
type ServerCredentials struct {
// contains filtered or unexported fields
}
ServerCredentials 服务端 mTLS 凭证
func NewServerCredentials ¶
func NewServerCredentials(cfg *Config) (*ServerCredentials, error)
NewServerCredentials 创建服务端 mTLS 凭证
func (*ServerCredentials) GRPCServerOption ¶
func (s *ServerCredentials) GRPCServerOption() grpc.ServerOption
GRPCServerOption 返回 gRPC 服务器选项
func (*ServerCredentials) StartAutoReload ¶
func (s *ServerCredentials) StartAutoReload()
StartAutoReload 启动证书自动重载
func (*ServerCredentials) TransportCredentials ¶
func (s *ServerCredentials) TransportCredentials() credentials.TransportCredentials
TransportCredentials 返回 gRPC 传输凭证
type ServiceIdentity ¶
type ServiceIdentity struct {
// 证书基本信息
CommonName string `json:"common_name"` // 证书 CN
OrganizationalUnits []string `json:"organizational_units"` // 证书 OU 列表
Organization []string `json:"organization"` // 证书 O 列表
DNSNames []string `json:"dns_names"` // SAN DNS 名称
IPAddresses []string `json:"ip_addresses"` // SAN IP 地址
// 解析后的服务标识
ServiceName string `json:"service_name"` // 服务名称(从 CN 或 SAN 提取)
ServiceNamespace string `json:"service_namespace"` // 服务命名空间
Environment string `json:"environment"` // 环境标识 (dev/staging/prod)
// 证书元数据
SerialNumber string `json:"serial_number"` // 证书序列号
NotBefore string `json:"not_before"` // 证书生效时间
NotAfter string `json:"not_after"` // 证书过期时间
IssuerCommonName string `json:"issuer_common_name"` // 颁发者 CN
}
ServiceIdentity 服务身份信息(从 mTLS 证书中提取)
func ExtractServiceIdentity ¶
func ExtractServiceIdentity(ctx context.Context) (*ServiceIdentity, error)
ExtractServiceIdentity 从 gRPC 上下文中提取服务身份
func ParseCertificateIdentity ¶
func ParseCertificateIdentity(cert *x509.Certificate) *ServiceIdentity
ParseCertificateIdentity 从 X.509 证书中解析服务身份
func ServiceIdentityFromContext ¶
func ServiceIdentityFromContext(ctx context.Context) (*ServiceIdentity, bool)
ServiceIdentityFromContext 从上下文获取服务身份
func (*ServiceIdentity) FullIdentifier ¶
func (s *ServiceIdentity) FullIdentifier() string
FullIdentifier 返回完整的服务标识符
type TLSConfigBuilder ¶
type TLSConfigBuilder struct {
// contains filtered or unexported fields
}
TLSConfigBuilder mTLS 配置构建器
func NewTLSConfigBuilder ¶
func NewTLSConfigBuilder(cfg *Config) (*TLSConfigBuilder, error)
NewTLSConfigBuilder 创建 TLS 配置构建器
func (*TLSConfigBuilder) CheckCertExpiry ¶
func (b *TLSConfigBuilder) CheckCertExpiry() (time.Duration, error)
CheckCertExpiry 检查证书过期时间
func (*TLSConfigBuilder) GetTLSConfig ¶
func (b *TLSConfigBuilder) GetTLSConfig() *tls.Config
GetTLSConfig 获取当前 TLS 配置
func (*TLSConfigBuilder) StartAutoReload ¶
func (b *TLSConfigBuilder) StartAutoReload()
StartAutoReload 启动证书自动重载