* doc/ref/init.xml, doc/ref/neon.xml: Document thread-safe SSL

handling.


git-svn-id: http://svn.webdav.org/repos/projects/neon/trunk@954 61a7d7f5-40b7-0310-9c16-bb0ea8cb1845

2 files changed, 76 insertions, 8 deletions

diff --git a/doc/ref/init.xml b/doc/ref/init.xml
index 32dcda5..234b48a 100644
--- a/doc/ref/init.xml
+++ b/doc/ref/init.xml
@@ -7,6 +7,7 @@
 
   <refnamediv>
     <refname id="ne_sock_init">ne_sock_init</refname>
+    <refname id="ne_sock_exit">ne_sock_exit</refname>
     <refpurpose>perform library initialization</refpurpose>
   </refnamediv>
   
@@ -21,6 +22,11 @@
 	<void/>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>void <function>ne_sock_exit</function></funcdef>
+	<void/>
+      </funcprototype>
+
     </funcsynopsis>
 
   </refsynopsisdiv>
@@ -31,8 +37,69 @@
     <para>In some platforms and configurations, &neon; may be using
     some socket or SSL libraries which require global initialization
     before use.  To perform this initialization, the
-    <function>ne_sock_init</function> function must be called once
-    before any other library functions are used.</para>
+    <function>ne_sock_init</function> function must be called before
+    any other library functions are used.</para>
+
+    <para>Once all use of &neon; is complete,
+    <function>ne_sock_exit</function> can be called to perform
+    de-initialization of socket or SSL libraries, if necessary.  Uses
+    of <function>ne_sock_init</function> and
+    <function>ne_sock_exit</function> are "reference counted"; if N
+    calls to <function>ne_sock_init</function> are made, only the Nth
+    call to <function>ne_sock_exit</function> will have effect.</para>
+
+    <para>Both the SSL libraries supported by &neon; &mdash; OpenSSL
+    and GnuTLS &mdash; require callbacks to be registered to allow
+    thread-safe use of SSL.  These callbacks are stored as global
+    variables and so their state persists for as long as the library
+    in question is loaded into the process.  If multiple users of the
+    SSL library exist within the process, this can be problematic,
+    particularly if one is dynamically loaded (and may subsequently be
+    unloaded).  If &neon; is configured using the
+    <literal>--enable-threadsafe-ssl</literal> flag, thread-safe SSL
+    support will be enabled automatically, as covered in the following
+    section.</para>
+    
+    <refsect2>
+      <title>Thread-safe SSL with OpenSSL</title>
+
+      <para>&neon; follows two simple rules when dealing with the
+      OpenSSL locking callbacks:
+
+      <itemizedlist>
+        
+        <listitem><simpara><function>ne_sock_init</function> will set
+        thread-safety locking callbacks if and only if no locking
+        callbacks are already registered.</simpara></listitem>
+        
+        <listitem><simpara><function>ne_sock_exit</function> will
+        unset the thread-safety locking callbacks if and only if the
+        locking callbacks registered are those registered by
+        <function>ne_sock_init</function>.</simpara></listitem>
+
+      </itemizedlist>
+
+      Applications and libraries should be able to co-operate to
+      ensure that SSL use is always thread-safe if similar rules are
+      always followed.</para>
+
+    </refsect2>
+
+    <refsect2>
+      <title>Thread-safe SSL with GnuTLS</title>
+
+      <para>The cryptography library used by GnuTLS, libgcrypt, only
+      supports an initialization operation to register thread-safety
+      callbacks.  <function>ne_sock_init</function> will register the
+      thread-safe locking callbacks on first use;
+      <function>ne_sock_exit</function> cannot unregister them.  If
+      multiple users of GnuTLS are present within the process, it is
+      unsafe to dynamically unload &neon; from the process if &neon;
+      is configured with thread-safe SSL support enabled (since the
+      callbacks would be left pointing at unmapped memory once &neon;
+      is unloaded).</para>
+
+    </refsect2>
 
   </refsect1>
 
@@ -52,4 +119,3 @@
   </refsect1>
 
 </refentry>
-
diff --git a/doc/ref/neon.xml b/doc/ref/neon.xml
index 7c11325..deef4af 100644
--- a/doc/ref/neon.xml
+++ b/doc/ref/neon.xml
@@ -42,11 +42,13 @@
     <function>gethostbyname</function> using thread-local
     storage.</para>
 
-    <para>To allow thread-safe use of the OpenSSL library, the
-    application must register some locking callbacks in accordance
-    with the <ulink
-    url="http://www.openssl.org/docs/crypto/threads.html">OpenSSL
-    documentation</ulink>.</para>
+    <para>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
+    libraries &neon; must be configured using the
+    <literal>--enable-threadsafe-ssl</literal>; if this is done,
+    locking callbacks will be registered by <xref
+    linkend="ne_sock_init"/>; note that care must be exercised if
+    &neon; is used in conjunction with another library which uses
+    OpenSSL or GnuTLS.</para>
 
     <para>Some platforms and libraries used by &neon; require global
     initialization before use; notably: