Document changes for SSL Mode=Require (#308)

conceptual/Npgsql/release-notes/8.0.md

@@ -28,6 +28,16 @@ Read PostgreSQL records as .NET tuples   | <xref:Npgsql.INpgsqlTypeMapperExtensi
 
 Existing code using the above features will start throwing exceptions after upgrading to Npgsql 8.0; the exceptions provide explicit guidance on how to add the opt-ins.
 
+### `SSL Mode=Require` no longer validates certificates
+
+tl;dr use `SSL Mode=VerifyCA` or `VerifyFull` in order to validate certificates provided by PostgreSQL.
+
+In versions of Npgsql older than 6.0, specifying `SSL Mode=Require` made Npgsql validate the SSL/TLS certificate provided by PostgreSQL. This did not align with the meaning of "require" in PostgreSQL and other clients, where it simply means that SSL/TLS is required, but without certificate validation. To align with the standard PostgreSQL meaning, starting with Npgsql 6.0 `VerifyCA` or `VerifyFull` must be specified to validate the certificate.
+
+To prevent existing usage of `Require` to silently stop validating, Npgsql 6.0 and 7.0 forced `Trust Server Certificate=true` to be specified; this made users aware of the change, guiding them to either switch to `VerifyCA`/`VerifyFull` (if they want validation) or to add `Trust Server Certificate=true` (if they don't). After two major versions, we are now removing the requirement to specify `Trust Server Certificate=true` with `SSL Mode=Require`; the latter will behave in the standard PostgreSQL way and will not verify certificates.
+
+For more context, see [#3988](https://github.com/npgsql/npgsql/issues/3988#issuecomment-933011009).
+
 ### Plugin APIs have been changed for NativeAOT/trimming support
 
 As part of the effort to make Npgsql compatible with NativeAOT and trimming, the plugin API was changed in fundamental, breaking ways. Although this API never had the stability guarantees of a true public API (it was and still is in an Internal namespace), external plugins which were developed with it will require adjustments.

conceptual/Npgsql/security.md

@@ -46,7 +46,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> `SSL Mode=Require` currently requires explicitly setting `Trust Server Certificate=true` as well (this requirement will be removed in a future version). This combination should be used with e.g. self-signed certificates, which don't need to be validated. As an alternative to `Trust Server Certificate=true`, provide your custom certificate validation via <xref:Npgsql.NpgsqlConnection.UserCertificateValidationCallback?displayProperty=nameWithType>.
+<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.