docs: clarify SSL certificate authority chain docs

Previously, the requirements of how intermediate certificates were
handled and their chain to root certificates was unclear.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 503a63a58bdc9c544ef58cb2fcaa92f2ead28388..15bc42cd61c58a34c77d00edf827e8a0e58e20cc 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -7122,7 +7122,9 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
    To allow server certificate verification, the certificate(s) of one or more
    trusted <acronym>CA</>s must be
    placed in the file <filename>~/.postgresql/root.crt</> in the user's home
-   directory. (On Microsoft Windows the file is named
+   directory. If intermediate <acronym>CA</>s appear in
+   <filename>root.crt</filename>, the file must also contain certificate
+   chains to their root <acronym>CA</>s. (On Microsoft Windows the file is named
    <filename>%APPDATA%\postgresql\root.crt</filename>.)
   </para>
 
@@ -7180,15 +7182,15 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
    <quote>intermediate</> certificate authority, rather than one that is
    directly trusted by the server.  To use such a certificate, append the
    certificate of the signing authority to the <filename>postgresql.crt</>
-   file, then its parent authority's certificate, and so on up to a
-   <quote>root</> authority that is trusted by the server.  The root
-   certificate should be included in every case where
-   <filename>postgresql.crt</> contains more than one certificate.
+   file, then its parent authority's certificate, and so on up to a certificate
+   authority, <quote>root</> or <quote>intermediate</>, that is trusted by
+   the server, i.e. signed by a certificate in the server's
+   <filename>root.crt</filename> file.
   </para>
 
   <para>
-   Note that <filename>root.crt</filename> lists the top-level CAs that are
-   considered trusted for signing server certificates.  In principle it need
+   Note that the client's <filename>~/.postgresql/root.crt</> lists the top-level CAs 
+   that are considered trusted for signing server certificates.  In principle it need
    not list the CA that signed the client's certificate, though in most cases
    that CA would also be trusted for server certificates.
   </para>

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index ab51782a7c16c63c18f4d073c978650d07e52841..491683730e0e161e82ed22cb047fdee8b80774ea 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1986,10 +1986,10 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    <quote>intermediate</> certificate authority, rather than one that is
    directly trusted by clients.  To use such a certificate, append the
    certificate of the signing authority to the <filename>server.crt</> file,
-   then its parent authority's certificate, and so on up to a <quote>root</>
-   authority that is trusted by the clients.  The root certificate should
-   be included in every case where <filename>server.crt</> contains more than
-   one certificate.
+   then its parent authority's certificate, and so on up to a certificate
+   authority, <quote>root</> or <quote>intermediate</>, that is trusted by
+   clients, i.e. signed by a certificate in the clients'
+   <filename>root.crt</filename> files.
   </para>
 
   <sect2 id="ssl-client-certificates">
@@ -2008,7 +2008,10 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    SSL connection startup.  (See <xref linkend="libpq-ssl"> for a
    description of how to set up certificates on the client.)  The server will
    verify that the client's certificate is signed by one of the trusted
-   certificate authorities.  Certificate Revocation List (CRL) entries
+   certificate authorities.  If intermediate <acronym>CA</>s appear in
+   <filename>root.crt</filename>, the file must also contain certificate
+   chains to their root <acronym>CA</>s.  Certificate Revocation List
+   (CRL) entries
    are also checked if the parameter <xref linkend="guc-ssl-crl-file"> is set.
    <!-- If this URL changes replace it with a URL to www.archive.org. -->
    (See <ulink
@@ -2026,8 +2029,9 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   </para>
 
   <para>
-   Note that <filename>root.crt</filename> lists the top-level CAs that are
-   considered trusted for signing client certificates.  In principle it need
+   Note that the server's <filename>root.crt</filename> lists the top-level
+   CAs that are considered trusted for signing client certificates.
+   In principle it need
    not list the CA that signed the server's certificate, though in most cases
    that CA would also be trusted for client certificates.
   </para>