From 97da1c020bfd04448e065d87a12c876b57538638 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Mon, 8 Feb 2021 23:52:42 +0100 Subject: [PATCH v26 06/10] nss: Documentation Basic documentation of the new API (keypass hooks) as well as config parameters and installation. Additionally there is a section on how to create certificate and keys using the NSS toolchain. --- doc/src/sgml/acronyms.sgml | 43 ++++++++++++ doc/src/sgml/config.sgml | 28 +++++++- doc/src/sgml/installation.sgml | 31 ++++++--- doc/src/sgml/libpq.sgml | 97 +++++++++++++++++++++++++- doc/src/sgml/runtime.sgml | 123 +++++++++++++++++++++++++++++++-- 5 files changed, 303 insertions(+), 19 deletions(-) diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml index 4e5ec983c0..7b02c8a622 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 5ef1c7ad3c..5482d83e65 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1238,6 +1238,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) @@ -1254,7 +1271,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. @@ -1456,8 +1475,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 66ad4ba938..1b71881c6e 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -976,15 +976,30 @@ build-postgresql: Build with support for SSL (encrypted) - connections. The only LIBRARY - supported is . This requires the - OpenSSL package to be installed. - configure will check for the required - header files and libraries to make sure that your - OpenSSL installation is sufficient - before proceeding. + connections. LIBRARY must be one of: - + + + + to build with OpenSSL support. + This requires the OpenSSL + package to be installed. configure will check + for the required header files and libraries to make sure that + your OpenSSL installation is sufficient + before proceeding. + + + + + to build with libnss support. + 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. + + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index b7a82453f0..ad2ec93848 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -830,6 +830,12 @@ int callback_fn(char *buf, int size, PGconn *conn); longjmp(...), etc. It must return normally. + + PQsetSSLKeyPassHook_OpenSSL has no effect unless + the server was compiled with OpenSSL + support. + + @@ -846,6 +852,70 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); + + PQgetSSLKeyPassHook_OpenSSL has no effect unless + the server was compiled with OpenSSL + support. + + + + + + + PQsetSSLKeyPassHook_nssPQsetSSLKeyPassHook_nss + + + PQsetSSLKeyPassHook_nss lets an application override + libpq's default handling of password protected + objects in the NSS database using + or interactive prompting. + + +void PQsetSSLKeyPassHook_nss(PQsslKeyPassHook_nss_type hook); + + + The application passes a pointer to a callback function with signature: + +char *callback_fn(PK11SlotInfo *slot, PRBool retry, void *arg); + + which libpq will call + instead of its default + PQdefaultSSLKeyPassHook_nss password handler. The + callback should determine the password for the token and return a + pointer to it. The returned pointer should be allocated with the NSS + PORT_Strdup function. The token for which the + password is requested is recorded in the slot anc can be identified by + calling PK11_GetTokenName. If no password is + known, the callback should return NULL. The memory + will be owned by NSS and should not be + freed. + + + + PQsetSSLKeyPassHook_nss has no effect unless + the server was compiled with NSS support. + + + + + + PQgetSSLKeyPassHook_nssPQgetSSLKeyPassHook_nss + + + PQgetSSLKeyPassHook_nss returns the current + NSS password hook, or NULL + if none has been set. + + +PQsslKeyPassHook_nss_type PQgetSSLKeyPassHook_nss(void); + + + + + PQgetSSLKeyPassHook_nss has no effect unless the + server was compiled with nss support. + + @@ -2497,6 +2567,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. @@ -2520,9 +2592,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. @@ -2549,6 +2626,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. + @@ -7982,6 +8063,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. + @@ -8008,6 +8094,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 bf877c0e0c..2578ee8c06 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2185,15 +2185,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. @@ -2213,8 +2219,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 @@ -2304,6 +2315,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 parameters for certificate and key filenames are used to identify the + nicknames in the database. + + + Using Client Certificates @@ -2378,7 +2401,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - SSL Server File Usage + SSL Server File Parameter Usage summarizes the files that are @@ -2425,6 +2448,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. + + @@ -2448,7 +2479,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - Creating Certificates + Creating Certificates with OpenSSL To create a simple self-signed certificate for the server, valid for 365 @@ -2552,6 +2583,88 @@ 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 + + + + + + Creating Certificates with NSS + + + To create a simple self-signed CA and certificate for the server, use the + following NSS commands. Replace + *.yourdomain.com with the server's host + name. Remove --empty-password in order to set + a password protecting the databases. The password can be passed to + certutil with the -f parameter. + First create a self-signed CA. To use a different certificate validity + time than the default, use -v to specify the + number of months of validity. + +mkdir root_ca.db +certutil -N -d "sql:root_ca.db/" --empty-password +certutil -S -d "sql:root_ca.db/" -n root_ca -s "CN=ca.yourdomain.com" \ + -x -k rsa -g 2048 -m 5432 -t CTu,CTu,CTu \ + --keyUsage certSigning -2 --nsCertType sslCA,smimeCA,objectSigningCA \ + -Z SHA256 +certutil -L -d "sql:root_ca.db/" -n root_ca -a > root_ca.pem + + Now create a server certificate database, and create a certificate signing + request for the CA. Then sign the request with the already created CA and + insert the certificate chain into the certificate database. + +mkdir server_cert.db +certutil -N -d "sql:server_cert.db/" --empty-password +certutil -R -d "sql:server_cert.db/" -s "CN=dbhost.yourdomain.com" \ + -o server_cert.csr -g 2048 -Z SHA256 + +certutil -C -d "sql:root_ca.db/" -c root_ca -i server_cert.csr \ + -o server_cert.der -m 5433 \ + --keyUsage keyEncipherment,dataEncipherment,digitalSignature \ + --nsCertType sslServer -Z SHA256 + +certutil -A -d "sql:server_cert.db/" -n root_ca -t CTu,CTu,CTu -a -i root_ca.pem +certutil -A -d "sql:server_cert.db/" -n server_cert -t CTu,CTu,CTu -i server_cert.der + + The server certificate is loaded into the certificate database as well as + the CA certificate in order to provide the chain of certificates. + + -- 2.21.1 (Apple Git-122.3)