From 28383a3d28b35faf5afe313a2ebe98f6a5168926 Mon Sep 17 00:00:00 2001 From: Diego Date: Mon, 31 Aug 2026 16:38:53 -0300 Subject: [PATCH v3 2/2] libpq: Add PQpassfileLookup() An application that connects through an intermediary, such as a local SSH tunnel, connects to a host and port that no longer match the password file entry written for the real server, so libpq's password file lookup comes up empty during connection establishment. Until now, such an application had to reimplement the password file parser on its side to keep .pgpass working. Expose the existing lookup as a public function, PQpassfileLookup(), so that a client can look up the password under the real server's host and port and pass the result as the password connection parameter while connecting to the intermediary's address. The function applies the same rules as connection establishment: the same field matching and de-escaping, the same localhost and default-port substitutions for missing values, the same permission checks, and the same fallback to PGPASSFILE and the default password file location when no file is given. Other libpq connection-parameter environment variables are not applied to the lookup keys; in particular, PGHOST and PGPORT are ignored. The result holds nothing but the password, so callers can clear it with explicit_bzero() over strlen() bytes before freeing it. Also add --passfile and --passfile-defaults modes to libpq_testclient, and a TAP test exercising the lookup; it needs no server. Author: Diego Reviewed-by: Yuriy Grigoryev Reviewed-by: Denis Smirnov Suggested-by: Denis Smirnov Discussion: https://postgr.es/m/B2EDB5AE-27F7-4580-871E-1C2433BAEF18@gmail.com Discussion: https://postgr.es/m/b650e555-11c7-415d-8bda-c747c492ab4a@gmail.com --- doc/src/sgml/libpq.sgml | 77 +++++++ src/interfaces/libpq/exports.txt | 1 + src/interfaces/libpq/fe-connect.c | 65 +++++- src/interfaces/libpq/libpq-fe.h | 9 + src/interfaces/libpq/meson.build | 1 + src/interfaces/libpq/t/007_passfile.pl | 209 +++++++++++++++++++ src/interfaces/libpq/test/libpq_testclient.c | 60 +++++- 7 files changed, 417 insertions(+), 5 deletions(-) create mode 100644 src/interfaces/libpq/t/007_passfile.pl diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 68487a3954f..2557abfab6d 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -7976,6 +7976,77 @@ char *PQencryptPassword(const char *passwd, const char *user); + + PQpassfileLookupPQpassfileLookup + + + + Looks up a password in a password file + (see ). + +char *PQpassfileLookup(const char *hostname, const char *port, + const char *dbname, const char *username, + const char *passfile); + + + + + This function performs the same password file lookup that connection + establishment performs when no password has been specified, and + returns the password from the first matching line. It is intended + for applications that connect through an intermediary, for example a + local SSH tunnel: such an application can look up the password under + the real server's host and port, and then pass the result as the + connection parameter while + connecting to the intermediary's address. + + + + The hostname, port, + dbname and username + arguments correspond to the first four fields of a password file + line. If hostname is NULL or + empty, or matches libpq's default socket + directory path, the host name localhost is + searched for; if port is NULL + or empty, the compiled-in default port is used. No defaults are + applied for dbname and + username; if either is NULL + or empty, no password is returned. + passfile is the password file to use; if it is + NULL or empty, the file named by the + PGPASSFILE environment variable is used if set, else + the default password file location (see ). + Other libpq connection-parameter + environment variables are not applied to the lookup keys; in + particular, PGHOST and PGPORT are + ignored. + + + + The return value is a string allocated by malloc, + or NULL if no matching password was found or the + lookup could not be completed, for example because of a memory + allocation failure. Use to free + the result when done with it. + + + + Note that the result contains a cleartext password, and that + does not erase it. The string + holds nothing but the password: libpq + writes nothing past its terminating zero byte, so a caller that + does not want the password to linger in memory can overwrite + strlen(result) + bytes before freeing it. The password file + permission requirements described in + apply, and, as during connection + establishment, a warning is written to stderr + if the file is ignored because of them. + + + + PQmakeEmptyPGresultPQmakeEmptyPGresult @@ -9462,6 +9533,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) is assumed that the file is stored in a directory that is secure, so no special permissions check is made. + + + An application can perform the same password file lookup that + connection establishment performs by calling + . + diff --git a/src/interfaces/libpq/exports.txt b/src/interfaces/libpq/exports.txt index 1e3d5bd5867..def61d63724 100644 --- a/src/interfaces/libpq/exports.txt +++ b/src/interfaces/libpq/exports.txt @@ -211,3 +211,4 @@ PQdefaultAuthDataHook 208 PQfullProtocolVersion 209 appendPQExpBufferVA 210 PQgetThreadLock 211 +PQpassfileLookup 212 diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c index a86564e192a..f660e518cb6 100644 --- a/src/interfaces/libpq/fe-connect.c +++ b/src/interfaces/libpq/fe-connect.c @@ -8005,7 +8005,8 @@ pwdfMatchesString(char *buf, const char *token) * explicit_bzero(ret, strlen(ret)); pqReleaseConnHosts() relies on this. * * On failure, *errmsg is set to an error to be returned. It is - * left NULL on success, or if no password could be found. + * left NULL on success, or if no password could be found. Callers + * that do not care about the distinction can pass errmsg as NULL. */ static char * passwordFromFile(const char *hostname, const char *port, @@ -8018,7 +8019,8 @@ passwordFromFile(const char *hostname, const char *port, #endif PQExpBufferData buf; - *errmsg = NULL; + if (errmsg) + *errmsg = NULL; if (dbname == NULL || dbname[0] == '\0') return NULL; @@ -8087,7 +8089,8 @@ passwordFromFile(const char *hostname, const char *port, /* Make sure there's a reasonable amount of room in the buffer */ if (!enlargePQExpBuffer(&buf, 128)) { - *errmsg = libpq_gettext("out of memory"); + if (errmsg) + *errmsg = libpq_gettext("out of memory"); break; } @@ -8145,7 +8148,8 @@ passwordFromFile(const char *hostname, const char *port, if (!ret) { - *errmsg = libpq_gettext("out of memory"); + if (errmsg) + *errmsg = libpq_gettext("out of memory"); return NULL; } @@ -8164,6 +8168,59 @@ passwordFromFile(const char *hostname, const char *port, } +/* + * PQpassfileLookup + * + * Look up a password in a password file, applying the same rules that + * connection establishment applies when no password has been specified. + * This lets applications that connect through an intermediary (for + * example, a local SSH tunnel) look up the password under the real + * server's host and port while connecting elsewhere. + * + * The first four arguments correspond to the fields of a password file + * line, and NULL or empty values are treated the same way as during + * connection establishment: hostname is matched as "localhost" (as is + * a hostname equal to the default Unix-socket directory), port + * defaults to DEF_PGPORT_STR, while dbname and username must be + * supplied. If passfile is NULL or empty, PGPASSFILE or the default + * password file location is used. + * + * Returns a malloc'd string the caller must free with PQfreemem(), or + * NULL if no matching password was found or the lookup could not be + * completed. The string holds nothing but the password (see + * passwordFromFile()), so a caller that wants it gone from memory can + * overwrite strlen() bytes before freeing it. + */ +char * +PQpassfileLookup(const char *hostname, const char *port, + const char *dbname, const char *username, + const char *passfile) +{ + char pgpassfile[MAXPGPATH]; + + if (passfile == NULL || passfile[0] == '\0') + { + const char *pgpassenv = getenv("PGPASSFILE"); + + if (pgpassenv != NULL && pgpassenv[0] != '\0') + passfile = pgpassenv; + else + { + char homedir[MAXPGPATH]; + + if (!pqGetHomeDirectory(homedir, sizeof(homedir))) + return NULL; + snprintf(pgpassfile, sizeof(pgpassfile), "%s/%s", + homedir, PGPASSFILE); + passfile = pgpassfile; + } + } + + return passwordFromFile(hostname, port, dbname, username, + passfile, NULL); +} + + /* * If the connection failed due to bad password, we should mention * if we got the password from the pgpassfile. diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h index f51fd620b0a..b63489a3bfe 100644 --- a/src/interfaces/libpq/libpq-fe.h +++ b/src/interfaces/libpq/libpq-fe.h @@ -69,6 +69,10 @@ extern "C" /* Indicates presence of the PQAUTHDATA_OAUTH_BEARER_TOKEN_V2 authdata hook */ #define LIBPQ_HAS_OAUTH_BEARER_TOKEN_V2 1 +/* Features added in PostgreSQL v20: */ +/* Indicates presence of PQpassfileLookup */ +#define LIBPQ_HAS_PASSFILE_LOOKUP 1 + /* * Option flags for PQcopyResult */ @@ -367,6 +371,11 @@ extern PQconninfoOption *PQconninfo(PGconn *conn); /* free the data structure returned by PQconndefaults() or PQconninfoParse() */ extern void PQconninfoFree(PQconninfoOption *connOptions); +/* look up a password in a password file */ +extern char *PQpassfileLookup(const char *hostname, const char *port, + const char *dbname, const char *username, + const char *passfile); + /* * close the current connection and reestablish a new one with the same * parameters diff --git a/src/interfaces/libpq/meson.build b/src/interfaces/libpq/meson.build index b0ae72167a1..b9f93ddb852 100644 --- a/src/interfaces/libpq/meson.build +++ b/src/interfaces/libpq/meson.build @@ -161,6 +161,7 @@ tests += { 't/004_load_balance_dns.pl', 't/005_negotiate_encryption.pl', 't/006_service.pl', + 't/007_passfile.pl', ], 'env': { 'with_ssl': ssl_library, diff --git a/src/interfaces/libpq/t/007_passfile.pl b/src/interfaces/libpq/t/007_passfile.pl new file mode 100644 index 00000000000..1a61c2c48c5 --- /dev/null +++ b/src/interfaces/libpq/t/007_passfile.pl @@ -0,0 +1,209 @@ +# Copyright (c) 2026, PostgreSQL Global Development Group +use strict; +use warnings FATAL => 'all'; +use File::Copy; +use PostgreSQL::Test::Utils; +use Test::More; + +# Test PQpassfileLookup(), via libpq_testclient --passfile. The lookup is +# purely client-side, so no server is involved. An argument of "-" is +# passed to the function as NULL, and an argument of "=" as an empty +# string (an empty argv element is not portable). + +my $td = PostgreSQL::Test::Utils::tempdir; +my $passfile = "$td/pgpass"; + +delete $ENV{PGPASSFILE}; + +# The compiled-in defaults that the lookup falls back to. +my ($defaults) = run_command([ 'libpq_testclient', '--passfile-defaults' ]); +$defaults =~ s/\r//g; +my ($defport, $socketdir) = split /\n/, $defaults; + +append_to_file($passfile, <<'EOF'); +# a comment line +server.example.com:5432:proddb:diego:secret1 +server.example.com:5433:*:diego:secret2 +localhost:*:mydb:me:localpw +special.example.com:5432:db\:colon:us\\er:pa\\ss\:word +endcolon.example.com:5432:enddb:enduser:end\: +server.example.com:5432:proddb:diego:shadowed +EOF +append_to_file($passfile, + "defport.example.com:$defport:defdb:defuser:defportpw\n"); +chmod 0600, $passfile or die "chmod: $!"; + +my ($out, $err); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5432', 'proddb', 'diego' + ]); +is($out, 'secret1', 'exact match returns the first matching password'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5433', 'anydb', 'diego' + ]); +is($out, 'secret2', 'wildcard field matches any value'); + +($out, $err) = run_command( + [ 'libpq_testclient', '--passfile', $passfile, '-', '-', 'mydb', 'me' ]); +is($out, 'localpw', 'NULL hostname and port match a localhost entry'); + +($out, $err) = run_command( + [ 'libpq_testclient', '--passfile', $passfile, '=', '-', 'mydb', 'me' ]); +is($out, 'localpw', 'empty hostname matches a localhost entry'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'defport.example.com', '-', 'defdb', 'defuser' + ]); +is($out, 'defportpw', 'NULL port matches an entry for the default port'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'defport.example.com', '=', 'defdb', 'defuser' + ]); +is($out, 'defportpw', 'empty port matches an entry for the default port'); + +SKIP: +{ + skip 'no default Unix-socket directory on this platform', 1 + unless defined $socketdir && $socketdir =~ m{^/}; + + ($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + $socketdir, '-', 'mydb', 'me' + ]); + is($out, 'localpw', + 'default socket directory matches a localhost entry'); +} + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'special.example.com', '5432', 'db:colon', 'us\\er' + ]); +is($out, 'pa\\ss:word', 'escaped characters are matched and de-escaped'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'endcolon.example.com', '5432', 'enddb', 'enduser' + ]); +is($out, 'end:', 'escaped colon at the end of the password is de-escaped'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5432', 'otherdb', 'diego' + ]); +is($err, 'no password found', 'no matching line returns no password'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', "$td/does_not_exist", + 'server.example.com', '5432', 'proddb', 'diego' + ]); +is($err, 'no password found', 'missing password file returns no password'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5432', '-', 'diego' + ]); +is($err, 'no password found', 'NULL dbname returns no password'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5432', '=', 'diego' + ]); +is($err, 'no password found', 'empty dbname returns no password'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5432', 'proddb', '-' + ]); +is($err, 'no password found', 'NULL username returns no password'); + +($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile, + 'server.example.com', '5432', 'proddb', '=' + ]); +is($err, 'no password found', 'empty username returns no password'); + +# A NULL or empty passfile falls back to the PGPASSFILE environment +# variable. +{ + local $ENV{PGPASSFILE} = $passfile; + + ($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', '-', + 'server.example.com', '5432', 'proddb', 'diego' + ]); + is($out, 'secret1', 'NULL passfile falls back to PGPASSFILE'); + + ($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', '=', + 'server.example.com', '5432', 'proddb', 'diego' + ]); + is($out, 'secret1', 'empty passfile falls back to PGPASSFILE'); +} + +SKIP: +{ + skip 'default password file location cannot be redirected on Windows', 1 + if $windows_os; + + # Without PGPASSFILE, the lookup falls back to ~/.pgpass. + my $homedir = PostgreSQL::Test::Utils::tempdir; + my $homepassfile = "$homedir/.pgpass"; + + append_to_file($homepassfile, + "home.example.com:5432:homedb:homeuser:homepw\n"); + chmod 0600, $homepassfile or die "chmod: $!"; + + local $ENV{HOME} = $homedir; + + ($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', '-', + 'home.example.com', '5432', 'homedb', 'homeuser' + ]); + is($out, 'homepw', 'NULL passfile falls back to ~/.pgpass'); +} + +SKIP: +{ + skip 'password file permissions are not checked on Windows', 2 + if $windows_os; + + my $passfile_insecure = "$td/pgpass_insecure"; + copy($passfile, $passfile_insecure) + or die "could not copy $passfile to $passfile_insecure: $!"; + chmod 0644, $passfile_insecure or die "chmod: $!"; + + ($out, $err) = run_command( + [ + 'libpq_testclient', '--passfile', $passfile_insecure, + 'server.example.com', '5432', 'proddb', 'diego' + ]); + like( + $err, + qr/has group or world access/, + 'insecure password file draws a warning'); + like($err, qr/no password found/, 'insecure password file is ignored'); +} + +done_testing(); diff --git a/src/interfaces/libpq/test/libpq_testclient.c b/src/interfaces/libpq/test/libpq_testclient.c index 20730709ee7..87309837489 100644 --- a/src/interfaces/libpq/test/libpq_testclient.c +++ b/src/interfaces/libpq/test/libpq_testclient.c @@ -23,6 +23,57 @@ print_ssl_library(void) printf("%s\n", lib); } +/* + * Print the compiled-in defaults that the passfile lookup falls back to, + * for use by the TAP test. + */ +static void +print_passfile_defaults(void) +{ + printf("%s\n%s\n", DEF_PGPORT_STR, DEFAULT_PGSOCKET_DIR); +} + +/* + * Look up a password with PQpassfileLookup(). The arguments are passfile, + * hostname, port, dbname and username; an argument of "-" is passed as + * NULL, and an argument of "=" as an empty string (an empty command-line + * argument cannot be relied on to survive process spawning everywhere). + */ +static int +test_passfile_lookup(int argc, char *argv[]) +{ + const char *args[5]; + char *password; + + if (argc != 7) + { + fprintf(stderr, "usage: libpq_testclient --passfile PASSFILE HOSTNAME PORT DBNAME USERNAME\n"); + return 1; + } + + for (int i = 0; i < 5; i++) + { + if (strcmp(argv[i + 2], "-") == 0) + args[i] = NULL; + else if (strcmp(argv[i + 2], "=") == 0) + args[i] = ""; + else + args[i] = argv[i + 2]; + } + + password = PQpassfileLookup(args[1], args[2], args[3], args[4], args[0]); + + if (!password) + { + fprintf(stderr, "no password found\n"); + return 1; + } + + printf("%s\n", password); + PQfreemem(password); + return 0; +} + int main(int argc, char *argv[]) { @@ -31,7 +82,14 @@ main(int argc, char *argv[]) print_ssl_library(); return 0; } + else if ((argc > 1) && !strcmp(argv[1], "--passfile")) + return test_passfile_lookup(argc, argv); + else if ((argc > 1) && !strcmp(argv[1], "--passfile-defaults")) + { + print_passfile_defaults(); + return 0; + } - printf("currently only --ssl is supported\n"); + printf("currently only --ssl, --passfile and --passfile-defaults are supported\n"); return 1; } -- 2.43.0