@@ -1848,33 +1848,127 @@ int PQconnectionUsedPassword(const PGconn *conn);
1848
1848
</para>
1849
1849
</listitem>
1850
1850
</varlistentry>
1851
+ </variablelist>
1852
+ </para>
1851
1853
1852
- <varlistentry id="libpq-pqgetssl">
1853
- <term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
1854
+ <para>
1855
+ The following functions return information related to SSL. This information
1856
+ usually doesn't change after a connection is established.
1857
+
1858
+ <variablelist>
1859
+ <varlistentry id="libpq-pqsslinuse">
1860
+ <term><function>PQsslInUse</function><indexterm><primary>PQsslInUse</></></term>
1854
1861
<listitem>
1855
1862
<para>
1856
- <indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
1857
- Returns the SSL structure used in the connection, or null
1858
- if SSL is not in use.
1863
+ Returns true (1) if the connection uses SSL, false (0) if not.
1859
1864
1860
1865
<synopsis>
1861
- void *PQgetssl (const PGconn *conn);
1866
+ int PQsslInUse (const PGconn *conn);
1862
1867
</synopsis>
1863
1868
</para>
1864
1869
1870
+ </listitem>
1871
+ </varlistentry>
1872
+
1873
+ <varlistentry id="libpq-pqsslAttribute">
1874
+ <term><function>PQsslAttribute</function><indexterm><primary>PQsslAttribute</></></term>
1875
+ <listitem>
1865
1876
<para>
1866
- This structure can be used to verify encryption levels, check server
1867
- certificates, and more. Refer to the <productname>OpenSSL</>
1868
- documentation for information about this structure.
1877
+ Returns SSL-related information about the connection.
1878
+
1879
+ <synopsis>
1880
+ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
1881
+ </synopsis>
1882
+ </para>
1883
+
1884
+ <para>
1885
+ The list of available attributes varies depending on the SSL library
1886
+ being used, and the type of connection. If an attribute is not
1887
+ available, returns NULL.
1888
+ </para>
1889
+
1890
+ <para>
1891
+ The following attributes are commonly available:
1892
+ <variablelist>
1893
+ <varlistentry>
1894
+ <term><literal>library</literal></term>
1895
+ <listitem>
1896
+ <para>
1897
+ Name of the SSL implementation in use. (Currently, only
1898
+ <literal>"OpenSSL"</literal> is implemented)
1899
+ </para>
1900
+ </listitem>
1901
+ </varlistentry>
1902
+ <varlistentry>
1903
+ <term><literal>protocol</literal></term>
1904
+ <listitem>
1905
+ <para>
1906
+ SSL/TLS version in use. Common values are "SSLv2", "SSLv3",
1907
+ "TLSv1", "TLSv1.1" and "TLSv1.2", but an implementation may
1908
+ return other strings if some other protocol is used.
1909
+ </para>
1910
+ </listitem>
1911
+ </varlistentry>
1912
+ <varlistentry>
1913
+ <term><literal>key_bits</literal></term>
1914
+ <listitem>
1915
+ <para>
1916
+ Number of key bits used by the encryption algorithm.
1917
+ </para>
1918
+ </listitem>
1919
+ </varlistentry>
1920
+ <varlistentry>
1921
+ <term><literal>cipher</literal></term>
1922
+ <listitem>
1923
+ <para>
1924
+ A short name of the ciphersuite used, e.g.
1925
+ <literal>"DHE-RSA-DES-CBC3-SHA"</literal>. The names are specific
1926
+ to each SSL implementation.
1927
+ </para>
1928
+ </listitem>
1929
+ </varlistentry>
1930
+ <varlistentry>
1931
+ <term><literal>compression</literal></term>
1932
+ <listitem>
1933
+ <para>
1934
+ If SSL compression is in use, returns the name of the compression
1935
+ algorithm, or "on" if compression is used but the algorithm is
1936
+ not known. If compression is not in use, returns "off".
1937
+ </para>
1938
+ </listitem>
1939
+ </varlistentry>
1940
+ </variablelist>
1869
1941
</para>
1942
+ </listitem>
1943
+ </varlistentry>
1870
1944
1945
+ <varlistentry id="libpq-pqsslattributes">
1946
+ <term><function>PQsslAttributes</function><indexterm><primary>PQsslAttributes</></></term>
1947
+ <listitem>
1948
+ <para>
1949
+ Return an array of SSL attribute names available. The array is terminated by a NULL pointer.
1950
+ <synopsis>
1951
+ const char **PQsslAttributes(const PGconn *conn);
1952
+ </synopsis>
1953
+ </para>
1954
+ </listitem>
1955
+ </varlistentry>
1956
+
1957
+ <varlistentry id="libpq-pqsslstruct">
1958
+ <term><function>PQsslStruct</function><indexterm><primary>PQsslStruct</></></term>
1959
+ <listitem>
1960
+ <para>
1961
+ Return a pointer to an SSL-implementation specific object describing
1962
+ the connection.
1963
+ <synopsis>
1964
+ void *PQsslStruct(const PGconn *conn, const char *struct_name);
1965
+ </synopsis>
1966
+ </para>
1871
1967
<para>
1872
- The actual return value is of type <type>SSL *</type>,
1873
- where <type>SSL</type> is a type defined by
1874
- the <productname>OpenSSL</productname> library, but it is not declared
1875
- this way to avoid requiring the <productname>OpenSSL</productname>
1876
- header files. To use this function, code along the following lines
1877
- could be used:
1968
+ The structs available depends on the SSL implementation in use.
1969
+ For OpenSSL, there is one struct, under the name "OpenSSL",
1970
+ and it returns a pointer to the OpenSSL <literal>SSL</literal> struct.
1971
+ To use this function, code along the following lines could be used:
1878
1972
<programlisting><![CDATA[
1879
1973
#include <libpq-fe.h>
1880
1974
#include <openssl/ssl.h>
@@ -1886,13 +1980,42 @@ void *PQgetssl(const PGconn *conn);
1886
1980
dbconn = PQconnectdb(...);
1887
1981
...
1888
1982
1889
- ssl = PQgetssl (dbconn);
1983
+ ssl = PQsslStruct (dbconn, "OpenSSL" );
1890
1984
if (ssl)
1891
1985
{
1892
1986
/* use OpenSSL functions to access ssl */
1893
1987
}
1894
1988
]]></programlisting>
1895
1989
</para>
1990
+ <para>
1991
+ This structure can be used to verify encryption levels, check server
1992
+ certificates, and more. Refer to the <productname>OpenSSL</>
1993
+ documentation for information about this structure.
1994
+ </para>
1995
+ </listitem>
1996
+ </varlistentry>
1997
+
1998
+ <varlistentry id="libpq-pqgetssl">
1999
+ <term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
2000
+ <listitem>
2001
+ <para>
2002
+ <indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
2003
+ Returns the SSL structure used in the connection, or null
2004
+ if SSL is not in use.
2005
+
2006
+ <synopsis>
2007
+ void *PQgetssl(const PGconn *conn);
2008
+ </synopsis>
2009
+ </para>
2010
+
2011
+ <para>
2012
+ This function is equivalent to PQsslStruct(conn, "OpenSSL"). It should
2013
+ not be used in new applications, because the returned struct is
2014
+ specific to OpenSSL and will not be available if another SSL
2015
+ implementation is used. To check if a connection uses SSL, call
2016
+ <function>PQsslInUse</> instead, and for more details about the
2017
+ connection, use <function>PQsslAttribute</>.
2018
+ </para>
1896
2019
</listitem>
1897
2020
</varlistentry>
1898
2021
0 commit comments