Debian Codegraph @

src/interfaces/libpq-oauth/README

raw
1 libpq-oauth is an optional module implementing the Device Authorization flow for
2 OAuth clients (RFC 8628). It is maintained as its own shared library in order to
3 isolate its dependency on libcurl. (End users who don't want the Curl dependency
4 can simply choose not to install this module.)
5
6 If a connection string allows the use of OAuth, and the server asks for it, and
7 a libpq client has not installed its own custom OAuth flow, libpq will attempt
8 to delay-load this module using dlopen() and the following ABI. Failure to load
9 results in a failed connection.
10
11 = Load-Time ABI =
12
13 This module ABI is an internal implementation detail, so it's subject to change
14 across major releases; the name of the module (libpq-oauth-MAJOR) reflects this.
15 The module exports the following symbols:
16
17 - PostgresPollingStatusType pg_fe_run_oauth_flow(PGconn *conn);
18 - void pg_fe_cleanup_oauth_flow(PGconn *conn);
19
20 pg_fe_run_oauth_flow and pg_fe_cleanup_oauth_flow are implementations of
21 conn->async_auth and conn->cleanup_async_auth, respectively.
22
23 At the moment, pg_fe_run_oauth_flow() relies on libpq's pg_g_threadlock and
24 libpq_gettext(), which must be injected by libpq using this initialization
25 function before the flow is run:
26
27 - void libpq_oauth_init(pgthreadlock_t threadlock,
28 libpq_gettext_func gettext_impl,
29 conn_errorMessage_func errmsg_impl,
30 conn_oauth_client_id_func clientid_impl,
31 conn_oauth_client_secret_func clientsecret_impl,
32 conn_oauth_discovery_uri_func discoveryuri_impl,
33 conn_oauth_issuer_id_func issuerid_impl,
34 conn_oauth_scope_func scope_impl,
35 conn_sasl_state_func saslstate_impl,
36 set_conn_altsock_func setaltsock_impl,
37 set_conn_oauth_token_func settoken_impl);
38
39 It also relies on access to several members of the PGconn struct. Not only can
40 these change positions across minor versions, but the offsets aren't necessarily
41 stable within a single minor release (conn->errorMessage, for instance, can
42 change offsets depending on configure-time options). Therefore the necessary
43 accessors (named conn_*) and mutators (set_conn_*) are injected here. With this
44 approach, we can safely search the standard dlopen() paths (e.g. RPATH,
45 LD_LIBRARY_PATH, the SO cache) for an implementation module to use, even if that
46 module wasn't compiled at the same time as libpq -- which becomes especially
47 important during "live upgrade" situations where a running libpq application has
48 the libpq-oauth module updated out from under it before it's first loaded from
49 disk.
50
51 = Static Build =
52
53 The static library libpq.a does not perform any dynamic loading. If the builtin
54 flow is enabled, the application is expected to link against libpq-oauth.a
55 directly to provide the necessary symbols. (libpq.a and libpq-oauth.a must be
56 part of the same build. Unlike the dynamic module, there are no translation
57 shims provided.)