summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/sslinfo.html
blob: afa0b1afde799bbe0755601549d940762ddda4fd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.42. sslinfo</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-spi.html" title="F.41. spi" /><link rel="next" href="tablefunc.html" title="F.43. tablefunc" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.42. sslinfo</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-spi.html" title="F.41. spi">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tablefunc.html" title="F.43. tablefunc">Next</a></td></tr></table><hr /></div><div class="sect1" id="SSLINFO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.42. sslinfo</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sslinfo.html#id-1.11.7.51.6">F.42.1. Functions Provided</a></span></dt><dt><span class="sect2"><a href="sslinfo.html#id-1.11.7.51.7">F.42.2. Author</a></span></dt></dl></div><a id="id-1.11.7.51.2" class="indexterm"></a><p>
  The <code class="filename">sslinfo</code> module provides information about the SSL
  certificate that the current client provided when connecting to
  <span class="productname">PostgreSQL</span>.  The module is useless (most functions
  will return NULL) if the current connection does not use SSL.
 </p><p>
  Some of the information available through this module can also be obtained
  using the built-in system view <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SSL-VIEW" title="28.2.10. pg_stat_ssl">
  <code class="structname">pg_stat_ssl</code></a>.
 </p><p>
  This extension won't build at all unless the installation was
  configured with <code class="literal">--with-ssl=openssl</code>.
 </p><div class="sect2" id="id-1.11.7.51.6"><div class="titlepage"><div><div><h3 class="title">F.42.1. Functions Provided</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
     <code class="function">ssl_is_used() returns boolean</code>
     <a id="id-1.11.7.51.6.2.1.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     Returns true if current connection to server uses SSL, and false
     otherwise.
    </p></dd><dt><span class="term">
     <code class="function">ssl_version() returns text</code>
     <a id="id-1.11.7.51.6.2.2.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     Returns the name of the protocol used for the SSL connection (e.g., TLSv1.0,
     TLSv1.1, TLSv1.2 or TLSv1.3).
    </p></dd><dt><span class="term">
     <code class="function">ssl_cipher() returns text</code>
     <a id="id-1.11.7.51.6.2.3.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     Returns the name of the cipher used for the SSL connection
     (e.g., DHE-RSA-AES256-SHA).
    </p></dd><dt><span class="term">
     <code class="function">ssl_client_cert_present() returns boolean</code>
     <a id="id-1.11.7.51.6.2.4.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     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.)
    </p></dd><dt><span class="term">
     <code class="function">ssl_client_serial() returns numeric</code>
     <a id="id-1.11.7.51.6.2.5.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     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).
    </p><p>
     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.
    </p></dd><dt><span class="term">
     <code class="function">ssl_client_dn() returns text</code>
     <a id="id-1.11.7.51.6.2.6.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     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.
    </p><p>
     The result looks like <code class="literal">/CN=Somebody /C=Some country/O=Some organization</code>.
    </p></dd><dt><span class="term">
     <code class="function">ssl_issuer_dn() returns text</code>
     <a id="id-1.11.7.51.6.2.7.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     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 <code class="function">ssl_client_dn</code>.
    </p><p>
     The combination of the return value of this function with the
     certificate serial number uniquely identifies the certificate.
    </p><p>
     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.
    </p></dd><dt><span class="term">
     <code class="function">ssl_client_dn_field(fieldname text) returns text</code>
     <a id="id-1.11.7.51.6.2.8.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     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 <span class="productname">OpenSSL</span> object
     database.  The following values are acceptable:
    </p><pre class="literallayout">
commonName (alias CN)
surname (alias SN)
name
givenName (alias GN)
countryName (alias C)
localityName (alias L)
stateOrProvinceName (alias ST)
organizationName (alias O)
organizationalUnitName (alias OU)
title
description
initials
postalCode
streetAddress
generationQualifier
description
dnQualifier
x500UniqueIdentifier
pseudonym
role
emailAddress
</pre><p>
     All of these fields are optional, except <code class="structfield">commonName</code>.
     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.
    </p></dd><dt><span class="term">
     <code class="function">ssl_issuer_field(fieldname text) returns text</code>
     <a id="id-1.11.7.51.6.2.9.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     Same as <code class="function">ssl_client_dn_field</code>, but for the certificate issuer
     rather than the certificate subject.
    </p></dd><dt><span class="term">
     <code class="function">ssl_extension_info() returns setof record</code>
     <a id="id-1.11.7.51.6.2.10.1.2" class="indexterm"></a>
    </span></dt><dd><p>
     Provide information about extensions of client certificate: extension name,
     extension value, and if it is a critical extension.
    </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.51.7"><div class="titlepage"><div><div><h3 class="title">F.42.2. Author</h3></div></div></div><p>
   Victor Wagner <code class="email">&lt;<a class="email" href="mailto:vitus@cryptocom.ru">vitus@cryptocom.ru</a>&gt;</code>, Cryptocom LTD
  </p><p>
   Dmitry Voronin <code class="email">&lt;<a class="email" href="mailto:carriingfate92@yandex.ru">carriingfate92@yandex.ru</a>&gt;</code>
  </p><p>
   E-Mail of Cryptocom OpenSSL development group:
   <code class="email">&lt;<a class="email" href="mailto:openssl@cryptocom.ru">openssl@cryptocom.ru</a>&gt;</code>
  </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-spi.html" title="F.41. spi">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tablefunc.html" title="F.43. tablefunc">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.41. spi </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.43. tablefunc</td></tr></table></div></body></html>