<application>libpq</application>'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_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 <application>libpq</application> will then call
       <emphasis>instead of</emphasis> its default
       <function>PQdefaultSSLKeyPassHook_OpenSSL</function> handler. The
       callback should determine the password for the key and copy it to
       result-buffer <parameter>buf</parameter> of size
       <parameter>size</parameter>. The string in <parameter>buf</parameter>
       must be null-terminated. The callback must return the length of the
       password stored in <parameter>buf</parameter> excluding the null
       terminator. On failure, the callback should set
       <literal>buf[0] = '\0'</literal> and return 0. See
       <function>PQdefaultSSLKeyPassHook_OpenSSL</function> in
       <application>libpq</application>'s source code for an example.
      </para>

      <para>
       If the user specified an explicit key location,
       its path will be in <literal>conn->sslkey</literal> 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 <productname>OpenSSL</productname> password
       callback or define their own handling.
      </para>

      <para>
       The app callback may choose to delegate unhandled cases to
       <function>PQdefaultSSLKeyPassHook_OpenSSL</function>,
       or call it first and try something else if it returns 0, or completely override it.
      </para>

      <para>
       The callback <emphasis>must not</emphasis> escape normal flow control with exceptions,
       <function>longjmp(...)</function>, etc. It must return normally.
      </para>

     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqgetsslkeypasshook-openssl">
     <term><function>PQgetSSLKeyPassHook_OpenSSL</function><indexterm><primary>PQgetSSLKeyPassHook_OpenSSL</primary></indexterm></term>
     <listitem>
      <para>
       <function>PQgetSSLKeyPassHook_OpenSSL</function> returns the current
       client certificate key password hook, or <literal>NULL</literal>
       if none has been set.

<synopsis>
PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
</synopsis>
      </para>

     </listitem>
    </varlistentry>

   </variablelist>
  </para>

  <sect2 id="libpq-connstring">
   <title>Connection Strings</title>

   <indexterm zone="libpq-connstring">
    <primary><literal>conninfo</literal></primary>
   </indexterm>

   <indexterm zone="libpq-connstring">
    <primary><literal>URI</literal></primary>
   </indexterm>

   <para>
    Several <application>libpq</application> functions parse a user-specified string to obtain
    connection parameters.  There are two accepted formats for these strings:
    plain keyword/value strings
    and URIs.  URIs generally follow
    <ulink url="https://datatracker.ietf.org/doc/html/rfc3986">RFC
    3986</ulink>, except that multi-host connection strings are allowed
    as further described below.
   </para>

   <sect3 id="libpq-connstring-keyword-value">
    <title>Keyword/Value Connection Strings</title>

   <para>
    In the keyword/value format, each parameter setting is in the form
    <replaceable>keyword</replaceable> <literal>=</literal>
    <replaceable>value</replaceable>, with space(s) between settings.
    Spaces around a setting's equal sign are
    optional. To write an empty value, or a value containing spaces, surround it
    with single quotes, for example <literal>keyword = 'a value'</literal>.