openconnect/www/tncc.xml

<PAGE>
	<INCLUDE file="inc/header.tmpl" />

	<VAR match="VAR_SEL_FEATURES" replace="selected" />
	<VAR match="VAR_SEL_FEATURE_TNCC" replace="selected" />
	<PARSE file="menu1.xml" />
	<PARSE file="menu2-features.xml" />

	<INCLUDE file="inc/content.tmpl" />

<h1>Juniper Host Checker (tncc.jar)</h1>

<p>The Host Checker mechanism is a security scanner for the <a
href="juniper.html">Juniper</a> VPNs, in the same vein as <a
href="csd.html">Cisco's CSD</a> and <a href="hip.html">GlobalProtect's
HIP</a>. It is also used by the <a href="pulse.html">Pulse Secure</a>
protocol but support for running it with the Pulse protocol is not included
in OpenConnect yet.</p>

<h3>Background</h3>

<p>Many sites require a Java applet to run certain tests as a precondition
of authentication. This works by sending a <tt>DSPREAUTH</tt> cookie
to the client which is attempting to authenticate, and the Java code
in <tt>tncc.jar</tt> then runs and communicates with the server, handing
back a new value for the <tt>DSPREAUTH</tt> cookie to be used when
autnentication continues.</p>

<p>This Java applet is a black-box binary provided by a server outside
of the client's control, and therefore has similar security concerns to Cisco's CSD
trojan.</p>

<h2>TNCC support in OpenConnect</h2>

<p>OpenConnect supports running the Java binary, or emulating its
behaviour, by passing the <tt>--csd-wrapper=SCRIPT</tt> argument
with a shell script.</p>

<p>The OpenConnect distribution includes <i>two</i> alternative
scripts to support the execution or emulation of Host Checker, in
the <tt>trojans/</tt> subdirectory:</p>

<ul>
  <li><tt>tncc-wrapper.py</tt>: This Python 3.x wrapper script runs the actual <tt>tncc.jar</tt> binary,
  with a little assistance. Running this wrapper requires you to build <tt>tncc-preload.so</tt> from
  <a href="https://github.com/russdill/ncsvc-socks-wrapper">russdill/ncsvs-socks-wrapper on GitHub</a>.
  Because of the security dangers of executing a server-provided trojan binary, this script should ideally be executed
  with the permissions of a low-privilege user (e.g. <tt>--csd-user=nobody</tt>).</li>

  <li><p><tt>tncc-emulate.py</tt>: This Python 3.x script does <b>not</b> actually run the <tt>tncc.jar</tt> binary.
  Instead, it <i>emulates</i> the behaviour of the <tt>tncc.jar</tt> binary, rather than actually
  executing it. Because this script does not actually execute a server-provided binary, security concerns are greatly
  alleviated.</p>

  <p>It may require configuration or customization to work with VPNs that have modified
  the behaviour of their Host Checker binaries in some way; consult its source code for details, starting with the
  list of environment variables that may be set to overridden some of the data that it sends to the server.</p>

  <p>This script is based entirely on <a href="https://github.com/russdill/juniper-vpn-py"><tt>tncc.py</tt>
  from russdill/juniper-vpn-py on GitHub</a>.)</p></li>
</ul>

<p>With either of these scripts, it may also be necessary to pass a Mozilla-compatible user agent string:</p>
<pre>
  ./openconnect --protocol=nc --useragent 'Mozilla/5.0 (Linux) Firefox' --csd-wrapper=trojans/tncc-wrapper.py vpn.example.com
</pre>

<INCLUDE file="inc/footer.tmpl" />
</PAGE>