doc/src/sgml/sslinfo.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="sslinfo">
   4  <title>sslinfo</title>
   5
   6  <indexterm zone="sslinfo">
   7   <primary>sslinfo</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>sslinfo</> module provides information about the SSL
  12   certificate that the current client provided when connecting to
  13   <productname>PostgreSQL</>.  The module is useless (most functions
  14   will return NULL) if the current connection does not use SSL.
  15  </para>
  16
  17  <para>
  18   This extension won't build at all unless the installation was
  19   configured with <literal>--with-openssl</>.
  20  </para>
  21
  22  <sect2>
  23   <title>Functions Provided</title>
  24
  25   <variablelist>
  26    <varlistentry>
  27     <term><function>
  28 ssl_is_used() returns boolean
  29     </function></term>
  30     <listitem>
  31     <para>
  32      Returns TRUE if current connection to server uses SSL, and FALSE
  33      otherwise.
  34     </para>
  35     </listitem>
  36    </varlistentry>
  37
  38    <varlistentry>
  39     <term><function>
  40 ssl_client_cert_present() returns boolean
  41     </function></term>
  42     <listitem>
  43     <para>
  44      Returns TRUE if current client has presented a valid SSL client
  45      certificate to the server, and FALSE otherwise.  (The server
  46      might or might not be configured to require a client certificate.)
  47     </para>
  48     </listitem>
  49    </varlistentry>
  50
  51    <varlistentry>
  52     <term><function>
  53 ssl_client_serial() returns numeric
  54     </function></term>
  55     <listitem>
  56     <para>
  57      Returns serial number of current client certificate.  The combination of
  58      certificate serial number and certificate issuer is guaranteed to
  59      uniquely identify a certificate (but not its owner &mdash; the owner
  60      ought to regularly change his keys, and get new certificates from the
  61      issuer).
  62     </para>
  63
  64     <para>
  65      So, if you run your own CA and allow only certificates from this CA to
  66      be accepted by the server, the serial number is the most reliable (albeit
  67      not very mnemonic) means to identify a user.
  68     </para>
  69     </listitem>
  70    </varlistentry>
  71
  72    <varlistentry>
  73     <term><function>
  74 ssl_client_dn() returns text
  75     </function></term>
  76     <listitem>
  77     <para>
  78      Returns the full subject of the current client certificate, converting
  79      character data into the current database encoding.  It is assumed that
  80      if you use non-ASCII characters in the certificate names, your
  81      database is able to represent these characters, too.  If your database
  82      uses the SQL_ASCII encoding, non-ASCII characters in the name will be
  83      represented as UTF-8 sequences.
  84     </para>
  85
  86     <para>
  87      The result looks like <literal>/CN=Somebody /C=Some country/O=Some organization</>.
  88     </para>
  89     </listitem>
  90    </varlistentry>
  91
  92    <varlistentry>
  93     <term><function>
  94 ssl_issuer_dn() returns text
  95     </function></term>
  96     <listitem>
  97     <para>
  98      Returns the full issuer name of the current client certificate, converting
  99      character data into the current database encoding.  Encoding conversions
 100      are handled the same as for <function>ssl_client_dn</>.
 101     </para>
 102     <para>
 103      The combination of the return value of this function with the
 104      certificate serial number uniquely identifies the certificate.
 105     </para>
 106     <para>
 107      This function is really useful only if you have more than one trusted CA
 108      certificate in your server's <filename>root.crt</> file, or if this CA
 109      has issued some intermediate certificate authority certificates.
 110     </para>
 111     </listitem>
 112    </varlistentry>
 113
 114    <varlistentry>
 115     <term><function>
 116 ssl_client_dn_field(fieldname text) returns text
 117     </function></term>
 118     <listitem>
 119     <para>
 120      This function returns the value of the specified field in the
 121      certificate subject, or NULL if the field is not present.
 122      Field names are string constants that are
 123      converted into ASN1 object identifiers using the OpenSSL object
 124      database.  The following values are acceptable:
 125     </para>
 126     <programlisting>
 127 commonName (alias CN)
 128 surname (alias SN)
 129 name
 130 givenName (alias GN)
 131 countryName (alias C)
 132 localityName (alias L)
 133 stateOrProvinceName (alias ST)
 134 organizationName (alias O)
 135 organizationUnitName (alias OU)
 136 title
 137 description
 138 initials
 139 postalCode
 140 streetAddress
 141 generationQualifier
 142 description
 143 dnQualifier
 144 x500UniqueIdentifier
 145 pseudonym
 146 role
 147 emailAddress
 148     </programlisting>
 149     <para>
 150      All of these fields are optional, except <structfield>commonName</>.
 151      It depends
 152      entirely on your CA's policy which of them would be included and which
 153      wouldn't.  The meaning of these fields, however, is strictly defined by
 154      the X.500 and X.509 standards, so you cannot just assign arbitrary
 155      meaning to them.
 156     </para>
 157     </listitem>
 158    </varlistentry>
 159
 160    <varlistentry>
 161     <term><function>
 162 ssl_issuer_field(fieldname text) returns text
 163     </function></term>
 164     <listitem>
 165     <para>
 166      Same as <function>ssl_client_dn_field</>, but for the certificate issuer
 167      rather than the certificate subject.
 168     </para>
 169     </listitem>
 170    </varlistentry>
 171   </variablelist>
 172  </sect2>
 173
 174  <sect2>
 175   <title>Author</title>
 176
 177   <para>
 178    Victor Wagner <email>vitus@cryptocom.ru</email>, Cryptocom LTD
 179   </para>
 180
 181   <para>
 182    E-Mail of Cryptocom OpenSSL development group:
 183    <email>openssl@cryptocom.ru</email>
 184   </para>
 185  </sect2>
 186
 187 </sect1>