Add API functions to libpq to interrogate SSL related stuff.

This makes it possible to query for things like the SSL version and cipher
used, without depending on OpenSSL functions or macros. That is a good
thing if we ever get another SSL implementation.

PQgetssl() still works, but it should be considered as deprecated as it
only works with OpenSSL. In particular, PQgetSslInUse() should be used to
check if a connection uses SSL, because as soon as we have another
implementation, PQgetssl() will return NULL even if SSL is in use.

1 files changed, 139 insertions, 16 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 75a4d518f26..39aede4b7b7 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1848,33 +1848,127 @@ int PQconnectionUsedPassword(const PGconn *conn);
       </para>
      </listitem>
     </varlistentry>
+   </variablelist>
+  </para>
 
-    <varlistentry id="libpq-pqgetssl">
-     <term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
+  <para>
+    The following functions return information related to SSL. This information
+    usually doesn't change after a connection is established.
+
+    <variablelist>
+    <varlistentry id="libpq-pqsslinuse">
+     <term><function>PQsslInUse</function><indexterm><primary>PQsslInUse</></></term>
      <listitem>
       <para>
-       <indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
-       Returns the SSL structure used in the connection, or null
-       if SSL is not in use.
+        Returns true (1) if the connection uses SSL, false (0) if not.
 
 <synopsis>
-void *PQgetssl(const PGconn *conn);
+int PQsslInUse(const PGconn *conn);
 </synopsis>
       </para>
 
+     </listitem>
+    </varlistentry>
+
+    <varlistentry id="libpq-pqsslAttribute">
+     <term><function>PQsslAttribute</function><indexterm><primary>PQsslAttribute</></></term>
+     <listitem>
       <para>
-       This structure can be used to verify encryption levels, check server
-       certificates, and more. Refer to the <productname>OpenSSL</>
-       documentation for information about this structure.
+        Returns SSL-related information about the connection.
+
+<synopsis>
+const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
+</synopsis>
+      </para>
+
+      <para>
+       The list of available attributes varies depending on the SSL library
+       being used, and the type of connection. If an attribute is not
+       available, returns NULL.
+      </para>
+
+      <para>
+       The following attributes are commonly available:
+       <variablelist>
+        <varlistentry>
+         <term><literal>library</literal></term>
+          <listitem>
+           <para>
+            Name of the SSL implementation in use. (Currently, only
+            <literal>"OpenSSL"</literal> is implemented)
+           </para>
+          </listitem>
+         </varlistentry>
+        <varlistentry>
+         <term><literal>protocol</literal></term>
+          <listitem>
+           <para>
+             SSL/TLS version in use. Common values are "SSLv2", "SSLv3", 
+             "TLSv1", "TLSv1.1" and "TLSv1.2", but an implementation may
+             return other strings if some other protocol is used.
+           </para>
+          </listitem>
+         </varlistentry>
+        <varlistentry>
+         <term><literal>key_bits</literal></term>
+          <listitem>
+           <para>
+            Number of key bits used by the encryption algorithm.
+           </para>
+          </listitem>
+         </varlistentry>
+        <varlistentry>
+         <term><literal>cipher</literal></term>
+          <listitem>
+           <para>
+            A short name of the ciphersuite used, e.g. 
+            <literal>"DHE-RSA-DES-CBC3-SHA"</literal>. The names are specific
+            to each SSL implementation.
+           </para>
+          </listitem>
+         </varlistentry>
+        <varlistentry>
+         <term><literal>compression</literal></term>
+          <listitem>
+           <para>
+            If SSL compression is in use, returns the name of the compression
+            algorithm, or "on" if compression is used but the algorithm is
+            not known. If compression is not in use, returns "off".
+           </para>
+          </listitem>
+         </varlistentry>
+       </variablelist>
       </para>
+     </listitem>
+    </varlistentry>
 
+    <varlistentry id="libpq-pqsslattributes">
+     <term><function>PQsslAttributes</function><indexterm><primary>PQsslAttributes</></></term>
+     <listitem>
+      <para>
+       Return an array of SSL attribute names available. The array is terminated by a NULL pointer.
+<synopsis>
+const char **PQsslAttributes(const PGconn *conn);
+</synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry id="libpq-pqsslstruct">
+     <term><function>PQsslStruct</function><indexterm><primary>PQsslStruct</></></term>
+     <listitem>
+      <para>
+       Return a pointer to an SSL-implementation specific object describing
+       the connection.
+<synopsis>
+void *PQsslStruct(const PGconn *conn, const char *struct_name);
+</synopsis>
+      </para>
       <para>
-       The actual return value is of type <type>SSL *</type>,
-       where <type>SSL</type> is a type defined by
-       the <productname>OpenSSL</productname> library, but it is not declared
-       this way to avoid requiring the <productname>OpenSSL</productname>
-       header files.  To use this function, code along the following lines
-       could be used:
+       The structs available depends on the SSL implementation in use.
+       For OpenSSL, there is one struct, under the name "OpenSSL",
+       and it returns a pointer to the OpenSSL <literal>SSL</literal> struct.
+       To use this function, code along the following lines could be used:
 <programlisting><![CDATA[
 #include <libpq-fe.h>
 #include <openssl/ssl.h>
@@ -1886,13 +1980,42 @@ void *PQgetssl(const PGconn *conn);
     dbconn = PQconnectdb(...);
     ...
 
-    ssl = PQgetssl(dbconn);
+    ssl = PQsslStruct(dbconn, "OpenSSL");
     if (ssl)
     {
         /* use OpenSSL functions to access ssl */
     }
 ]]></programlisting>
       </para>
+      <para>
+       This structure can be used to verify encryption levels, check server
+       certificates, and more. Refer to the <productname>OpenSSL</>
+       documentation for information about this structure.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry id="libpq-pqgetssl">
+     <term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
+     <listitem>
+      <para>
+       <indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
+       Returns the SSL structure used in the connection, or null
+       if SSL is not in use.
+
+<synopsis>
+void *PQgetssl(const PGconn *conn);
+</synopsis>
+      </para>
+
+      <para>
+       This function is equivalent to PQsslStruct(conn, "OpenSSL"). It should
+       not be used in new applications, because the returned struct is
+       specific to OpenSSL and will not be available if another SSL
+       implementation is used. To check if a connection uses SSL, call
+       <function>PQsslInUse</> instead, and for more details about the
+       connection, use <function>PQsslAttribute</>.
+      </para>
      </listitem>
     </varlistentry>