Update docs for GnuTLS and PKCS#11 support

Signed-off-by: David Woodhouse <David.Woodhouse@intel.com>

openconnect.8.in

@@ -101,15 +101,19 @@ when backgrounding
 .B \-c,\-\-certificate=CERT
 Use SSL client certificate
 .I CERT
+which may be either a file name or, if OpenConnect has been built with an appropriate
+version of GnuTLS, a PKCS#11 URL.
 .TP
 .B \-e,\-\-cert\-expire\-warning=DAYS
 Give a warning when SSL client certificate has
 .I DAYS
 left before expiry
 .TP
 .B \-k,\-\-sslkey=KEY
-Use SSL private key file
+Use SSL private key
 .I KEY
+which may be either a file name or, if OpenConnect has been built with an appropriate
+version of GnuTLS, a PKCS#11 URL.
 .TP
 .B \-C,\-\-cookie=COOKIE
 Use WebVPN cookie

www/building.xml

@@ -25,7 +25,7 @@ libraries and tools installed:</p>
 <ul>
   <li><b><tt>libxml2</tt></b></li>
   <li><b><tt>zlib</tt></b></li>
-  <li><b><tt>OpenSSL</tt></b></li>
+  <li>Either <b><tt>OpenSSL</tt></b> or <b><tt>GnuTLS</tt></b></li>
   <li><b><tt>pkg-config</tt></b></li>
 </ul>
 And <em>optionally</em> also:
@@ -39,9 +39,9 @@ environment, without having to manually give it the <tt>--proxy</tt> argument
 on the command line.</p>
 
 <h2>Install vpnc-script</h2>
- <p>Since version 3.17, OpenConnect automatically uses a <a href="vpnc-script.html">vpnc-script</a>
- to configure the network. It needs to be told where that script is, when it is
- being compiled.</p>
+ <p>Since version 3.17, The <a href="vpnc-script.html">vpnc-script</a> that OpenConnect
+ uses to configure the network is no longer optional, so it needs to be told at compile
+ time where to find that script.</p>
  <p>The <tt>configure</tt> script will check whether <tt>/etc/vpnc/vpnc-script</tt>
  exists and can be executed, and will fail if not. If you don't already have
  a copy then you should install one. It might be in a separate <tt>vpnc-script</tt>
@@ -69,6 +69,10 @@ well without it, so you'll still have to install it later.</p>
     <li><tt>make install</tt> <i>(If you want to install it)</i></li>
   </ul>
 
+<p>Note that OpenConnect will attempt to use the OpenSSL library by default.
+If you want it to use GnuTLS instead, then add <tt>--with-gnutls</tt> to the
+<tt>./configure</tt> command above.</p>
+
 <p>If compilation fails, please make sure you have a working compiler and the
 <b>development</b> packages for all the required libraries mentioned above. If
 it still doesn't build, please send the full output in a plain-text mail to the

www/changelog.xml

@@ -20,7 +20,7 @@
        <li>Enable PKCS#11 token support when built with GnuTLS.</li>
        <li>Eliminate all SSL library exposure through <tt>libopenconnect</tt>.</li>
        <li>Parse split DNS information, provide <tt>$CISCO_SPLIT_DNS</tt> environment variable to <tt>vpnc-script</tt>.</li>
-       <li>Attempt to provide new-style MTU information to server.</li>
+       <li>Attempt to provide new-style MTU information to server <i>(on Linux only, unless specified on command line)</i>.</li>
        <li>Allow building against GnuTLS, including DTLS support.</li>
        <li>Add <tt>--with-pkgconfigdir=</tt> option to <tt>configure</tt> for FreeBSD's benefit <i>(<a href="https://bugs.freedesktop.org/show_bug.cgi?id=48743">fd#48743</a>)</i>.</li>
      </ul><br/>

www/connecting.xml

@@ -14,19 +14,32 @@
 
 <p>Once you have <a href="building.html">installed</a> OpenConnect and checked that you have a
 <a href="vpnc-script.html">vpnc-script</a> which will set up the routing and DNS for it, using OpenConnect
- is very simple. As root, run the following command:<br/>
-      <tt>openconnect --script /etc/vpnc/vpnc-script https://vpn.mycompany.com/</tt>
+ is very simple. As root, run the following command:
+ <ul>
+   <li><tt>openconnect https://vpn.mycompany.com/</tt></li>
+ </ul>
     </p>
 
-That should be it, if you have a password-based login. If you use
+<p>That should be it, if you have a password-based login. If you use
 certificates, you'll need to tell OpenConnect where to find the
-certificate with the <tt>-c</tt> option. You might need to steal the
+certificate with the <tt>-c</tt> option.</p>
+
+<p>You can provide the certificate either as the file name of a PKCS#12 or PEM file,
+or if OpenConnect is built against a suitable version of GnuTLS you can provide the
+certificate in the form of a PKCS#11 URL:
+<ul>
+  <li><tt>openconnect -c certificate.pem https://vpn.mycompany.com/</tt></li>
+  <li><tt>openconnect -c pkcs11:id=X_%b04%c3%85%d4u%e7%0b%10v%08%c9%0dA%8f%3bl%df https://vpn.mycompany.com/</tt></li>
+</ul>
+</p>
+
+<p>You might need to steal the
 certificate from your Windows certificate store using a tool like <a
-href="http://www.isecpartners.com/application-security-tools/jailbreak.html">Jailbreak</a>.
+href="http://www.isecpartners.com/application-security-tools/jailbreak.html">Jailbreak</a>.</p>
 <p>
 To start with, you can ignore anything you see in the <a href="technical.html">technical</a>
-page about needing to patch OpenSSL so that DTLS works &#8212; you
-don't really need it, although it will make your connections much
+page about needing to patch OpenSSL or GnuTLS so that DTLS works &#8212; you
+can survive without it, although DTLS will make your connections much
 faster if you're experiencing packet loss between you and the VPN
 server. But you can worry about that later.
 </p>

www/features.xml

@@ -12,6 +12,7 @@
 	<h1>Features</h1>
 
 <ul>
+  <li>Use of SSL certificates from smart cards / PKCS#11 tokens <i>(when built with GnuTLS)</i> or from TPM <i>(when built with OpenSSL)</i>.</li>
   <li>Connection through HTTP proxy, including <a href="http://code.google.com/p/libproxy/">libproxy</a> support for automatic proxy configuration.</li>
   <li>Connection through SOCKS5 proxy.</li>
   <li>Automatic detection of IPv4 and IPv6 address, routes.</li>

www/technical.xml

@@ -27,14 +27,15 @@ datagrams, and will only <em>actually</em> pass traffic over the HTTPS
 connection if that fails. The UDP connectivity is done using Datagram
 TLS, which is supported by OpenSSL.</p>
 
-<h2>OpenSSL/DTLS compatibility</h2>
+<h2>DTLS compatibility</h2>
 
 <p><i><b>Note: DTLS is optional and not required for basic connectivity, as explained above.</b></i></p>
 
 <p>Unfortunately, Cisco used an old version of OpenSSL for their server,
 which predates the official RFC and has a few differences in the
 implementation of DTLS.
 </p>
+<h3>OpenSSL</h3>
 <p>Compatibility support for their "speshul" version of the protocol is
 in the 0.9.8m and later releases of OpenSSL (and 1.0.0-beta2 and later).
 </p>
@@ -52,5 +53,14 @@ For versions older than 0.9.8j, some generic DTLS bug fixes are also required:
 </ul>
 The username/password for OpenSSL RT is 'guest/guest'
 
+<h3>GnuTLS</h3>
+
+<p>Support for Cisco's version of DTLS was included in GnuTLS in June 2012, in
+<a href="http://git.savannah.gnu.org/gitweb/?p=gnutls.git;a=commitdiff;h=fd5ca1afb">
+commit fd5ca1af</a> which will be part of GnuTLS 3.1.</p>
+
+<p>The same patch will hopefully also be applied to the GnuTLS 3.0.x release branch
+for 3.0.21, or it can be applied manually from <a href="http://git.infradead.org/users/dwmw2/gnutls.git/commitdiff_plain/436135d727cbfb1673f0c308869a6c15b2e17697">here</a>.</p>
+
 	<INCLUDE file="inc/footer.tmpl" />
 </PAGE>