Rename PQsetSSLKeyPassHook and friends

adunstan · adunstan · commit 36d1087611bf · 2020-05-16T16:20:43.000-04:00
4dc6355 provided a way for libraries and clients to modify how libpq handles client certificate passphrases, by installing a hook. However, these routines are quite specific to how OpenSSL works, so it's misleading and not future-proof to have these names not refer to OpenSSL. Change all the names to add "_OpenSSL" after "Hook", and fix the docs accordingly. Author: Daniel Gustafsson Discussion: https://postgr.es/m/981DE552-E399-45C2-9F60-3F0E3770CC61@yesql.se
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
@@ -777,30 +777,30 @@ PGPing PQping(const char *conninfo);
     </varlistentry>
 
     <varlistentry id="libpq-pqsetsslkeypasshook">
-     <term><function>PQsetSSLKeyPassHook</function><indexterm><primary>PQsetSSLKeyPassHook</primary></indexterm></term>
+     <term><function>PQsetSSLKeyPassHook_OpenSSL</function><indexterm><primary>PQsetSSLKeyPassHook_OpenSSL</primary></indexterm></term>
      <listitem>
       <para>
-       <function>PQsetSSLKeyPassHook</function> lets an application override
+       <function>PQsetSSLKeyPassHook_OpenSSL</function> lets an application override
        <literal>libpq</literal>'s <link linkend="libpq-ssl-clientcert">default
        handling of encrypted client certificate key files</link> using
        <xref linkend="libpq-connect-sslpassword"/> or interactive prompting.
 
 <synopsis>
-void PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook);
+void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
 </synopsis>
 
        The application passes a pointer to a callback function with signature:
 <programlisting>
 int callback_fn(char *buf, int size, PGconn *conn);
 </programlisting>
        which <literal>libpq</literal> will then call <emphasis>instead of</emphasis>
-       its default <function>PQdefaultSSLKeyPassHook</function> handler. The callback
+       its default <function>PQdefaultSSLKeyPassHook_OpenSSL</function> handler. The callback
        should determine the password for the key and copy it to result-buffer
        <literal>buf</literal> of size <literal>size</literal>. The string in <literal>
        buf</literal> must be null-terminated. The callback must return the length of
        the password stored in <literal>buf</literal> excluding the null terminator.
        On failure, the callback should set <literal>buf[0] = '\0'</literal> and return 0.
-       See <function>PQdefaultSSLKeyPassHook</function> in <literal>libpq</literal>'s
+       See <function>PQdefaultSSLKeyPassHook_OpenSSL</function> in <literal>libpq</literal>'s
        source code for an example.
       </para>
        
@@ -814,7 +814,7 @@ int callback_fn(char *buf, int size, PGconn *conn);
 
       <para>
        The app callback may choose to delegate unhandled cases to
-       <function>PQdefaultSSLKeyPassHook</function>,
+       <function>PQdefaultSSLKeyPassHook_OpenSSL</function>,
        or call it first and try something else if it returns 0, or completely override it.
       </para>
 
@@ -835,7 +835,7 @@ int callback_fn(char *buf, int size, PGconn *conn);
        if none has been set.
 
 <synopsis>
-PQsslKeyPassHook_type PQgetSSLKeyPassHook(void);
+PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook(void);
 </synopsis>
       </para>
 
diff --git a/src/interfaces/libpq/fe-secure-openssl.c b/src/interfaces/libpq/fe-secure-openssl.c
@@ -95,7 +95,7 @@ static long win32_ssl_create_mutex = 0;
 #endif
 #endif							/* ENABLE_THREAD_SAFETY */
 
-static PQsslKeyPassHook_type PQsslKeyPassHook = NULL;
+static PQsslKeyPassHook_OpenSSL_type PQsslKeyPassHook = NULL;
 static int	ssl_protocol_version_to_openssl(const char *protocol);
 
 /* ------------------------------------------------------------ */
@@ -1669,7 +1669,7 @@ my_SSL_set_fd(PGconn *conn, int fd)
  * prevent openssl from ever prompting on stdin.
  */
 int
-PQdefaultSSLKeyPassHook(char *buf, int size, PGconn *conn)
+PQdefaultSSLKeyPassHook_OpenSSL(char *buf, int size, PGconn *conn)
 {
 	if (conn->sslpassword)
 	{
@@ -1686,14 +1686,14 @@ PQdefaultSSLKeyPassHook(char *buf, int size, PGconn *conn)
 	}
 }
 
-PQsslKeyPassHook_type
+PQsslKeyPassHook_OpenSSL_type
 PQgetSSLKeyPassHook(void)
 {
 	return PQsslKeyPassHook;
 }
 
 void
-PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook)
+PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook)
 {
 	PQsslKeyPassHook = hook;
 }
@@ -1711,7 +1711,7 @@ PQssl_passwd_cb(char *buf, int size, int rwflag, void *userdata)
 	if (PQsslKeyPassHook)
 		return PQsslKeyPassHook(buf, size, conn);
 	else
-		return PQdefaultSSLKeyPassHook(buf, size, conn);
+		return PQdefaultSSLKeyPassHook_OpenSSL(buf, size, conn);
 }
 
 /*
diff --git a/src/interfaces/libpq/fe-secure.c b/src/interfaces/libpq/fe-secure.c
@@ -431,20 +431,20 @@ PQsslAttributeNames(PGconn *conn)
 	return result;
 }
 
-PQsslKeyPassHook_type
-PQgetSSLKeyPassHook(void)
+PQsslKeyPassHook_OpenSSL_type
+PQgetSSLKeyPassHook_OpenSSL(void)
 {
 	return NULL;
 }
 
 void
-PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook)
+PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook)
 {
 	return;
 }
 
 int
-PQdefaultSSLKeyPassHook(char *buf, int size, PGconn *conn)
+PQdefaultSSLKeyPassHook_OpenSSL(char *buf, int size, PGconn *conn)
 {
 	return 0;
 }
diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
@@ -617,13 +617,13 @@ extern int	pg_char_to_encoding(const char *name);
 extern const char *pg_encoding_to_char(int encoding);
 extern int	pg_valid_server_encoding_id(int encoding);
 
-/* == in fe-secure-openssl.c === */
+/* === in fe-secure-openssl.c === */
 
 /* Support for overriding sslpassword handling with a callback. */
-typedef int (*PQsslKeyPassHook_type) (char *buf, int size, PGconn *conn);
-extern PQsslKeyPassHook_type PQgetSSLKeyPassHook(void);
-extern void PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook);
-extern int	PQdefaultSSLKeyPassHook(char *buf, int size, PGconn *conn);
+typedef int (*PQsslKeyPassHook_OpenSSL_type) (char *buf, int size, PGconn *conn);
+extern PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook(void);
+extern void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
+extern int	PQdefaultSSLKeyPassHook_OpenSSL(char *buf, int size, PGconn *conn);
 
 #ifdef __cplusplus
 }

Original file line number	Diff line number	Diff line change
`@@ -95,7 +95,7 @@ static long win32_ssl_create_mutex = 0;`
`95`	`95`	`#endif`
`96`	`96`	`#endif /* ENABLE_THREAD_SAFETY */`
`97`	`97`
`98`		`-static PQsslKeyPassHook_type PQsslKeyPassHook = NULL;`
	`98`	`+static PQsslKeyPassHook_OpenSSL_type PQsslKeyPassHook = NULL;`
`99`	`99`	`static int ssl_protocol_version_to_openssl(const char *protocol);`
`100`	`100`
`101`	`101`	`/* ------------------------------------------------------------ */`
`@@ -1669,7 +1669,7 @@ my_SSL_set_fd(PGconn *conn, int fd)`
`1669`	`1669`	`* prevent openssl from ever prompting on stdin.`
`1670`	`1670`	`*/`
`1671`	`1671`	`int`
`1672`		`-PQdefaultSSLKeyPassHook(char buf, int size, PGconn conn)`
	`1672`	`+PQdefaultSSLKeyPassHook_OpenSSL(char buf, int size, PGconn conn)`
`1673`	`1673`	`{`
`1674`	`1674`	`if (conn->sslpassword)`
`1675`	`1675`	`{`
`@@ -1686,14 +1686,14 @@ PQdefaultSSLKeyPassHook(char buf, int size, PGconn conn)`
`1686`	`1686`	`}`
`1687`	`1687`	`}`
`1688`	`1688`
`1689`		`-PQsslKeyPassHook_type`
	`1689`	`+PQsslKeyPassHook_OpenSSL_type`
`1690`	`1690`	`PQgetSSLKeyPassHook(void)`
`1691`	`1691`	`{`
`1692`	`1692`	`return PQsslKeyPassHook;`
`1693`	`1693`	`}`
`1694`	`1694`
`1695`	`1695`	`void`
`1696`		`-PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook)`
	`1696`	`+PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook)`
`1697`	`1697`	`{`
`1698`	`1698`	`PQsslKeyPassHook = hook;`
`1699`	`1699`	`}`
`@@ -1711,7 +1711,7 @@ PQssl_passwd_cb(char buf, int size, int rwflag, void userdata)`
`1711`	`1711`	`if (PQsslKeyPassHook)`
`1712`	`1712`	`return PQsslKeyPassHook(buf, size, conn);`
`1713`	`1713`	`else`
`1714`		`- return PQdefaultSSLKeyPassHook(buf, size, conn);`
	`1714`	`+ return PQdefaultSSLKeyPassHook_OpenSSL(buf, size, conn);`
`1715`	`1715`	`}`
`1716`	`1716`
`1717`	`1717`	`/*`
Original file line number	Diff line number	Diff line change
`@@ -431,20 +431,20 @@ PQsslAttributeNames(PGconn *conn)`
`431`	`431`	`return result;`
`432`	`432`	`}`
`433`	`433`
`434`		`-PQsslKeyPassHook_type`
`435`		`-PQgetSSLKeyPassHook(void)`
	`434`	`+PQsslKeyPassHook_OpenSSL_type`
	`435`	`+PQgetSSLKeyPassHook_OpenSSL(void)`
`436`	`436`	`{`
`437`	`437`	`return NULL;`
`438`	`438`	`}`
`439`	`439`
`440`	`440`	`void`
`441`		`-PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook)`
	`441`	`+PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook)`
`442`	`442`	`{`
`443`	`443`	`return;`
`444`	`444`	`}`
`445`	`445`
`446`	`446`	`int`
`447`		`-PQdefaultSSLKeyPassHook(char buf, int size, PGconn conn)`
	`447`	`+PQdefaultSSLKeyPassHook_OpenSSL(char buf, int size, PGconn conn)`
`448`	`448`	`{`
`449`	`449`	`return 0;`
`450`	`450`	`}`