OpenConnect supports three types of software tokens for automatically generating one-time passwords:
OATH HOTP/TOTP tokens are also supported in hardware by:
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.
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:
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:
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:
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.
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:
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.
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:
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.
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.