From fa4add50c4ea97c48881fa8cb3863df80141643c Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Fri, 6 Dec 2013 09:42:08 -0500 Subject: [PATCH] docs: clarify SSL certificate authority chain docs Previously, the requirements of how intermediate certificates were handled and their chain to root certificates was unclear. --- doc/src/sgml/libpq.sgml | 16 +++++++++------- doc/src/sgml/runtime.sgml | 18 +++++++++++------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 503a63a58b..15bc42cd61 100644 --- 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 CAs must be placed in the file ~/.postgresql/root.crt in the user's home - directory. (On Microsoft Windows the file is named + directory. If intermediate CAs appear in + root.crt, the file must also contain certificate + chains to their root CAs. (On Microsoft Windows the file is named %APPDATA%\postgresql\root.crt.) @@ -7180,15 +7182,15 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) 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 postgresql.crt - file, then its parent authority's certificate, and so on up to a - root authority that is trusted by the server. The root - certificate should be included in every case where - postgresql.crt contains more than one certificate. + file, then its parent authority's certificate, and so on up to a certificate + authority, root or intermediate, that is trusted by + the server, i.e. signed by a certificate in the server's + root.crt file. - Note that root.crt lists the top-level CAs that are - considered trusted for signing server certificates. In principle it need + Note that the client's ~/.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. diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index ab51782a7c..491683730e 100644 --- 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 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 server.crt file, - then its parent authority's certificate, and so on up to a root - authority that is trusted by the clients. The root certificate should - be included in every case where server.crt contains more than - one certificate. + then its parent authority's certificate, and so on up to a certificate + authority, root or intermediate, that is trusted by + clients, i.e. signed by a certificate in the clients' + root.crt files. @@ -2008,7 +2008,10 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 SSL connection startup. (See 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 CAs appear in + root.crt, the file must also contain certificate + chains to their root CAs. Certificate Revocation List + (CRL) entries are also checked if the parameter is set. (See - Note that root.crt lists the top-level CAs that are - considered trusted for signing client certificates. In principle it need + Note that the server's root.crt 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.