| 1 |
<!-- doc/src/sgml/sslinfo.sgml --> |
| 2 |
|
| 3 |
<sect1 id="sslinfo" xreflabel="sslinfo"> |
| 4 |
<title>sslinfo — obtain client SSL information</title> |
| 5 |
|
| 6 |
<indexterm zone="sslinfo"> |
| 7 |
<primary>sslinfo</primary> |
| 8 |
</indexterm> |
| 9 |
|
| 10 |
<para> |
| 11 |
The <filename>sslinfo</filename> module provides information about the SSL |
| 12 |
certificate that the current client provided when connecting to |
| 13 |
<productname>PostgreSQL</productname>. The module is useless (most functions |
| 14 |
will return NULL) if the current connection does not use SSL. |
| 15 |
</para> |
| 16 |
|
| 17 |
<para> |
| 18 |
Some of the information available through this module can also be obtained |
| 19 |
using the built-in system view <link linkend="monitoring-pg-stat-ssl-view"> |
| 20 |
<structname>pg_stat_ssl</structname></link>. |
| 21 |
</para> |
| 22 |
|
| 23 |
<para> |
| 24 |
This extension won't build at all unless the installation was |
| 25 |
configured with <literal>--with-ssl=openssl</literal>. |
| 26 |
</para> |
| 27 |
|
| 28 |
<sect2 id="sslinfo-functions"> |
| 29 |
<title>Functions Provided</title> |
| 30 |
|
| 31 |
<variablelist> |
| 32 |
<varlistentry> |
| 33 |
<term> |
| 34 |
<function>ssl_is_used() returns boolean</function> |
| 35 |
<indexterm> |
| 36 |
<primary>ssl_is_used</primary> |
| 37 |
</indexterm> |
| 38 |
</term> |
| 39 |
<listitem> |
| 40 |
<para> |
| 41 |
Returns true if current connection to server uses SSL, and false |
| 42 |
otherwise. |
| 43 |
</para> |
| 44 |
</listitem> |
| 45 |
</varlistentry> |
| 46 |
|
| 47 |
<varlistentry> |
| 48 |
<term> |
| 49 |
<function>ssl_version() returns text</function> |
| 50 |
<indexterm> |
| 51 |
<primary>ssl_version</primary> |
| 52 |
</indexterm> |
| 53 |
</term> |
| 54 |
<listitem> |
| 55 |
<para> |
| 56 |
Returns the name of the protocol used for the SSL connection (e.g., TLSv1.0, |
| 57 |
TLSv1.1, TLSv1.2 or TLSv1.3). |
| 58 |
</para> |
| 59 |
</listitem> |
| 60 |
</varlistentry> |
| 61 |
|
| 62 |
<varlistentry> |
| 63 |
<term> |
| 64 |
<function>ssl_cipher() returns text</function> |
| 65 |
<indexterm> |
| 66 |
<primary>ssl_cipher</primary> |
| 67 |
</indexterm> |
| 68 |
</term> |
| 69 |
<listitem> |
| 70 |
<para> |
| 71 |
Returns the name of the cipher used for the SSL connection |
| 72 |
(e.g., DHE-RSA-AES256-SHA). |
| 73 |
</para> |
| 74 |
</listitem> |
| 75 |
</varlistentry> |
| 76 |
|
| 77 |
<varlistentry> |
| 78 |
<term> |
| 79 |
<function>ssl_client_cert_present() returns boolean</function> |
| 80 |
<indexterm> |
| 81 |
<primary>ssl_client_cert_present</primary> |
| 82 |
</indexterm> |
| 83 |
</term> |
| 84 |
<listitem> |
| 85 |
<para> |
| 86 |
Returns true if current client has presented a valid SSL client |
| 87 |
certificate to the server, and false otherwise. (The server |
| 88 |
might or might not be configured to require a client certificate.) |
| 89 |
</para> |
| 90 |
</listitem> |
| 91 |
</varlistentry> |
| 92 |
|
| 93 |
<varlistentry> |
| 94 |
<term> |
| 95 |
<function>ssl_client_serial() returns numeric</function> |
| 96 |
<indexterm> |
| 97 |
<primary>ssl_client_serial</primary> |
| 98 |
</indexterm> |
| 99 |
</term> |
| 100 |
<listitem> |
| 101 |
<para> |
| 102 |
Returns serial number of current client certificate. The combination of |
| 103 |
certificate serial number and certificate issuer is guaranteed to |
| 104 |
uniquely identify a certificate (but not its owner — the owner |
| 105 |
ought to regularly change their keys, and get new certificates from the |
| 106 |
issuer). |
| 107 |
</para> |
| 108 |
|
| 109 |
<para> |
| 110 |
So, if you run your own CA and allow only certificates from this CA to |
| 111 |
be accepted by the server, the serial number is the most reliable (albeit |
| 112 |
not very mnemonic) means to identify a user. |
| 113 |
</para> |
| 114 |
</listitem> |
| 115 |
</varlistentry> |
| 116 |
|
| 117 |
<varlistentry> |
| 118 |
<term> |
| 119 |
<function>ssl_client_dn() returns text</function> |
| 120 |
<indexterm> |
| 121 |
<primary>ssl_client_dn</primary> |
| 122 |
</indexterm> |
| 123 |
</term> |
| 124 |
<listitem> |
| 125 |
<para> |
| 126 |
Returns the full subject of the current client certificate, converting |
| 127 |
character data into the current database encoding. It is assumed that |
| 128 |
if you use non-ASCII characters in the certificate names, your |
| 129 |
database is able to represent these characters, too. If your database |
| 130 |
uses the SQL_ASCII encoding, non-ASCII characters in the name will be |
| 131 |
represented as UTF-8 sequences. |
| 132 |
</para> |
| 133 |
|
| 134 |
<para> |
| 135 |
The result looks like <literal>/CN=Somebody /C=Some country/O=Some organization</literal>. |
| 136 |
</para> |
| 137 |
</listitem> |
| 138 |
</varlistentry> |
| 139 |
|
| 140 |
<varlistentry> |
| 141 |
<term> |
| 142 |
<function>ssl_issuer_dn() returns text</function> |
| 143 |
<indexterm> |
| 144 |
<primary>ssl_issuer_dn</primary> |
| 145 |
</indexterm> |
| 146 |
</term> |
| 147 |
<listitem> |
| 148 |
<para> |
| 149 |
Returns the full issuer name of the current client certificate, converting |
| 150 |
character data into the current database encoding. Encoding conversions |
| 151 |
are handled the same as for <function>ssl_client_dn</function>. |
| 152 |
</para> |
| 153 |
<para> |
| 154 |
The combination of the return value of this function with the |
| 155 |
certificate serial number uniquely identifies the certificate. |
| 156 |
</para> |
| 157 |
<para> |
| 158 |
This function is really useful only if you have more than one trusted CA |
| 159 |
certificate in your server's certificate authority file, or if this CA |
| 160 |
has issued some intermediate certificate authority certificates. |
| 161 |
</para> |
| 162 |
</listitem> |
| 163 |
</varlistentry> |
| 164 |
|
| 165 |
<varlistentry> |
| 166 |
<term> |
| 167 |
<function>ssl_client_dn_field(fieldname text) returns text</function> |
| 168 |
<indexterm> |
| 169 |
<primary>ssl_client_dn_field</primary> |
| 170 |
</indexterm> |
| 171 |
</term> |
| 172 |
<listitem> |
| 173 |
<para> |
| 174 |
This function returns the value of the specified field in the |
| 175 |
certificate subject, or NULL if the field is not present. |
| 176 |
Field names are string constants that are converted into ASN1 object |
| 177 |
identifiers using the <productname>OpenSSL</productname> object |
| 178 |
database. The following values are acceptable: |
| 179 |
</para> |
| 180 |
<literallayout class="monospaced"> |
| 181 |
commonName (alias CN) |
| 182 |
surname (alias SN) |
| 183 |
name |
| 184 |
givenName (alias GN) |
| 185 |
countryName (alias C) |
| 186 |
localityName (alias L) |
| 187 |
stateOrProvinceName (alias ST) |
| 188 |
organizationName (alias O) |
| 189 |
organizationalUnitName (alias OU) |
| 190 |
title |
| 191 |
description |
| 192 |
initials |
| 193 |
postalCode |
| 194 |
streetAddress |
| 195 |
generationQualifier |
| 196 |
description |
| 197 |
dnQualifier |
| 198 |
x500UniqueIdentifier |
| 199 |
pseudonym |
| 200 |
role |
| 201 |
emailAddress |
| 202 |
</literallayout> |
| 203 |
<para> |
| 204 |
All of these fields are optional, except <structfield>commonName</structfield>. |
| 205 |
It depends |
| 206 |
entirely on your CA's policy which of them would be included and which |
| 207 |
wouldn't. The meaning of these fields, however, is strictly defined by |
| 208 |
the X.500 and X.509 standards, so you cannot just assign arbitrary |
| 209 |
meaning to them. |
| 210 |
</para> |
| 211 |
</listitem> |
| 212 |
</varlistentry> |
| 213 |
|
| 214 |
<varlistentry> |
| 215 |
<term> |
| 216 |
<function>ssl_issuer_field(fieldname text) returns text</function> |
| 217 |
<indexterm> |
| 218 |
<primary>ssl_issuer_field</primary> |
| 219 |
</indexterm> |
| 220 |
</term> |
| 221 |
<listitem> |
| 222 |
<para> |
| 223 |
Same as <function>ssl_client_dn_field</function>, but for the certificate issuer |
| 224 |
rather than the certificate subject. |
| 225 |
</para> |
| 226 |
</listitem> |
| 227 |
</varlistentry> |
| 228 |
|
| 229 |
<varlistentry> |
| 230 |
<term> |
| 231 |
<function>ssl_extension_info() returns setof record</function> |
| 232 |
<indexterm> |
| 233 |
<primary>ssl_extension_info</primary> |
| 234 |
</indexterm> |
| 235 |
</term> |
| 236 |
<listitem> |
| 237 |
<para> |
| 238 |
Provide information about extensions of client certificate: extension name, |
| 239 |
extension value, and if it is a critical extension. |
| 240 |
</para> |
| 241 |
</listitem> |
| 242 |
</varlistentry> |
| 243 |
</variablelist> |
| 244 |
</sect2> |
| 245 |
|
| 246 |
<sect2 id="sslinfo-author"> |
| 247 |
<title>Author</title> |
| 248 |
|
| 249 |
<para> |
| 250 |
Victor Wagner <email>[email protected]</email>, Cryptocom LTD |
| 251 |
</para> |
| 252 |
|
| 253 |
<para> |
| 254 |
Dmitry Voronin <email>[email protected]</email> |
| 255 |
</para> |
| 256 |
|
| 257 |
<para> |
| 258 |
E-Mail of Cryptocom OpenSSL development group: |
| 259 |
<email>[email protected]</email> |
| 260 |
</para> |
| 261 |
</sect2> |
| 262 |
|
| 263 |
</sect1> |