修复自定义证书导入与配置应用流程
Security Checks / security (push) Waiting to run

This commit is contained in:
xuans committed 2026-09-08 14:03:41 +08:00
1 parent fd2e703b2c
commit 2e4813ec92
11 files changed
+660 -34

No files matched your search

+25
View File
@@ -279,6 +279,15 @@ func (m *ConfigManager) Validate(ctx context.Context, req ValidateRequest) (*Val
if err != nil {
return nil, err
}
if req.Section == SectionSSL {
if _, err := prepareCustomSSLPaths(m.loader.root, &candidate); err != nil {
issue, ok := SSLValidationIssue(err)
if !ok {
issue = PublicIssue{Code: "SSL_INVALID", Message: "证书校验失败,请检查证书文件"}
}
return &ValidationResult{Valid: false, Generation: current.Generation, Issues: []PublicIssue{issue}}, nil
}
}
setCandidateGeneration(&candidate, current.Generation+1)
if err := ValidateRuntimeConfig(candidate, m.options); err != nil {
return &ValidationResult{Valid: false, Generation: current.Generation, Issues: []PublicIssue{{Code: "CONFIG_INVALID", Message: err.Error()}}}, nil
@@ -312,6 +321,13 @@ func (m *ConfigManager) Update(ctx context.Context, req UpdateRequest) (*UpdateR
if err != nil {
return nil, err
}
var sslMaterial *customSSLMaterial
if req.Section == SectionSSL {
sslMaterial, err = prepareCustomSSLPaths(m.loader.root, &candidate)
if err != nil {
return nil, err
}
}
if err := contextError(ctx); err != nil {
return nil, err
}
@@ -332,6 +348,10 @@ func (m *ConfigManager) Update(ctx context.Context, req UpdateRequest) (*UpdateR
if err != nil {
return nil, err
}
if err := sslMaterial.stage(m.loader.root, &candidate); err != nil {
return nil, err
}
setCandidateGeneration(&candidate, current.Generation+1)
m.mu.Lock()
m.pending = &pendingConfig{ID: id, Candidate: candidate, Section: req.Section, Actor: req.Actor, Confirmation: req.Confirmation, PreviousRestart: append([]ServiceName(nil), m.status.PendingRestart...)}
m.status.PendingRestart = mergeServices(m.status.PendingRestart, servicesForSection(req.Section))
@@ -397,6 +417,11 @@ func (m *ConfigManager) apply(ctx context.Context, generation uint64, actor Audi
if err := ValidateRuntimeConfig(candidate, m.options); err != nil {
return nil, err
}
if pending.Section == SectionSSL {
if err := validateCustomSSLReferences(m.loader.root, candidate); err != nil {
return nil, err
}
}
if err := ValidateRuntimeSecrets(m.vault, current); err != nil {
return nil, err
}
+210
View File
@@ -0,0 +1,210 @@
package config
import (
"errors"
"io"
"os"
"path/filepath"
"strings"
)
var ErrSSLFileUnavailable = errors.New("SSL certificate file is missing or unreadable")
// customSSLMaterial 在只读准备阶段保留已校验的材料,确认后再暂存,避免重新读取外部文件。
type customSSLMaterial struct {
privateKey []byte
certificate []byte
domains []string
}
func prepareCustomSSLPaths(root string, candidate *RuntimeConfig) (*customSSLMaterial, error) {
ssl := &candidate.SSL.TLS
if EffectiveSSLManagement(*ssl) != SSLManagementCustom {
return nil, nil
}
certificatePath := strings.TrimSpace(ssl.CertificateRef)
privateKeyPath := strings.TrimSpace(ssl.PrivateKeyRef)
if certificatePath == "" && privateKeyPath == "" {
return nil, nil
}
if certificatePath == "" || privateKeyPath == "" {
return nil, ErrInvalidSSLReference
}
// 已保存的受管引用只复验,不重复导入;普通相对路径以项目运行根目录为基准。
if strings.HasPrefix(certificatePath, managedSSLRelativeRoot+"/") && strings.HasPrefix(privateKeyPath, managedSSLRelativeRoot+"/") {
return nil, validateCustomSSLReferences(root, *candidate)
}
var err error
certificatePath, err = resolveCustomSSLInput(root, certificatePath)
if err != nil {
return nil, err
}
privateKeyPath, err = resolveCustomSSLInput(root, privateKeyPath)
if err != nil {
return nil, err
}
material := &customSSLMaterial{domains: runtimeCertificateDomains(candidate)}
material.privateKey, err = readExternalSSLFile(privateKeyPath, true)
if err != nil {
return nil, err
}
material.certificate, err = readExternalSSLFile(certificatePath, false)
if err != nil {
return nil, err
}
if err := validateSSLMaterial(material.privateKey, material.certificate, nil, material.domains); err != nil {
return nil, err
}
ssl.Mode = ManagedSSLModeUpload
ssl.DefaultDirectory = "config/ssl"
ssl.CustomDirectory = "config/ssl"
// 仅在内存中使用合法占位引用完成跨分区校验,最终候选必须换成独立版本。
ssl.CertificateRef = managedSSLReference(ManagedSSLModeUpload, "public.crt")
ssl.PrivateKeyRef = managedSSLReference(ManagedSSLModeUpload, "private.key")
return material, nil
}
func (material *customSSLMaterial) stage(root string, candidate *RuntimeConfig) error {
if material == nil {
return nil
}
reference, err := stageManagedSSLAtRoot(root, ManagedSSLModeUpload, material.privateKey, material.certificate, nil, material.domains)
if err != nil {
return err
}
candidate.SSL.TLS.CertificateRef = reference.CertificateRef
candidate.SSL.TLS.PrivateKeyRef = reference.PrivateKeyRef
return nil
}
func resolveCustomSSLInput(root, value string) (string, error) {
for _, part := range strings.FieldsFunc(value, func(r rune) bool { return r == '/' || r == '\\' }) {
if part == ".." {
return "", ErrInvalidSSLReference
}
}
if !filepath.IsAbs(value) {
if isWindowsAbsolute(value) || filepath.VolumeName(value) != "" || strings.HasPrefix(value, "/") || strings.HasPrefix(value, `\`) {
return "", ErrInvalidSSLReference
}
value = filepath.Join(root, value)
}
path, err := filepath.Abs(value)
if err != nil {
return "", ErrInvalidSSLReference
}
return path, nil
}
func readExternalSSLFile(path string, privateKey bool) ([]byte, error) {
info, err := os.Lstat(path)
if err != nil {
return nil, ErrSSLFileUnavailable
}
if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() || info.Size() <= 0 || info.Size() > maxManagedSSLFileSize || hasMultipleFileLinks(path) {
return nil, ErrUnsafeSSLFile
}
resolvedDirectory, err := filepath.EvalSymlinks(filepath.Dir(path))
if err != nil || filepath.Clean(resolvedDirectory) != filepath.Clean(filepath.Dir(path)) {
return nil, ErrUnsafeSSLFile
}
if privateKey && info.Mode().Perm()&0077 != 0 && runtimeSupportsPermissionCheck() {
return nil, ErrSSLPrivateKeyPermission
}
file, err := os.Open(path)
if err != nil {
return nil, ErrSSLFileUnavailable
}
defer file.Close()
opened, err := file.Stat()
if err != nil || !os.SameFile(info, opened) {
return nil, ErrUnsafeSSLFile
}
data, err := io.ReadAll(io.LimitReader(file, maxManagedSSLFileSize+1))
if err != nil {
return nil, ErrSSLFileUnavailable
}
after, err := os.Lstat(path)
if err != nil || !os.SameFile(info, after) || info.Size() != after.Size() || !info.ModTime().Equal(after.ModTime()) || len(data) != int(info.Size()) || len(data) > maxManagedSSLFileSize {
return nil, ErrUnsafeSSLFile
}
return data, nil
}
func validateCustomSSLReferences(root string, candidate RuntimeConfig) error {
ssl := candidate.SSL.TLS
if EffectiveSSLManagement(ssl) != SSLManagementCustom || ssl.CertificateRef == "" && ssl.PrivateKeyRef == "" {
return nil
}
reference, err := resolveManagedSSLReferencesAtRoot(root, ssl)
if err != nil {
return err
}
privateKey, err := readExternalSSLFile(reference.PrivateKeyPath, true)
if err != nil {
return err
}
certificate, err := readExternalSSLFile(reference.CertificatePath, false)
if err != nil {
return err
}
return validateSSLMaterial(privateKey, certificate, nil, runtimeCertificateDomains(&candidate))
}
func runtimeCertificateDomains(candidate *RuntimeConfig) []string {
return SSLCertificateDomains(candidate.Root.Domains.Primary, candidate.Root.Domains.Web, candidate.Root.Domains.Accepted)
}
// SSLCertificateDomains 统一初始化和配置管理所需的 Web、主域及邮件协议域名。
func SSLCertificateDomains(primary, web string, accepted []string) []string {
seen := make(map[string]bool)
var domains []string
appendDomain := func(value string) {
value = strings.ToLower(strings.TrimSpace(value))
if value != "" && !seen[value] {
seen[value] = true
domains = append(domains, value)
}
}
appendDomain(web)
appendDomain(primary)
for _, domain := range accepted {
domain = strings.TrimSpace(domain)
if domain == "" {
continue
}
appendDomain(domain)
appendDomain("smtp." + domain)
appendDomain("pop." + domain)
appendDomain("imap." + domain)
}
return domains
}
// SSLValidationIssue 将已知证书错误转换成安全的中文提示,不回显磁盘路径或私钥材料。
func SSLValidationIssue(err error) (PublicIssue, bool) {
issue := PublicIssue{Code: "SSL_INVALID"}
switch {
case errors.Is(err, ErrSSLFileUnavailable):
issue.Message = "证书或私钥文件不存在或无法读取,请检查服务器路径和运行用户权限"
case errors.Is(err, ErrSSLCertificateMismatch):
issue.Message = "证书与私钥不匹配,请选择同一套证书文件"
case errors.Is(err, ErrSSLCertificateExpired):
issue.Message = "证书尚未生效或已经过期,请更换有效证书"
case errors.Is(err, ErrSSLCertificateDomain):
issue.Message = "证书未覆盖已配置的主域名、Web 域名或 SMTP、IMAP、POP3 域名"
case errors.Is(err, ErrSSLPrivateKeyPermission):
issue.Message = "私钥权限过于宽松,请限制为仅运行用户可读取"
case errors.Is(err, ErrUnsafeSSLFile):
issue.Message = "证书文件不安全或大小无效,请使用不超过 1 MB 的普通文件,避免链接文件"
case errors.Is(err, ErrInvalidSSLMaterial):
issue.Message = "证书内容、证书链或密钥强度无效,请使用有效的 PEM 证书和私钥"
case errors.Is(err, ErrInvalidSSLReference):
issue.Message = "请填写完整的证书和私钥路径,路径不能包含上级目录跳转"
case errors.Is(err, ErrInvalidSSLMode), errors.Is(err, ErrInvalidSSL):
issue.Message = "证书管理方式或存储配置无效,请检查 SSL 配置"
default:
return PublicIssue{}, false
}
return issue, true
}
+36 -12
View File
@@ -99,6 +99,10 @@ func LoadRuntimeTLSCertificate(cfg *Config) (tls.Certificate, error) {
// ImportManagedSSL 校验证书材料后写入候选目录,并原子切换 current 目录。
func ImportManagedSSL(mode string, privateKeyPEM, certificatePEM, issuerPEM []byte, domains []string) (ManagedSSLReference, error) {
return importManagedSSLAtRoot(ROOT_PATH, mode, privateKeyPEM, certificatePEM, issuerPEM, domains)
}
func importManagedSSLAtRoot(root string, mode string, privateKeyPEM, certificatePEM, issuerPEM []byte, domains []string) (ManagedSSLReference, error) {
if !validManagedSSLMode(mode) {
return ManagedSSLReference{}, ErrInvalidSSLMode
}
@@ -106,11 +110,11 @@ func ImportManagedSSL(mode string, privateKeyPEM, certificatePEM, issuerPEM []by
return ManagedSSLReference{}, err
}
rootPath, err := managedSSLRootPath(mode)
rootPath, err := managedSSLRootPathAtRoot(root, mode)
if err != nil {
return ManagedSSLReference{}, err
}
if err := ensureManagedDirectory(rootPath); err != nil {
if err := ensureManagedDirectoryAtRoot(root, rootPath); err != nil {
return ManagedSSLReference{}, err
}
@@ -199,21 +203,25 @@ func ImportManagedSSL(mode string, privateKeyPEM, certificatePEM, issuerPEM []by
// ResolveManagedSSLReferences 将内部引用解析为受控文件路径,拒绝任意路径输入。
func ResolveManagedSSLReferences(ssl SSLConfig) (ManagedSSLReference, error) {
return resolveManagedSSLReferencesAtRoot(ROOT_PATH, ssl)
}
func resolveManagedSSLReferencesAtRoot(root string, ssl SSLConfig) (ManagedSSLReference, error) {
if !validManagedSSLMode(ssl.Mode) {
return ManagedSSLReference{}, ErrInvalidSSLMode
}
if ssl.CertificateRef == "" || ssl.PrivateKeyRef == "" {
return ManagedSSLReference{}, ErrInvalidSSLReference
}
rootPath, err := managedSSLRootPath(ssl.Mode)
rootPath, err := managedSSLRootPathAtRoot(root, ssl.Mode)
if err != nil {
return ManagedSSLReference{}, err
}
certificatePath, err := resolveManagedReference(rootPath, ssl.CertificateRef, "public.crt")
certificatePath, err := resolveManagedReferenceAtRoot(root, rootPath, ssl.CertificateRef, "public.crt")
if err != nil {
return ManagedSSLReference{}, err
}
privateKeyPath, err := resolveManagedReference(rootPath, ssl.PrivateKeyRef, "private.key")
privateKeyPath, err := resolveManagedReferenceAtRoot(root, rootPath, ssl.PrivateKeyRef, "private.key")
if err != nil {
return ManagedSSLReference{}, err
}
@@ -363,10 +371,14 @@ func validManagedSSLMode(mode string) bool {
}
func managedSSLRootPath(mode string) (string, error) {
return managedSSLRootPathAtRoot(ROOT_PATH, mode)
}
func managedSSLRootPathAtRoot(root string, mode string) (string, error) {
if !validManagedSSLMode(mode) {
return "", ErrInvalidSSLMode
}
rootPath, err := filepath.Abs(filepath.Clean(ROOT_PATH))
rootPath, err := filepath.Abs(filepath.Clean(root))
if err != nil {
return "", err
}
@@ -386,6 +398,10 @@ func managedSSLReference(mode, name string) string {
}
func resolveManagedReference(rootPath, reference, expectedName string) (string, error) {
return resolveManagedReferenceAtRoot(ROOT_PATH, rootPath, reference, expectedName)
}
func resolveManagedReferenceAtRoot(root, rootPath, reference, expectedName string) (string, error) {
rawReference := strings.TrimSpace(reference)
if rawReference == "" || strings.Contains(rawReference, `\`) || filepath.IsAbs(rawReference) || isWindowsAbsolute(rawReference) {
return "", ErrInvalidSSLReference
@@ -394,7 +410,7 @@ func resolveManagedReference(rootPath, reference, expectedName string) (string,
if filepath.ToSlash(filepath.Clean(reference)) != rawReference {
return "", ErrInvalidSSLReference
}
workspaceRoot, err := filepath.Abs(filepath.Clean(ROOT_PATH))
workspaceRoot, err := filepath.Abs(filepath.Clean(root))
if err != nil {
return "", ErrInvalidSSLReference
}
@@ -424,21 +440,25 @@ func validSSLVersion(version string) bool {
// StageManagedSSL 只写入独立版本,不替换现用文件;配置事务成功后引用才生效。
func StageManagedSSL(mode string, privateKeyPEM, certificatePEM, issuerPEM []byte, domains []string) (ManagedSSLReference, error) {
return stageManagedSSLAtRoot(ROOT_PATH, mode, privateKeyPEM, certificatePEM, issuerPEM, domains)
}
func stageManagedSSLAtRoot(root string, mode string, privateKeyPEM, certificatePEM, issuerPEM []byte, domains []string) (ManagedSSLReference, error) {
if err := validateSSLMaterial(privateKeyPEM, certificatePEM, issuerPEM, domains); err != nil {
return ManagedSSLReference{}, err
}
root, err := managedSSLRootPath(mode)
managedRoot, err := managedSSLRootPathAtRoot(root, mode)
if err != nil {
return ManagedSSLReference{}, err
}
if err := ensureManagedDirectory(root); err != nil {
if err := ensureManagedDirectoryAtRoot(root, managedRoot); err != nil {
return ManagedSSLReference{}, err
}
token, err := randomStorageToken()
if err != nil {
return ManagedSSLReference{}, err
}
directory := filepath.Join(root, "version-"+token)
directory := filepath.Join(managedRoot, "version-"+token)
if err := os.Mkdir(directory, 0700); err != nil {
return ManagedSSLReference{}, err
}
@@ -461,7 +481,7 @@ func StageManagedSSL(mode string, privateKeyPEM, certificatePEM, issuerPEM []byt
if err := validateManagedSSLFiles(publicPath, privatePath); err != nil {
return ManagedSSLReference{}, err
}
rootPath, err := filepath.Abs(ROOT_PATH)
rootPath, err := filepath.Abs(root)
if err != nil {
return ManagedSSLReference{}, err
}
@@ -580,7 +600,11 @@ func removeManagedSSLDirectory(directory string) error {
}
func ensureManagedDirectory(directory string) error {
rootPath, err := filepath.Abs(filepath.Clean(ROOT_PATH))
return ensureManagedDirectoryAtRoot(ROOT_PATH, directory)
}
func ensureManagedDirectoryAtRoot(root, directory string) error {
rootPath, err := filepath.Abs(filepath.Clean(root))
if err != nil {
return err
}
+52
View File
@@ -203,6 +203,58 @@ func TestValidateSSLMaterialRejectsDomainExpiryAndWeakKeys(t *testing.T) {
}
}
func TestPrepareCustomSSLPathsImportsExternalFilesOnlyWhenSaving(t *testing.T) {
root := t.TempDir()
previousRoot := ROOT_PATH
ROOT_PATH = root
t.Cleanup(func() { ROOT_PATH = previousRoot })
external := t.TempDir()
privateKeyPEM, certificatePEM := testManagedCertificate(t, "mail.example.com", time.Now().Add(-time.Hour), time.Now().Add(24*time.Hour), 2048)
privateKeyPath := filepath.Join(external, "privkey.pem")
certificatePath := filepath.Join(external, "fullchain.pem")
if err := os.WriteFile(privateKeyPath, privateKeyPEM, 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(certificatePath, certificatePEM, 0600); err != nil {
t.Fatal(err)
}
runtime := validRuntimeConfig()
runtime.Root.Domains = DomainConfig{Primary: "mail.example.com", Web: "mail.example.com"}
runtime.SSL.TLS = SSLConfig{
Management: SSLManagementCustom,
Mode: ManagedSSLModeUpload,
DefaultDirectory: "config/ssl",
CustomDirectory: "config/ssl",
CertificateRef: certificatePath,
PrivateKeyRef: privateKeyPath,
}
material, err := prepareCustomSSLPaths(root, &runtime)
if err != nil {
t.Fatalf("校验外部证书失败: %v", err)
}
if runtime.SSL.TLS.CertificateRef == certificatePath || runtime.SSL.TLS.PrivateKeyRef == privateKeyPath {
t.Fatal("仅校验阶段不应保留外部证书路径")
}
managedRoot := filepath.Join(root, "config", "ssl", "managed", "upload")
if _, err := os.Stat(managedRoot); !os.IsNotExist(err) {
t.Fatalf("仅校验阶段不应创建受管目录,error = %v", err)
}
if err := material.stage(root, &runtime); err != nil {
t.Fatalf("保存外部证书失败: %v", err)
}
if runtime.SSL.TLS.CertificateRef == certificatePath || runtime.SSL.TLS.PrivateKeyRef == privateKeyPath {
t.Fatal("保存后不应继续使用外部证书路径")
}
if !strings.HasPrefix(runtime.SSL.TLS.CertificateRef, "config/ssl/managed/upload/version-") {
t.Fatalf("证书引用未切换到受管版本: %q", runtime.SSL.TLS.CertificateRef)
}
if _, err := ResolveManagedSSLReferences(runtime.SSL.TLS); err != nil {
t.Fatalf("受管证书引用无法解析: %v", err)
}
}
func TestValidateSSLMaterialAcceptsBundledIssuerWithoutDuplicateChainEntry(t *testing.T) {
privateKeyPEM, certificatePEM, issuerPEM := testChainedCertificate(t)
certificateBundle := append(append([]byte{}, certificatePEM...), issuerPEM...)
+3
View File
@@ -42,6 +42,9 @@ func configErrorDetails(err error) (string, int, string, map[string]string) {
status := http.StatusBadRequest
message := "配置请求未完成"
fields := map[string]string(nil)
if issue, ok := config.SSLValidationIssue(err); ok {
return issue.Code, http.StatusUnprocessableEntity, issue.Message, nil
}
var denial *access.Denial
switch {
+10
View File
@@ -2,6 +2,7 @@ package controllers
import (
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"strings"
@@ -14,6 +15,15 @@ import (
"git.pcux.cn/xuans/Smail/services/dbmigration"
)
func TestConfigSSLErrorUsesSafeSpecificMessage(t *testing.T) {
for _, failure := range []error{config.ErrSSLFileUnavailable, config.ErrSSLCertificateMismatch, config.ErrSSLCertificateExpired, config.ErrSSLCertificateDomain, config.ErrInvalidSSLReference} {
code, status, message, _ := configErrorDetails(fmt.Errorf("%w: /private/internal-path", failure))
if code != "SSL_INVALID" || status != http.StatusUnprocessableEntity || message == "" || strings.Contains(message, "/private/") || strings.Contains(message, "配置校验未通过") {
t.Fatalf("证书错误未正确脱敏或区分: %s %d %s", code, status, message)
}
}
}
func TestWriteConfigErrorKeepsStableAuthorizationCode(t *testing.T) {
recorder := httptest.NewRecorder()
writeConfigError(recorder, &access.Denial{Code: access.CodeRecoveryCodeRequired})
+1 -22
View File
@@ -313,28 +313,7 @@ func sslDomains(cfg *config.Config) []string {
if cfg == nil {
return nil
}
seen := make(map[string]struct{})
domains := make([]string, 0, len(cfg.Domains)*3+1)
appendDomain := func(domain string) {
domain = strings.TrimSpace(domain)
if domain == "" {
return
}
if _, exists := seen[domain]; exists {
return
}
seen[domain] = struct{}{}
domains = append(domains, domain)
}
appendDomain(cfg.WebDomain)
appendDomain(cfg.Domain)
for _, domain := range cfg.Domains {
appendDomain(domain)
appendDomain("smtp." + domain)
appendDomain("pop." + domain)
appendDomain("imap." + domain)
}
return domains
return config.SSLCertificateDomains(cfg.Domain, cfg.WebDomain, cfg.Domains)
}
func certificateMatchesConfiguredDomains(cert *x509.Certificate, cfg *config.Config) bool {