begriffs open source - ai-pg/blob - full-docs/txt/sslinfo.txt

   1
   2 F.42. sslinfo — obtain client SSL information #
   3
   4    F.42.1. Functions Provided
   5    F.42.2. Author
   6
   7    The sslinfo module provides information about the SSL certificate that
   8    the current client provided when connecting to PostgreSQL. The module
   9    is useless (most functions will return NULL) if the current connection
  10    does not use SSL.
  11
  12    Some of the information available through this module can also be
  13    obtained using the built-in system view pg_stat_ssl.
  14
  15    This extension won't build at all unless the installation was
  16    configured with --with-ssl=openssl.
  17
  18 F.42.1. Functions Provided #
  19
  20    ssl_is_used() returns boolean
  21           Returns true if current connection to server uses SSL, and false
  22           otherwise.
  23
  24    ssl_version() returns text
  25           Returns the name of the protocol used for the SSL connection
  26           (e.g., TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3).
  27
  28    ssl_cipher() returns text
  29           Returns the name of the cipher used for the SSL connection
  30           (e.g., DHE-RSA-AES256-SHA).
  31
  32    ssl_client_cert_present() returns boolean
  33           Returns true if current client has presented a valid SSL client
  34           certificate to the server, and false otherwise. (The server
  35           might or might not be configured to require a client
  36           certificate.)
  37
  38    ssl_client_serial() returns numeric
  39           Returns serial number of current client certificate. The
  40           combination of certificate serial number and certificate issuer
  41           is guaranteed to uniquely identify a certificate (but not its
  42           owner — the owner ought to regularly change their keys, and get
  43           new certificates from the issuer).
  44
  45           So, if you run your own CA and allow only certificates from this
  46           CA to be accepted by the server, the serial number is the most
  47           reliable (albeit not very mnemonic) means to identify a user.
  48
  49    ssl_client_dn() returns text
  50           Returns the full subject of the current client certificate,
  51           converting character data into the current database encoding. It
  52           is assumed that if you use non-ASCII characters in the
  53           certificate names, your database is able to represent these
  54           characters, too. If your database uses the SQL_ASCII encoding,
  55           non-ASCII characters in the name will be represented as UTF-8
  56           sequences.
  57
  58           The result looks like /CN=Somebody /C=Some country/O=Some
  59           organization.
  60
  61    ssl_issuer_dn() returns text
  62           Returns the full issuer name of the current client certificate,
  63           converting character data into the current database encoding.
  64           Encoding conversions are handled the same as for ssl_client_dn.
  65
  66           The combination of the return value of this function with the
  67           certificate serial number uniquely identifies the certificate.
  68
  69           This function is really useful only if you have more than one
  70           trusted CA certificate in your server's certificate authority
  71           file, or if this CA has issued some intermediate certificate
  72           authority certificates.
  73
  74    ssl_client_dn_field(fieldname text) returns text
  75           This function returns the value of the specified field in the
  76           certificate subject, or NULL if the field is not present. Field
  77           names are string constants that are converted into ASN1 object
  78           identifiers using the OpenSSL object database. The following
  79           values are acceptable:
  80
  81 commonName (alias CN)
  82 surname (alias SN)
  83 name
  84 givenName (alias GN)
  85 countryName (alias C)
  86 localityName (alias L)
  87 stateOrProvinceName (alias ST)
  88 organizationName (alias O)
  89 organizationalUnitName (alias OU)
  90 title
  91 description
  92 initials
  93 postalCode
  94 streetAddress
  95 generationQualifier
  96 description
  97 dnQualifier
  98 x500UniqueIdentifier
  99 pseudonym
 100 role
 101 emailAddress
 102
 103           All of these fields are optional, except commonName. It depends
 104           entirely on your CA's policy which of them would be included and
 105           which wouldn't. The meaning of these fields, however, is
 106           strictly defined by the X.500 and X.509 standards, so you cannot
 107           just assign arbitrary meaning to them.
 108
 109    ssl_issuer_field(fieldname text) returns text
 110           Same as ssl_client_dn_field, but for the certificate issuer
 111           rather than the certificate subject.
 112
 113    ssl_extension_info() returns setof record
 114           Provide information about extensions of client certificate:
 115           extension name, extension value, and if it is a critical
 116           extension.
 117
 118 F.42.2. Author #
 119
 120    Victor Wagner <vitus@cryptocom.ru>, Cryptocom LTD
 121
 122    Dmitry Voronin <carriingfate92@yandex.ru>
 123
 124    E-Mail of Cryptocom OpenSSL development group: <openssl@cryptocom.ru>