Add Windows and MacOS native certificate support

docs/content/documentation/ssl.md

@@ -38,6 +38,20 @@ Information on how to actually implement such a class is beyond the scope of thi
 are the [JSSE Reference Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
 and the source to the `NonValidatingFactory` provided by the JDBC driver.
 
+## Available SSLSocketFactory Implementations
+
+The following implementations of SSLSocketFactory are shipped with the driver.
+
+|sslfactory|Description|
+|---|---|
+|org.postgresql.ssl.DefaultJavaSSLFactory|Use the JDK default implementation.|
+|org.postgresql.ssl.KeychainSSLFactory|Use certificates and keys from the MacOS keychain. If the MacOS truststore is unsupported by the JDK, we fall back to the default cacerts JKS truststore.|
+|org.postgresql.ssl.LibPQFactory|Use the same certificates and keys as the libpq library. The key must be in DER encoded PKCS8 format. This is the default when sslfactory is unspecified.|
+|org.postgresql.ssl.MSCAPILocalMachineSSLFactory|Use certificates and keys from the Windows local machine certificate manager.|
+|org.postgresql.ssl.MSCAPISSLFactory|Use certificates and keys from the Windows certificate manager belonging to the current user.|
+|org.postgresql.ssl.NonValidatingFactory|Connect to anyone without checking. No validation is performed.|
+|org.postgresql.ssl.SingleCertValidatingFactory|Accept the pinned server certificate specified in the sslfactoryarg parameter.|
+
 ## Configuring the Client
 
 There are a number of connection parameters for configuring the client for SSL. See [SSL Connection parameters](/documentation/use/#connection-parameters/)
@@ -122,6 +136,10 @@ When starting your Java application you must specify this keystore and password
 
 In the event of problems extra debugging information is available by adding `-Djavax.net.debug=ssl` to your command line.
 
+### Choosing a Specific Certificate
+
+When using the Keychain or MSCAPI factories, and more than one client certificate matches during SSL negotiation, the first negotiated certificate will be chosen. To control which of many negotiated certificates will be returned, the sslsubject parameter can be used to set the subject of the certificate to be chosen. Note that sslsubject chooses from the list of negotiated certificates, it does not override the negotiation mechanism. If there is no match, no certificate will be sent to the server.
+
 ### Using SSL without Certificate Validation
 
 In some situations it may not be possible to configure your Java environment to make the server certificate available, for example in an applet. For a large scale deployment it would be best to get a certificate signed by recognized

pgjdbc/src/main/java/org/postgresql/PGProperty.java

@@ -701,6 +701,14 @@ public enum PGProperty {
       null,
       "The location of the root certificate for authenticating the server."),
 
+  /**
+   * The subject of the desired client certificate in a store containing many certificates.
+   */
+  SSL_SUBJECT(
+      "sslsubject",
+      null,
+      "The subject of the desired client certificate in a store with many certificates."),
+
   /**
    * Specifies the name of the SSPI service class that forms the service class part of the SPN. The
    * default, {@code POSTGRES}, is almost always correct.

pgjdbc/src/main/java/org/postgresql/ds/common/BaseDataSource.java

@@ -774,6 +774,22 @@ public void setSslPasswordCallback(@Nullable String className) {
     PGProperty.SSL_PASSWORD_CALLBACK.set(properties, className);
   }
 
+  /**
+   * @return SSL subject
+   * @see PGProperty#SSL_SUBJECT
+   */
+  public @Nullable String getSslSubject() {
+    return PGProperty.SSL_SUBJECT.getOrDefault(properties);
+  }
+
+  /**
+   * @param file SSL subject
+   * @see PGProperty#SSL_SUBJECT
+   */
+  public void setSslSubject(@Nullable String file) {
+    PGProperty.SSL_SUBJECT.set(properties, file);
+  }
+
   /**
    * @param applicationName application name
    * @see PGProperty#APPLICATION_NAME

pgjdbc/src/main/java/org/postgresql/ssl/KeychainSSLFactory.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2024, PostgreSQL Global Development Group
+ * See the LICENSE file in the project root for more information.
+ */
+
+package org.postgresql.ssl;
+
+import org.postgresql.util.PSQLException;
+
+import java.util.Properties;
+
+/**
+ * <p>Provides a SSLSocketFactory that authenticates the remote server against
+ * the keychain provided by MacOS.</p>
+ *
+ * <p>Older versions of the JDK support MacOS key stores but not trust stores.
+ * If the trust store implementation is not found, this factory falls back to
+ * the default JDK trust store in <code>cacerts</code>.
+ *
+ * <p>When multiple certificates match for the given connection, the optional
+ * <code>sslsubject</code> connection property can be used to choose the
+ * desired certificate from the matching set. Note that this property does not
+ * override the certificate selection outside of the matching set.
+ */
+public class KeychainSSLFactory extends SSLFactory {
+
+  public KeychainSSLFactory(Properties info) throws PSQLException {
+    super(info, "TLS", "PKIX", "Apple",
+                "KeychainStore",
+                "Apple", "KeychainStore-ROOT");
+  }
+
+}

pgjdbc/src/main/java/org/postgresql/ssl/MSCAPILocalMachineSSLFactory.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2024, PostgreSQL Global Development Group
+ * See the LICENSE file in the project root for more information.
+ */
+
+package org.postgresql.ssl;
+
+import org.postgresql.util.PSQLException;
+
+import java.util.Properties;
+
+/**
+ * <p>Provides a SSLSocketFactory that authenticates the remote server against
+ * the local machine's certificate store provided by Windows.</p>
+ *
+ * <p>The remote certificate is validated against the local machine's
+ * certificate trust store.</p>
+ *
+ * <p>When multiple certificates match for the given connection, the optional
+ * <code>sslsubject</code> connection property can be used to choose the
+ * desired certificate from the matching set. Note that this property does not
+ * override the certificate selection outside of the matching set.
+ */
+public class MSCAPILocalMachineSSLFactory extends SSLFactory {
+
+  public MSCAPILocalMachineSSLFactory(Properties info) throws PSQLException {
+    super(info, "TLS", "PKIX", "SunMSCAPI",
+            "Windows-MY-LOCALMACHINE",
+            "SunMSCAPI", "Windows-ROOT");
+  }
+
+}

pgjdbc/src/main/java/org/postgresql/ssl/MSCAPISSLFactory.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2024, PostgreSQL Global Development Group
+ * See the LICENSE file in the project root for more information.
+ */
+
+package org.postgresql.ssl;
+
+import org.postgresql.util.PSQLException;
+
+import java.util.Properties;
+
+/**
+ * <p>Provides a SSLSocketFactory that authenticates the remote server against
+ * the logged in user's certificate store provided by Windows.</p>
+ *
+ * <p>The remote certificate is validated against the logged in user's
+ * certificate trust store.</p>
+ *
+ * <p>When multiple certificates match for the given connection, the optional
+ * <code>sslsubject</code> connection property can be used to choose the
+ * desired certificate from the matching set. Note that this property does not
+ * override the certificate selection outside of the matching set.
+ */
+public class MSCAPISSLFactory extends SSLFactory {
+
+  public MSCAPISSLFactory(Properties info) throws PSQLException {
+    super(info, "TLS", "PKIX", "SunMSCAPI",
+            "Windows-MY",
+            "SunMSCAPI", "Windows-ROOT");
+  }
+
+}

pgjdbc/src/main/java/org/postgresql/ssl/SSLFactory.java

@@ -0,0 +1,197 @@
+/*
+ * Copyright (c) 2024, PostgreSQL Global Development Group
+ * See the LICENSE file in the project root for more information.
+ */
+
+package org.postgresql.ssl;
+
+import org.postgresql.PGProperty;
+import org.postgresql.util.GT;
+import org.postgresql.util.PSQLException;
+import org.postgresql.util.PSQLState;
+
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.io.IOException;
+import java.security.KeyManagementException;
+import java.security.KeyStore;
+import java.security.KeyStoreException;
+import java.security.NoSuchAlgorithmException;
+import java.security.NoSuchProviderException;
+import java.security.UnrecoverableKeyException;
+import java.security.cert.CertificateException;
+import java.util.Properties;
+
+import javax.net.ssl.KeyManager;
+import javax.net.ssl.KeyManagerFactory;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManagerFactory;
+import javax.net.ssl.X509KeyManager;
+import javax.security.auth.x500.X500Principal;
+
+/**
+ * Socket factory that uses typical "zero configuration" key and trust
+ * stores, like the native Windows "SunMSCAPI" or native Apple "Apple"
+ * providers.
+ */
+public class SSLFactory extends WrappedFactory {
+
+  protected SSLFactory(Properties info, final String protocol, final String algorithm, final String keyStoreProvider, final String keyStoreType, final String trustStoreProvider, final String trustStoreType) throws PSQLException {
+
+    SSLContext ctx;
+    final KeyStore keyStore;
+    KeyStore trustStore;
+    final char[] keyPassphrase = new char[0];
+    final String sslsubject = PGProperty.SSL_SUBJECT.getOrDefault(info);
+    final @Nullable X500Principal subject;
+    final KeyManagerFactory keyManagerFactory;
+    final TrustManagerFactory trustManagerFactory;
+
+    try {
+
+      keyStore = KeyStore.getInstance(keyStoreType, keyStoreProvider);
+
+    } catch (KeyStoreException ex) {
+      throw new PSQLException(GT.tr("SSL keystore {0} not available.",
+                keyStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    } catch (NoSuchProviderException ex) {
+      throw new PSQLException(GT.tr("SSL keystore {0} not available.",
+                keyStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      keyStore.load(null, null);
+
+    } catch (CertificateException ex) {
+      throw new PSQLException(GT.tr("SSL keystore {0} could not be loaded.",
+                keyStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    } catch (IOException ex) {
+      throw new PSQLException(GT.tr("SSL keystore {0} could not be loaded.",
+                keyStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    } catch (NoSuchAlgorithmException ex) {
+      throw new PSQLException(GT.tr("Could not find a Java cryptographic algorithm: {0}.",
+                ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      keyManagerFactory = KeyManagerFactory
+              .getInstance(algorithm);
+
+    } catch (NoSuchAlgorithmException ex) {
+      throw new PSQLException(GT.tr("Could not find a Java cryptographic algorithm: {0}.",
+                ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      keyManagerFactory.init(keyStore, keyPassphrase);
+
+    } catch (NoSuchAlgorithmException ex) {
+      throw new PSQLException(GT.tr("Could not find a Java cryptographic algorithm: {0}.",
+                ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    } catch (KeyStoreException ex) {
+      throw new PSQLException(GT.tr("Could not initialize SSL keystore."),
+                PSQLState.CONNECTION_FAILURE, ex);
+    } catch (UnrecoverableKeyException ex) {
+      throw new PSQLException(GT.tr("Could not read SSL key."),
+                PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      trustStore = KeyStore.getInstance(trustStoreType, trustStoreProvider);
+
+    } catch (KeyStoreException ex) {
+      // On the Mac, the truststore is new and won't be available
+      // on old versions of the JDK. In these cases fall back to
+      // the default truststore in cacerts.
+      if (ex.getCause() instanceof NoSuchAlgorithmException) {
+        trustStore = null;
+      } else {
+        throw new PSQLException(GT.tr("SSL truststore {0} not available.",
+                    trustStoreType), PSQLState.CONNECTION_FAILURE, ex);
+      }
+    } catch (NoSuchProviderException ex) {
+      throw new PSQLException(GT.tr("SSL truststore {0} not available.",
+                trustStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      if (trustStore != null) {
+        trustStore.load(null, null);
+      }
+
+    } catch (CertificateException ex) {
+      throw new PSQLException(GT.tr("SSL truststore {0} could not be loaded.",
+                trustStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    } catch (IOException ex) {
+      throw new PSQLException(GT.tr("SSL truststore {0} could not be loaded.",
+                trustStoreType), PSQLState.CONNECTION_FAILURE, ex);
+    } catch (NoSuchAlgorithmException ex) {
+      throw new PSQLException(GT.tr("Could not find a Java cryptographic algorithm: {0}.",
+                ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      trustManagerFactory = TrustManagerFactory
+              .getInstance(algorithm);
+
+    } catch (NoSuchAlgorithmException ex) {
+      throw new PSQLException(GT.tr("Could not find a Java cryptographic algorithm: {0}.",
+                ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      trustManagerFactory.init(trustStore);
+
+    } catch (KeyStoreException ex) {
+      throw new PSQLException(GT.tr("Could not initialize SSL truststore."),
+                PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      ctx = SSLContext.getInstance(protocol);
+
+    } catch (NoSuchAlgorithmException ex) {
+      throw new PSQLException(GT.tr("Could not find a Java cryptographic algorithm: {0}.",
+                ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      if (sslsubject != null && sslsubject.length() != 0) {
+        subject = new X500Principal(sslsubject);
+      } else {
+        subject = null;
+      }
+
+    } catch (IllegalArgumentException ex) {
+      throw new PSQLException(GT.tr("Could not parse sslsubject {0}: {1}.",
+              sslsubject, ex.getMessage()), PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    try {
+
+      KeyManager km = keyManagerFactory.getKeyManagers()[0];
+
+      if (subject != null) {
+        km = new SubjectKeyManager(X509KeyManager.class.cast(km), subject);
+      }
+
+      ctx.init(new KeyManager[] { km }, null, null);
+
+    } catch (KeyManagementException ex) {
+      throw new PSQLException(GT.tr("Could not initialize SSL keystore/truststore."),
+                PSQLState.CONNECTION_FAILURE, ex);
+    }
+
+    factory = ctx.getSocketFactory();
+
+  }
+}