Safe Haskell	None
Language	Haskell2010

Hmssql.Connection.Tls

Description

TLS for both flavors of SQL Server encryption:

Strict (TDS 8.0): TLS on the raw byte stream from byte zero, with ALPN tds/8.0. The TDS packet stream runs inside the TLS session.
Hosted (TDS 7.x ENCRYPT_ON / ENCRYPT_OFF): the TLS handshake records are carried inside TDS PRELOGIN packets; once the handshake completes, TLS records go directly on the byte stream and TDS packets go inside them.

Synopsis

data TlsSettings = TlsSettings {
- tlsTrustServerCertificate :: !Bool
- tlsUseSystemCertificateStore :: !Bool
- tlsCaCertificateFiles :: ![FilePath]
- tlsExtraCertificates :: ![SignedCertificate]
- tlsHostNameInCertificate :: !(Maybe Text)
}
defaultTlsSettings :: TlsSettings
buildCertificateStore :: TlsSettings -> IO CertificateStore
strictTlsHandshake :: Connection -> TlsSettings -> String -> IO ()
hostedTlsHandshake :: Connection -> TlsSettings -> String -> IO ()

Documentation

data TlsSettings Source #

How the server's certificate is validated, in every mode that uses TLS. defaultTlsSettings validates against the system store; the fields add trust, override the name checked, or turn validation off.

Constructors

TlsSettings

Fields

tlsTrustServerCertificate :: !Bool
Skip certificate validation entirely. Encryption still applies, but the server's identity is not verified.
A certificate whose extended key usage extension doesn't include server authentication is refused even so: tls checks that itself, whatever the validation decided. (SQL Server doesn't use such a certificate anyway: it requires a certificate for server authentication.) With tls 2.5 or later, so is a certificate whose RSA key is shorter than 2048 bits.
tlsUseSystemCertificateStore :: !Bool
Trust the system's certificate store. It is loaded once per process, by the first connection that uses it (loading it takes about 20 ms and 38 MB of allocation on macOS, where it runs the security tool), so certificates added to the system store later are seen only by a new process.
tlsCaCertificateFiles :: ![FilePath]
PEM files whose certificates are trusted in addition to the system store. A self-signed server certificate can be listed here directly. Each is read and parsed by every connection that uses it (about 70 us for a one-certificate file), so a replaced file takes effect with the next connection; an application that connects often and wants to parse a file once can read it itself (readSignedObject) and pass the certificates as tlsExtraCertificates.
tlsExtraCertificates :: ![SignedCertificate]
Trusted certificates supplied in memory.
tlsHostNameInCertificate :: !(Maybe Text)
Validate the certificate against this name instead of the host that was connected to. The server name sent in the TLS handshake (SNI) is still connectHost, or none if that is an IP address.

defaultTlsSettings :: TlsSettings Source #

Validate the server's certificate against the system store, for the host that was connected to, with no extra certificates trusted.

buildCertificateStore :: TlsSettings -> IO CertificateStore Source #

The certificates to validate a server against: the system store (if tlsUseSystemCertificateStore), the files (read now: nothing is cached by path, so a replaced file, even one with the modification time it had, is what the next connection trusts) and the in-memory certificates.

strictTlsHandshake :: Connection -> TlsSettings -> String -> IO () Source #

TDS 8.0: negotiate TLS directly on the socket and switch the connection's transport to it. Throws ProtocolError if the server's first byte is not TLS, or if the handshake ends without the server selecting tds/8.0; nothing is sent inside the session before that check.

hostedTlsHandshake :: Connection -> TlsSettings -> String -> IO () Source #

TDS 7.x: negotiate TLS with the handshake records wrapped in PRELOGIN packets, then switch the connection's transport to the TLS session.