Repair memory leaks in plpython.
[pgsql.git] / doc / src / sgml / sslinfo.sgml
blob85d49f66537cf03dec6801f8ff16500bfc4bd9b0
1 <!-- doc/src/sgml/sslinfo.sgml -->
3 <sect1 id="sslinfo" xreflabel="sslinfo">
4 <title>sslinfo &mdash; obtain client SSL information</title>
6 <indexterm zone="sslinfo">
7 <primary>sslinfo</primary>
8 </indexterm>
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>
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>
23 <para>
24 This extension won't build at all unless the installation was
25 configured with <literal>--with-ssl=openssl</literal>.
26 </para>
28 <sect2 id="sslinfo-functions">
29 <title>Functions Provided</title>
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>
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>
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>
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>
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 &mdash; the owner
105 ought to regularly change their keys, and get new certificates from the
106 issuer).
107 </para>
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>
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>
134 <para>
135 The result looks like <literal>/CN=Somebody /C=Some country/O=Some organization</literal>.
136 </para>
137 </listitem>
138 </varlistentry>
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>
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>
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>
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>
246 <sect2 id="sslinfo-author">
247 <title>Author</title>
249 <para>
250 Victor Wagner <email>vitus@cryptocom.ru</email>, Cryptocom LTD
251 </para>
253 <para>
254 Dmitry Voronin <email>carriingfate92@yandex.ru</email>
255 </para>
257 <para>
258 E-Mail of Cryptocom OpenSSL development group:
259 <email>openssl@cryptocom.ru</email>
260 </para>
261 </sect2>
263 </sect1>