mtls

package
v0.3.9 Latest Latest
Warning

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

Go to latest
Published: Dec 10, 2025 License: Apache-2.0 Imports: 13 Imported by: 0

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

View Source
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 GetServiceName

func GetServiceName(ctx context.Context) string

GetServiceName 快速获取服务名称

func GetServiceNamespace

func GetServiceNamespace(ctx context.Context) string

GetServiceNamespace 快速获取服务命名空间

func IsEnvironment

func IsEnvironment(s string) bool

IsEnvironment 判断是否为环境标识

func MatchDNSSAN

func MatchDNSSAN(actual, pattern string) bool

MatchDNSSAN 匹配 DNS SAN(支持通配符)

func NewClientTLSConfig

func NewClientTLSConfig(certFile, keyFile, caFile, serverName string) (*tls.Config, error)

NewClientTLSConfig 快速创建客户端 TLS 配置

func NewMutualTLSConfig

func NewMutualTLSConfig(certFile, keyFile, caFile string) (*tls.Config, error)

NewMutualTLSConfig 快速创建双向 TLS 配置(用于服务端)

func ParseServiceFromCN

func ParseServiceFromCN(cn string) (serviceName, namespace string)

ParseServiceFromCN 从 CN 解析服务名称

func ParseServiceFromDNS

func ParseServiceFromDNS(dns string) (serviceName, namespace string)

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 配置

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig 返回默认的 mTLS 配置

func (*Config) Validate

func (c *Config) Validate() error

Validate 验证配置

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) Stop

func (s *ServerCredentials) Stop()

Stop 停止自动重载

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 返回完整的服务标识符

func (*ServiceIdentity) String

func (s *ServiceIdentity) String() string

String 返回服务身份的字符串表示

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 启动证书自动重载

func (*TLSConfigBuilder) Stop

func (b *TLSConfigBuilder) Stop()

Stop 停止自动重载

Jump to

Keyboard shortcuts

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