NAME¶
stoken - software token for cryptographic authentication
SYNOPSIS¶
stoken [
tokencode] [
--stdin] [
--force]
[
opts]
stoken import {
--file=file|--token=token_string}
[--force] [opts]
stoken setpin [
opts]
stoken setpass [
opts]
stoken show [
--seed] [
opts]
stoken export [{
--blocks|
--iphone|
--android|
--v3|
--sdtid}]
[
opts]
stoken issue [--
template=
file]
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) "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 imported from a
file: stoken import --file=FILE.SDTID.
Tokens supplied as QR codes can be converted back to standard URIs by running
zbarimg(1) on the image file.
The device ID, if used, can be viewed in the "about" menu for the RSA
soft token app on the phone. Numeric ctf strings and smartphone tokens bound
to a device ID contain a seed that is encrypted using the device ID, so the ID
must be furnished before stoken can successfully import the token.
sdtid files can be imported without knowledge of the device ID, as long
as the password (if any) is known.
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. It can be used in conjunction with
qrencode(1) to send a token to a smartphone:
qrencode -l H `stoken export --random --android` -o - | display -
stoken issue generates a new software token in XML
sdtid format. A
template file, itself in
sdtid format, may be provided to override some
or all of the human-readable fields. This would permit appropriate serial
numbers, expiration dates, usernames, etc. to be specified. If Secret, Seed,
or MAC fields are present in the template file, they will be ignored.
GLOBAL OPTIONS¶
- --rcfile=file
- Use an alternate .stokenrc configuration file. This is typically
used to support multiple tokens on the same user's UNIX account. Note that
the .stokenrc file stores additional data (such as the PIN), so it
cannot be parsed as a "raw" token string by stoken
--file.
- --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, setpass, and issue. 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 or issue command to encrypt the new
token with a specific device ID. This is only used for testing
purposes.
- --blocks, --iphone, --android, --v3
- 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.
- --sdtid, --xml
- These options are synonyms. Both export a token to standard output in
RSA's sdtid XML format.
- --template=file
- Used with the export or issue commands to override fields in
the XML output. The template file should look like any standard
sdtid file, but all fields are optional and will default to
reasonably sane values if omitted. This can be used to force the output
XML to use a specific serial number, user name, expiration date, etc.
Correct MAC checksums will be (re)computed on the provided values. See the
examples directory in the source distribution for more
information.
- --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
- Read a ctf string, an Android/iPhone URI, or an XML sdtid token
from file instead of the .stokenrc configuration. 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.
BUGS/TODO¶
sdtid support is still new and may choke on unexpected input. As a
short-term workaround you can try commenting out the sanity checks in
sdtid_decrypt() to see if the problem goes away.
Features under development include: 30-second tokens, v3 ctf strings, hardware
token seeds (and the
stoken split command needed to work with them),
and support for non-Linux hosts.
Patches are always welcome.
SEE ALSO¶
stoken-gui(1).
FILES¶
- ~/.stokenrc
- Default configuration file.
AUTHOR¶
Kevin Cernekee <cernekee@gmail.com>