From 4e15bdbec554609f0ed441bfc680479b8c6a04c1 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Tue, 4 Oct 2016 14:43:43 +0200
Subject: [PATCH 3/3] A first stab at updating the docs to handle multiple SSL
 libraries

At this point it's a mere start and a nudge in the corner and not
even close to a finished patch. Keeping the current structure of
having a single set of config option seems key though, keeping the
differences between the libraries small and contained.
---
 doc/src/sgml/libpq.sgml   |  44 +++++++++++-----
 doc/src/sgml/runtime.sgml | 124 +++++++++++++++++++++++++++++++++-------------
 2 files changed, 121 insertions(+), 47 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4e34f00..78fcf4c 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1237,13 +1237,14 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>sslcompression</literal></term>
       <listitem>
        <para>
+        This requires <productname>OpenSSL</> 1.0.0 or later, when using
+        other SSL libraries this setting will be ignored.
         If set to 1 (default), data sent over SSL connections will be
         compressed.
-        If set to 0, compression will be disabled (this requires
-        <productname>OpenSSL</> 1.0.0 or later).
+        If set to 0, compression will be disabled.
         This parameter is ignored if a connection without SSL is made,
-        or if the version of <productname>OpenSSL</> used does not support
-        it.
+        if the version of <productname>OpenSSL</> used does not support
+        it or an SSL library other than <productname>OpenSSL</> is used.
        </para>
        <para>
         Compression uses CPU time, but can improve throughput if
@@ -1304,7 +1305,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         revocation list (CRL).  Certificates listed in this file, if it
         exists, will be rejected while attempting to authenticate the
         server's certificate.  The default is
-        <filename>~/.postgresql/root.crl</>.
+        <filename>~/.postgresql/root.crl</>. This setting is ignored
+        when using <productname>Secure Transport</> which require the
+        CRL to be included in the certificate.
        </para>
       </listitem>
      </varlistentry>
@@ -1900,8 +1903,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
          <term><literal>library</literal></term>
           <listitem>
            <para>
-            Name of the SSL implementation in use. (Currently, only
-            <literal>"OpenSSL"</literal> is implemented)
+            Name of the SSL implementation in use.
            </para>
           </listitem>
          </varlistentry>
@@ -7322,9 +7324,14 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
    <productname>PostgreSQL</> has native support for using <acronym>SSL</>
    connections to encrypt client/server communications for increased
    security. See <xref linkend="ssl-tcp"> for details about the server-side
-   <acronym>SSL</> functionality.
+   <acronym>SSL</> functionality. Multiple SSL libraries are supported and
+   are enabled at build time.
+   Table <xref linkend="supported-ssl-libraries"> lists the supported SSL
+   libraries.
   </para>
 
+  <sect2>
+   <title>Using OpenSSL</title>
   <para>
    <application>libpq</application> reads the system-wide
    <productname>OpenSSL</productname> configuration file. By default, this
@@ -7334,6 +7341,15 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
    <envar>OPENSSL_CONF</envar> to the name of the desired configuration
    file.
   </para>
+  </sect2>
+
+  <sect2>
+   <title>Using Secure Transport</title>
+  <para>
+   <productname>Secure Transport</productname> utilize the Keychain of the
+   current user. WRITEME. 
+  </para>
+  </sect2>
 
  <sect2 id="libq-ssl-certificates">
   <title>Client Verification of Server Certificates</title>
@@ -7380,10 +7396,13 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
   </para>
 
   <para>
-   Certificate Revocation List (CRL) entries are also checked
-   if the file <filename>~/.postgresql/root.crl</filename> exists
+   Certificate Revocation List (<acronym>CRL</>) entries are also checked. When libpq
+   is built using <productname>OpenSSL</>
+   the file <filename>~/.postgresql/root.crl</filename> is used
    (<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
-   Windows).
+   Windows). When using <productname>Secure Transport</> the CRL must be
+   included in the server certificate for Keychain to perform certificate
+   revocation checks automatically.
   </para>
 
   <para>
@@ -7661,7 +7680,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
      <row>
       <entry><filename>~/.postgresql/root.crl</></entry>
       <entry>certificates revoked by certificate authorities</entry>
-      <entry>server certificate must not be on this list</entry>
+      <entry>any certificate in this list will be rejected; server certificate
+      must not be on this list</entry>
      </row>
 
     </tbody>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 88ec120..632939c 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2117,12 +2117,42 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   <para>
    <productname>PostgreSQL</> has native support for using
    <acronym>SSL</> connections to encrypt client/server communications
-   for increased security. This requires that
-   <productname>OpenSSL</productname> is installed on both client and
+   for increased security. This requires that a supported SSL library
+   is installed on both client and
    server systems and that support in <productname>PostgreSQL</> is
-   enabled at build time (see <xref linkend="installation">).
+   enabled at build time (see <xref linkend="installation">). Clients are
+   not required to use the same SSL library as the server, all supported
+   libraries are compatible.
+   Table <xref linkend="supported-ssl-libraries"> lists the supported SSL
+   libraries.
   </para>
 
+  <table id="supported-ssl-libraries">
+   <title>Supported SSL libraries</title>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>Library</entry>
+      <entry>Platform</entry>
+     </row>
+    </thead>
+
+    <tbody>
+
+     <row>
+      <entry><productname>OpenSSL</productname></entry>
+      <entry>All platforms supported by <productname>PostgreSQL</productname></entry>
+     </row>
+
+     <row>
+      <entry><productname>Secure Transport</productname></entry>
+      <entry><productname>Apple macOS</productname></entry>
+     </row>
+
+    </tbody>
+   </tgroup>
+  </table>
+
   <para>
    With <acronym>SSL</> support compiled in, the
    <productname>PostgreSQL</> server can be started with
@@ -2137,41 +2167,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   </para>
 
   <para>
-   <productname>PostgreSQL</productname> reads the system-wide
-   <productname>OpenSSL</productname> configuration file. By default, this
-   file is named <filename>openssl.cnf</filename> and is located in the
-   directory reported by <literal>openssl version -d</>.
-   This default can be overridden by setting environment variable
-   <envar>OPENSSL_CONF</envar> to the name of the desired configuration file.
-  </para>
-
-  <para>
-   <productname>OpenSSL</productname> supports a wide range of ciphers
-   and authentication algorithms, of varying strength.  While a list of
-   ciphers can be specified in the <productname>OpenSSL</productname>
-   configuration file, you can specify ciphers specifically for use by
-   the database server by modifying <xref linkend="guc-ssl-ciphers"> in
-   <filename>postgresql.conf</>.
-  </para>
-
-  <note>
-   <para>
-    It is possible to have authentication without encryption overhead by
-    using <literal>NULL-SHA</> or <literal>NULL-MD5</> ciphers.  However,
-    a man-in-the-middle could read and pass communications between client
-    and server.  Also, encryption overhead is minimal compared to the
-    overhead of authentication.  For these reasons NULL ciphers are not
-    recommended.
-   </para>
-  </note>
-
-  <para>
-   To start in <acronym>SSL</> mode, files containing the server certificate
-   and private key must exist.  By default, these files are expected to be
+   To start in <acronym>SSL</> mode, a server certificate
+   and private key must exist.  By default, these are expected to be in files
    named <filename>server.crt</> and <filename>server.key</>, respectively, in
    the server's data directory, but other names and locations can be specified
    using the configuration parameters <xref linkend="guc-ssl-cert-file">
-   and <xref linkend="guc-ssl-key-file">.
+   and <xref linkend="guc-ssl-key-file">. See the notes on the library used
+   for specifics on how certificates and keys can be specified.
   </para>
 
   <para>
@@ -2202,6 +2204,58 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    <filename>root.crt</filename> files.
   </para>
 
+  <note>
+   <para>
+    It is possible to have authentication without encryption overhead by
+    using NULL ciphers (<literal>NULL-SHA</> or <literal>NULL-MD5</> in
+    <productname>OpenSSL</productname> for example).  However,
+    a man-in-the-middle could read and pass communications between client
+    and server.  Also, encryption overhead is minimal compared to the
+    overhead of authentication.  For these reasons NULL ciphers are not
+    recommended.
+   </para>
+  </note>
+
+  <sect2 id="ssl-library-openssl">
+   <title>Using OpenSSL</title>
+
+  <para>
+   <productname>PostgreSQL</productname> reads the system-wide
+   <productname>OpenSSL</productname> configuration file. By default, this
+   file is named <filename>openssl.cnf</filename> and is located in the
+   directory reported by <literal>openssl version -d</>.
+   This default can be overridden by setting environment variable
+   <envar>OPENSSL_CONF</envar> to the name of the desired configuration file.
+  </para>
+
+  <para>
+   <productname>OpenSSL</productname> supports a wide range of ciphers
+   and authentication algorithms, of varying strength.  While a list of
+   ciphers can be specified in the <productname>OpenSSL</productname>
+   configuration file, you can specify ciphers specifically for use by
+   the database server by modifying <xref linkend="guc-ssl-ciphers"> in
+   <filename>postgresql.conf</>.
+  </para>
+  </sect2>
+
+  <sect2 id="ssl-library-secure-transport">
+   <title>Using Secure Transport</title>
+   
+  <para>
+   <productname>Secure Transport</productname> can use certificates and
+   keys either stored in files or load them from
+   <productname>Keychain</productname> by prefixing the configuration
+   parameters <xref linkend="guc-ssl-cert-file"> and
+   <xref linkend="guc-ssl-key-file"> with <literal>keychain:</>.
+   It is not possible to load certificate revocation list, <acronym>CRL</acronym>,
+   manually with <productname>Secure Transport</productname>, certificate revocation
+   can only be handled from within <productname>Keychain</productname>.  When using a
+   certificate stored in <productname>Keychain</productname>, certificate revocation
+   is automatically supported via CRL and <acronym>OCSP</acronym> if the URL for
+   the revocation responder is contained in the certificate.
+  </para>
+  </sect2>
+  
   <sect2 id="ssl-client-certificates">
    <title>Using Client Certificates</title>
 
-- 
2.6.4 (Apple Git-63)

