# One Time Password support

OpenConnect supports three types of software tokens for automatically generating one-time passwords:

- RSA SecurID tokens using libstoken
- OATH TOTP (RFC6238) tokens
- OATH HOTP (RFC4226) tokens

OATH HOTP/TOTP tokens are also supported in hardware by:

- ykneo-oath applet on the Yubikey NEO and similar devices

On the command line, the token mode is specified with the `--token-mode` argument, which can be one of `rsa`, `totp`, `hotp` or `yubioath`.

The token secret is provided with the `--token-secret` argument, and the precise form it takes is dependent on the type of token as described below.

For the `openconnect` command line program, if the first character of the `--token-secret` value is / or @, the argument is interpreted as a filename. The secret data will be loaded from (and potentially saved back to, in the case of HOTP tokens) the specified file.

In each case, the automatic token generation will be tried twice before it is automatically disabled and the user asked to enter tokencodes manually.

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 let us know.

## SecurID

If no `--token-secret` argument is provided in SecurID mode, the default `.stokenrc` 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 "RSA SecurID - read from ~/.stokenrc" vs. "RSA SecurID - manually entered".

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 `stoken import` command:

- 286510182209303756117707012447003320623006...
- 29658-21098-45467-64675-65731-01441-11337...
  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.
- com.rsa.securid.iphone://ctf?ctfData=229639330774927764401...
  iPhone-compatible token strings.
- http://127.0.0.1/securid/ctf?ctfData=250494932146245277466...
- http://127.0.0.1/securid/ctf?ctfData=AwAAfBc3QSopPxxjLGnxf...
  Android-compatible token strings.
- <?xml version=...
  RSA sdtid-formatted XML files. These should be generally be imported from a file: '`--token-secret @FILE.SDTID`'

Additionally, a filename (prefixed by the `@` or `/` characters) may refer to a stoken rcfile. The default behaviour if no `--token-secret` file is provided is therefore equivalent to:

- @${HOME}/.stokenrc

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:

- PIN included in tokencode computation
  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.
- PIN manually prepended to tokencode
  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 Password: prompt, the user concatenates his PIN and the tokencode: PIN & Tokencode = Passcode.
- No PIN
  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.

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

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.

## TOTP (Time-Based One-Time Password)

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:

- SecretSecret!
- sha256:SecretSecret!
- sha512:SecretSecret!
  For secrets which are actually UTF-8 strings instead of entirely randomly generated data, they may be specified directly in this form.
- 0x53656372657453656372657421
- sha256:0x53656372657453656372657421
- sha512:0x53656372657453656372657421
  This is the hexadecimal form which (without the leading `0x`) is accepted by default by the `oathtool` program.
- base32:KNSWG4TFORJWKY3SMV2CC===
- sha256:base32:KNSWG4TFORJWKY3SMV2CC===
- sha512:base32:KNSWG4TFORJWKY3SMV2CC===
  This is the base32 form which is accepted by the `oathtool` program with its `-b` option..
- <?xml version=...
  PSKC XML files conforming to RFC6030. These should be generally be imported from a file: '`--token-secret @FILE.PSKC`'
- otpauth://totp/Issuer:user@example.com?secret=BASE32SECRET&period=30&algorithm=SHA256&issuer=Issuer
  The `otpauth://` URI format as used by Google Authenticator and other token apps. The `secret` parameter (base32-encoded) is mandatory; `period` (default 30), `algorithm` (SHA1, SHA256, SHA512), and `issuer` are optional. This is the format typically provided by QR codes for token enrollment.

The default HMAC algorithm for TOTP tokens is SHA-1. SHA-256 and SHA-512 are also supported; to use them prefix "`sha256:`" or "`sha512:`" 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 this erratum to RFC6238 for current status.

The default TOTP time step is 30 seconds. Tokens with a non-standard period (e.g. 60 seconds) will need to use the `otpauth://` URI format or a PSKC file to specify the period; the other secret formats do not carry this information.

## HOTP (HMAC-Based One-Time Password)

HOTP tokens are very similar to TOTP tokens except that they are event-based, and contain an additional counter which is incremented each time a token is generated.

For HOTP tokens, the secret and counter may be provided in one of the following forms:

- SecretSecret!,99
- 0x53656372657453656372657421,99
- base32:KNSWG4TFORJWKY3SMV2CC===,99
  These correspond to the raw forms of the TOTP tokens given above, with the counter value appended in decimal form after a comma.
- <?xml version=...
  PSKC XML files conforming to RFC6030 will contain the counter value.
- otpauth://hotp/Issuer:user@example.com?secret=BASE32SECRET&counter=0&algorithm=SHA256&issuer=Issuer
  The `otpauth://` URI format. The `counter` parameter specifies the current counter value and will be updated when the token is used.

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 counter field will be discarded. Therefore it is advisable to use the @filename form of the `--token-secret` argument, and the updated secret with incremented counter value will be stored back to the file each time a token is generated.

The token will be stored back to the file in the same form that it was originally provided.

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

HOTP tokens also support SHA-256 and SHA-512 in precisely the same fashion as TOTP tokens, as described above.

## Yubikey HOTP/TOTP

The ykneo-oath applet implements secure HOTP/TOTP support by storing the private key within the hardware device so that it cannot be recovered.

The applet can store multiple credentials. If a `--token-secret` 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.

Yubikey support is not yet implemented in NetworkManager.