granicus.if.org Git - postgresql/blob - doc/src/sgml/sslinfo.sgml

   1 <!-- doc/src/sgml/sslinfo.sgml -->
   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_version() returns text
  41     </function></term>
  42     <listitem>
  43     <para>
  44      Returns the name of the protocol used for the SSL connection (e.g. SSLv2,
  45      SSLv3, or TLSv1).
  46     </para>
  47     </listitem>
  48    </varlistentry>
  49
  50    <varlistentry>
  51     <term><function>
  52 ssl_cipher() returns text
  53     </function></term>
  54     <listitem>
  55     <para>
  56      Returns the name of the cipher used for the SSL connection
  57      (e.g. DHE-RSA-AES256-SHA).
  58     </para>
  59     </listitem>
  60    </varlistentry>
  61
  62    <varlistentry>
  63     <term><function>
  64 ssl_client_cert_present() returns boolean
  65     </function></term>
  66     <listitem>
  67     <para>
  68      Returns TRUE if current client has presented a valid SSL client
  69      certificate to the server, and FALSE otherwise.  (The server
  70      might or might not be configured to require a client certificate.)
  71     </para>
  72     </listitem>
  73    </varlistentry>
  74
  75    <varlistentry>
  76     <term><function>
  77 ssl_client_serial() returns numeric
  78     </function></term>
  79     <listitem>
  80     <para>
  81      Returns serial number of current client certificate.  The combination of
  82      certificate serial number and certificate issuer is guaranteed to
  83      uniquely identify a certificate (but not its owner &mdash; the owner
  84      ought to regularly change his keys, and get new certificates from the
  85      issuer).
  86     </para>
  87
  88     <para>
  89      So, if you run your own CA and allow only certificates from this CA to
  90      be accepted by the server, the serial number is the most reliable (albeit
  91      not very mnemonic) means to identify a user.
  92     </para>
  93     </listitem>
  94    </varlistentry>
  95
  96    <varlistentry>
  97     <term><function>
  98 ssl_client_dn() returns text
  99     </function></term>
 100     <listitem>
 101     <para>
 102      Returns the full subject of the current client certificate, converting
 103      character data into the current database encoding.  It is assumed that
 104      if you use non-ASCII characters in the certificate names, your
 105      database is able to represent these characters, too.  If your database
 106      uses the SQL_ASCII encoding, non-ASCII characters in the name will be
 107      represented as UTF-8 sequences.
 108     </para>
 109
 110     <para>
 111      The result looks like <literal>/CN=Somebody /C=Some country/O=Some organization</>.
 112     </para>
 113     </listitem>
 114    </varlistentry>
 115
 116    <varlistentry>
 117     <term><function>
 118 ssl_issuer_dn() returns text
 119     </function></term>
 120     <listitem>
 121     <para>
 122      Returns the full issuer name of the current client certificate, converting
 123      character data into the current database encoding.  Encoding conversions
 124      are handled the same as for <function>ssl_client_dn</>.
 125     </para>
 126     <para>
 127      The combination of the return value of this function with the
 128      certificate serial number uniquely identifies the certificate.
 129     </para>
 130     <para>
 131      This function is really useful only if you have more than one trusted CA
 132      certificate in your server's <filename>root.crt</> file, or if this CA
 133      has issued some intermediate certificate authority certificates.
 134     </para>
 135     </listitem>
 136    </varlistentry>
 137
 138    <varlistentry>
 139     <term><function>
 140 ssl_client_dn_field(fieldname text) returns text
 141     </function></term>
 142     <listitem>
 143     <para>
 144      This function returns the value of the specified field in the
 145      certificate subject, or NULL if the field is not present.
 146      Field names are string constants that are
 147      converted into ASN1 object identifiers using the OpenSSL object
 148      database.  The following values are acceptable:
 149     </para>
 150 <literallayout class="monospaced">
 151 commonName (alias CN)
 152 surname (alias SN)
 153 name
 154 givenName (alias GN)
 155 countryName (alias C)
 156 localityName (alias L)
 157 stateOrProvinceName (alias ST)
 158 organizationName (alias O)
 159 organizationUnitName (alias OU)
 160 title
 161 description
 162 initials
 163 postalCode
 164 streetAddress
 165 generationQualifier
 166 description
 167 dnQualifier
 168 x500UniqueIdentifier
 169 pseudonym
 170 role
 171 emailAddress
 172 </literallayout>
 173     <para>
 174      All of these fields are optional, except <structfield>commonName</>.
 175      It depends
 176      entirely on your CA's policy which of them would be included and which
 177      wouldn't.  The meaning of these fields, however, is strictly defined by
 178      the X.500 and X.509 standards, so you cannot just assign arbitrary
 179      meaning to them.
 180     </para>
 181     </listitem>
 182    </varlistentry>
 183
 184    <varlistentry>
 185     <term><function>
 186 ssl_issuer_field(fieldname text) returns text
 187     </function></term>
 188     <listitem>
 189     <para>
 190      Same as <function>ssl_client_dn_field</>, but for the certificate issuer
 191      rather than the certificate subject.
 192     </para>
 193     </listitem>
 194    </varlistentry>
 195   </variablelist>
 196  </sect2>
 197
 198  <sect2>
 199   <title>Author</title>
 200
 201   <para>
 202    Victor Wagner <email>vitus@cryptocom.ru</email>, Cryptocom LTD
 203   </para>
 204
 205   <para>
 206    E-Mail of Cryptocom OpenSSL development group:
 207    <email>openssl@cryptocom.ru</email>
 208   </para>
 209  </sect2>
 210
 211 </sect1>