2007-12-06 05:12:10 +01:00
|
|
|
<!-- $PostgreSQL: pgsql/doc/src/sgml/sslinfo.sgml,v 1.3 2007/12/06 04:12:10 tgl Exp $ -->
|
2007-11-11 00:30:46 +01:00
|
|
|
|
|
|
|
<sect1 id="sslinfo">
|
|
|
|
<title>sslinfo</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<indexterm zone="sslinfo">
|
|
|
|
<primary>sslinfo</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
The <filename>sslinfo</> module provides information about the SSL
|
|
|
|
certificate that the current client provided when connecting to
|
|
|
|
<productname>PostgreSQL</>. The module is useless (most functions
|
|
|
|
will return NULL) if the current connection does not use SSL.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<para>
|
|
|
|
This extension won't build at all unless the installation was
|
|
|
|
configured with <literal>--with-openssl</>.
|
|
|
|
</para>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
|
|
|
<sect2>
|
2007-12-06 05:12:10 +01:00
|
|
|
<title>Functions Provided</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_is_used() returns boolean
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
Returns TRUE if current connection to server uses SSL, and FALSE
|
2007-11-11 00:30:46 +01:00
|
|
|
otherwise.
|
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_client_cert_present() returns boolean
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
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.)
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_client_serial() returns numeric
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
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 — the owner
|
|
|
|
ought to regularly change his keys, and get new certificates from the
|
|
|
|
issuer).
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
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.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_client_dn() returns text
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
Returns the full subject of the current client certificate, converting
|
2007-11-11 00:30:46 +01:00
|
|
|
character data into the current database encoding. It is assumed that
|
2007-12-06 05:12:10 +01:00
|
|
|
if you use non-ASCII characters in the certificate names, your
|
2007-11-11 00:30:46 +01:00
|
|
|
database is able to represent these characters, too. If your database
|
2007-12-06 05:12:10 +01:00
|
|
|
uses the SQL_ASCII encoding, non-ASCII characters in the name will be
|
2007-11-11 00:30:46 +01:00
|
|
|
represented as UTF-8 sequences.
|
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
The result looks like <literal>/CN=Somebody /C=Some country/O=Some organization</>.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_issuer_dn() returns text
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
Returns the full issuer name of the current client certificate, converting
|
|
|
|
character data into the current database encoding. Encoding conversions
|
|
|
|
are handled the same as for <function>ssl_client_dn</>.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
The combination of the return value of this function with the
|
|
|
|
certificate serial number uniquely identifies the certificate.
|
|
|
|
</para>
|
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
This function is really useful only if you have more than one trusted CA
|
|
|
|
certificate in your server's <filename>root.crt</> file, or if this CA
|
|
|
|
has issued some intermediate certificate authority certificates.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_client_dn_field(fieldname text) returns text
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
|
|
|
This function returns the value of the specified field in the
|
2007-12-06 05:12:10 +01:00
|
|
|
certificate subject, or NULL if the field is not present.
|
|
|
|
Field names are string constants that are
|
|
|
|
converted into ASN1 object identifiers using the OpenSSL object
|
2007-11-11 00:30:46 +01:00
|
|
|
database. The following values are acceptable:
|
|
|
|
</para>
|
|
|
|
<programlisting>
|
|
|
|
commonName (alias CN)
|
|
|
|
surname (alias SN)
|
|
|
|
name
|
|
|
|
givenName (alias GN)
|
2007-12-06 05:12:10 +01:00
|
|
|
countryName (alias C)
|
2007-11-11 00:30:46 +01:00
|
|
|
localityName (alias L)
|
|
|
|
stateOrProvinceName (alias ST)
|
|
|
|
organizationName (alias O)
|
|
|
|
organizationUnitName (alias OU)
|
|
|
|
title
|
|
|
|
description
|
|
|
|
initials
|
|
|
|
postalCode
|
|
|
|
streetAddress
|
|
|
|
generationQualifier
|
|
|
|
description
|
|
|
|
dnQualifier
|
|
|
|
x500UniqueIdentifier
|
2007-12-06 05:12:10 +01:00
|
|
|
pseudonym
|
2007-11-11 00:30:46 +01:00
|
|
|
role
|
|
|
|
emailAddress
|
|
|
|
</programlisting>
|
2007-11-11 15:23:18 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
All of these fields are optional, except <structfield>commonName</>.
|
|
|
|
It depends
|
|
|
|
entirely on your CA's policy which of them would be included and which
|
|
|
|
wouldn't. The meaning of these fields, however, is strictly defined by
|
2007-11-11 00:30:46 +01:00
|
|
|
the X.500 and X.509 standards, so you cannot just assign arbitrary
|
|
|
|
meaning to them.
|
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><function>
|
|
|
|
ssl_issuer_field(fieldname text) returns text
|
|
|
|
</function></term>
|
|
|
|
<listitem>
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
Same as <function>ssl_client_dn_field</>, but for the certificate issuer
|
2007-11-11 00:30:46 +01:00
|
|
|
rather than the certificate subject.
|
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Author</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
|
|
|
Victor Wagner <email>vitus@cryptocom.ru</email>, Cryptocom LTD
|
2007-12-06 05:12:10 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
E-Mail of Cryptocom OpenSSL development group:
|
2007-11-11 00:30:46 +01:00
|
|
|
<email>openssl@cryptocom.ru</email>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
</sect1>
|