From 4dc63552109f65cebbe168203bd62c5e4c753162 Mon Sep 17 00:00:00 2001 From: Andrew Dunstan Date: Sat, 30 Nov 2019 15:27:13 -0500 Subject: libq support for sslpassword connection param, DER format keys This patch providies for support for password protected SSL client keys in libpq, and for DER format keys, both encrypted and unencrypted. There is a new connection parameter sslpassword, which is supplied to the OpenSSL libraries via a callback function. The callback function can also be set by an application by calling PQgetSSLKeyPassHook(). There is also a function to retreive the connection setting, PQsslpassword(). Craig Ringer and Andrew Dunstan Reviewed by: Greg Nancarrow Discussion: https://postgr.es/m/f7ee88ed-95c4-95c1-d4bf-7b415363ab62@2ndQuadrant.com --- doc/src/sgml/libpq.sgml | 134 +++++++++++++++++++++++++++++++++++++++++ doc/src/sgml/postgres-fdw.sgml | 2 +- 2 files changed, 135 insertions(+), 1 deletion(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 8c657d2d8d8..5a48c39b562 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -776,6 +776,72 @@ PGPing PQping(const char *conninfo); + + PQsetSSLKeyPassHookPQsetSSLKeyPassHook + + + PQsetSSLKeyPassHook lets an application override + libpq's default + handling of encrypted client certificate key files using + or interactive prompting. + + +void PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook); + + + The application passes a pointer to a callback function with signature: + + int callback_fn(char *buf, int size, PGconn *conn); + + which libpq will then call instead of + its default PQdefaultSSLKeyPassHook handler. The callback + should determine the password for the key and copy it to result-buffer + buf of size size. The string in + buf must be null-terminated. The calback must return the length of + the password stored in buf excluding the null terminator. + On failure, the callback should set buf[0] = '\0' and return 0. + See PQdefaultSSLKeyPassHook in libpq's + source code for an example. + + + + If the user specified an explicit key location, + its path will be in conn->pgsslkey when the callback + is invoked. This will be empty if the default key path is being used. + For keys that are engine specifiers, it is up to engine implementations + whether they use the OpenSSL password callback or define their own handling. + + + + The app callback may choose to delegate unhandled cases to + PQdefaultSSLKeyPassHook, + or call it first and try something else if it returns 0, or completely override it. + + + + The callback must not escape normal flow control with exceptions, + longjmp(...), etc. It must return normally. + + + + + + + PQgetSSLKeyPassHookPQgetSSLKeyPassHook + + + PQgetSSLKeyPassHook returns the current + client certificate key password hook, or NULL + if none has been set. + + +PQsslKeyPassHook_type PQgetSSLKeyPassHook(void); + + + + + + @@ -1586,6 +1652,36 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname + + sslpassword + + + This parameter specifies the password for the secret key specified in + sslkey, allowing client certificate private keys + to be stored in encrypted form on disk even when interactive passphrase + input is not practical. + + + Specifying this parameter with any non-empty value suppresses the + Enter PEM passphrase: + prompt that OpenSSL will emit by default when an encrypted client + certificate key is provided to libpq. + + + If the key is not encrypted this parameter is ignored. The parameter has no + effect on keys specified by OpenSSL engines unless the engine uses the + OpenSSL password callback mechanism for prompts. + + + There is no environment variable equivalent to this option, and no + facility for looking it up in .pgpass. It can be + used in a service file connection definition. Users with + more sophisticated uses should consider using openssl engines and + tools like PKCS#11 or USB crypto offload devices. + + + + sslrootcert @@ -1771,6 +1867,24 @@ char *PQpass(const PGconn *conn); + + PQsslpasswordPQsslpassword + + + + Returns the password for the SSL client key. + +char *PQsslpassword(const PGconn *conn); + + + + + will return the SSL password specified + in the connection parameters. + + + + PQhostPQhost @@ -7499,6 +7613,26 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) certificates on the server (). + + The certificate and key may be in PEM or ASN.1 DER format. + + + + The key may be + stored in cleartext or encrypted with a passphrase using any algorithm supported + by OpenSSL, like AES-128. If the key is stored encrypted, then the passphrase + may be provided in the connection + option. If an encrypted key is supplied and the sslpassword + option is absent or blank, a password will be prompted for interactively by + OpenSSL with a + + Enter PEM Passphrase: + + prompt if a TTY is available. Applications can override the client certificate + prompt and the handling of the sslpassword parameter by supplying + their own key password callback; see . + + For instructions on creating certificates, see . diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index ed369cb54b8..1d4bafd9f06 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -112,7 +112,7 @@ - user and password (specify these + user, password and sslpassword (specify these in a user mapping, instead) -- cgit v1.2.3