Provided by: stoken_0.2-1_amd64 
NAME
stoken - software token for cryptographic authentication
SYNOPSIS
stoken [tokencode] [--stdin] [--force] [opts]
stoken import {--file=path|--token=token_string} [--force] [opts]
stoken setpin [opts]
stoken setpass [opts]
stoken show [--seed] [opts]
stoken export [{--blocks|--iphone|--android}] [opts]
stoken help
stoken version
DESCRIPTION
stoken is a software token compatible with RSA SecurID 128-bit (AES) tokens. The command-line interface
provides facilities for importing new tokens, displaying the current tokencode, encrypting the seed with
a user-specified password, storing the user's PIN alongside the token, and viewing or exporting the token
data.
BASIC USAGE
Use stoken import to decode a token string and write it into ~/.stokenrc. This may prompt for a device
ID and/or password, depending on what options your administrator used to create the token. The token
string can be provided on the command line, or read from a text file.
stoken will autodetect the following types of token strings:
286510182209303756117707012447003320623006...
29658-21098-45467-64675-65731-01441-11337...
Pure numeric (81-digit) 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...
Android-compatible token strings.
The device ID, if used, can be viewed in the "about" menu for the RSA soft token app on the phone.
By default, stoken import will refuse to overwrite an existing token in ~/.stokenrc. The --force switch
overrides this check.
stoken import will normally prompt for a new password, which is used to encrypt the seed before storing
it in ~/.stokenrc. This can be bypassed by entering an empty password, or specifying --new-password=''
on the command line. It is recommended to choose a longer, hard-to-guess passphrase for this purpose.
After a token has been imported, running stoken with no arguments will prompt for any required password
or PIN, then display the current tokencode.
Tokencodes are computed from the raw (decrypted) seed data, the current time of day, and the PIN. If the
same seed is installed on multiple devices, they should all produce identical tokencodes. If they do
not, double-check the timezone setting and consider using NTP to synchronize the system time to a known
good source.
stoken setpin can be used to save the PIN in ~/.stokenrc. Not all tokens will require a PIN; this can be
configured by the SecurID administrator when generating new tokens. Setting an empty PIN will remove the
PIN from ~/.stokenrc so that the user will be prompted every time it is required. See the SECURITY
CONSIDERATIONS section below for additional details.
stoken setpass encrypts the seed and PIN (if present) in ~/.stokenrc with a user-selectable password or
passphrase. If an empty password is entered, the password will be removed. See the SECURITY
CONSIDERATIONS section below for additional details.
VIEWING TOKENS
stoken show displays information about the current token, typically read from ~/.stokenrc. The --seed
option displays the encrypted and decrypted seed bytes (which should be treated as sensitive data, as
they can be used to derive tokencodes).
stoken export translates the current token into a format suitable for importation to another device.
GLOBAL OPTIONS
--rcfile=file
Use an alternate .stokenrc file. This is typically used to support multiple tokens on the same
user account.
--password=password, -p password
Use a password supplied from the command line, instead of prompting the user. See notes in
SECURITY CONSIDERATIONS below.
--pin=pin, -n pin
Use a PIN supplied from the command line, instead of prompting the user. See notes in SECURITY
CONSIDERATIONS below. If you save your PIN in ~/.stokenrc, note that --pin=0000 is often required
when activating a new soft token for the first time.
OTHER OPTIONS
--new-password=password
Supply the encryption password from the command line for operations that write out a token string
or .stokenrc file: import, export, and setpass. See notes in SECURITY CONSIDERATIONS below.
--keep-password
If the token in the .stokenrc file is protected with a password, retain the same password when
exporting the token. By default, the export operation will not encrypt the token with a password;
note that it may not be possible to enter all possible passwords on devices with limited text
input capabilities (such as feature phones).
--new-pin=pin
Supply a new PIN from the command line for the setpin operation. See notes in SECURITY
CONSIDERATIONS below.
--new-devid=devid
Used with the export command to encrypt the new token with a specific device ID. This is only
used for testing purposes.
--blocks, --iphone, --android
Used with the export command to select the output format. See examples in BASIC USAGE. By
default, the export command will print an unformatted 81-digit string to standard output.
--use-time={unix_time|+offset|-offset}
Instead of generating a tokencode based on the current time of day, force a specific time, or
adjust the current time based on a positive or negative offset (specified in seconds). This is
only used for testing purposes.
--stdin, -s
When generating a tokencode that requires either a password or PIN, read the password or PIN as
single line from standard input. This is intended to allow external programs to call stoken to
generate single-use passwords without user intervention; see NON-INTERACTIVE USE below.
--force, -f
Override token expiration date checks (for tokencode) or token overwrite checks (for import).
--batch, -b
Abort with an error exit code if any user input is required. Intended for automated operation and
testing.
--file=file
Use a token from file instead of the .stokenrc file. Most stoken commands accept this flag, but
it is expected that the typical user will save his token in ~/.stokenrc instead of supplying it by
hand on every invocation. Typically --file and --token are only used for the import command.
--token=token_string
Use a token from the command line instead of the .stokenrc file. See above notes on --file.
--random
Generate a random token on the fly. Used for testing or demonstrations only. These tokens should
not be used for real authentication.
--help, -h
Display basic usage information.
--version, -v
Display version information.
SECURITY CONSIDERATIONS
Software tokens, unlike hardware tokens, are relatively easy to replicate. Systems that store soft token
seeds should be carefully guarded to prevent unauthorized disclosure. The use of whole-disk encryption,
such as TrueCrypt, is strongly recommended for laptops and other portable devices that are easily lost or
stolen.
stoken permits users to store their PIN in ~/.stokenrc to allow for automated (scriptable) generation of
tokencodes, but the risks of this approach should be carefully weighed against the benefits.
Using the setpass command to encrypt the seed and PIN in ~/.stokenrc provides some degree of protection
against unauthorized access, but does not necessarily cover all possible attack vectors. A host that is
already compromised (e.g. running a keylogger) will not provide adequate protection for any seed(s)
stored on it.
stoken encryption passwords may be up to 40 characters long. A longer passphrase constructed from
several random words can provide more protection from brute-force attacks than a shorter password.
Entering a password or PIN on the command line is generally unsafe on multiuser systems, as other users
may be able to view the command line arguments in ps or similar utilities. The command line could also
be cached in shell history files.
stoken attempts to lock pages to prevent swapping out to disk, but does not scrub secrets from process
memory.
NON-INTERACTIVE USE
Other applications, such as VPN clients, may want to invoke stoken non-interactively to generate single-
use passwords. Three usage modes are supported, depending on the level of security (and/or convenience)
that is required:
No password or PIN
The user configures stoken to print a tokencode immediately upon invocation, with no prompts, by using
setpin to store the PIN in ~/.stokenrc and using setpass to set an empty password. The other application
can then invoke stoken --batch and read the tokencode through a pipe from standard output.
This provides no security for the seed, but may be useful in applications where (re-)authentication is
frequent or unattended operation is required.
Save the PIN and set a password
The user configures stoken to encrypt the ~/.stokenrc secrets with a password using setpass, then saves
the PIN with setpin. The PIN and the seed will both be encrypted with the password. The other
application will request the password from the user, then call stoken --stdin, write the password to
stoken's standard input through a pipe, and read back a tokencode from stoken's standard output.
No password; prompt for the PIN
Similar to above, but set an empty password using setpass, do not save the PIN in ~/.stokenrc, and pass
the PIN to stoken --stdin via standard input.
SEE ALSO
stoken-gui(1).
FILES
~/.stokenrc
Default configuration file.
AUTHOR
Kevin Cernekee <cernekee@gmail.com>
2012-09-09 stoken(1)