<!-- doc/src/sgml/sslinfo.sgml -->

<sect1 id="sslinfo" xreflabel="sslinfo">
 <title>sslinfo &mdash; obtain client SSL information</title>

 <indexterm zone="sslinfo">
  <primary>sslinfo</primary>
 </indexterm>

 <para>
  The <filename>sslinfo</filename> module provides information about the SSL
  certificate that the current client provided when connecting to
  <productname>PostgreSQL</productname>.  The module is useless (most functions
  will return NULL) if the current connection does not use SSL.
 </para>

 <para>
  Some of the information available through this module can also be obtained
  using the built-in system view <link linkend="monitoring-pg-stat-ssl-view">
  <structname>pg_stat_ssl</structname></link>.
 </para>

 <para>
  This extension won't build at all unless the installation was
  configured with <literal>--with-ssl=openssl</literal>.
 </para>

 <sect2 id="sslinfo-functions">
  <title>Functions Provided</title>

  <variablelist>
   <varlistentry>
    <term>
     <function>ssl_is_used() returns boolean</function>
     <indexterm>
      <primary>ssl_is_used</primary>
     </indexterm>
    </term>
    <listitem>
    <para>
     Returns true if current connection to server uses SSL, and false
     otherwise.
    </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>ssl_version() returns text</function>
     <indexterm>
      <primary>ssl_version</primary>
     </indexterm>
    </term>
    <listitem>
    <para>
     Returns the name of the protocol used for the SSL connection (e.g., TLSv1.0,
     TLSv1.1, TLSv1.2 or TLSv1.3).
    </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>ssl_cipher() returns text</function>
     <indexterm>
      <primary>ssl_cipher</primary>
     </indexterm>
    </term>
    <listitem>
    <para>
     Returns the name of the cipher used for the SSL connection
     (e.g., DHE-RSA-AES256-SHA).
    </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>ssl_client_cert_present() returns boolean</function>
     <indexterm>
      <primary>ssl_client_cert_present</primary>
     </indexterm>
    </term>
    <listitem>
    <para>
     Returns true if current client has presented a valid SSL client
     certificate to the server, and false otherwise.  (The server
     might or might not be configured to require a client certificate.)
    </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>ssl_client_serial() returns numeric</function>
     <indexterm>
      <primary>ssl_client_serial</primary>
     </indexterm>
    </term>
    <listitem>
    <para>
     Returns serial number of current client certificate.  The combination of
     certificate serial number and certificate issuer is guaranteed to
     uniquely identify a certificate (but not its owner &mdash; the owner
     ought to regularly change their keys, and get new certificates from the
     issuer).
    </para>

    <para>
     So, if you run your own CA and allow only certificates from this CA to
     be accepted by the server, the serial number is the most reliable (albeit
     not very mnemonic) means to identify a user.
    </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>ssl_client_dn() returns text</function>
     <indexterm>
      <primary>ssl_client_dn</primary>
     </indexterm>
    </term>
    <listitem>
    <para>
     Returns the full subject of the current client certificate, converting
     character data into the current database encoding.  It is assumed that
     if you use non-ASCII characters in the certificate names, your
     database is able to represent these characters,