/usr/share/doc/openconnect/html/token.html is in openconnect 7.08-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>OpenConnect VPN client.</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="VPN client compatible with Cisco AnyConnect SSL VPN" />
<meta name="keywords" content="OpenConnect, AnyConnect, Cisco, VPN, SSLVPN, SSL VPN" />
<link href="./styles/main.css" rel="styleSheet" type="text/css" />
<link href='http://fonts.googleapis.com/css?family=Raleway' rel='stylesheet' type='text/css' />
</head>
<body>
<div id="logo" align="right">
<img src="./images/openconnect.png" height="96px" alt="OpenConnect" />
</div>
<div id="main">
<div id="menu1">
<span class="nonsel">
<a href="index.html"><span>Home</span></a>
</span>
<span class="sel">
<a href="features.html"><span>Features</span></a>
</span>
<span class="nonsel">
<a href="building.html"><span>Getting Started</span></a>
</span>
<span class="nonsel">
<a href="mail.html"><span>Mailing List / Help</span></a>
</span>
<span class="nonsel">
<a href="contribute.html"><span>Contribute</span></a>
</span>
<span class="nonsel">
<a href="anyconnect.html"><span>Protocols</span></a>
</span>
<span class="nonsel">
<a href="http://www.infradead.org/ocserv/"><span>VPN Server</span></a>
</span>
<p>OpenConnect VPN client</p>
</div>
<div id="menu2">
<span class="nonsel">
<a href="features.html"><span>Feature list</span></a>
</span>
<span class="nonsel">
<a href="nonroot.html"><span>Running as non-root user</span></a>
</span>
<span class="nonsel">
<a href="csd.html"><span>Cisco Secure Desktop</span></a>
</span>
<span class="nonsel">
<a href="gui.html"><span>GUI</span></a>
</span>
<span class="nonsel">
<a href="charset.html"><span>Character sets</span></a>
</span>
<span class="sel">
<a href="token.html"><span>One Time Passwords</span></a>
</span>
<span class="nonsel">
<a href="pkcs11.html"><span>Smart Cards / PKCS#11</span></a>
</span>
<span class="nonsel">
<a href="tpm.html"><span>Trusted Platform Module (TPM)</span></a>
</span>
</div>
<div id="textbox">
<div id="text">
</div>
<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="http://en.wikipedia.org/wiki/SecurID">RSA SecurID</a> tokens using
<a href="http://stoken.sourceforge.net/">libstoken</a></li>
<li>OATH TOTP <i>(<a href="http://tools.ietf.org/html/rfc6238">RFC6238</a>)</i> tokens</li>
<li>OATH HOTP <i>(<a href="http://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 specifed 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><?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>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 & 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="http://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="http://www.nongnu.org/oath-toolkit/oathtool.1.html">oathtool</a></tt>
program with its <tt>-b</tt> option..</li>
<li><b><?xml version=...</b><br />
PSKC XML files conforming to <a href="http://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="http://www.rfc-editor.org/errata_search.php?rfc=6238&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><?xml version=...</b><br />
PSKC XML files conforming to <a href="http://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>
</div>
</div>
</body>
</html>
|