Document Npgsql 10 GSS session encryption

roji · roji · commit 8ff8ae58d0df · 2025-12-01T12:34:41.000+01:00
diff --git a/conceptual/Npgsql/connection-string-parameters.md b/conceptual/Npgsql/connection-string-parameters.md
@@ -19,6 +19,7 @@ Passfile     | Path to a PostgreSQL password file (PGPASSFILE), from which the p
 
 Parameter                    | Description                                                                                                                                 | Default
 ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------
+GSS Encryption Mode          | Controls whether GSS encryption is used, depending on server support. [See docs for possible values and more info](security.md).            | Prefer
 SSL Mode                     | Controls whether SSL is used, depending on server support. [See docs for possible values and more info](security.md).                       | Prefer
 Trust Server Certificate     | Whether to trust the server certificate without validating it. [See docs for more info](security.md).                                       | false
 SSL Certificate              | Location of a client certificate to be sent to the server. [See docs](security.md).                                                         | PGSSLCERT
diff --git a/conceptual/Npgsql/release-notes/10.0.md b/conceptual/Npgsql/release-notes/10.0.md
@@ -20,7 +20,9 @@ Note that these changes modify the metric names and tracing span tags, and so ar
 
 ## GSSAPI session encryption
 
-GSSAPI session encryption is an alternative to SSL/TLS session encryption, where special temporary tokens are used to encrypt traffic between the client and the server (MIT Kerberos is one of the GSSAPI providers that can be used for that), unlike SSL/TLS, where SSL certificate is used for the same purpose. You can use the `GssEncryptionMode` connection string parameter to control whether GSS session encryption is used; the default is `Prefer`, which will enable the feature if possible but proceed if it's not available. To learn more, see PostgreSQL [docs](https://www.postgresql.org/docs/current/gssapi-enc.html).
+GSSAPI session encryption is an alternative to SSL/TLS session encryption, where special temporary tokens are used to encrypt traffic between the client and the server (MIT Kerberos is one of the GSSAPI providers that can be used for that), unlike SSL/TLS, where the SSL certificate is used for the same purpose. You can use the `GssEncryptionMode` connection string parameter to control whether GSS session encryption is used; the default is `Prefer`, which will enable the feature if possible but proceed if it's not available.
+
+To learn more, [see the security and encryption docs](../security.md).
 
 ## Support for RequireAuth in connection string
 
diff --git a/conceptual/Npgsql/security.md b/conceptual/Npgsql/security.md
@@ -37,13 +37,25 @@ dataSource.Password = <new password>;
 
 Any physical connection that's opened after this point will use the newly-injected password.
 
-## Encryption (SSL/TLS)
+## GSS session encryption (GSS-API)
+
+Connections to PostgreSQL are unencrypted by default, but you can turn on session encryption if you wish. Npgsql 10 supports GSS-API for session encryption, and defaults to it if PostgreSQL is set up to support GSS-API (GSS-API is preferred over SSL/TLS).
 
-By default PostgreSQL connections are unencrypted, but you can turn on SSL/TLS encryption if you wish. First, you have to set up your PostgreSQL to receive SSL/TLS connections [as described here](http://www.postgresql.org/docs/current/static/ssl-tcp.html). Once that's done, specify `SSL Mode` in your connection string as detailed below.
+To use GSS-API, configure your PostgreSQL for GSS-API session encryption ([docs](https://www.postgresql.org/docs/current/gssapi-enc.html)). Once that's done, you can use `GSS Encryption Mode` in your connection string to configure support (this is similar to the PG [`gccencmode`](https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE) parameter):
 
-### [Version 6.0+](#tab/tabid-1)
+SSL Mode            | Meaning
+------------------- | ---------
+Disable             | Only try a non-GSSAPI-encrypted connection.
+Prefer (default)    | If there are GSSAPI credentials present (i.e., in a credentials cache), first try a GSSAPI-encrypted connection; if that fails or there are no credentials, try a non-GSSAPI-encrypted connection. This is the default when PostgreSQL has been compiled with GSSAPI support.
+Require             | Only try a GSSAPI-encrypted connection.
 
-Starting with 6.0, the following `SSL Mode` values are supported (see the [PostgreSQL docs](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS) for more details):
+The default mode is `Prefer`, which allows GSS-API session encryption but does not require it.
+
+## Encryption (SSL/TLS)
+
+As an alternative to GSS-API, you can use SSL/TLS. First, you have to set up your PostgreSQL to receive SSL/TLS connections [as described here](http://www.postgresql.org/docs/current/static/ssl-tcp.html). Once that's done, specify `SSL Mode` in your connection string as detailed below.
+
+The following `SSL Mode` values are supported (see the [PostgreSQL docs](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS) for more details):
 
 SSL Mode            | Eavesdropping protection | Man-in-the-middle protection | Statement
 ------------------- | ------------------------ | ---------------------------- | ---------
@@ -54,25 +66,7 @@ Require<sup>1</sup> | Yes                      | No                           |
 VerifyCA            | Yes                      | Depends on CA policy         | I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server that I trust.
 VerifyFull          | Yes                      | Yes                          | I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server I trust, and that it's the one I specify.
 
-<sup>1</sup> Prior to Npgsql 8.0, `SSL Mode=Require` required explicitly setting `Trust Server Certificate=true` as well, to make it explicit that the server certificate isn't validated. Starting with 8.0, `Trust Server Certificate=true` is no longer required and does nothing.
-
-The default mode in 6.0+ is `Prefer`, which allows SSL but does not require it, and does not validate certificates.
-
-### [Older versions](#tab/tabid-2)
-
-Versions prior to 6.0 supported the following `SSL Mode` values:
-
-SSL Mode    | Eavesdropping protection | Man-in-the-middle protection | Statement
------------ | ------------------------ | ---------------------------- | ---------
-Disable     | No                       | No                           | I don't care about security, and I don't want to pay the overhead of encryption.
-Prefer      | Maybe                    | Maybe                        | I don't care about encryption, but I wish to pay the overhead of encryption if the server supports it.
-Require     | Yes                      | Yes                          | I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server I trust, and that it's the one I specify.
-
-The default mode prior to 6.0 was `Disable`.
-
-To disable certificate validation when using `Require`, set `Trust Server Certificate` to true; this allows connecting to servers with e.g. self-signed certificates, while still requiring encryption.
-
----
+The default mode is `Prefer`, which allows SSL but does not require it, and does not validate certificates.
 
 ### SSL Negotiation
 
