自动准备初始化证书目录并在提交前校验代理入口

This commit is contained in:
xuans committed 2026-09-27 00:03:31 +08:00
1 parent d174fb66e0
commit 176bf6ed6b
21 files changed
+889 -12

No files matched your search

+23 -2
View File
@@ -1,17 +1,23 @@
package bootstrap
import (
"context"
"crypto/rand"
"errors"
"os"
"path/filepath"
"strings"
"git.pcux.cn/xuans/Scert/backend/internal/certstorage"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
// prepareCertificateRoot 在申请证书前验证路径,并以实际运行身份探测创建、写入和清理权限。
func prepareCertificateRoot(paths config.PathsConfig, requested string) (string, error) {
return prepareCertificateRootContext(context.Background(), paths, requested)
}
func prepareCertificateRootContext(ctx context.Context, paths config.PathsConfig, requested string) (string, error) {
root := strings.TrimSpace(requested)
if root == "" {
root = paths.Certificate
@@ -48,7 +54,9 @@ func prepareCertificateRoot(paths config.PathsConfig, requested string) (string,
}
}
if err := os.MkdirAll(root, 0o700); err != nil {
return unwritable(err)
if prepareErr := certstorage.Prepare(ctx, root); prepareErr != nil {
return unwritable(errors.Join(err, prepareErr))
}
}
directory, err := os.OpenRoot(root)
if err != nil {
@@ -59,7 +67,20 @@ func prepareCertificateRoot(paths config.PathsConfig, requested string) (string,
name := ".scert-write-check-" + rand.Text()
probe, err := directory.OpenFile(name, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
if err != nil {
return unwritable(err)
if prepareErr := certstorage.Prepare(ctx, root); prepareErr != nil {
return unwritable(errors.Join(err, prepareErr))
}
// systemd 已替换该挂载点;必须重新打开目录,不能复用旧的只读描述符。
_ = directory.Close()
directory, err = os.OpenRoot(root)
if err != nil {
return unwritable(err)
}
defer directory.Close()
probe, err = directory.OpenFile(name, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
if err != nil {
return unwritable(err)
}
}
_, writeErr := probe.Write([]byte("scert"))
syncErr := probe.Sync()
+18 -1
View File
@@ -35,6 +35,8 @@ const (
CompleteErrorInternal CompleteErrorKind = "internal"
CompleteErrorCertificatePath CompleteErrorKind = "certificate_path"
CompleteErrorCertificateAccess CompleteErrorKind = "certificate_access"
CompleteErrorProxyTrust CompleteErrorKind = "proxy_trust"
CompleteErrorProxyReadiness CompleteErrorKind = "proxy_readiness"
)
// CompleteError 只向 HTTP 层公开安全分类和通用说明,底层错误不得直接返回浏览器。
@@ -120,6 +122,7 @@ type CompleteDependencies struct {
IssueIP completionIPIssuer
SaveConfig completionConfigSaver
ValidateFiles completionCertificateValidator
VerifyProxy func(context.Context, config.Config) error
RollbackDomain func(context.Context, certificate.SavedResource) error
RollbackIP func(context.Context, ManagementCertificate) error
RemoveFile func(string) error
@@ -144,6 +147,7 @@ type Completer struct {
issueIP completionIPIssuer
saveConfig completionConfigSaver
validateFiles completionCertificateValidator
verifyProxy func(context.Context, config.Config) error
rollbackDomain func(context.Context, certificate.SavedResource) error
rollbackIP func(context.Context, ManagementCertificate) error
removeFile func(string) error
@@ -152,6 +156,9 @@ type Completer struct {
}
func NewCompleter(dependencies CompleteDependencies) *Completer {
if dependencies.VerifyProxy == nil {
dependencies.VerifyProxy = verifySetupProxy
}
if dependencies.OpenDatabase == nil {
dependencies.OpenDatabase = database.Open
}
@@ -193,6 +200,7 @@ func NewCompleter(dependencies CompleteDependencies) *Completer {
openDatabase: dependencies.OpenDatabase, migrate: dependencies.Migrate,
ensureAdmin: dependencies.EnsureAdmin, issueIP: dependencies.IssueIP,
saveConfig: dependencies.SaveConfig, validateFiles: dependencies.ValidateFiles,
verifyProxy: dependencies.VerifyProxy,
rollbackDomain: dependencies.RollbackDomain, rollbackIP: dependencies.RollbackIP,
removeFile: dependencies.RemoveFile, warn: dependencies.Warn,
completed: dependencies.BaseConfig.SetupReady,
@@ -214,6 +222,10 @@ func (completer *Completer) Complete(ctx context.Context, request CompleteReques
return result, err
}
request = normalizeCompleteRequest(request)
// 在消耗数据库和 DNS 验证令牌、创建目录或申请证书之前拒绝不受支持的信任组合。
if request.HTTPSMode == "proxy" && (request.ACMEEnvironment != "production" || request.WebHostname == "") {
return result, completeError(CompleteErrorProxyTrust, "代理管理入口必须使用正式域名证书", nil)
}
if err := validateCompleteRequest(request); err != nil {
return result, completeError(CompleteErrorInput, "初始化参数无效", err)
}
@@ -246,7 +258,7 @@ func (completer *Completer) Complete(ctx context.Context, request CompleteReques
candidate := completer.base
candidate.Normalize()
certificateRoot, err := prepareCertificateRoot(candidate.Paths, request.CertificateRoot)
certificateRoot, err := prepareCertificateRootContext(ctx, candidate.Paths, request.CertificateRoot)
if err != nil {
return result, err
}
@@ -331,6 +343,11 @@ func (completer *Completer) Complete(ctx context.Context, request CompleteReques
}
candidate.Server.TLSCert = certificateResult.fullChainPath
candidate.Server.TLSKey = certificateResult.privateKeyPath
if candidate.Server.HTTPSMode == "proxy" {
if err := completer.verifyProxy(ctx, candidate); err != nil {
return result, completeError(CompleteErrorProxyReadiness, "管理代理入口验证失败,初始化尚未提交", err)
}
}
firewallContext, cancelFirewall := context.WithTimeout(ctx, 30*time.Second)
firewallResult, err = completer.firewall.OpenTCP(firewallContext, candidate.Server.Port)
@@ -11,9 +11,12 @@ func TestCompleterPreservesExternalProxyPort(t *testing.T) {
fixture := newCompletionFixture(t, "admin.example.test")
request := fixture.request("admin.example.test")
request.HTTPSMode = "proxy"
request.ACMEEnvironment = "production"
request.ServerPort = 9004
request.ProxyHTTPSPort = 8004
result, err := fixture.completer(nil).Complete(context.Background(), request)
result, err := fixture.completer(func(deps *CompleteDependencies) {
deps.VerifyProxy = func(context.Context, config.Config) error { return nil }
}).Complete(context.Background(), request)
if err != nil {
t.Fatal(err)
}
@@ -0,0 +1,100 @@
package bootstrap
import (
"context"
"crypto/rand"
"crypto/tls"
"errors"
"io"
"net"
"net/http"
"strconv"
"strings"
"time"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
// verifySetupProxy 使用候选证书临时监听真实上游端口,再从公开域名穿过代理核验随机响应。
// 不跟随重定向、不使用环境代理、不关闭 TLS 校验;失败时不提交初始化配置。
func verifySetupProxy(ctx context.Context, candidate config.Config) error {
transport := &http.Transport{
TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS12},
DialContext: (&net.Dialer{Timeout: 3 * time.Second}).DialContext,
TLSHandshakeTimeout: 3 * time.Second, DisableKeepAlives: true,
}
return verifySetupProxyTransport(ctx, candidate, transport)
}
func verifySetupProxyTransport(ctx context.Context, candidate config.Config, transport *http.Transport) error {
defer transport.CloseIdleConnections()
if candidate.Server.HTTPSMode != "proxy" {
return nil
}
material, err := tls.LoadX509KeyPair(candidate.Server.TLSCert, candidate.Server.TLSKey)
if err != nil {
return err
}
host := strings.Trim(strings.TrimSpace(candidate.Server.Host), "[]")
if !strings.EqualFold(host, "localhost") {
ip := net.ParseIP(host)
if ip == nil || !ip.IsLoopback() {
host = "127.0.0.1"
}
}
listener, err := net.Listen("tcp", net.JoinHostPort(host, strconv.Itoa(candidate.Server.Port)))
if err != nil {
return err
}
defer listener.Close()
token := rand.Text()
path := "/.well-known/scert-setup/" + rand.Text()
server := &http.Server{
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Cache-Control", "no-store")
if r.Method != http.MethodGet || r.URL.Path != path {
http.Error(w, "管理入口正在验证", http.StatusServiceUnavailable)
return
}
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
_, _ = io.WriteString(w, token)
}),
TLSConfig: &tls.Config{MinVersion: tls.VersionTLS12, Certificates: []tls.Certificate{material}},
ReadHeaderTimeout: 3 * time.Second, WriteTimeout: 3 * time.Second, MaxHeaderBytes: 8192,
}
done := make(chan struct{})
go func() { defer close(done); _ = server.ServeTLS(listener, "", "") }()
defer func() { _ = server.Close(); <-done }()
ctx, cancel := context.WithTimeout(ctx, 12*time.Second)
defer cancel()
client := &http.Client{Transport: transport, Timeout: 4 * time.Second,
CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
}
address := strings.TrimRight(candidate.ManagementURL(), "/") + path
for successes := 0; ; {
request, err := http.NewRequestWithContext(ctx, http.MethodGet, address, nil)
if err != nil {
return err
}
response, err := client.Do(request)
valid := false
if err == nil {
body, readErr := io.ReadAll(io.LimitReader(response.Body, 256))
_ = response.Body.Close()
valid = readErr == nil && response.StatusCode == http.StatusOK && string(body) == token
}
if valid {
successes++
} else {
successes = 0
}
if successes >= 3 {
return nil
}
select {
case <-ctx.Done():
return errors.New("公开代理入口未能连续通过候选上游证书及随机响应校验")
case <-time.After(150 * time.Millisecond):
}
}
}
@@ -0,0 +1,71 @@
package bootstrap
import (
"context"
"errors"
"net/http"
"net/http/httptest"
"os"
"strings"
"testing"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
func TestProxyRejectsUntrustedModeBeforeConsumingVerification(t *testing.T) {
for _, mode := range []string{"staging", "ip"} {
t.Run(mode, func(t *testing.T) {
fixture := newCompletionFixture(t, "admin.example.test")
request := fixture.request("admin.example.test")
request.HTTPSMode = "proxy"
if mode == "ip" {
request.WebHostname = ""
request.WebPublicIP = "203.0.113.10"
request.ACMEEnvironment = "production"
}
_, err := fixture.completer(nil).Complete(context.Background(), request)
var failure *CompleteError
if !errors.As(err, &failure) || failure.Kind != CompleteErrorProxyTrust || fixture.issuer.calls != 0 {
t.Fatalf("信任模式未提前拒绝:%v", err)
}
if _, _, err := fixture.database.Claim(fixture.databaseToken); err != nil {
t.Fatalf("数据库令牌被消耗:%v", err)
}
if _, _, err := fixture.dns.Claim(fixture.dnsToken); err != nil {
t.Fatalf("DNS 令牌被消耗:%v", err)
}
})
}
}
func TestProxyFailureDoesNotCommitInitialization(t *testing.T) {
fixture := newCompletionFixture(t, "admin.example.test")
request := fixture.request("admin.example.test")
request.HTTPSMode = "proxy"
request.ACMEEnvironment = "production"
checked := false
_, err := fixture.completer(func(deps *CompleteDependencies) {
deps.VerifyProxy = func(_ context.Context, candidate config.Config) error {
checked = candidate.Server.TLSCert != "" && candidate.Server.TLSKey != ""
return errors.New("secret diagnostic")
}
}).Complete(context.Background(), request)
var failure *CompleteError
if !checked || !errors.As(err, &failure) || failure.Kind != CompleteErrorProxyReadiness {
t.Fatalf("未验证候选代理:%v", err)
}
if _, err := os.Stat(fixture.configPath); !errors.Is(err, os.ErrNotExist) {
t.Fatal("代理失败仍提交了初始化配置")
}
response := httptest.NewRecorder()
writeBootstrapCompletionError(response, failure)
if response.Code != http.StatusUnprocessableEntity || strings.Contains(response.Body.String(), "secret") {
t.Fatal("代理错误未脱敏")
}
}
func TestDirectModeDoesNotRequireProxy(t *testing.T) {
if err := verifySetupProxy(context.Background(), config.Config{Server: config.ServerConfig{HTTPSMode: "direct"}}); err != nil {
t.Fatal(err)
}
}
@@ -0,0 +1,86 @@
package bootstrap
import (
"context"
"crypto/tls"
"crypto/x509"
"io"
"log"
"net"
"net/http"
"net/http/httptest"
"net/http/httputil"
"net/url"
"os"
"path/filepath"
"strconv"
"testing"
"time"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
func TestProxyPreflightStrictTLSAndResponseProof(t *testing.T) {
for _, mode := range []string{"trusted", "untrusted-upstream", "untrusted-public", "wrong-response", "redirect"} {
t.Run(mode, func(t *testing.T) {
material := completionDomainResource("admin.example.test")
directory := t.TempDir()
cert := filepath.Join(directory, "chain.pem")
key := filepath.Join(directory, "key.pem")
if err := os.WriteFile(cert, material.Certificate, 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(key, material.PrivateKey, 0o600); err != nil {
t.Fatal(err)
}
reservation, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
port := reservation.Addr().(*net.TCPAddr).Port
_ = reservation.Close()
target, _ := url.Parse("https://127.0.0.1:" + strconv.Itoa(port))
upstreamRoots := x509.NewCertPool()
if mode != "untrusted-upstream" {
upstreamRoots.AppendCertsFromPEM(material.Certificate)
}
reverse := httputil.NewSingleHostReverseProxy(target)
reverse.ErrorLog = log.New(io.Discard, "", 0)
upstream := &http.Transport{TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS12, RootCAs: upstreamRoots, ServerName: "admin.example.test"}}
defer upstream.CloseIdleConnections()
reverse.Transport = upstream
proxy := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if mode == "wrong-response" {
_, _ = io.WriteString(w, "unrelated-service")
return
}
if mode == "redirect" {
http.Redirect(w, r, "/login", http.StatusFound)
return
}
reverse.ServeHTTP(w, r)
}))
defer proxy.Close()
publicRoots := x509.NewCertPool()
if mode != "untrusted-public" {
publicRoots.AddCert(proxy.Certificate())
}
transport := &http.Transport{TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS12, RootCAs: publicRoots}, DisableKeepAlives: true}
candidate := config.Config{
Server: config.ServerConfig{Host: "127.0.0.1", Port: port, HTTPSMode: "proxy", ProxyHTTPSPort: proxy.Listener.Addr().(*net.TCPAddr).Port, TLSCert: cert, TLSKey: key},
Web: config.WebConfig{Hostname: "127.0.0.1"},
}
ctx, cancel := context.WithTimeout(t.Context(), time.Second)
defer cancel()
err = verifySetupProxyTransport(ctx, candidate, transport)
if (err == nil) != (mode == "trusted") {
t.Fatalf("代理校验结果不正确:%s %v", mode, err)
}
listener, err := net.Listen("tcp", target.Host)
if err != nil {
t.Fatalf("预检未释放正式端口:%v", err)
}
_ = listener.Close()
})
}
}
+5 -1
View File
@@ -278,10 +278,14 @@ func writeBootstrapCompletionError(writer http.ResponseWriter, err error) {
case errors.As(err, &completionErr):
// 不转发底层错误或可注入的说明,防止密码、凭据引用及验证令牌泄露。
switch completionErr.Kind {
case CompleteErrorProxyTrust:
writeBootstrapError(writer, http.StatusUnprocessableEntity, "反向代理管理入口需要管理域名和正式环境证书;测试环境证书或 IP 自签名证书不能用于此模式。请使用直接 HTTPS 测试,或改用正式域名证书")
case CompleteErrorProxyReadiness:
writeBootstrapError(writer, http.StatusUnprocessableEntity, "公开管理入口未通过代理连通验证,初始化未提交。请检查域名解析、代理公开端口、上游端口、上游证书信任及转发规则,修正后重新验证并提交")
case CompleteErrorCertificatePath:
writeBootstrapError(writer, http.StatusBadRequest, "证书部署根目录必须是服务器上的独立绝对路径,不能使用根目录、符号链接或与配置、数据、日志、备份目录重叠")
case CompleteErrorCertificateAccess:
writeBootstrapError(writer, http.StatusUnprocessableEntity, "证书部署根目录无法创建或写入,请检查 Scert 运行账户权限及服务的可写目录限制")
writeBootstrapError(writer, http.StatusUnprocessableEntity, "证书目录自动准备未完成,请检查目录是否位于安装时批准的范围内,以及目录准备服务是否运行。不会接管其他用户的目录或放开整个系统的写入权限")
case CompleteErrorInput:
writeBootstrapError(writer, http.StatusBadRequest, "初始化参数无效,请检查管理员、管理入口和服务配置")
case CompleteErrorVerification: