docs: touch up SSL keyfile documentation (#1836)

document differences between how PKCS-8 and PKCS-12 keyfiles are
handled, and when the sslcert setting has an effect

Co-authored-by: Papp István Péter <[email protected]>

Author: pip25

docs/documentation/head/connect.md

@@ -120,20 +120,22 @@ Connection conn = DriverManager.getConnection(url);
 
 * **sslcert** = String
 
-	Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt
+	Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows.
 
     It can be a PEM encoded X509v3 certificate
 
-	*Note:* defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows 
+	*Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile.
 
 * **sslkey** = String
 
 	Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. 
 
-	*Note:* The key file **must** be in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command:
+	*Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command:
 
 	`openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES`
 
+	PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension.
+
 	If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password.
 
     *Note:* The use of -v1 PBE-MD5-DES might be inadequate in environments where high level of security is needed and the key is not protected

docs/documentation/head/ssl-client.md

@@ -40,13 +40,15 @@ In the case where the certificate validation is failing you can try `sslcert=` a
 not send the client certificate. If the server is not configured to authenticate using the certificate
 it should connect.
 
-The location of the client certificate, client key and root certificate can be overridden with the
+The location of the client certificate, the PKCS-8 client key and root certificate can be overridden with the
 `sslcert`, `sslkey`, and `sslrootcert` settings respectively. These default to /defaultdir/postgresql.crt,
 /defaultdir/postgresql.pk8, and /defaultdir/root.crt respectively where defaultdir is
 ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows
 
-as of version 42.2.9 PKCS12 is supported. In this archive format the key, cert and root cert are all
-in one file which by default is /defaultdir/postgresql.p12
+As of version 42.2.9 PKCS-12 is also supported. In this archive format the client key and the client
+certificate are in one file, which needs to be set with the `sslkey` parameter. For the PKCS-12 format
+to be recognized, the file extension must be ".p12" (supported since 42.2.9) or ".pfx" (since 42.2.16).
+(In this case the `sslcert` parameter is ignored.)
 
 Finer control of the SSL connection can be achieved using the `sslmode` connection parameter.
 This parameter is the same as the libpq `sslmode` parameter and the currently SSL implements the