mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-15 21:50:22 +02:00
2eb4a831e5
The lower case spellings are C and C++ standard and are used in most parts of the PostgreSQL sources. The upper case spellings are only used in some files/modules. So standardize on the standard spellings. The APIs for ICU, Perl, and Windows define their own TRUE and FALSE, so those are left as is when using those APIs. In code comments, we use the lower-case spelling for the C concepts and keep the upper-case spelling for the SQL concepts. Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
258 lines
6.9 KiB
Plaintext
258 lines
6.9 KiB
Plaintext
<!-- doc/src/sgml/sslinfo.sgml -->
|
|
|
|
<sect1 id="sslinfo" xreflabel="sslinfo">
|
|
<title>sslinfo</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>
|
|
This extension won't build at all unless the installation was
|
|
configured with <literal>--with-openssl</literal>.
|
|
</para>
|
|
|
|
<sect2>
|
|
<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, or TLSv1.2).
|
|
</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 — 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, too. If your database
|
|
uses the SQL_ASCII encoding, non-ASCII characters in the name will be
|
|
represented as UTF-8 sequences.
|
|
</para>
|
|
|
|
<para>
|
|
The result looks like <literal>/CN=Somebody /C=Some country/O=Some organization</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<function>ssl_issuer_dn() returns text</function>
|
|
<indexterm>
|
|
<primary>ssl_issuer_dn</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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</function>.
|
|
</para>
|
|
<para>
|
|
The combination of the return value of this function with the
|
|
certificate serial number uniquely identifies the certificate.
|
|
</para>
|
|
<para>
|
|
This function is really useful only if you have more than one trusted CA
|
|
certificate in your server's certificate authority file, or if this CA
|
|
has issued some intermediate certificate authority certificates.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<function>ssl_client_dn_field(fieldname text) returns text</function>
|
|
<indexterm>
|
|
<primary>ssl_client_dn_field</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This function returns the value of the specified field in the
|
|
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
|
|
database. The following values are acceptable:
|
|
</para>
|
|
<literallayout class="monospaced">
|
|
commonName (alias CN)
|
|
surname (alias SN)
|
|
name
|
|
givenName (alias GN)
|
|
countryName (alias C)
|
|
localityName (alias L)
|
|
stateOrProvinceName (alias ST)
|
|
organizationName (alias O)
|
|
organizationUnitName (alias OU)
|
|
title
|
|
description
|
|
initials
|
|
postalCode
|
|
streetAddress
|
|
generationQualifier
|
|
description
|
|
dnQualifier
|
|
x500UniqueIdentifier
|
|
pseudonym
|
|
role
|
|
emailAddress
|
|
</literallayout>
|
|
<para>
|
|
All of these fields are optional, except <structfield>commonName</structfield>.
|
|
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
|
|
the X.500 and X.509 standards, so you cannot just assign arbitrary
|
|
meaning to them.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<function>ssl_issuer_field(fieldname text) returns text</function>
|
|
<indexterm>
|
|
<primary>ssl_issuer_field</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Same as <function>ssl_client_dn_field</function>, but for the certificate issuer
|
|
rather than the certificate subject.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<function>ssl_extension_info() returns setof record</function>
|
|
<indexterm>
|
|
<primary>ssl_extension_info</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Provide information about extensions of client certificate: extension name,
|
|
extension value, and if it is a critical extension.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Author</title>
|
|
|
|
<para>
|
|
Victor Wagner <email>vitus@cryptocom.ru</email>, Cryptocom LTD
|
|
</para>
|
|
|
|
<para>
|
|
Dmitry Voronin <email>carriingfate92@yandex.ru</email>
|
|
</para>
|
|
|
|
<para>
|
|
E-Mail of Cryptocom OpenSSL development group:
|
|
<email>openssl@cryptocom.ru</email>
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|