Skip to content
Permalink
Browse files
Update docs for GnuTLS and PKCS#11 support
Signed-off-by: David Woodhouse <David.Woodhouse@intel.com>
  • Loading branch information
David Woodhouse authored and David Woodhouse committed Jun 11, 2012
1 parent cd0472b commit e66e32b8973e960cace239f3e25c0fd4b8e2cb2f
Showing with 46 additions and 14 deletions.
  1. +5 −1 openconnect.8.in
  2. +8 −4 www/building.xml
  3. +1 −1 www/changelog.xml
  4. +20 −7 www/connecting.xml
  5. +1 −0 www/features.xml
  6. +11 −1 www/technical.xml
@@ -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
@@ -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
@@ -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/>
@@ -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>
@@ -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>
@@ -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>

0 comments on commit e66e32b

Please sign in to comment.