From f4c70b174391df62a0ea74849f293672706d1ab9 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Mon, 1 Dec 2025 12:31:28 +0100 Subject: [PATCH] Document Npgsql 10 GSS session encryption --- .../Npgsql/connection-string-parameters.md | 1 + conceptual/Npgsql/release-notes/10.0.md | 4 +- conceptual/Npgsql/security.md | 40 ++++++++----------- 3 files changed, 21 insertions(+), 24 deletions(-) diff --git a/conceptual/Npgsql/connection-string-parameters.md b/conceptual/Npgsql/connection-string-parameters.md index 8a12fe84..30cfd2cd 100644 --- 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 index 422cf8e7..58d2bf14 100644 --- 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 index 1ccfa96d..35109382 100644 --- a/conceptual/Npgsql/security.md +++ b/conceptual/Npgsql/security.md @@ -37,13 +37,25 @@ dataSource.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. +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 @@ Require1 | 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. -1 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