Get-DbaNetworkEncryption - Add command to retrieve TLS certificate from SQL Server network

[andreasjordan]

Fixes #9112

Adds Get-DbaNetworkEncryption which retrieves the TLS/SSL certificate presented by a SQL Server instance during the TLS handshake, without requiring Windows host access or WinRM.

Key features:

• Connects directly to SQL Server's TCP port via TLS/SSL
• No Windows host access required (no WinRM)
• Handles named instances via SQL Browser (UDP 1434) with proper DNS resolution
• Returns Subject, Issuer, Thumbprint, Expiration, DNS SANs, and more
• Graceful error handling for instances without TLS configured

This complements Get-DbaNetworkCertificate (which reads from the Windows registry, requires WinRM) by instead showing what certificate is actually being presented to clients.

Generated with Claude Code

[potatoqualitee]

very cool command!

[andreasjordan]

@claude The command does not work.

This is the verbose output:

PS C:\Users\Admin.ordix> Get-DbaNetworkEncryption -SqlInstance fci01 -Verbose
VERBOSE: [08:34:08][Get-DbaNetworkEncryption] Connecting to fci01 on port 1433 to retrieve TLS certificate
WARNING: [08:34:08][Get-DbaNetworkEncryption] Failed to retrieve certificate from fci01 | Invalid pre-login response from fci01:1433

The variable $bytesRead has the value "0" after line 185.

[claude]

Claude finished @andreasjordan's task in 3m 57s —— View job

---

Fixed: Malformed Pre-Login Packet

• Analyzing the issue
• Reading the source file
• Identifying the root cause
• Implementing the fix
• Committing and pushing changes

Root cause: The $preLoginBytes array had incorrect data-section offsets in the TDS pre-login option headers.

The original packet had 5 option entries (VERSION, ENCRYPTION, INSTOPT, THREADID, MARS) × 5 bytes each + 1 terminator = 26 bytes of headers, meaning data could only start at payload offset 26 or higher. But the offsets claimed:

• VERSION data at offset 21 → overlaps with MARS header bytes
• ENCRYPTION data at offset 27 → overlaps with terminator
• INSTOPT/THREADID/MARS data at offsets 28-29 → past the packet end

SQL Server detected the malformed packet and closed the TCP connection immediately, causing NetworkStream.Read() to return 0.

Fix: Simplified to just two options (VERSION + ENCRYPTION) with correct offsets:

Field	Payload offset	Length
VERSION option header	0	5 bytes
ENCRYPTION option header	5	5 bytes
TERMINATOR	10	1 byte
VERSION data	11 (0x0B) ✓	6 bytes
ENCRYPTION data	17 (0x11) ✓	1 byte

Total packet: 8 (TDS header) + 18 (payload) = 26 bytes = 0x1A — matches the length field.

Commit: d7c6952
|

[andreasjordan]

@claude Now I get this error:

PS C:\Users\Admin.ordix> Get-DbaNetworkEncryption -SqlInstance fci01 -Verbose
VERBOSE: [08:57:42][Get-DbaNetworkEncryption] Connecting to fci01 on port 1433 to retrieve TLS certificate
WARNING: [08:57:48][Get-DbaNetworkEncryption] Failed to retrieve certificate from fci01 | Exception calling "AuthenticateAsClient" with "1" argument(s): "Unable to read data from the transport connection: A connecti
on attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond."

[claude]

Claude finished @andreasjordan's task in 3m 54s —— View job

---

Fixed: TLS Handshake Timeout

• Analyzing the error
• Reading the current implementation
• Implementing the fix
• Committing and pushing changes

Root cause: SQL Server uses a STARTTLS-style TLS negotiation where TLS handshake messages (ClientHello, ServerHello, etc.) are wrapped inside TDS packets (type 0x12) throughout the entire handshake phase. The previous code was passing the raw NetworkStream directly to SslStream, so AuthenticateAsClient sent a raw TLS ClientHello. SQL Server saw this as an invalid TDS packet, stopped responding, and the call timed out after ~6 seconds.

Fix in commit 1de6d6d:

Added DbaTools.TdsWrappingStream — a System.IO.Stream subclass compiled at runtime via Add-Type. It:

• Writes: Wraps each Write() call's data in a TDS packet header (type 0x12, EOM status, correct length) before forwarding to the inner NetworkStream
• Reads: Reads the 8-byte TDS header first, then returns just the payload — stripping the TDS framing

SslStream now wraps this TdsWrappingStream instead of the raw NetworkStream, so the TLS ClientHello is correctly framed as SQL Server expects.

Bonus fix: The server's pre-login response is now parsed to find the ENCRYPTION option byte. If the server replies with ENCRYPT_NOT_SUP (0x02), a clear error is raised immediately instead of hanging:

Server does not support TLS encryption - no certificate is presented

The TdsWrappingStream type is compiled once per session (guarded by -not ('DbaTools.TdsWrappingStream' -as [type])), so repeated calls within the same PowerShell session don't recompile it.
|

[andreasjordan]

@claude Now the command does not fail anymore, but returns an empty output:

PS C:\Users\Admin.ordix> Get-DbaNetworkEncryption -SqlInstance fci01 -Verbose
VERBOSE: [09:06:03][Get-DbaNetworkEncryption] Connecting to fci01 on port 1433 to retrieve TLS certificate


ComputerName : fci01
InstanceName : MSSQLSERVER
SqlInstance  : fci01
Port         : 1433
Subject      : 
Issuer       : 
Thumbprint   : 
NotBefore    : 
Expires      : 
DnsNameList  : {}
SerialNumber : 
Certificate  : System.Security.Cryptography.X509Certificates.X509Certificate2

But the instance has a certificate configured.

[claude]

Claude finished @andreasjordan's task in 1m 11s —— View job

---

Fixed: Empty Certificate Properties

• Analyzing the issue
• Reading the current implementation
• Identifying the root cause
• Implementing the fix
• Committing and pushing changes

Root cause: The $certValidationCallback scriptblock set $script:capturedCertificate = $certificate, but .NET-invoked scriptblock callbacks don't reliably write back to PowerShell session variables. The variable stayed $null, and New-Object X509Certificate2($null) created an empty certificate object — which explains the output showing System.Security.Cryptography.X509Certificates.X509Certificate2 with all blank properties.

Fix (commit 6003556): Replaced the callback-based capture with $sslStream.RemoteCertificate — the documented, reliable property for retrieving the server certificate after a completed TLS handshake. The callback is still present (needed to suppress certificate validation errors so we can always complete the handshake), but no longer responsible for capturing the cert.

[andreasjordan]

Ok, the command works now as expected.

But the code is from Claude and not (as in the issue suggested) based on the function from Jordan Borean (https://gist.github.com/jborean93/44f92e4dfa613c5a1e7889fa7a7c2563).

I locally changed the code to use the function from Jordan Borean and it worked as well. So now I'm not sure where we want to go. And I don't want to decide. What do you think, @potatoqualitee ?