From 8f5cf6930875caa48f70c3982b9d176beb2f6e86 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Wed, 28 Oct 2020 11:26:31 +0100 Subject: [PATCH v15 4/6] NSS Documentation --- doc/src/sgml/acronyms.sgml | 43 +++++++++++++++++++ doc/src/sgml/config.sgml | 28 ++++++++++-- doc/src/sgml/installation.sgml | 30 ++++++++++++- doc/src/sgml/libpq.sgml | 27 ++++++++++-- doc/src/sgml/runtime.sgml | 78 ++++++++++++++++++++++++++++++++-- 5 files changed, 195 insertions(+), 11 deletions(-) diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml index 4e5ec983c0..4f6f0cf353 100644 --- a/doc/src/sgml/acronyms.sgml +++ b/doc/src/sgml/acronyms.sgml @@ -441,6 +441,28 @@ + + NSPR + + + + Netscape Portable Runtime + + + + + + NSS + + + + Network Security Services + + + + ODBC @@ -539,6 +561,17 @@ + + PKCS#12 + + + + Public-Key Cryptography Standards #12 + + + + PL @@ -684,6 +717,16 @@ + + TLS + + + + Transport Layer Security + + + + TOAST diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index f043433e31..f7ae3b1be1 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1208,6 +1208,23 @@ include_dir 'conf.d' + + ssl_database (string) + + ssl_database configuration parameter + + + + + Specifies the name of the file containing the server certificates and + keys when using NSS for SSL + connections. This parameter can only be set in the + postgresql.conf file or on the server command + line. + + + + ssl_ciphers (string) @@ -1224,7 +1241,9 @@ include_dir 'conf.d' connections using TLS version 1.2 and lower are affected. There is currently no setting that controls the cipher choices used by TLS version 1.3 connections. The default value is - HIGH:MEDIUM:+3DES:!aNULL. The default is usually a + HIGH:MEDIUM:+3DES:!aNULL for servers which have + been built with OpenSSL as the + SSL library. The default is usually a reasonable choice unless you have specific security requirements. @@ -1426,8 +1445,11 @@ include_dir 'conf.d' Sets an external command to be invoked when a passphrase for decrypting an SSL file such as a private key needs to be obtained. By - default, this parameter is empty, which means the built-in prompting - mechanism is used. + default, this parameter is empty. When the server is using + OpenSSL, this means the built-in prompting + mechanism is used. When using NSS, there is + no default prompting so a blank callback will be used returning an + empty password. The command must print the passphrase to the standard output and exit diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 0ac1cb9999..bd09124fb0 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -250,7 +250,7 @@ su - postgres - You need OpenSSL, if you want to support + You need a supported SSL library, if you want to support encrypted client connections. OpenSSL is also required for random number generation on platforms that do not have /dev/urandom (except Windows). The minimum @@ -966,6 +966,31 @@ build-postgresql: + + + + NSS + NSPR + SSL + + + + + Build with support for SSL (encrypted) + connections using NSS. This requires the + NSS package to be installed. Additionally, + NSS requires NSPR + to be installed. configure will check for the + required header files and libraries to make sure that your + NSS installation is sufficient before + proceeding. + + + This option is incompatible with --with-openssl. + + + + @@ -982,6 +1007,9 @@ build-postgresql: your OpenSSL installation is sufficient before proceeding. + + This option is incompatible with --with-nss. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 9ce32fb39b..61d9082052 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -2459,6 +2459,8 @@ void *PQsslStruct(const PGconn *conn, const char *struct_name); The struct(s) available depend on the SSL implementation in use. + + For OpenSSL, there is one struct, available under the name "OpenSSL", and it returns a pointer to the OpenSSL SSL struct. @@ -2482,9 +2484,14 @@ void *PQsslStruct(const PGconn *conn, const char *struct_name); ]]> - This structure can be used to verify encryption levels, check server - certificates, and more. Refer to the OpenSSL - documentation for information about this structure. + For NSS, there is one struct available under + the name "NSS", and it returns a pointer to the + NSS PRFileDesc. + + + These structures can be used to verify encryption levels, check server + certificates, and more. Refer to the SSL library + documentation for information about these structures. @@ -2511,6 +2518,10 @@ void *PQgetssl(const PGconn *conn); instead, and for more details about the connection, use . + + This function returns NULL when SSL + librariaes other than OpenSSL are used. + @@ -7943,6 +7954,11 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); before first opening a database connection. Also be sure that you have done that initialization before opening a database connection. + + + This function does nothing when using NSS as + the SSL library. + @@ -7969,6 +7985,11 @@ void PQinitSSL(int do_ssl); might be preferable for applications that need to work with older versions of libpq. + + + This function does nothing when using NSS as + the SSL library. + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 17e938148c..fe7e305b75 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2183,15 +2183,21 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 SSL + TLS PostgreSQL has native support for using SSL connections to encrypt client/server communications for increased security. This requires that - OpenSSL is installed on both client and + a supported TLS library is installed on both client and server systems and that support in PostgreSQL is enabled at build time (see ). + Supported libraries are OpenSSL and + NSS. The terms SSL and + TLS are often used interchangeably to mean a secure + connection using a TLS protocol, even though + SSL protocols are no longer supported. @@ -2211,8 +2217,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - To start in SSL mode, files containing the server certificate - and private key must exist. By default, these files are expected to be + To start in SSL mode, a server certificate + and private key must exist. The below sections on the different libraries + will discuss how to configure these. + + + + By default, these files are expected to be named server.crt and server.key, respectively, in the server's data directory, but other names and locations can be specified using the configuration parameters @@ -2302,6 +2313,18 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 + + NSS Configuration + + + PostgreSQL will look for certificates and keys + in the NSS database specified by the parameter + in postgresql.conf. + The paramaters for certificate and key filenames are used to identify the + nicknames in the database. + + + Using Client Certificates @@ -2376,7 +2399,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - SSL Server File Usage + SSL Server File Parameter Usage summarizes the files that are @@ -2423,6 +2446,14 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 client certificate must not be on this list + + + certificate database + contains server certificates, keys and revocation lists; only + used when PostgreSQL is built with support + for NSS. + + @@ -2550,6 +2581,45 @@ openssl x509 -req -in server.csr -text -days 365 \ + + NSS Certificate Databases + + + When using NSS, all certificates and keys must + be loaded into an NSS certificate database. + + + + To create a new NSS certificate database and + load the certificates created in , + use the following NSS commands: + +certutil -d "sql:server.db" -N --empty-password +certutil -d "sql:server.db" -A -n server.crt -i server.crt -t "CT,C,C" +certutil -d "sql:server.db" -A -n root.crt -i root.crt -t "CT,C,C" + + This will give the certificate the filename as the nickname identifier in + the database which is created as server.db. + + + Then load the server key, which require converting it to + PKCS#12 format using the + OpenSSL tools: + +openssl pkcs12 -export -out server.pfx -inkey server.key -in server.crt \ + -certfile root.crt -passout pass: +pk12util -i server.pfx -d server.db -W '' + + + + Finally a certificate revocation list can be loaded with the following + commands: + +crlutil -I -i server.crl -d server.db -B + + + + -- 2.21.1 (Apple Git-122.3)