Add serverCertificate parameter for byte-comparison validation with backward compatibility (#305)

* Initial plan

* Implement certificate hostname validation skip for strict encryption

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Fix certificate verification logic to use Roots instead of Intermediates

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Add nil checks for PeerCertificates and fix duplicate comment

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Remove InsecureSkipVerify from setupTLSCertificateOnly, use VerifyPeerCertificate in setupTLSCommonName

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Fix intermediate certificate handling in setupTLSCommonName

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Improve comments and optimize intermediate cert handling

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Fix TLS handshake error by using InsecureSkipVerify with VerifyPeerCertificate callback

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Add security documentation explaining InsecureSkipVerify usage

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Use VerifyConnection instead of InsecureSkipVerify for hostname validation skip

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Update msdsn/conn_str.go

avoid duplicate RootCAs assignment

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update msdsn/conn_str_go115pre.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Skip hostname validation for all encryption modes when certificate is provided

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Fix: Use VerifyPeerCertificate instead of VerifyConnection for hostname skip

VerifyConnection runs AFTER standard TLS verification (including hostname check),
so it cannot be used to skip hostname validation. Changed back to using
InsecureSkipVerify=true with VerifyPeerCertificate callback, which is the correct
pattern for custom certificate verification that skips hostname checks.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Change certificate validation to byte comparison like Microsoft.Data.SqlClient

Instead of validating certificate chain/expiry/subject, now simply compares
the raw bytes of the server certificate with the provided certificate file.
This matches the behavior of Microsoft.Data.SqlClient and eliminates the
need for complete certificate chains.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Consolidate setupTLSCertificateOnly into conn_str.go

Moved setupTLSCertificateOnly from build-tag-specific files to conn_str.go
since the implementation is identical for all Go versions. This reduces code
duplication and makes the codebase easier to maintain.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Replace fmt.Errorf with errors.New for simple error messages

Changed fmt.Errorf() to errors.New() for error messages without format
specifiers, following Go best practices. This is more idiomatic and efficient.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Update README, CHANGELOG, and version for certificate validation feature

- Added documentation in README.md explaining certificate-based server validation
- Included OpenSSL command example for obtaining server certificates
- Added connection string examples for using certificates with encryption
- Updated CHANGELOG.md with new feature description for v1.9.6
- Incremented version to v1.9.6 in version.go

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Fix CHANGELOG.md: only prepend v1.9.6 without renumbering earlier versions

Reverted the inadvertent renumbering of earlier changelog entries. Now only
v1.9.6 is added at the top while preserving the original version numbers
(1.9.3, 1.9.2, 1.9.1, etc.) for all previous entries.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Add serverCertificate parameter for backward compatibility

To preserve backward compatibility with the existing 'certificate' parameter:
- Added new 'serverCertificate' parameter for byte-comparison validation
- Reverted 'certificate' parameter to traditional X.509 chain validation
- serverCertificate cannot be used with certificate or hostnameincertificate
- Updated README.md with clear documentation of both parameters
- Updated CHANGELOG.md to reflect the new parameter and compatibility
- Updated tests to verify both validation methods
- All msdsn tests pass successfully

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Revert setupTLSCommonName to original implementation for backward compatibility

Restored the original setupTLSCommonName implementation that uses VerifyConnection
instead of VerifyPeerCertificate. This maintains backward compatibility since:
- setupTLSCommonName is only used for the 'certificate' parameter path
- It is not needed for the new 'serverCertificate' parameter functionality
- The original implementation has been in production and should not change unnecessarily

All msdsn tests pass successfully.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Fix SetupTLS function call parameters in tds.go

Fixed parameter order in msdsn.SetupTLS calls to match the updated function
signature that includes both certificate and serverCertificate parameters.
The function signature is:
SetupTLS(certificate, serverCertificate, insecureSkipVerify, hostInCertificate, minTLSVersion)

This resolves the AppVeyor build errors.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

* Address code review feedback: remove trailing whitespace and fix issue reference

- Removed trailing whitespace from lines 257, 265, 271, 279, 321, and 331 in conn_str.go
- Updated CHANGELOG.md to reference issue #304 instead of placeholder #xxx
- Ran go fmt to ensure proper code formatting

All msdsn tests pass successfully.

Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>
Co-authored-by: David Shiflet <david.shiflet@microsoft.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -1,4 +1,12 @@
 # Changelog
+## 1.9.6
+
+### Features
+
+* Added new `serverCertificate` connection parameter for byte-for-byte certificate validation, matching Microsoft.Data.SqlClient behavior. This parameter skips hostname validation, chain validation, and expiry checks, only verifying that the server's certificate exactly matches the provided file. This is useful when the server's hostname doesn't match the certificate CN/SAN. (#304)
+* The existing `certificate` parameter maintains backward compatibility with traditional X.509 chain validation including hostname checks, expiry validation, and chain-of-trust verification.
+* `serverCertificate` cannot be used with `certificate` or `hostnameincertificate` parameters to prevent conflicting validation methods.
+
 ## 1.9.3
 
 ### Bug fixes

README.md

@@ -58,8 +58,9 @@ Other supported formats are listed below.
 * `TrustServerCertificate`
   * false - Server certificate is checked. Default is false if encrypt is specified.
   * true - Server certificate is not checked. Default is true if encrypt is not specified. If trust server certificate is true, driver accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing.
-* `certificate` - The file that contains the public key certificate of the CA that signed the SQL Server certificate. The specified certificate overrides the go platform specific CA certificates. Currently, certificates of PEM type are supported.
-* `hostNameInCertificate` - Specifies the Common Name (CN) in the server certificate. Default value is the server host.
+* `certificate` - The file path to a certificate authority (CA) certificate or server certificate for traditional X.509 chain validation. The specified certificate overrides the go platform specific CA certificates. The driver validates the certificate chain, expiry, and hostname. Supports PEM and DER formats.
+* `serverCertificate` - The file path to a server certificate for byte-for-byte comparison validation (new in v1.9.6). The driver validates that the server's certificate exactly matches this file, skipping chain validation, expiry checks, and hostname validation. This matches Microsoft.Data.SqlClient behavior. Cannot be used with `certificate` or `hostnameincertificate`. Supports PEM and DER formats.
+* `hostNameInCertificate` - Specifies the Common Name (CN) in the server certificate. Default value is the server host. Used with the `certificate` parameter, not applicable for `serverCertificate`.
 * `tlsmin` - Specifies the minimum TLS version for negotiating encryption with the server. Recognized values are `1.0`, `1.1`, `1.2`, `1.3`. If not set to a recognized value the default value for the `tls` package will be used. The default is currently `1.2`. 
 * `ServerSPN` - The kerberos SPN (Service Principal Name) for the server. Default is MSSQLSvc/host:port.
 * `Workstation ID` - The workstation name (default is the host name)
@@ -204,6 +205,66 @@ For further information on usage:
     * `odbc:server=localhost;user id=sa;database=master;app name=MyAppName;krb5-configfile=path/to/file;krb5-credcachefile=path/to/cache;authenticator=krb5`
     * `odbc:server=localhost;user id=sa;database=master;app name=MyAppName;krb5-configfile=path/to/file;krb5-realm=domain.com;krb5-keytabfile=path/to/keytabfile;authenticator=krb5`
 
+### Using server certificates with encryption
+
+The driver supports two ways to validate server certificates:
+
+#### 1. `serverCertificate` - Byte-for-byte certificate comparison (New in v1.9.6)
+
+When you provide a `serverCertificate` parameter, the driver validates the server by comparing the certificate bytes exactly with the provided file. This:
+- Skips hostname validation (allows mismatched hostnames)
+- Skips certificate chain validation and expiry checks
+- Only accepts connections where the server's certificate exactly matches the provided file
+- Matches the behavior of Microsoft.Data.SqlClient
+
+This is useful when:
+- The server's DNS name doesn't match the certificate CN/SAN
+- You want to validate against a specific certificate without hostname validation
+- You're connecting through proxies or load balancers with different hostnames
+
+**Restrictions**: `serverCertificate` cannot be used with `certificate` or `hostnameincertificate` parameters.
+
+#### 2. `certificate` - Traditional chain validation (Backward compatible)
+
+The `certificate` parameter performs standard X.509 certificate chain validation:
+- Validates the certificate chain against the provided CA certificate(s)
+- Checks certificate expiry and validity
+- Enforces hostname validation (unless `hostnameincertificate` is used)
+
+#### Obtaining the server certificate
+
+You can obtain a copy of the server's certificate using OpenSSL:
+
+```bash
+openssl s_client -connect server:1433 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > cert.pem
+```
+
+#### Example connection strings
+
+Using `serverCertificate` for byte-comparison (skips hostname validation):
+
+URL format:
+```
+sqlserver://username:password@host:1433?database=master&encrypt=true&serverCertificate=/path/to/cert.pem
+```
+
+ADO format:
+```
+server=myserver;user id=sa;password=mypass;database=master;encrypt=true;serverCertificate=/path/to/cert.pem
+```
+
+Using `certificate` for traditional chain validation:
+
+URL format:
+```
+sqlserver://username:password@host:1433?database=master&encrypt=true&certificate=/path/to/ca.pem
+```
+
+ADO format:
+```
+server=myserver;user id=sa;password=mypass;database=master;encrypt=true;certificate=/path/to/ca.pem
+```
+
 ### Azure Active Directory authentication
 
 Azure Active Directory authentication uses temporary authentication tokens to authenticate.

money.go

@@ -7,7 +7,7 @@ import (
 	"github.com/shopspring/decimal"
 )
 
-type Money[D decimal.Decimal|decimal.NullDecimal] struct {
+type Money[D decimal.Decimal | decimal.NullDecimal] struct {
 	Decimal D
 }
 
@@ -20,5 +20,5 @@ func (m Money[D]) Value() (driver.Value, error) {
 func (m *Money[D]) Scan(v any) error {
 	scanner, _ := any(&m.Decimal).(sql.Scanner)
 
-	return scanner.Scan(v);
+	return scanner.Scan(v)
 }

money_test.go

@@ -17,7 +17,7 @@ func TestBulkInvalidString(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoneyN,
-			Size: 8,
+			Size:   8,
 		},
 	}
 
@@ -36,7 +36,7 @@ func TestBulkInvalidType(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoneyN,
-			Size: 8,
+			Size:   8,
 		},
 	}
 
@@ -55,7 +55,7 @@ func TestBulkMoneyN(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoneyN,
-			Size: 8,
+			Size:   8,
 		},
 	}
 
@@ -79,7 +79,7 @@ func TestBulkMoneyPositive(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoney,
-			Size: 8,
+			Size:   8,
 		},
 	}
 
@@ -103,7 +103,7 @@ func TestBulkMoneyNegative(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoney,
-			Size: 8,
+			Size:   8,
 		},
 	}
 
@@ -127,7 +127,7 @@ func TestBulkMoney4Positive(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoney4,
-			Size: 4,
+			Size:   4,
 		},
 	}
 
@@ -151,7 +151,7 @@ func TestBulkMoney4Negative(t *testing.T) {
 	col := columnStruct{
 		ti: typeInfo{
 			TypeId: typeMoney4,
-			Size: 4,
+			Size:   4,
 		},
 	}
 
@@ -222,8 +222,8 @@ func TestMoneyDecimal(t *testing.T) {
 	s := &Stmt{}
 
 	res, err := s.makeParam(Money[shopspring.Decimal]{
-			shopspring.New(-82913823232, -4),
-		},
+		shopspring.New(-82913823232, -4),
+	},
 	)
 
 	if err != nil {
@@ -397,7 +397,6 @@ func TestMoneyScanNullDecimal(t *testing.T) {
 	}
 }
 
-
 func readMoney(buf []byte) int64 {
 	return int64((uint64(binary.LittleEndian.Uint32(buf)) << 32) | uint64(binary.LittleEndian.Uint32(buf[4:])))
 }

msdsn/conn_str.go

@@ -1,6 +1,7 @@
 package msdsn
 
 import (
+	"bytes"
 	"crypto/tls"
 	"crypto/x509"
 	"encoding/pem"
@@ -65,6 +66,7 @@ const (
 	Port                   = "port"
 	TrustServerCertificate = "trustservercertificate"
 	Certificate            = "certificate"
+	ServerCertificate      = "servercertificate"
 	TLSMin                 = "tlsmin"
 	PacketSize             = "packet size"
 	LogParam               = "log"
@@ -193,7 +195,9 @@ func readCertificate(certificate string) ([]byte, error) {
 }
 
 // Build a tls.Config object from the supplied certificate.
-func SetupTLS(certificate string, insecureSkipVerify bool, hostInCertificate string, minTLSVersion string) (*tls.Config, error) {
+// serverCertificate is used for byte-comparison validation (skips chain validation and hostname validation)
+// certificate is used for traditional chain validation
+func SetupTLS(certificate string, serverCertificate string, insecureSkipVerify bool, hostInCertificate string, minTLSVersion string) (*tls.Config, error) {
 	config := tls.Config{
 		ServerName:         hostInCertificate,
 		InsecureSkipVerify: insecureSkipVerify,
@@ -206,13 +210,27 @@ func SetupTLS(certificate string, insecureSkipVerify bool, hostInCertificate str
 		MinVersion:                  TLSVersionFromString(minTLSVersion),
 	}
 
+	// Handle serverCertificate parameter (byte-comparison validation)
+	if len(serverCertificate) > 0 {
+		pem, err := readCertificate(serverCertificate)
+		if err != nil {
+			return nil, fmt.Errorf("cannot read server certificate %q: %w", serverCertificate, err)
+		}
+		if err := setupTLSServerCertificateOnly(&config, pem); err != nil {
+			return nil, err
+		}
+		return &config, nil
+	}
+
+	// Handle certificate parameter (traditional chain validation)
 	if len(certificate) == 0 {
 		return &config, nil
 	}
 	pem, err := readCertificate(certificate)
 	if err != nil {
 		return nil, fmt.Errorf("cannot read certificate %q: %w", certificate, err)
 	}
+
 	if strings.Contains(config.ServerName, ":") && !insecureSkipVerify {
 		err := setupTLSCommonName(&config, pem)
 		if err != skipSetup {
@@ -225,6 +243,45 @@ func SetupTLS(certificate string, insecureSkipVerify bool, hostInCertificate str
 	return &config, nil
 }
 
+// setupTLSServerCertificateOnly validates that the server certificate matches the provided certificate via byte comparison
+// This matches the behavior of Microsoft.Data.SqlClient
+func setupTLSServerCertificateOnly(config *tls.Config, pemData []byte) error {
+	// To match the behavior of Microsoft.Data.SqlClient, we simply compare the raw bytes
+	// of the server's certificate with the provided certificate file. This approach:
+	// - Does not validate certificate chain, expiry, or subject
+	// - Only checks that the server's certificate exactly matches the provided certificate
+	// - Skips hostname validation (which is the intended behavior)
+	//
+	// We use InsecureSkipVerify=true with VerifyPeerCertificate callback because
+	// VerifyConnection runs AFTER standard verification (including hostname check).
+
+	// Parse the expected certificate from the PEM data
+	block, _ := pem.Decode(pemData)
+	if block == nil {
+		return errors.New("failed to decode PEM certificate")
+	}
+	// Store the raw certificate bytes (DER format) for comparison
+	expectedCertBytes := block.Bytes
+
+	config.InsecureSkipVerify = true
+	config.VerifyPeerCertificate = func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error {
+		if len(rawCerts) == 0 {
+			return errors.New("no peer certificates provided")
+		}
+
+		// Compare the server's certificate bytes with the expected certificate bytes
+		// This matches the Microsoft.Data.SqlClient behavior: just compare raw bytes
+		serverCertBytes := rawCerts[0]
+
+		if !bytes.Equal(serverCertBytes, expectedCertBytes) {
+			return errors.New("server certificate doesn't match the provided certificate")
+		}
+
+		return nil
+	}
+	return nil
+}
+
 // Parse and handle encryption parameters. If encryption is desired, it returns the corresponding tls.Config object.
 func parseTLS(params map[string]string, host string) (Encryption, *tls.Config, error) {
 	trustServerCert := false
@@ -259,12 +316,25 @@ func parseTLS(params map[string]string, host string) (Encryption, *tls.Config, e
 		}
 	}
 	certificate := params[Certificate]
+	serverCertificate := params[ServerCertificate]
+	hostInCertificate := params[HostNameInCertificate]
+
+	// Validate parameter combinations
+	if len(serverCertificate) > 0 {
+		if len(certificate) > 0 {
+			return encryption, nil, errors.New("cannot specify both 'certificate' and 'serverCertificate' parameters")
+		}
+		if len(hostInCertificate) > 0 {
+			return encryption, nil, errors.New("cannot specify both 'serverCertificate' and 'hostnameincertificate' parameters")
+		}
+	}
+
 	if encryption != EncryptionDisabled {
 		tlsMin := params[TLSMin]
 		if encrypt == "strict" {
 			trustServerCert = false
 		}
-		tlsConfig, err := SetupTLS(certificate, trustServerCert, host, tlsMin)
+		tlsConfig, err := SetupTLS(certificate, serverCertificate, trustServerCert, host, tlsMin)
 		if err != nil {
 			return encryption, nil, fmt.Errorf("failed to setup TLS: %w", err)
 		}
@@ -711,11 +781,11 @@ func splitAdoConnectionStringParts(dsn string) []string {
 	var parts []string
 	var current strings.Builder
 	inQuotes := false
-	
+
 	runes := []rune(dsn)
 	for i := 0; i < len(runes); i++ {
 		char := runes[i]
-		
+
 		if char == '"' {
 			if inQuotes && i+1 < len(runes) && runes[i+1] == '"' {
 				// Double quote escape sequence - add both quotes to current part
@@ -735,12 +805,12 @@ func splitAdoConnectionStringParts(dsn string) []string {
 			current.WriteRune(char)
 		}
 	}
-	
+
 	// Add the last part if it's not empty
 	if current.Len() > 0 {
 		parts = append(parts, current.String())
 	}
-	
+
 	return parts
 }
 

msdsn/conn_str_go115pre.go

@@ -3,9 +3,11 @@
 
 package msdsn
 
-import "crypto/tls"
+import (
+	"crypto/tls"
+)
 
-func setupTLSCommonName(config *tls.Config, pem []byte) error {
+func setupTLSCommonName(config *tls.Config, pemData []byte) error {
 	// Prior to Go 1.15, the TLS allowed ":" when checking the hostname.
 	// See https://golang.org/issue/40748 for details.
 	return skipSetup