Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(mssql): apply the TLS settings to SQL Server connections (#21568)

zchpeterd1485e1d971b
diff --git a/backend/common/testcontainer/shared.go b/backend/common/testcontainer/shared.go
index 42044c9102..b0d17c46fe 100644
--- a/backend/common/testcontainer/shared.go
+++ b/backend/common/testcontainer/shared.go
@@ -92,6 +92,7 @@ func SharedPg17Container(t testing.TB) *Container { return shared(t, sharedPg17)
func SharedTLSPgContainer(t testing.TB) *Container { return shared(t, sharedTLSPg) }
// SharedMSSQLContainer is SharedPgContainer for SQL Server; tests take a database each.
+// Its certificate is signed by the CA at GetTLSCAPath.
func SharedMSSQLContainer(t testing.TB) *Container { return shared(t, sharedMSSQL) }
// SharedTiDBContainer is SharedPgContainer for TiDB; tests take a database each
diff --git a/backend/common/testcontainer/testcontainer.go b/backend/common/testcontainer/testcontainer.go
index 52238fd47d..60432aecf4 100644
--- a/backend/common/testcontainer/testcontainer.go
+++ b/backend/common/testcontainer/testcontainer.go
@@ -15,6 +15,7 @@ import (
"net"
"os"
"path/filepath"
+ "strings"
"time"
"github.com/pkg/errors"
@@ -45,8 +46,8 @@ func (c *Container) GetPassword() string { return c.password }
// GetDB is the admin connection, nil for an engine with no database/sql driver.
func (c *Container) GetDB() *sql.DB { return c.db }
-// GetTLSCAPath returns the CA certificate path for a TLS-enabled PostgreSQL
-// container.
+// GetTLSCAPath returns the path of the CA that signed the server certificate
+// of the TLS PostgreSQL or the SQL Server container.
func (c *Container) GetTLSCAPath() string { return c.tlsCAPath }
func (c *Container) Close(ctx context.Context) {
@@ -189,7 +190,7 @@ func getPg17Container(ctx context.Context) (*Container, error) {
// connecting with sslmode=verify-full and the CA at GetTLSCAPath. The admin
// handle stays on plaintext.
func getTLSPgContainer(ctx context.Context) (retC *Container, retErr error) {
- tlsDir, ca, certificate, key, err := createPostgreSQLTLSMaterial()
+ tlsDir, ca, certificate, key, err := createTLSMaterial(net.ParseIP("127.0.0.1"), net.ParseIP("::1"))
if err != nil {
return nil, err
}
@@ -242,15 +243,44 @@ func GetMySQLContainer(ctx context.Context) (*Container, error) {
})
}
-func getMSSQLContainer(ctx context.Context) (*Container, error) {
+// mssqlTLSConf points SQL Server at the certificate getMSSQLContainer copies in,
+// leaving encryption up to the client.
+const mssqlTLSConf = `[network]
+tlscert = /var/opt/mssql/tls/server.crt
+tlskey = /var/opt/mssql/tls/server.key
+tlsprotocols = 1.2
+forceencryption = 0
+`
+
+// getMSSQLContainer starts SQL Server with a certificate from the CA at
+// GetTLSCAPath. The certificate names localhost and no IP address, so a client
+// that verifies it through 127.0.0.1 fails the host name check. The admin
+// handle does not verify.
+func getMSSQLContainer(ctx context.Context) (retC *Container, retErr error) {
const user, password = "sa", "Test123!"
- return start(ctx, testcontainers.ContainerRequest{
+ tlsDir, ca, certificate, key, err := createTLSMaterial()
+ if err != nil {
+ return nil, err
+ }
+ defer func() {
+ if retErr != nil {
+ _ = os.RemoveAll(tlsDir)
+ }
+ }()
+
+ c, err := start(ctx, testcontainers.ContainerRequest{
Image: "mcr.microsoft.com/mssql/server:2022-latest",
Env: map[string]string{
"ACCEPT_EULA": "Y",
"SA_PASSWORD": password,
"MSSQL_PID": "Express",
},
+ // Copied in as root while SQL Server runs as mssql, so the key must be world-readable.
+ Files: []testcontainers.ContainerFile{
+ {Reader: bytes.NewReader(certificate), ContainerFilePath: "/var/opt/mssql/tls/server.crt", FileMode: 0o644},
+ {Reader: bytes.NewReader(key), ContainerFilePath: "/var/opt/mssql/tls/server.key", FileMode: 0o644},
+ {Reader: strings.NewReader(mssqlTLSConf), ContainerFilePath: "/var/opt/mssql/mssql.conf", FileMode: 0o644},
+ },
WaitingFor: wait.ForLog("SQL Server is now ready for client connections").
WithStartupTimeout(3 * time.Minute),
}, spec{
@@ -262,6 +292,11 @@ func getMSSQLContainer(ctx context.Context) (*Container, error) {
return fmt.Sprintf("sqlserver://%s:%s@%s:%s?database=master", c.username, c.password, c.host, c.port)
},
})
+ if err != nil {
+ return nil, err
+ }
+ c.tlsDir, c.tlsCAPath = tlsDir, ca
+ return c, nil
}
// getTiDBContainer starts TiDB, which speaks the MySQL protocol with no
@@ -298,8 +333,10 @@ func getMongoDBContainer(ctx context.Context) (*Container, error) {
})
}
-func createPostgreSQLTLSMaterial() (string, string, []byte, []byte, error) {
- tlsDir, err := os.MkdirTemp("", "bytebase-postgres-tls-*")
+// createTLSMaterial issues a server certificate for localhost and ips from a
+// fresh CA, and writes the CA to a temporary directory the caller removes.
+func createTLSMaterial(ips ...net.IP) (string, string, []byte, []byte, error) {
+ tlsDir, err := os.MkdirTemp("", "bytebase-tls-*")
if err != nil {
return "", "", nil, nil, err
}
@@ -319,7 +356,7 @@ func createPostgreSQLTLSMaterial() (string, string, []byte, []byte, error) {
now := time.Now()
caTemplate := x509.Certificate{
SerialNumber: serial,
- Subject: pkix.Name{CommonName: "Bytebase PostgreSQL Test CA"},
+ Subject: pkix.Name{CommonName: "Bytebase Test CA"},
NotBefore: now.Add(-time.Minute),
NotAfter: now.Add(24 * time.Hour),
IsCA: true,
@@ -346,7 +383,7 @@ func createPostgreSQLTLSMaterial() (string, string, []byte, []byte, error) {
SerialNumber: serial,
Subject: pkix.Name{CommonName: "localhost"},
DNSNames: []string{"localhost"},
- IPAddresses: []net.IP{net.ParseIP("127.0.0.1"), net.ParseIP("::1")},
+ IPAddresses: ips,
NotBefore: now.Add(-time.Minute),
NotAfter: now.Add(24 * time.Hour),
KeyUsage: x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
diff --git a/backend/migrator/export_test.go b/backend/migrator/export_test.go
new file mode 100644
index 0000000000..fa53d7df7c
--- /dev/null
+++ b/backend/migrator/export_test.go
@@ -0,0 +1,5 @@
+package migrator
+
+// MigrationFS is the embedded migrations, for the migrator_test tests that
+// apply one to a database.
+var MigrationFS = migrationFS
diff --git a/backend/migrator/migration/3.24/0001##mssql_verify_tls_off.sql b/backend/migrator/migration/3.24/0001##mssql_verify_tls_off.sql
new file mode 100644
index 0000000000..7d5442a67d
--- /dev/null
+++ b/backend/migrator/migration/3.24/0001##mssql_verify_tls_off.sql
@@ -0,0 +1,23 @@
+-- Before 3.24, SQL Server connections never verified the server certificate,
+-- even with verifyTlsCertificate on. The driver now verifies, so turn it off
+-- where TLS is on: those data sources keep connecting as they did, and the
+-- instance form shows that the certificate is not verified. Deleting the key
+-- is protojson's form of false.
+UPDATE instance
+SET metadata = jsonb_set(
+ metadata,
+ '{dataSources}',
+ (
+ SELECT jsonb_agg(
+ CASE
+ WHEN ds @> '{"useSsl": true, "verifyTlsCertificate": true}'
+ THEN ds - 'verifyTlsCertificate'
+ ELSE ds
+ END
+ ORDER BY ord
+ )
+ FROM jsonb_array_elements(metadata->'dataSources') WITH ORDINALITY AS t(ds, ord)
+ )
+)
+WHERE metadata->>'engine' = 'MSSQL'
+ AND metadata->'dataSources' @> '[{"useSsl": true, "verifyTlsCertificate": true}]';
diff --git a/backend/migrator/migration_test.go b/backend/migrator/migration_test.go
new file mode 100644
index 0000000000..3f22ed8d12
--- /dev/null
+++ b/backend/migrator/migration_test.go
@@ -0,0 +1,48 @@
+package migrator_test
+
+import (
+ "context"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common/testcontainer"
+ "github.com/bytebase/bytebase/backend/migrator"
+)
+
+func TestMain(m *testing.M) { testcontainer.Main(m) }
+
+func TestMigration3_24_1_MSSQLVerifyTLSOff(t *testing.T) {
+ ctx := context.Background()
+ _, db := testcontainer.NewPgDatabase(t)
+ _, err := db.ExecContext(ctx, `
+ CREATE TABLE instance (
+ resource_id TEXT PRIMARY KEY,
+ metadata JSONB NOT NULL DEFAULT '{}'
+ );
+ INSERT INTO instance (resource_id, metadata) VALUES
+ ('mssql-verify', '{"engine":"MSSQL","dataSources":[{"id":"admin","useSsl":true,"verifyTlsCertificate":true,"sslCa":"ca"},{"id":"ro","type":"READ_ONLY","useSsl":true,"verifyTlsCertificate":true}]}'),
+ ('mssql-verify-without-tls', '{"engine":"MSSQL","dataSources":[{"id":"admin","useSsl":true,"verifyTlsCertificate":true},{"id":"ro","type":"READ_ONLY","verifyTlsCertificate":true}]}'),
+ ('mssql-tls', '{"engine":"MSSQL","dataSources":[{"id":"admin","useSsl":true}]}'),
+ ('mssql-no-data-sources', '{"engine":"MSSQL","dataSources":[]}'),
+ ('postgres-verify', '{"engine":"POSTGRES","dataSources":[{"id":"admin","useSsl":true,"verifyTlsCertificate":true}]}');
+ `)
+ require.NoError(t, err)
+
+ statement, err := migrator.MigrationFS.ReadFile("migration/3.24/0001##mssql_verify_tls_off.sql")
+ require.NoError(t, err)
+ _, err = db.ExecContext(ctx, string(statement))
+ require.NoError(t, err)
+
+ for resourceID, want := range map[string]string{
+ "mssql-verify": `{"engine":"MSSQL","dataSources":[{"id":"admin","useSsl":true,"sslCa":"ca"},{"id":"ro","type":"READ_ONLY","useSsl":true}]}`,
+ "mssql-verify-without-tls": `{"engine":"MSSQL","dataSources":[{"id":"admin","useSsl":true},{"id":"ro","type":"READ_ONLY","verifyTlsCertificate":true}]}`,
+ "mssql-tls": `{"engine":"MSSQL","dataSources":[{"id":"admin","useSsl":true}]}`,
+ "mssql-no-data-sources": `{"engine":"MSSQL","dataSources":[]}`,
+ "postgres-verify": `{"engine":"POSTGRES","dataSources":[{"id":"admin","useSsl":true,"verifyTlsCertificate":true}]}`,
+ } {
+ var got string
+ require.NoError(t, db.QueryRowContext(ctx, `SELECT metadata::text FROM instance WHERE resource_id = $1`, resourceID).Scan(&got))
+ require.JSONEq(t, want, got, resourceID)
+ }
+}
diff --git a/backend/migrator/migrator_test.go b/backend/migrator/migrator_test.go
index d1b6a45e03..a412202b61 100644
--- a/backend/migrator/migrator_test.go
+++ b/backend/migrator/migrator_test.go
@@ -10,8 +10,8 @@ import (
func TestLatestVersion(t *testing.T) {
files, err := getSortedVersionedFiles()
require.NoError(t, err)
- require.Equal(t, semver.MustParse("3.24.0"), *files[len(files)-1].version)
- require.Equal(t, "migration/3.24/0000##access_grant_query_hash.sql", files[len(files)-1].path)
+ require.Equal(t, semver.MustParse("3.24.1"), *files[len(files)-1].version)
+ require.Equal(t, "migration/3.24/0001##mssql_verify_tls_off.sql", files[len(files)-1].path)
}
func TestVersionUnique(t *testing.T) {
diff --git a/backend/plugin/db/mssql/mssql.go b/backend/plugin/db/mssql/mssql.go
index f4d8efc5f2..21ca002ec0 100644
--- a/backend/plugin/db/mssql/mssql.go
+++ b/backend/plugin/db/mssql/mssql.go
@@ -7,9 +7,11 @@ import (
"fmt"
"io"
"log/slog"
+ "maps"
"net/url"
"os"
"slices"
+ "strconv"
"strings"
"time"
@@ -18,6 +20,7 @@ import (
"github.com/golang-sql/sqlexp"
gomssqldb "github.com/microsoft/go-mssqldb"
"github.com/microsoft/go-mssqldb/azuread"
+ "github.com/microsoft/go-mssqldb/msdsn"
// Kerberos Active Directory authentication outside Windows.
_ "github.com/microsoft/go-mssqldb/integratedauth/krb5"
@@ -58,89 +61,123 @@ func newDriver() db.Driver {
// Open opens a MSSQL driver.
func (d *Driver) Open(_ context.Context, _ storepb.Engine, config db.ConnectionConfig) (db.Driver, error) {
- query := url.Values{}
- query.Add("app name", "bytebase")
- if config.ConnectionContext.DatabaseName != "" {
- query.Add("database", config.ConnectionContext.DatabaseName)
- } else if config.DataSource.Database != "" {
- query.Add("database", config.DataSource.Database)
- }
-
- // In order to be compatible with db servers that only support old versions of tls.
- // See: https://github.com/microsoft/go-mssqldb/issues/33
- query.Add("tlsmin", "1.0")
-
- // Add extra connection parameters if specified in the DataSource
- for key, value := range config.DataSource.GetExtraConnectionParameters() {
- query.Add(key, value)
- }
-
- var err error
- if config.DataSource.GetUseSsl() && config.DataSource.GetSslCa() != "" {
- // Due to Golang runtime limitation, x509 package will throw the error of 'certificate relies on legacy Common Name field, use SANs instead.
- // Driver reads the certificate from file instead of regarding it as certificate content.
- // https://github.com/microsoft/go-mssqldb/blob/main/msdsn/conn_str.go#L159
- // TODO(zp): Driver supports .der format also.
- const pattern string = "cert-*.pem"
- file, err := os.CreateTemp(os.TempDir(), pattern)
- if err != nil {
- return nil, errors.Wrapf(err, "failed to create temporary file with pattern %s", pattern)
- }
- fName := file.Name()
- defer func(err error) {
- if err != nil {
- _ = os.Remove(fName)
- } else {
- d.certFilePath = fName
- }
- }(err)
- _, err = file.WriteString(config.DataSource.GetSslCa())
- if err != nil {
- return nil, errors.Wrapf(err, "failed to write certificate to file %s", fName)
+ database := config.ConnectionContext.DatabaseName
+ if database == "" {
+ database = config.DataSource.Database
+ }
+ caFile, err := writeCAFile(config.DataSource)
+ if err != nil {
+ return nil, err
+ }
+ driverName, dsn := connectionDSN(config.DataSource, config.Password, database, caFile)
+ db, err := sql.Open(driverName, dsn)
+ if err != nil {
+ removeCAFile(caFile)
+ return nil, err
+ }
+ d.db = db
+ d.databaseName = config.ConnectionContext.DatabaseName
+ d.certFilePath = caFile
+ return d, nil
+}
+
+// connectionDSN returns the go-mssqldb driver name and DSN. caFile is the data source's CA
+// written to disk, or empty.
+//
+// go-mssqldb matches parameter keys case-insensitively and accepts each key once, so Extra
+// Parameters merge by lowercased key. They override the app name and tlsmin defaults, never the
+// database or the Azure credential. With TLS mode TLS, the TLS section sets a floor that Extra
+// Parameters may raise but not lower: encrypt=true unless they ask for encrypt=strict, and
+// TrustServerCertificate=false when Verify server certificate is on or they ask for it. The
+// section's CA replaces a certificate parameter. With TLS mode Disabled, Extra Parameters apply as
+// given over a TrustServerCertificate=true default.
+func connectionDSN(ds *storepb.DataSource, password, database, caFile string) (string, string) {
+ params := map[string]string{
+ msdsn.AppName: "bytebase",
+ // Older SQL Server versions offer only TLS 1.0: https://github.com/microsoft/go-mssqldb/issues/33.
+ msdsn.TLSMin: "1.0",
+ }
+ extra := ds.GetExtraConnectionParameters()
+ // Sorted, so keys that differ only in case resolve the same way every time.
+ for _, key := range slices.Sorted(maps.Keys(extra)) {
+ params[strings.ToLower(key)] = extra[key]
+ }
+ if database != "" {
+ params[msdsn.Database] = database
+ }
+ if ds.GetUseSsl() {
+ if !strings.EqualFold(params[msdsn.Encrypt], "strict") {
+ params[msdsn.Encrypt] = "true"
}
- if err = file.Close(); err != nil {
- return nil, errors.Wrapf(err, "failed to close file %s", fName)
+ trust, err := strconv.ParseBool(params[msdsn.TrustServerCertificate])
+ verify := ds.GetVerifyTlsCertificate() || (err == nil && !trust)
+ params[msdsn.TrustServerCertificate] = strconv.FormatBool(!verify)
+ if caFile != "" {
+ params[msdsn.Certificate] = caFile
}
- query.Add("certificate", fName)
+ } else if _, ok := params[msdsn.TrustServerCertificate]; !ok {
+ params[msdsn.TrustServerCertificate] = "true"
}
- query.Add("TrustServerCertificate", "true")
driverName := "sqlserver"
- password := config.Password
- if config.DataSource.GetAuthenticationType() == storepb.DataSource_AZURE_IAM {
+ if ds.GetAuthenticationType() == storepb.DataSource_AZURE_IAM {
driverName = azuread.DriverName
- if azureCredential := config.DataSource.GetAzureCredential(); azureCredential != nil {
- query.Add("fedauth", azuread.ActiveDirectoryServicePrincipal)
- query.Add("user id", fmt.Sprintf("%s@%s", azureCredential.ClientId, azureCredential.TenantId))
- query.Add("password", azureCredential.ClientSecret)
+ if credential := ds.GetAzureCredential(); credential != nil {
+ params["fedauth"] = azuread.ActiveDirectoryServicePrincipal
+ params[msdsn.UserID] = fmt.Sprintf("%s@%s", credential.ClientId, credential.TenantId)
+ params[msdsn.Password] = credential.ClientSecret
password = ""
} else {
- query.Add("fedauth", azuread.ActiveDirectoryDefault)
+ params["fedauth"] = azuread.ActiveDirectoryDefault
}
}
+
+ query := url.Values{}
+ for key, value := range params {
+ query.Set(key, value)
+ }
u := &url.URL{
Scheme: "sqlserver",
- User: url.UserPassword(config.DataSource.Username, password),
- Host: fmt.Sprintf("%s:%s", config.DataSource.Host, config.DataSource.Port),
+ User: url.UserPassword(ds.Username, password),
+ Host: fmt.Sprintf("%s:%s", ds.Host, ds.Port),
RawQuery: query.Encode(),
}
- var db *sql.DB
- db, err = sql.Open(driverName, u.String())
+ return driverName, u.String()
+}
+
+// writeCAFile writes the data source's CA to a temporary file, because go-mssqldb reads a CA only
+// from a .pem or .der path. It returns "" when TLS is off or no CA is set.
+func writeCAFile(ds *storepb.DataSource) (string, error) {
+ if !ds.GetUseSsl() || ds.GetSslCa() == "" {
+ return "", nil
+ }
+ file, err := os.CreateTemp("", "cert-*.pem")
if err != nil {
- return nil, err
+ return "", errors.Wrap(err, "failed to create the CA certificate file")
+ }
+ _, err = file.WriteString(ds.GetSslCa())
+ if closeErr := file.Close(); err == nil {
+ err = closeErr
+ }
+ if err != nil {
+ removeCAFile(file.Name())
+ return "", errors.Wrap(err, "failed to write the CA certificate file")
+ }
+ return file.Name(), nil
+}
+
+func removeCAFile(path string) {
+ if path == "" {
+ return
+ }
+ if err := os.Remove(path); err != nil {
+ slog.Warn("failed to delete temporary file", slog.String("path", path), log.BBError(err))
}
- d.db = db
- d.databaseName = config.ConnectionContext.DatabaseName
- return d, nil
}
// Close closes the driver.
func (d *Driver) Close(_ context.Context) error {
- if d.certFilePath != "" {
- if err := os.Remove(d.certFilePath); err != nil {
- slog.Warn("failed to delete temporary file", slog.String("path", d.certFilePath), log.BBError(err))
- }
- }
+ removeCAFile(d.certFilePath)
if d.db != nil {
return d.db.Close()
}
diff --git a/backend/plugin/db/mssql/mssql_test.go b/backend/plugin/db/mssql/mssql_test.go
index 4634197668..485ec963f8 100644
--- a/backend/plugin/db/mssql/mssql_test.go
+++ b/backend/plugin/db/mssql/mssql_test.go
@@ -2,18 +2,233 @@ package mssql
import (
"context"
+ "crypto/ecdsa"
+ "crypto/elliptic"
+ "crypto/rand"
+ "crypto/x509"
+ "crypto/x509/pkix"
+ "encoding/pem"
"fmt"
+ "math/big"
+ "os"
+ "path/filepath"
"strings"
"testing"
"time"
+ "github.com/microsoft/go-mssqldb/azuread"
+ "github.com/microsoft/go-mssqldb/msdsn"
"github.com/stretchr/testify/require"
"github.com/bytebase/bytebase/backend/common/testcontainer"
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
"github.com/bytebase/bytebase/backend/plugin/db"
)
+func TestConnectionDSNAppliesTLSSettings(t *testing.T) {
+ dir := t.TempDir()
+ writeCA := func(name string) (string, *x509.CertPool) {
+ ca := newTestCA(t)
+ path := filepath.Join(dir, name)
+ require.NoError(t, os.WriteFile(path, ca, 0o600))
+ pool := x509.NewCertPool()
+ require.True(t, pool.AppendCertsFromPEM(ca))
+ return path, pool
+ }
+ sectionCA, sectionPool := writeCA("section.pem")
+ extraCA, extraPool := writeCA("extra.pem")
+ systemPool, err := x509.SystemCertPool()
+ require.NoError(t, err)
+
+ for _, tc := range []struct {
+ name string
+ useSSL bool
+ verify bool
+ caFile string
+ extra map[string]string
+ encryption msdsn.Encryption
+ // roots verify the server certificate; nil means any certificate is accepted.
+ roots *x509.CertPool
+ }{
+ {name: "disabled", encryption: msdsn.EncryptionOff},
+ {name: "disabled ignores verify", verify: true, encryption: msdsn.EncryptionOff},
+ {name: "tls", useSSL: true, encryption: msdsn.EncryptionRequired},
+ {name: "tls with a CA", useSSL: true, caFile: sectionCA, encryption: msdsn.EncryptionRequired},
+ {name: "tls verified against the CA", useSSL: true, verify: true, caFile: sectionCA, encryption: msdsn.EncryptionRequired, roots: sectionPool},
+ {name: "tls verified against system trust", useSSL: true, verify: true, encryption: msdsn.EncryptionRequired, roots: systemPool},
+
+ {name: "extra parameters cannot turn verification off", useSSL: true, verify: true, caFile: sectionCA, extra: map[string]string{"TrustServerCertificate": "true"}, encryption: msdsn.EncryptionRequired, roots: sectionPool},
+ {name: "extra parameters cannot make encryption optional", useSSL: true, extra: map[string]string{"encrypt": "false"}, encryption: msdsn.EncryptionRequired},
+ {name: "extra parameters cannot disable encryption", useSSL: true, extra: map[string]string{"Encrypt": "DISABLE"}, encryption: msdsn.EncryptionRequired},
+ {name: "extra parameters can require strict encryption", useSSL: true, extra: map[string]string{"Encrypt": "Strict"}, encryption: msdsn.EncryptionStrict, roots: systemPool},
+ {name: "extra parameters can turn verification on", useSSL: true, caFile: sectionCA, extra: map[string]string{"trustservercertificate": "false"}, encryption: msdsn.EncryptionRequired, roots: sectionPool},
+ {name: "the CA replaces a certificate parameter", useSSL: true, verify: true, caFile: sectionCA, extra: map[string]string{"Certificate": extraCA}, encryption: msdsn.EncryptionRequired, roots: sectionPool},
+ {name: "a certificate parameter replaces system trust", useSSL: true, verify: true, extra: map[string]string{"certificate": extraCA}, encryption: msdsn.EncryptionRequired, roots: extraPool},
+
+ {name: "disabled applies encrypt", extra: map[string]string{"encrypt": "true"}, encryption: msdsn.EncryptionRequired},
+ {name: "disabled applies TrustServerCertificate", extra: map[string]string{"TrustServerCertificate": "false"}, encryption: msdsn.EncryptionOff, roots: systemPool},
+ {name: "disabled applies encrypt=disable", extra: map[string]string{"encrypt": "disable"}, encryption: msdsn.EncryptionDisabled},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ ds := &storepb.DataSource{
+ Host: "db.example.com",
+ Port: "1433",
+ Username: "bytebase",
+ UseSsl: tc.useSSL,
+ VerifyTlsCertificate: tc.verify,
+ ExtraConnectionParameters: tc.extra,
+ }
+ driverName, dsn := connectionDSN(ds, "password", "", tc.caFile)
+ require.Equal(t, "sqlserver", driverName)
+ cfg, err := msdsn.Parse(dsn)
+ require.NoError(t, err)
+ require.Equal(t, tc.encryption, cfg.Encryption)
+ if tc.encryption == msdsn.EncryptionDisabled {
+ require.Nil(t, cfg.TLSConfig)
+ return
+ }
+ require.Equal(t, tc.roots == nil, cfg.TLSConfig.InsecureSkipVerify)
+ if tc.roots != nil {
+ require.Equal(t, "db.example.com", cfg.TLSConfig.ServerName)
+ require.True(t, tc.roots.Equal(cfg.TLSConfig.RootCAs), "verified against the wrong roots")
+ }
+ })
+ }
+}
+
+func TestConnectionDSNMergesExtraParameters(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ ds *storepb.DataSource
+ database string
+ driverName string
+ // want holds the parameters go-mssqldb reads from the DSN.
+ want map[string]string
+ }{
+ {
+ name: "defaults",
+ ds: &storepb.DataSource{Username: "bytebase"},
+ database: "db1",
+ driverName: "sqlserver",
+ want: map[string]string{"app name": "bytebase", "tlsmin": "1.0", "database": "db1", "user id": "bytebase", "password": "password"},
+ },
+ {
+ name: "extra parameters override the app name and tlsmin",
+ ds: &storepb.DataSource{ExtraConnectionParameters: map[string]string{"App Name": "etl", "TLSMin": "1.2"}},
+ driverName: "sqlserver",
+ want: map[string]string{"app name": "etl", "tlsmin": "1.2"},
+ },
+ {
+ name: "the database comes from Bytebase",
+ ds: &storepb.DataSource{ExtraConnectionParameters: map[string]string{"Database": "other"}},
+ database: "db1",
+ driverName: "sqlserver",
+ want: map[string]string{"database": "db1"},
+ },
+ {
+ name: "extra parameters name the database when Bytebase has none",
+ ds: &storepb.DataSource{ExtraConnectionParameters: map[string]string{"database": "other"}},
+ driverName: "sqlserver",
+ want: map[string]string{"database": "other"},
+ },
+ {
+ name: "the Azure credential comes from Bytebase",
+ ds: &storepb.DataSource{
+ AuthenticationType: storepb.DataSource_AZURE_IAM,
+ IamExtension: &storepb.DataSource_AzureCredential_{AzureCredential: &storepb.DataSource_AzureCredential{TenantId: "tenant", ClientId: "client", ClientSecret: "secret"}},
+ ExtraConnectionParameters: map[string]string{"FedAuth": azuread.ActiveDirectoryMSI, "User ID": "other", "Password": "other"},
+ },
+ driverName: azuread.DriverName,
+ want: map[string]string{"fedauth": azuread.ActiveDirectoryServicePrincipal, "user id": "client@tenant", "password": "secret"},
+ },
+ {
+ name: "Azure without a credential uses the default chain",
+ ds: &storepb.DataSource{AuthenticationType: storepb.DataSource_AZURE_IAM},
+ driverName: azuread.DriverName,
+ want: map[string]string{"fedauth": azuread.ActiveDirectoryDefault},
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ driverName, dsn := connectionDSN(tc.ds, "password", tc.database, "")
+ require.Equal(t, tc.driverName, driverName)
+ cfg, err := msdsn.Parse(dsn)
+ require.NoError(t, err)
+ for key, value := range tc.want {
+ require.Equal(t, value, cfg.Parameters[key], key)
+ }
+ })
+ }
+}
+
+func TestOpenAppliesTLSSettings(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ container := testcontainer.SharedMSSQLContainer(t)
+ signer, err := os.ReadFile(container.GetTLSCAPath())
+ require.NoError(t, err)
+ ca, otherCA := string(signer), string(newTestCA(t))
+
+ for _, tc := range []struct {
+ name string
+ // host is localhost, the name in the server certificate, or 127.0.0.1, which it lacks.
+ host string
+ ds *storepb.DataSource
+ // encryptOption is the session's sys.dm_exec_connections.encrypt_option.
+ encryptOption string
+ wantErr string
+ }{
+ {name: "disabled ignores verify", host: "127.0.0.1", ds: &storepb.DataSource{VerifyTlsCertificate: true, SslCa: otherCA}, encryptOption: "FALSE"},
+ {name: "tls accepts any certificate", host: "127.0.0.1", ds: &storepb.DataSource{UseSsl: true, SslCa: otherCA}, encryptOption: "TRUE"},
+ {name: "tls verified against the CA", host: "localhost", ds: &storepb.DataSource{UseSsl: true, VerifyTlsCertificate: true, SslCa: ca}, encryptOption: "TRUE"},
+ {name: "a host missing from the certificate", host: "127.0.0.1", ds: &storepb.DataSource{UseSsl: true, VerifyTlsCertificate: true, SslCa: ca}, wantErr: "doesn't contain any IP SANs"},
+ {name: "a CA that did not sign the certificate", host: "localhost", ds: &storepb.DataSource{UseSsl: true, VerifyTlsCertificate: true, SslCa: otherCA}, wantErr: "certificate signed by unknown authority"},
+ {name: "system trust rejects a private CA", host: "localhost", ds: &storepb.DataSource{UseSsl: true, VerifyTlsCertificate: true}, wantErr: "tls: failed to verify certificate"},
+ {
+ name: "extra parameters cannot turn verification off",
+ host: "127.0.0.1",
+ ds: &storepb.DataSource{UseSsl: true, VerifyTlsCertificate: true, SslCa: ca, ExtraConnectionParameters: map[string]string{"TrustServerCertificate": "true"}},
+ wantErr: "doesn't contain any IP SANs",
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+ tc.ds.Username, tc.ds.Host, tc.ds.Port = container.GetUsername(), tc.host, container.GetPort()
+ driver, err := (&Driver{}).Open(ctx, storepb.Engine_MSSQL, db.ConnectionConfig{DataSource: tc.ds, Password: container.GetPassword()})
+ require.NoError(t, err)
+ defer driver.Close(ctx)
+
+ var encryptOption string
+ err = driver.GetDB().QueryRowContext(ctx, "SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID").Scan(&encryptOption)
+ if tc.wantErr != "" {
+ require.ErrorContains(t, err, tc.wantErr)
+ return
+ }
+ require.NoError(t, err)
+ require.Equal(t, tc.encryptOption, encryptOption)
+ })
+ }
+}
+
+// newTestCA returns a self-signed CA certificate in PEM.
+func newTestCA(t *testing.T) []byte {
+ t.Helper()
+ key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+ require.NoError(t, err)
+ template := &x509.Certificate{
+ SerialNumber: big.NewInt(1),
+ Subject: pkix.Name{CommonName: "Unrelated Test CA"},
+ NotBefore: time.Now().Add(-time.Minute),
+ NotAfter: time.Now().Add(time.Hour),
+ IsCA: true,
+ BasicConstraintsValid: true,
+ KeyUsage: x509.KeyUsageCertSign,
+ }
+ der, err := x509.CreateCertificate(rand.Reader, template, template, &key.PublicKey, key)
+ require.NoError(t, err)
+ return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
+}
+
func TestShowplanStatistic(t *testing.T) {
for _, tc := range []struct {
name string
diff --git a/docs/design/sql-server-tls.md b/docs/design/sql-server-tls.md
new file mode 100644
index 0000000000..3e88618f34
--- /dev/null
+++ b/docs/design/sql-server-tls.md
@@ -0,0 +1,208 @@
+# SQL Server TLS
+
+Status: implemented in this PR · 2026-10-09 · [BYT-10305](https://linear.app/bytebase/issue/BYT-10305)
+
+The instance form's TLS section (TLS mode, Verify server certificate, CA certificate) has never
+reached the SQL Server driver. The driver hard-codes `TrustServerCertificate=true` and never sets
+`encrypt`, so it never verifies the server certificate and leaves the session unencrypted after
+login. **The TLS section decides the connection: TLS mode TLS encrypts the whole session, Verify
+server certificate checks the certificate chain and the host name, and Extra Parameters can make
+that stricter, never weaker.** The upgrade turns Verify server certificate off on existing data
+sources that use TLS, where it was on but never applied, so they keep connecting.
+
+## Problem
+
+Reproduced on 2026-10-09 against SQL Server 2022 CU24 from Bytebase 3.23.0:
+
+- **Nothing is verified.** With TLS mode TLS and Verify server certificate on, Bytebase connects
+ without a CA, and through an IP address that isn't in the certificate's subject alternative
+ names (SANs). Anyone on the network path can present a certificate and read the SQL login.
+- **The session isn't encrypted.** With TLS mode TLS and a CA, the session's
+ `sys.dm_exec_connections.encrypt_option` stays `FALSE`. Only `encrypt=true` in Extra Parameters,
+ or `forceencryption=1` on the server, makes it `TRUE`.
+- **Users can't opt in.** `TrustServerCertificate=false` in Extra Parameters fails with `key
+ TrustServerCertificate provided more than once`.
+
+`Driver.Open` in `backend/plugin/db/mssql/mssql.go` appends `TrustServerCertificate=true` after the
+Extra Parameters and never maps `use_ssl` or `verify_tls_certificate` to `encrypt`. It passes the
+pasted CA to go-mssqldb as `certificate`, but go-mssqldb never checks against it because trust is
+on. The DSN is built as a case-sensitive `url.Values`, while go-mssqldb compares keys
+case-insensitively. An Extra Parameter that repeats a key Bytebase sets fails to parse when spelled
+the same way, and when its case differs, either value can win each time Bytebase opens the
+database.
+
+## Principle
+
+> What the TLS section shows is what the connection does. An upgrade doesn't break a connection
+> that works today: where the stored settings and the connection disagreed, the upgrade changes the
+> settings to match the connection, and the form shows it.
+
+## How go-mssqldb reads the options
+
+Bytebase links `github.com/bytebase/go-mssqldb` at `3ff3ca07d898`, which `go.mod` substitutes for
+`microsoft/go-mssqldb v1.11.0`. `parseTLS` in `msdsn/conn_str.go` reads:
+
+| `encrypt` | What is encrypted |
+|---|---|
+| unset, `false`, `optional`, `no`, `0`, `f` | The login packet only, unless the server forces encryption |
+| `true`, `mandatory`, `yes`, `1`, `t` | The whole session; the connection fails if the server can't encrypt |
+| `strict` | The whole connection, with TLS before the TDS handshake (TDS 8.0, SQL Server 2022 and later); always verifies |
+| `disable` | Nothing |
+
+- **`TrustServerCertificate`:** `true` accepts any certificate, `false` verifies it. It defaults to
+ `true` when `encrypt` is unset and to `false` when `encrypt` is set.
+- **`certificate`:** a `.pem` or `.der` file. When set, it is the only CA trusted; otherwise the
+ system roots are.
+- **Host name:** the check uses `hostNameInCertificate` or the server host. When SQL Server routes
+ the login to another server, go-mssqldb checks the routed server's name instead.
+
+## Decisions
+
+**D1 · Map the TLS section onto go-mssqldb's own DSN options.** Bytebase sets `encrypt`,
+`TrustServerCertificate` and `certificate`, and go-mssqldb builds the TLS configuration. Rejected:
+building a `tls.Config` with `util.GetTLSConfig`, as MySQL and PostgreSQL do. The Azure AD
+connector accepts only a DSN. When SQL Server routes a login (Azure SQL redirection, read-only
+routing), go-mssqldb checks the routed server's name, but a Bytebase verifier bound to the original
+host would keep checking the old name.
+
+**D2 · TLS mode TLS sets `encrypt=true`.** The whole session is encrypted, not just the login.
+Rejected: leaving `encrypt` unset, which keeps the session readable on the network. Rejected:
+`encrypt=strict`, which needs SQL Server 2022 and always verifies, so it would break older servers
+and every data source with Verify off. It stays available as an Extra Parameter.
+
+**D3 · Verify server certificate maps to `TrustServerCertificate`.** With Verify on, Bytebase sets
+`TrustServerCertificate=false`. The chain is checked against the CA when one is set (pasted or file
+path), otherwise against the system roots, and the host name against Host. With Verify off,
+Bytebase sets `TrustServerCertificate=true`. As today, Bytebase writes the CA file whenever TLS is
+on and a CA is set, so `encrypt=strict` or `TrustServerCertificate=false` in Extra Parameters
+verifies against that CA.
+
+**D4 · TLS mode Disabled keeps today's connection.** `encrypt` stays unset, so the login packet is
+encrypted when the server supports it, and `TrustServerCertificate` defaults to `true`. Rejected:
+`encrypt=disable`, which fails against servers that force encryption and stops encrypting the
+login.
+
+**D5 · Extra Parameters can raise the TLS section's floor, not lower it.** Keys compare
+case-insensitively, as in go-mssqldb.
+
+- **TLS mode TLS.** The section sets `encrypt=true`, plus `TrustServerCertificate=false` when
+ Verify is on. `encrypt=strict` and `TrustServerCertificate=false` in Extra Parameters raise that
+ floor, so they apply. Any other value of those keys is replaced. The section's CA replaces a
+ `certificate` parameter; without one, the parameter applies.
+- **TLS mode Disabled.** Extra Parameters apply as given. The `encrypt=true` workaround keeps
+ working, and `TrustServerCertificate=false` now verifies instead of failing.
+
+This matches MySQL and PostgreSQL, whose TLS settings override Extra Parameters when TLS is on.
+Rejected: Extra Parameters always win, which lets the form show Verify on over a connection that
+trusts any certificate, the bug being fixed. Rejected: an error on conflict. The section already
+overrides the value, and an error would stop data sources that connect today.
+
+**D6 · Every key Bytebase sets merges case-insensitively.** `app name` and `tlsmin` are defaults
+that an Extra Parameter overrides, so `tlsmin=1.2` now works. The database and the Azure credential
+(`fedauth`, `user id`, `password`) always come from Bytebase. Today an Extra Parameter that repeats
+one of these keys fails with `provided more than once`, or wins at random when its case differs.
+
+**D7 · The upgrade turns Verify server certificate off where it never applied.** Migration `3.24.1`
+removes `verifyTlsCertificate` from SQL Server data sources where `useSsl` and
+`verifyTlsCertificate` are both true. Since 3.18.0 the form turns Verify on whenever TLS is
+enabled, so these data sources are common. Honoring the stored value would fail every one whose
+server presents SQL Server's self-signed certificate or whose Host isn't in the certificate.
+Rejected: honoring the stored value. It is secure, but syncs, queries and rollouts would stop
+until someone edits each data source. Data sources with TLS off keep their stored value: it has no
+effect, and the form turns Verify back on when TLS is enabled.
+
+**D8 · Mutual TLS stays hidden for SQL Server.** The linked go-mssqldb has no DSN option for a
+client certificate.
+
+## States
+
+What Bytebase sends, by TLS section, with no Extra Parameters:
+
+| TLS mode | Verify | CA | `encrypt` | `TrustServerCertificate` | `certificate` | Encrypted | Certificate check |
+|---|---|---|---|---|---|---|---|
+| Disabled | any | any | unset | `true` | unset | Login packet only, unless the server forces encryption | None |
+| TLS | Off | any | `true` | `true` | CA file if set | Whole session | None |
+| TLS | On | Pasted or file path | `true` | `false` | CA file | Whole session | Chain to the CA; host name |
+| TLS | On | System trust | `true` | `false` | unset | Whole session | Chain to the system roots; host name |
+
+Extra Parameters under TLS mode TLS:
+
+| Key | Value | Result |
+|---|---|---|
+| `encrypt` | `strict` | Applies |
+| `encrypt` | Anything else | Replaced by `true` |
+| `TrustServerCertificate` | `false` | Applies |
+| `TrustServerCertificate` | `true` or invalid | Replaced: `false` with Verify on, `true` with it off |
+| `certificate` | A path | Replaced by the section's CA; applies when the section has none |
+
+Under TLS mode Disabled, Extra Parameters apply as given.
+
+## Upgrade and breaking changes
+
+| Before the upgrade | After |
+|---|---|
+| TLS mode TLS, Verify on | Verify shows off. The whole session is encrypted, and the certificate is still not checked. |
+| TLS mode TLS, Verify off | The whole session is encrypted; before, only the login was. |
+| TLS mode Disabled | Unchanged |
+| An Extra Parameter repeating a key Bytebase sets | No longer fails. Under TLS mode TLS, a value weaker than the section is replaced. |
+
+These changes can break an existing setup:
+
+1. **Verify server certificate now verifies.** Turning it on through the form, the API or
+ Terraform gives a connection that fails unless the certificate chains to the CA (or a system
+ root) and names the Host. Typical failures are SQL Server's self-signed certificate (`certificate
+ signed by unknown authority`) and connecting by IP address or short name (`doesn't contain any
+ IP SANs`, `certificate is valid for …, not …`).
+2. **Terraform turns Verify back on.** The provider sends every data source on update, and
+ `verify_tls_certificate` defaults to `false`. A configuration that sets `verify_tls_certificate
+ = true` on a SQL Server data source shows a diff after the upgrade, and the next `terraform
+ apply` turns Verify back on. The apply succeeds, because updating an instance doesn't test the
+ connection. Syncs, queries and rollouts then fail if the certificate doesn't verify. Before
+ applying, make the certificate verifiable or set the value to `false`. Configurations that omit
+ the field are unaffected.
+3. **TLS mode TLS requires the server to encrypt the session.** A server that doesn't support
+ encryption now fails to connect. SQL Server always can, using a self-signed certificate when
+ none is configured.
+4. **Weaker Extra Parameters are ignored under TLS mode TLS.** These are `encrypt=false`,
+ `optional` or `disable`, and `TrustServerCertificate=true` with Verify on.
+
+Release note draft:
+
+> **SQL Server: TLS settings now take effect.** TLS mode TLS encrypts the whole session, and
+> Verify server certificate checks the server's certificate against your CA, or the system's
+> trusted CAs, and the host name. The upgrade turns Verify server certificate off on existing SQL
+> Server data sources that use TLS, so they keep connecting as before; turn it on to verify.
+> **Terraform:** if your configuration sets `verify_tls_certificate = true` on a SQL Server data
+> source, the next `terraform apply` turns verification on. Make sure the certificate verifies
+> first, or set it to `false`.
+
+## Scope
+
+| File | Change |
+|---|---|
+| `backend/plugin/db/mssql/mssql.go` | `connectionDSN` builds the DSN from the TLS section and Extra Parameters (D1 to D6), with the precedence comment; `writeCAFile` no longer leaks the file when a write fails |
+| `backend/migrator/migration/3.24/0001##mssql_verify_tls_off.sql` | D7 |
+| `backend/common/testcontainer/testcontainer.go` | The shared SQL Server presents a certificate from a test CA that names `localhost` and no IP address |
+
+Tests:
+
+- `TestConnectionDSNAppliesTLSSettings` covers every row of both States tables, read back through
+ go-mssqldb's `msdsn.Parse`.
+- `TestConnectionDSNMergesExtraParameters` covers D6.
+- `TestOpenAppliesTLSSettings` runs against SQL Server 2022. Disabled leaves `encrypt_option` at
+ `FALSE`. TLS encrypts the session and accepts any certificate. Verify accepts the signing CA
+ through `localhost`, and rejects `127.0.0.1`, an unrelated CA and system trust. A
+ `TrustServerCertificate=true` Extra Parameter can't turn verification off.
+- `TestMigration3_24_1_MSSQLVerifyTLSOff` runs D7 against PostgreSQL. It brings back one migration
+ test on the shared container, as
+ [`backend-test-execution-time.md`](backend-test-execution-time.md) asks.
+
+## Not in this PR
+
+- The SQL Server connection page (bytebase/bytebase.com#232,
+ `docs/get-started/connect/sql-server.mdx`) warns in its TLS section that Bytebase doesn't verify
+ the certificate yet. When this ships, replace the warning with the release version and how TLS
+ mode and Verify server certificate behave. Also drop its Extra Parameters note that
+ `TrustServerCertificate` fails.
+- A hint in the connection error that points at the CA and Host fields.
+- Client certificates (D8).