Import neon-0.24.1.

git-svn-id: http://svn.webdav.org/repos/projects/neon/branches/0.24.x@244 61a7d7f5-40b7-0310-9c16-bb0ea8cb1845

12 files changed, 470 insertions, 137 deletions

diff --git a/doc/ref/clicert.xml b/doc/ref/clicert.xml
index 47a2ce0..c61404c 100644
--- a/doc/ref/clicert.xml
+++ b/doc/ref/clicert.xml
@@ -146,7 +146,7 @@ ne_ssl_set_clicert(sess, ccert);
   <refsect1>
     <title>See also</title>
 
-    <para><xref linkend="ne_ssl_certificate"/></para>
+    <para><xref linkend="ne_ssl_cert_read"/></para>
   </refsect1>
 
 </refentry>
diff --git a/doc/ref/neon.xml b/doc/ref/neon.xml
index 9857c63..7c11325 100644
--- a/doc/ref/neon.xml
+++ b/doc/ref/neon.xml
@@ -34,11 +34,38 @@
   <refsect2>
     <title>Thread-safeness and global initialization</title>
 
-    <para>&neon; itself is implemented to be thread-safe (avoiding
-    any use of global state), but in some configurations makes use of
-    other libraries which require global initialization.  The
-    <xref linkend="ne_sock_init"/> function should be called before
-    any other use of the &neon; library interface.</para>
+    <para>&neon; itself is implemented to be thread-safe (avoiding any
+    use of global state), but relies on the operating system providing
+    a thread-safe resolver interface.  Modern operating systems offer
+    the thread-safe <function>getaddrinfo</function> interface, which
+    &neon; supports; some others implement
+    <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>Some platforms and libraries used by &neon; require global
+    initialization before use; notably:
+
+    <itemizedlist>
+      <listitem><simpara>OpenSSL requires global initialization to
+      load shared lookup tables.</simpara></listitem>
+
+      <listitem><simpara>The SOCKS library requires initialization
+      before use.</simpara></listitem>
+
+      <listitem><simpara>The Win32 socket library requires
+      initialization before use.</simpara></listitem>
+    </itemizedlist>
+
+    The <xref linkend="ne_sock_init"/> function should be called
+    before any other use of &neon; to perform any necessary
+    initialization needed for the particular platform.</para>
+
   </refsect2>
 
   <refsect2>
@@ -91,11 +118,12 @@
   <refsect2>
     <title>Argument validation</title>
   
-    <para>&neon; does not attempt to validate that arguments passed to
-    functions conform to the API (for instance, checking that pointer
-    arguments are not &null;).  Any use of the &neon; API which is not
-    documented to produce a certain behaviour results in
-    <emphasis>undefined behaviour</emphasis>, by definition.</para>
+    <para>&neon; does not attempt to validate that the parameters
+    passed to functions conform to the API (for instance, checking
+    that pointer arguments are not &null;).  Any use of the &neon; API
+    which is not documented to produce a certain behaviour results is
+    said to produce <emphasis>undefined behaviour</emphasis>; it is
+    likely that &neon; will segfault under these conditions.</para>
 
   </refsect2>
 
@@ -111,6 +139,15 @@
   </refsect2>
 
   <refsect2>
+    <title>User interaction</title>
+
+    <para>As a pure library interface, &neon; will never produce
+    output on <constant>stdout</constant> or
+    <constant>stderr</constant>; all user interaction is the
+    responsibilty of the application.</para>
+  </refsect2>
+
+  <refsect2>
     <title>Memory handling</title>
 
     <para>neon does not attempt to cope gracefully with an
diff --git a/doc/ref/req.xml b/doc/ref/req.xml
index 7c36d5c..0dfcd9a 100644
--- a/doc/ref/req.xml
+++ b/doc/ref/req.xml
@@ -53,7 +53,7 @@ parameter, combined with the <parameter>path</parameter> parameter.</para>
 <para>The <parameter>path</parameter> string used must conform to the
 <literal>abs_path</literal> definition given in RFC2396, with an
 optional "?query" part, and must be URI-escaped by the caller (for
-instance, using <function>ne_path_escape</function>.  If the string
+instance, using <function>ne_path_escape</function>).  If the string
 comes from an untrusted source, failure to perform URI-escaping
 results in a security vulnerability.</para>
 
@@ -145,7 +145,7 @@ non-zero error code otherwise.</para>
 	<title>Example</title>
 	
 	<para>An example of applying a <literal>MKCOL</literal>
-	operation to the resource at the location
+	operation to the resource at the location 
 	<literal>http://www.example.com/foo/bar/</literal>:</para>
 
 	<programlisting>ne_session *sess = ne_session_create("http", "www.example.com", 80);
diff --git a/doc/ref/sess.xml b/doc/ref/sess.xml
index 8fcd9cb..93f0038 100644
--- a/doc/ref/sess.xml
+++ b/doc/ref/sess.xml
@@ -65,9 +65,9 @@ global initialization needed by any libraries used by &neon;.</para>
 	<para>To enable SSL/TLS for the session, pass the string
 <literal>"https"</literal> as the <parameter>scheme</parameter>
 parameter, and either register a certificate verification function
-(see <xref linkend="ne_ssl_set_verify"/>) or load the appropriate CA
-certificate (see <xref linkend="ne_ssl_load_ca"/>, <xref
-linkend="ne_ssl_load_default_ca"/>).</para>
+(see <xref linkend="ne_ssl_set_verify"/>) or trust the appropriate 
+certificate (see <xref linkend="ne_ssl_trust_cert"/>, <xref
+linkend="ne_ssl_trust_default_ca"/>).</para>
 
 	<para>If an HTTP proxy server should be used for the session,
 <function>ne_session_proxy</function> must be called giving the
@@ -91,7 +91,7 @@ session pointer produces undefined behaviour.</para>
 
         <para>The hostname passed to
 <function>ne_session_create</function> is resolved when the first
-request using the session is dispached; a DNS resolution failure can
+request using the session is dispatched; a DNS resolution failure can
 only be detected at that time (using the <literal>NE_LOOKUP</literal>
 error code); see <xref linkend="ne_request_dispatch"/> for
 details.</para>
@@ -117,7 +117,7 @@ ne_session_destroy(sess);
       <refsect1>
 	<title>See Also</title>
 
-	<para><xref linkend="ne_ssl_set_verify"/>, <xref linkend="ne_ssl_load_ca"/>, <xref linkend="ne_sock_init"/></para>
+	<para><xref linkend="ne_ssl_set_verify"/>, <xref linkend="ne_ssl_trust_cert"/>, <xref linkend="ne_sock_init"/></para>
       </refsect1>
 
     </refentry>
diff --git a/doc/ref/shave.xml b/doc/ref/shave.xml
index a5b745a..914699d 100644
--- a/doc/ref/shave.xml
+++ b/doc/ref/shave.xml
@@ -32,7 +32,8 @@
 	<para><function>ne_shave</function> returns a portion of
 <parameter>str</parameter> with any leading or trailing characters in
 the <parameter>whitespace</parameter> array removed.
-<parameter>str</parameter> may be modified.</para>
+<parameter>str</parameter> may be modified.  Note that the return
+value may not be equal to <parameter>str</parameter>.</para>
 
       </refsect1>
 
diff --git a/doc/ref/sslcert.xml b/doc/ref/sslcert.xml
index 46dbffd..d2d0376 100644
--- a/doc/ref/sslcert.xml
+++ b/doc/ref/sslcert.xml
@@ -1,66 +1,111 @@
-    <refentry id="refsslcert">
-
-      <refmeta>
-	<refentrytitle>ne_ssl_certificate</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname id="ne_ssl_certificate">ne_ssl_certificate</refname>
-	<refname id="ne_ssl_dname">ne_ssl_dname</refname>
-	<refpurpose>structures representing SSL certificates</refpurpose>
-      </refnamediv>
-      
-      <refsynopsisdiv>
-
-	<funcsynopsis><funcsynopsisinfo>#include &lt;ne_session.h&gt;
-
-/* A simplified X.509 distinguished name. */
-typedef struct {
-    const char *country, *state, *locality, *organization;
-    const char *organizationalUnit;
-    const char *commonName;
-} <type>ne_ssl_dname</type>;
-
-/* A simplified SSL certificate. */
-typedef struct {
-    const <type>ne_ssl_dname</type> *subject, *issuer;
-    const char *from, *until;
-} <type>ne_ssl_certificate</type>;
-
-</funcsynopsisinfo></funcsynopsis>
-
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Description</title>
-	
-	<para>The <type>ne_ssl_dname</type> structure is used to
-represent a simplified X.509 distinguished name, as used in SSL
-certificates; a distinguished name is used to uniquely identify an
-entity.  Along with the fields giving the geographical and
-organizational location of the entity, the
-<structfield>commonName</structfield> field will be assigned the DNS
-hostname of the entity.  The
-<function>ne_ssl_readable_dname</function> function can be used to
-create a single-line string out of an <type>ne_ssl_dname</type>
-structure.</para>
-
-	<para>The <type>ne_ssl_certificate</type> structure is used to
-represent a simplified SSL certificate; containing the distinguished
-names of the <firstterm>issuer</firstterm> and
-<firstterm>subject</firstterm> of the certificate.  The issuer is the
-entity which has digitally signed the certificate to guarantee its
-authenticity; the subject is the owner of the certificate.  A
-certificate is only valid for a certain period of time: the
-<structfield>from</structfield> and <structfield>until</structfield>
-contain strings giving the validity period.</para>
-
-      </refsect1>
-
-      <refsect1>
-	<title>See Also</title>
-	<para><xref linkend="ne_ssl_dname"/>, <xref linkend="ne_ssl_set_verify"/></para>
-      </refsect1>
-
-    </refentry>
+<refentry id="refcert">
+
+  <refmeta>
+    <refentrytitle>ne_ssl_cert_identity</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_ssl_cert_identity">ne_ssl_cert_identity</refname>
+    <refname id="ne_ssl_cert_signedby">ne_ssl_cert_signedby</refname>
+    <refname id="ne_ssl_cert_issuer">ne_ssl_cert_issuer</refname>
+    <refname id="ne_ssl_cert_subject">ne_ssl_cert_subject</refname>
+    <refpurpose>functions to access certificate properties</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_ssl.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>const char *<function>ne_ssl_cert_identity</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>const ne_ssl_certificate *<function>ne_ssl_cert_signedby</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>const ne_ssl_dname *<function>ne_ssl_cert_subject</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>const ne_ssl_dname *<function>ne_ssl_cert_issuer</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The function <function>ne_ssl_cert_identity</function>
+    retrieves the <quote>identity</quote> of a certificate; for an
+    SSL server certificate, this will be the hostname for which the
+    certificate was issued.  In PKI parlance, the identity is the
+    <emphasis>common name</emphasis> attribute of the distinguished name of
+    the certificate subject.</para>
+
+    <para>The functions <function>ne_ssl_cert_subject</function> and
+    <function>ne_ssl_cert_issuer</function> can be used to access the
+    objects representing the distinguished name of the subject and of
+    the issuer of a certificate, respectively.</para>
+
+    <para>If a certificate object is part of a certificate chain, then
+    <function>ne_ssl_cert_signedby</function> can be used to find the
+    certificate which signed a particular certificate. For a
+    self-signed certificate or a certificate for which the full chain
+    is not available, this function will return &null;.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Return value</title>
+
+    <para><function>ne_ssl_cert_issuer</function> and
+    <function>ne_ssl_cert_subject</function> are guaranteed to never
+    return &null;. <function>ne_ssl_cert_identity</function> may
+    return &null; if the certificate has no specific
+    <quote>identity</quote>. <function>ne_ssl_cert_signedby</function>
+    may return &null; as covered above.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>The following function could be used to display information
+    about a given certificate:</para>
+
+    <programlisting>void dump_cert(const ne_ssl_certificate *cert) {
+  const char *id = ne_ssl_cert_identity(cert);
+  char *dn;
+
+  if (id) 
+    printf("Certificate was issued for '%s'.\n", id);
+
+  dn = ne_ssl_readable_dname(ne_ssl_cert_subject(cert));
+  printf("Subject: %s\n", dn);
+  free(dn);
+
+  dn = ne_ssl_readable_dname(ne_ssl_cert_issuer(cert));
+  printf("Issuer: %s\n", dn);
+  free(dn);
+}</programlisting>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+
+    <para><xref linkend="ne_ssl_cert_cmp"/>, <xref linkend="ne_ssl_readable_dname"/></para>
+  </refsect1>
+
+</refentry>
+
diff --git a/doc/ref/sslcert2.xml b/doc/ref/sslcert2.xml
new file mode 100644
index 0000000..216d294
--- /dev/null
+++ b/doc/ref/sslcert2.xml
@@ -0,0 +1,49 @@
+<refentry id="refsslcert2">
+
+  <refmeta>
+    <refentrytitle>ne_ssl_cert_cmp</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_ssl_cert_cmp">ne_ssl_cert_cmp</refname>
+    <refname id="ne_ssl_cert_free">ne_ssl_cert_free</refname>
+    <refpurpose>functions to operate on certificate objects</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_header.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>ne_ssl_cert_cmp</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>c1</parameter></paramdef>
+        <paramdef>const ne_ssl_certificate *<parameter>c2</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>ne_ssl_cert_free</function></funcdef>
+        <paramdef>ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <function>ne_ssl_cert_cmp</function> function can be
+    used to compare two certificate objects; it returns zero if they
+    refer to the same certificate, and non-zero otherwise.</para>
+
+    <para>The <function>ne_ssl_cert_free</function> function can be
+    used to destroy a certificate object when it is no longer
+    needed.</para>
+
+  </refsect1>
+
+</refentry>
+
diff --git a/doc/ref/sslcertio.xml b/doc/ref/sslcertio.xml
new file mode 100644
index 0000000..394045e
--- /dev/null
+++ b/doc/ref/sslcertio.xml
@@ -0,0 +1,95 @@
+<refentry id="refsslcertio">
+
+  <refmeta>
+    <refentrytitle>ne_ssl_cert_read</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_ssl_cert_read">ne_ssl_cert_read</refname>
+    <refname id="ne_ssl_cert_write">ne_ssl_cert_write</refname>
+    <refname id="ne_ssl_cert_import">ne_ssl_cert_import</refname>
+    <refname id="ne_ssl_cert_export">ne_ssl_cert_export</refname>
+    <refpurpose>functions to read or write certificates to and from files or strings</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_ssl.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>ne_ssl_certificate *<function>ne_ssl_cert_read</function></funcdef>
+        <paramdef>const char *<parameter>filename</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>ne_ssl_cert_write</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+        <paramdef>const char *<parameter>filename</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>ne_ssl_certificate *<function>ne_ssl_cert_import</function></funcdef>
+        <paramdef>const char *<parameter>data</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>char *<function>ne_ssl_cert_export</function></funcdef>
+        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <function>ne_ssl_cert_write</function> function writes a
+    certificate to a file using the PEM encoding.  The
+    <function>ne_ssl_cert_export</function> function returns a
+    base64-encoded &nul;-terminated string representing the
+    certificate.  This string is malloc-allocated and should be
+    destroyed using <function>free</function> by the caller.</para>
+
+    <para>The <function>ne_ssl_cert_read</function> function reads a
+    certificate from a PEM-encoded file, and returns a certificate
+    object.  The <function>ne_ssl_cert_import</function> function
+    returns a certificate object from a base64-encoded string,
+    <parameter>data</parameter>, as returned by
+    <function>ne_ssl_cert_export</function>.  The certificate object
+    returned by these functions should be destroyed using <xref
+    linkend="ne_ssl_cert_free"/> after use.</para>
+
+
+  </refsect1>
+
+  <refsect1>
+    <title>Return value</title>
+
+    <para><function>ne_ssl_cert_read</function> returns &null; if a
+    certificate could not be read from the file.
+    <function>ne_ssl_cert_write</function> returns non-zero if the
+    certificate could not be written to the file.
+    <function>ne_ssl_cert_export</function> always returns a
+    &nul;-terminated string, and never &null;.
+    <function>ne_ssl_cert_import</function> returns &null; if the
+    string was not a valid base64-encoded certificate.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Encoding Formats</title>
+
+    <para>The string produced by
+    <function>ne_ssl_cert_export</function> is the base64 encoding of
+    the DER representation of the certificate.  The file written by
+    <function>ne_ssl_cert_write</function> uses the PEM format: this
+    is the base64 encoding of the DER representation with newlines
+    every 64 characters, and start and end marker lines.</para>
+  </refsect1>
+
+</refentry>
+
diff --git a/doc/ref/ssldname.xml b/doc/ref/ssldname.xml
index accc2cb..e1fd454 100644
--- a/doc/ref/ssldname.xml
+++ b/doc/ref/ssldname.xml
@@ -51,16 +51,23 @@ creates a single-line, human-readable string out of an
       <refsect1>
 	<title>Return value</title>
 
-	<para><function>ne_ssl_readable_dname</function> returns a 
-	<function>malloc</function>-allocated string, and never
-	NULL.</para>
+	<para><function>ne_ssl_readable_dname</function> returns a <function>malloc</function>-allocated
+        string, and never &null;.</para>
+
+      </refsect1>
+
+      <refsect1>
+	<title>Examples</title>
+
+        <para>See <xref linkend="ne_ssl_cert_subject"/> for an example
+        use of <function>ne_ssl_readable_dname</function>.</para>
 
       </refsect1>
 
       <refsect1>
 	<title>See also</title>
 
-	<para><xref linkend="ne_ssl_certificate"/></para>
+	<para><xref linkend="ne_ssl_cert_subject"/></para>
       </refsect1>
 
     </refentry>
diff --git a/doc/ref/ssltrust.xml b/doc/ref/ssltrust.xml
new file mode 100644
index 0000000..5a22f50
--- /dev/null
+++ b/doc/ref/ssltrust.xml
@@ -0,0 +1,72 @@
+    <refentry id="refsslca">
+
+      <refmeta>
+	<refentrytitle>ne_ssl_trust_cert</refentrytitle>
+	<manvolnum>3</manvolnum>
+      </refmeta>
+
+      <refnamediv>
+	<refname id="ne_ssl_trust_cert">ne_ssl_trust_cert</refname>
+	<refname id="ne_ssl_trust_default_ca">ne_ssl_trust_default_ca</refname>
+	<refpurpose>functions to indicate that certificates are trusted</refpurpose>
+      </refnamediv>
+      
+      <refsynopsisdiv>
+	
+	<funcsynopsis>
+
+	  <funcsynopsisinfo>#include &lt;ne_session.h&gt;</funcsynopsisinfo>
+
+	  <funcprototype>
+	    <funcdef>void <function>ne_ssl_trust_cert</function></funcdef>
+	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
+	    <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
+	  </funcprototype>
+
+	  <funcprototype>
+	    <funcdef>void <function>ne_ssl_trust_default_ca</function></funcdef>
+	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
+	  </funcprototype>
+
+	</funcsynopsis>
+	
+      </refsynopsisdiv>
+
+      <refsect1>
+	<title>Description</title>
+
+	<para>To indicate that a given certificate is trusted by the
+user, the certificate object can be passed to
+<function>ne_ssl_trust_cert</function>.  The certificate object is
+duplicated internally and can subequently be destroyed.</para>
+
+	<para>The SSL library in use by &neon; may include a default
+set of CA certificates; calling the
+<function>ne_ssl_trust_default_ca</function> function will indicate
+that these CAs are trusted by the user.</para>
+
+      </refsect1>
+
+      <refsect1>
+	<title>Examples</title>
+
+	<para>Load the CA certificate stored in <filename>/path/to/cacert.pem</filename>:</para>
+	<programlisting>&egsess;
+ne_ssl_certificate *cert = ne_ssl_cert_read("/path/to/cacert.pem");
+
+if (cert) {
+   ne_ssl_trust_cert(sess, cert);
+   ne_ssl_cert_free(cert);
+} else {
+   printf("Could not load CA cert: %s\n", ne_get_error(sess));
+}</programlisting>
+      </refsect1>
+
+      <refsect1>
+	<title>See also</title>
+
+	<para><xref linkend="ne_ssl_cert_read"/>, <xref
+	linkend="ne_ssl_cert_import"/>, <xref
+	linkend="ne_ssl_cert_free"/></para> </refsect1>
+
+    </refentry>
diff --git a/doc/ref/sslvfy.xml b/doc/ref/sslvfy.xml
index 98f0054..b044d5b 100644
--- a/doc/ref/sslvfy.xml
+++ b/doc/ref/sslvfy.xml
@@ -1,4 +1,4 @@
-    <refentry id="refsslvfy">
+    <refentry id="refsslvfy"> <!-- -*- xml-mode -*- -->
 
       <refmeta>
 	<refentrytitle>ne_ssl_set_verify</refentrytitle>
@@ -19,7 +19,7 @@
 	  <!-- hard to put data type declarations here -->
 
 	  <funcprototype>
-	    <funcdef>typedef int (*<function>ne_ssl_verify_fn</function>)</funcdef>
+	    <funcdef>typedef int <function>ne_ssl_verify_fn</function></funcdef>
 	    <paramdef>void *<parameter>userdata</parameter></paramdef>
 	    <paramdef>int <parameter>failures</parameter></paramdef>
 	    <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
@@ -44,7 +44,7 @@ callback can be registered using
 <function>ne_ssl_set_verify</function>.  If such a callback is not
 registered, when a connection is established to an SSL server which
 does not present a certificate signed by a trusted CA (see <xref
-linkend="ne_ssl_load_ca"/>), or if the certificate presented is invalid in
+linkend="ne_ssl_trust_cert"/>), or if the certificate presented is invalid in
 some way, the connection will fail.</para>
 
 	<para>When the callback is invoked, the
@@ -54,35 +54,42 @@ is equal to the bit-wise OR of one or more of the following
 constants (and is guaranteed to be non-zero):</para>
 
 	<variablelist>
-	  <varlistentry><term><filename>NE_SSL_NOTYETVALID</filename></term>
+	  <varlistentry><term><constant>NE_SSL_NOTYETVALID</constant></term>
 	    <listitem>
-	      <para>The certificate is not yet valid.</para>
+	      <simpara>The certificate is not yet valid.</simpara>
 	    </listitem>
 	  </varlistentry>
-	  <varlistentry><term><filename>NE_SSL_EXPIRED</filename></term>
+	  <varlistentry><term><constant>NE_SSL_EXPIRED</constant></term>
 	    <listitem>
-	      <para>The certificate has expired.</para>
+	      <simpara>The certificate has expired.</simpara>
 	    </listitem>
 	  </varlistentry>
-	  <varlistentry><term><filename>NE_SSL_CNMISMATCH</filename></term>
+	  <varlistentry><term><constant>NE_SSL_IDMISMATCH</constant></term>
 	    <listitem>
-	      <para>The hostname used for the session does not match
-the hostname to which the certificate was issued: this could mean that
-the connection has been intercepted.</para>
+	      <simpara>The hostname used for the session does not match
+the hostname to which the certificate was issued.</simpara>
 	    </listitem>
 	  </varlistentry>
-	  <varlistentry><term><filename>NE_SSL_UNKNOWNCA</filename></term>
+	  <varlistentry><term><constant>NE_SSL_UNTRUSTED</constant></term>
 	    <listitem>
-	      <para>The Certificate Authority which signed the certificate
-is not trusted.</para>
+	      <simpara>The Certificate Authority which signed the certificate
+is not trusted.</simpara>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
+	<para>Note that if either of the
+	<constant>NE_SSL_IDMISMATCH</constant> or
+	<constant>NE_SSL_UNTRUSTED</constant> failures is given, the
+	connection may have been intercepted by a third party, and
+	must not be presumed to be <quote>secure</quote>.</para>
+
 	<para>The <parameter>cert</parameter> parameter passed to the
-callback describes the certificate which was presented by the server,
-see <xref linkend="ne_ssl_certificate"/> for more details.  The certificate
-object given is only valid until the callback returns.</para>
+callback represents the certificate which was presented by the server.
+If the server presented a chain of certificates, the chain can be
+accessed using <xref linkend="ne_ssl_cert_signedby"/>.  The
+<parameter>cert</parameter> object given is not valid after the
+callback returns.</para>
 
       </refsect1>
 
@@ -97,35 +104,51 @@ which case, the connection will fail).</para>
       <refsect1>
 	<title>Examples</title>
 
-	<para>Manual certificate verification:</para>
+	<para>The following code implements an example verification
+	callback, using the <function>dump_cert</function> function
+	from <xref linkend="ne_ssl_cert_subject"/> to display
+	certification information.  Notice that the hostname of the
+	server used for the session is passed as the
+	<parameter>userdata</parameter> parameter to the
+	callback.</para>
+
 	<programlisting>
 static int
 my_verify(void *userdata, int failures, const ne_ssl_certificate *cert)
 {
-   /* leak the return values of ne_ssl_readable_dname for simplicity! */
-   printf("Issuer: %s\n", ne_ssl_readable_dname(cert->issuer);
-   printf("Subject: %s\n", ne_ssl_readable_dname(cert->subject);
-   if (failures &amp; NE_SSL_CNMISMATCH) {
-      printf("Server certificate was issued to `%s'; "
-             "connection may have been intercepted!\n",
-             cert->subject->commonName);
-   }
-   if (failures &amp; NE_SSL_EXPIRED) {
-      printf("Server certificate expired on %s!", cert->until);
-   }
-   /* ... check for other failures ... */
-   if (prompt_user())
-      return 1; /* fail verification */
-   else
-      return 0; /* trust certificate */
+  const char *hostname = userdata;
+
+  dump_cert(cert);
+
+  puts("Certificate verification failed - the connection may have been "
+       "intercepted by a third party!");
+
+  if (failures &amp; NE_SSL_IDMISMATCH) { 
+    const char *id = ne_ssl_cert_identity(cert);
+    if (id) 
+      printf("Server certificate was issued to '%s' not '%s'.\n",
+             id, hostname);
+    else
+      printf("The certificate was not issued for '%s'\n", hostname);
+  }
+
+  if (failures &amp; NE_SSL_UNTRUSTED)
+    puts("The certificate is not signed by a trusted Certificate Authority.");
+
+  /* ... check for validity failures ... */
+
+  if (prompt_user())
+    return 1; /* fail verification */
+  else
+    return 0; /* trust the certificate anyway */
 }
 
 int
 main(...)
 {
-    ne_session *sess = ne_session_create("https", "some.host.name", 443);
-    ne_ssl_set_verify(sess, my_verify, NULL);
-    ...
+  ne_session *sess = ne_session_create("https", "some.host.name", 443);
+  ne_ssl_set_verify(sess, my_verify, "some.host.name");
+  ...
 }</programlisting>
 
       </refsect1>
@@ -133,8 +156,8 @@ main(...)
       <refsect1>
 	<title>See also</title>
 
-	<para><xref linkend="ne_ssl_certificate"/>, <xref linkend="ne_ssl_load_ca"/>, 
-        <xref linkend="ne_ssl_dname"/>, <xref linkend="ne_ssl_readable_dname"/></para>
+	<para><xref linkend="ne_ssl_trust_cert"/>, <xref
+	linkend="ne_ssl_readable_dname"/>, <xref linkend="ne_ssl_cert_subject"/></para>
       </refsect1>
 
-    </refentry>
+   </refentry>
diff --git a/doc/ref/status.xml b/doc/ref/status.xml
index 56616ea..fbc38b7 100644
--- a/doc/ref/status.xml
+++ b/doc/ref/status.xml
@@ -32,8 +32,12 @@ The <structfield>major_version</structfield> and
 supported by the server issuing the response.  The
 <structfield>code</structfield> field gives the status code of the
 result (lying between 100 and 999 inclusive), and the
-<structfield>klass</structfield> field gives the class, which is equal
-to the most significant digit of the status.</para>
+<structfield>klass</structfield> field gives the
+class<footnote><para>the field is named <quote>klass</quote> not
+<quote>class</quote> so that the header can be used from a C++
+program, in which <quote>class</quote> is a reserved
+word)</para></footnote>, which is equal to the most significant digit
+of the status.</para>
 
 	<para>There are five classes of HTTP status code defined by
 	RFC2616:</para>
@@ -41,28 +45,28 @@ to the most significant digit of the status.</para>
 	<variablelist>
 	  <varlistentry>
 	    <term><literal>1xx</literal></term>
-	    <listitem><para>Informational response.</para></listitem>
+	    <listitem><simpara>Informational response.</simpara></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>2xx</literal></term>
-	    <listitem><para>Success: the operation was successful</para></listitem>
+	    <listitem><simpara>Success: the operation was successful</simpara></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>3xx</literal></term>
-	    <listitem><para>Redirection</para></listitem>
+	    <listitem><simpara>Redirection</simpara></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
-	    <term><literal>4xx</literal></term> <listitem><para>Client
+	    <term><literal>4xx</literal></term> <listitem><simpara>Client
 	    error: the request made was incorrect in some
-	    manner.</para></listitem>
+	    manner.</simpara></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>5xx</literal></term>
-	    <listitem><para>Server error</para></listitem>
+	    <listitem><simpara>Server error</simpara></listitem>
 	  </varlistentry>
 	</variablelist>