openconnect/www/token.xml

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

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

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

<h1>One Time Password support</h1>

<p>OpenConnect supports three types of software tokens for automatically
generating one-time passwords:</p>
<ul>
  <li><a href="https://en.wikipedia.org/wiki/SecurID">RSA SecurID</a> tokens using
      <a href="http://stoken.sf.net/">libstoken</a></li>
  <li>OATH TOTP <i>(<a href="https://tools.ietf.org/html/rfc6238">RFC6238</a>)</i> tokens</li>
  <li>OATH HOTP <i>(<a href="https://tools.ietf.org/html/rfc4226">RFC4226</a>)</i> tokens</li>
</ul>
 <p>OATH HOTP/TOTP tokens are also supported in hardware by:</p>
 <ul><li><a href="https://developers.yubico.com/ykneo-oath/">ykneo-oath</a> applet on
 the <a href="https://www.yubico.com/products/yubikey-hardware/yubikey-neo/">Yubikey NEO</a>
 and similar devices</li></ul>

<p>On the command line, the token mode is specified with the <tt>--token-mode</tt>
argument, which can be one of <tt>rsa</tt>, <tt>totp</tt>, <tt>hotp</tt> or <tt>yubioath</tt>.</p>
<p>The token secret is provided with the <tt>--token-secret</tt>
argument, and the precise form it takes is dependent on the type of
token as described below.</p>
<p>For the <tt>openconnect</tt> command line program, if the first character of
the <tt>--token-secret</tt> value is / or @, the argument is interpreted as a
filename. The secret data will be loaded from <i>(and potentially saved back
to, in the case of HOTP tokens)</i> the specified file.</p>

<p>In each case, the automatic token generation will be tried twice before it
is automatically disabled and the user asked to enter tokencodes manually.</p>
<p>SecurID token codes will automatically fill in the primary password field in the
authentication form presented by the server, while OATH token codes will
fill in the secondary password field. This behaviour is empirically determined by
the requirements of the servers that we have tested with; if you find a configuration
in which it is not appropriate, please <a href="mail.html">let us know</a>.</p>

<h2>SecurID</h2>

<p>If no <tt>--token-secret</tt> argument is provided in SecurID mode, the
default <tt>.stokenrc</tt> file from the user's home directory will be used.
For the NetworkManager integration, this is a separate choice for the token
type — the UI has separate choices for <i>"RSA SecurID - read from ~/.stokenrc"</i> vs.
<i>"RSA SecurID - manually entered"</i>.</p>

<p>If a token is provided — either directly on the command line, as the contents
of a referenced file, or entered into the NetworkManager configuration dialog —
it may take one of the many forms accepted by the <tt>stoken import</tt> command:</p>
<ul>
  <li><b>286510182209303756117707012447003320623006...</b></li>
  <li><b>29658-21098-45467-64675-65731-01441-11337...</b><br/>
  Pure numeric (81-digit) "ctf" (compressed token format) strings,
  with or without dashes. These may have been furnished as-is, or
  they could have been derived from an sdtid file by the RSA
  TokenConverter program.</li>
   <li><b>com.rsa.securid.iphone://ctf?ctfData=229639330774927764401...</b><br/>
   iPhone-compatible token strings.</li>

   <li><b>http://127.0.0.1/securid/ctf?ctfData=250494932146245277466...</b></li>
   <li><b>http://127.0.0.1/securid/ctf?ctfData=AwAAfBc3QSopPxxjLGnxf...</b><br/>
   Android-compatible token strings.</li>

   <li><b>&amp;lt;?xml version=...</b><br/>
   RSA sdtid-formatted XML files. These should be generally be imported from a
   file: '<tt>--token-secret @<i>FILE.SDTID</i></tt>'</li>
</ul>
<p>Additionally, a filename <i>(prefixed by the <tt>@</tt> or <tt>/</tt> characters)</i>
may refer to a stoken rcfile. The default behaviour if no <tt>--token-secret</tt> file
is provided is therefore equivalent to:</p>
<ul>
  <li><b>@<i>${HOME}</i>/.stokenrc</b></li>
</ul>

<p>SecurID two-factor authentication is based on something you have (a
hardware or software token) and something you know (a 4-8 digit PIN code).
SecurID administrators can provision software tokens in three different
ways:</p>

<ul>
  <li><b>PIN included in tokencode computation</b><br/>
  In most deployments, the software token application will prompt the user for
  a PIN, and then use the PIN to help calculate an 8-digit tokencode by summing
  each of the lower digits (modulo 10).  The tokencode displayed by the app is
  then entered verbatim into the password field.</li>
  <li><b>PIN manually prepended to tokencode</b><br/>
  In other cases, the software token application will not prompt for a PIN; it
  will simply display a "bare" tokencode, often 6 digits long, similar to a
  SecurID hardware token (SID700 or equivalent).  In response to the
  <i>Password:</i> prompt, the user concatenates his PIN and the tokencode:
  <i>PIN &amp; Tokencode = Passcode</i>.</li>
  <li><b>No PIN</b><br/>
  In rare cases, the server is configured such that a PIN is not required at
  all.  In this case, the software token application does not prompt for a
  PIN and the user simply enters the tokencode into the password field.</li>
</ul>

<p>For the first case, OpenConnect will prompt for a PIN if the PIN has not
been saved in <tt>~/.stokenrc</tt> using the <tt>stoken setpin</tt> command.
Otherwise the saved PIN will automatically be used, permitting unattended
operation.  This works with all versions of libstoken.</p>

<p>For the second and third cases, OpenConnect will unconditionally prompt
for a PIN and concatenate the PIN with the generated tokencode.  If
appropriate, an empty PIN may be entered.  This requires libstoken v0.8 or
higher.</p>

<h2>TOTP (Time-Based One-Time Password)</h2>

<p>As with SecurID tokens, OATH TOTP tokens may be provided either directly on the command line, as the contents
of a referenced file, or entered into the NetworkManager configuration dialog.
They may be specified in one of the following forms:</p>

<ul>
  <li><b>SecretSecret!</b></li>
  <li><b>sha256:SecretSecret!</b></li>
  <li><b>sha512:SecretSecret!</b><br/>
  For secrets which are actually UTF-8 strings instead of entirely randomly generated
  data, they may be specified directly in this form.</li>
  <li><b>0x53656372657453656372657421</b></li>
  <li><b>sha256:0x53656372657453656372657421</b></li>
  <li><b>sha512:0x53656372657453656372657421</b><br/>
  This is the hexadecimal form which <i>(without the leading <tt>0x</tt>)</i> is
  accepted by default by the
  <tt><a href="https://www.nongnu.org/oath-toolkit/oathtool.1.html">oathtool</a></tt>
  program.</li>
  <li><b>base32:KNSWG4TFORJWKY3SMV2CC===</b></li>
  <li><b>sha256:base32:KNSWG4TFORJWKY3SMV2CC===</b></li>
  <li><b>sha512:base32:KNSWG4TFORJWKY3SMV2CC===</b><br/>
  This is the base32 form which is accepted by the
  <tt><a href="https://www.nongnu.org/oath-toolkit/oathtool.1.html">oathtool</a></tt>
  program with its <tt>-b</tt> option..</li>
  <li><b>&amp;lt;?xml version=...</b><br/>
  PSKC XML files conforming to <a href="https://tools.ietf.org/html/rfc6030">RFC6030</a>.
  These should be generally be imported from a file: '<tt>--token-secret @<i>FILE.PSKC</i></tt>'</li>
</ul>

<p>The default HMAC algorithm for TOTP tokens is SHA-1. SHA-256 and
SHA-512 are also supported; to use them prefix "<tt>sha256:</tt>" or
"<tt>sha512:</tt>" when explicitly providing a key on the command line.
Algorithms other than SHA-1 are not yet supported with PSKC files until
the relevant standards have been updated to indicate how they shall be
indicated in the PSKC file. See <a href="https://www.rfc-editor.org/errata_search.php?rfc=6238&amp;eid=4249">this erratum</a> to RFC6238 for current status.</p>



<h2>HOTP (HMAC-Based One-Time Password)</h2>

<p>HOTP tokens are very similar to TOTP tokens except that they are event-based, and
contain an additional <i>counter</i> which is incremented each time a token is
generated.</p>
<p>For HOTP tokens, the secret and counter may be provided in one of the following forms:</p>

<ul>
  <li><b>SecretSecret!,99</b></li>
  <li><b>0x53656372657453656372657421,99</b></li>
  <li><b>base32:KNSWG4TFORJWKY3SMV2CC===,99</b><br/>
  These correspond to the raw forms of the TOTP tokens given above, with the <i>counter</i>
  value appended in decimal form after a comma.</li>
  <li><b>&amp;lt;?xml version=...</b><br/>
  PSKC XML files conforming to <a href="https://tools.ietf.org/html/rfc6030">RFC6030</a> will
  contain the <i>counter</i> value.</li>
</ul>

<p>Although it is possible to specify HOTP tokens in their raw form
on the command line, that's not very useful because any updates to the <i>counter</i> field
will be discarded. Therefore it is advisable to use the <i>@filename</i> form of the
<tt>--token-secret</tt> argument, and the updated secret with incremented <i>counter</i>
value will be stored back to the file each time a token is generated.</p>
<p>The token will be stored back to the file in the same form that it was originally
provided.</p>

<p>Although NetworkManager-openconnect only supports direct token
entry <i>(you can't enter <tt>@filename</tt> into its GUI
configuration and expect that to work)</i>, versions which are new enough
to support HOTP will also have support for reading the updated counter values
back from <tt>libopenconnect</tt> and storing them to the NetworkManager VPN
configuration. So if you configure a VPN connection with a HOTP token secret of <tt>"0x1234,1"</tt>
and authenticate once, you should be able to go back into the configuration and see
that the token secret has been updated to <tt>"0x1234,2"</tt>.</p>

<p>HOTP tokens also support SHA-256 and SHA-512 in precisely the same
fashion as TOTP tokens, as described above.</p>
<h2>Yubikey HOTP/TOTP</h2>

<p>The <a href="https://developers.yubico.com/ykneo-oath/">ykneo-oath</a> applet
implements secure HOTP/TOTP support by storing the private key within the hardware
device so that it cannot be recovered.</p>

<p>The applet can store multiple credentials. If a <tt>--token-secret</tt> argument
is provided, it specifies the name of the credential which is to be used. Otherwise
OpenConnect will use the first credential found on the device.</p>

<p>Yubikey support is not yet implemented in NetworkManager.</p>

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