1stoken(1) General Commands Manual stoken(1)
2
6 stoken - software token for cryptographic authentication
7
9 stoken [tokencode] [--stdin] [--force] [--next] [opts]
10 stoken import {--file=file | --token=token_string} [--force] [opts]
12 stoken setpin [opts]
14 stoken setpass [opts]
16 stoken show [--seed] [opts]
18 stoken export [{--blocks | --iphone | --android | --v3 | --sdtid |
20 --qr=file.png | --show-qr}] [opts]
21 stoken issue [--template=file]
23 stoken help
25 stoken version
27
29 stoken is a software token compatible with RSA SecurID 128-bit (AES)
30 tokens. The command-line interface provides facilities for importing
31 new tokens, displaying the current tokencode, encrypting the seed with
32 a user-specified password, storing the user's PIN alongside the token,
33 and viewing or exporting the token data.
34
36 Use stoken import to decode a token string and write it into
37 ~/.stokenrc. This may prompt for a device ID and/or password,
38 depending on what options your administrator used to create the token.
39 The token string can be provided on the command line, or read from a
40 text file.
41 stoken will autodetect the following types of token strings:
43 286510182209303756117707012447003320623006...
45 29658-21098-45467-64675-65731-01441-11337...
46 Pure numeric (81-digit) "ctf" (compressed token format) strings,
47 with or without dashes. These may have been furnished as-is, or
48 they could have been derived from an sdtid file by the RSA
49 TokenConverter program.
50 com.rsa.securid.iphone://ctf?ctfData=229639330774927764401...
52 iPhone-compatible token strings.
53 http://127.0.0.1/securid/ctf?ctfData=250494932146245277466...
55 http://127.0.0.1/securid/ctf?ctfData=AwAAfBc3QSopPxxjLGnxf...
56 Android-compatible token strings.
57 <?xml version=...
59 RSA sdtid-formatted XML files. These should be imported from a
60 file: stoken import --file=FILE.SDTID.
61 Tokens supplied as QR codes can be converted back to standard URIs by
63 running zbarimg(1) on the image file.
64 The device ID, if used, can be viewed in the "about" menu for the RSA
66 soft token app on the phone. Numeric ctf strings and smartphone tokens
67 bound to a device ID contain a seed that is encrypted using the device
68 ID, so the ID must be furnished before stoken can successfully import
69 the token. sdtid files can be imported without knowledge of the device
70 ID, as long as the password (if any) is known.
71 By default, stoken import will refuse to overwrite an existing token in
73 ~/.stokenrc. The --force switch overrides this check.
74 stoken import will normally prompt for a new password, which is used to
76 encrypt the seed before storing it in ~/.stokenrc. This can be
77 bypassed by entering an empty password, or specifying --new-password=''
78 on the command line. It is recommended to choose a longer, hard-to-
79 guess passphrase for this purpose.
80 After a token has been imported, running stoken with no arguments will
82 prompt for any required password or PIN, then display the current
83 tokencode.
84 Tokencodes are computed from the raw (decrypted) seed data, the current
86 time of day, and the PIN. If the same seed is installed on multiple
87 devices, they should all produce identical tokencodes. If they do not,
88 double-check the timezone setting and consider using NTP to synchronize
89 the system time to a known good source.
90 stoken setpin can be used to save the PIN in ~/.stokenrc. Not all
92 tokens will require a PIN; this can be configured by the SecurID
93 administrator when generating new tokens. Setting an empty PIN will
94 remove the PIN from ~/.stokenrc so that the user will be prompted every
95 time it is required. See the SECURITY CONSIDERATIONS section below for
96 additional details.
97 stoken setpass encrypts the seed and PIN (if present) in ~/.stokenrc
99 with a user-selectable password or passphrase. If an empty password is
100 entered, the password will be removed. See the SECURITY CONSIDERATIONS
101 section below for additional details.
102
104 stoken show displays information about the current token, typically
105 read from ~/.stokenrc. The --seed option displays the encrypted and
106 decrypted seed bytes (which should be treated as sensitive data, as
107 they can be used to derive tokencodes).
108 stoken export translates the current token into a format suitable for
110 importation to another device.
111 stoken issue generates a new software token in XML sdtid format. A
113 template file, itself in sdtid format, may be provided to override some
114 or all of the human-readable fields. This would permit appropriate
115 serial numbers, expiration dates, usernames, etc. to be specified. If
116 Secret, Seed, or MAC fields are present in the template file, they will
117 be ignored.
118
120 --rcfile=file
121 Use an alternate .stokenrc configuration file. This is
122 typically used to support multiple tokens on the same user's
123 UNIX account. Note that the .stokenrc file stores additional
124 data (such as the PIN), so it cannot be parsed as a "raw" token
125 string by stoken --file.
126 --password=password, -p password
128 Use a password supplied from the command line, instead of
129 prompting the user. See notes in SECURITY CONSIDERATIONS below.
130 --pin=pin, -n pin
132 Use a PIN supplied from the command line, instead of prompting
133 the user. See notes in SECURITY CONSIDERATIONS below. If you
134 save your PIN in ~/.stokenrc, note that --pin=0000 is often
135 required when activating a new soft token for the first time.
136 --devid=devid
138 Use a device ID supplied from the command line to decrypt the
139 token. A token can be bound to a class GUID device ID (i.e. a
140 certain type of device, such as "iPhone" or "Android"), a unique
141 device ID (one specific unit), or nothing. stoken will attempt
142 to autodetect matches with a class GUID, but on rare occasions
143 this results in false positives due to hash collisions. In
144 these cases, the bound device ID should be specified on the
145 command line to override autodetection.
146
148 --new-password=password
149 Supply the encryption password from the command line for
150 operations that write out a token string or .stokenrc file:
151 import, export, setpass, and issue. See notes in SECURITY
152 CONSIDERATIONS below.
153 --keep-password
155 If the token in the .stokenrc file is protected with a password,
156 retain the same password when exporting the token. By default,
157 the export operation will not encrypt the token with a password;
158 note that it may not be possible to enter all possible passwords
159 on devices with limited text input capabilities (such as feature
160 phones).
161 --new-pin=pin
163 Supply a new PIN from the command line for the setpin operation.
164 See notes in SECURITY CONSIDERATIONS below.
165 --new-devid=devid
167 Used with the export or issue command to encrypt the new token
168 with a specific device ID. This is only used for testing
169 purposes.
170 --blocks, --iphone, --android, --v3
172 Used with the export command to select the output format. See
173 examples in BASIC USAGE. By default, the export command will
174 print an unformatted 81-digit string to standard output.
175 --sdtid, --xml
177 These options are synonyms. Both export a token to standard
178 output in RSA's sdtid XML format.
179 --qr=file.png
181 Encode the token as a QR code and write it to file.png. This
182 requires the qrencode program to be installed.
183 --show-qr
185 Encode the token as a QR code and immediately display it on the
186 screen. This requires the qrencode program to be installed. If
187 the QR_VIEWER environment variable is set, stoken will use that
188 program as the preferred viewer. Otherwise it will try to
189 execute a few common Linux image viewers, and give up if none of
190 them exist.
191 --template=file
193 Used with the export or issue commands to override fields in the
194 XML output. The template file should look like any standard
195 sdtid file, but all fields are optional and will default to
196 reasonably sane values if omitted. This can be used to force
197 the output XML to use a specific serial number, user name,
198 expiration date, etc. Correct MAC checksums will be
199 (re)computed on the provided values. See the examples directory
200 in the source distribution for more information.
201
203 --use-time={unix_time|+offset|-offset}
204 Instead of generating a tokencode based on the current time of
205 day, force a specific time, or adjust the current time based on
206 a positive or negative offset (specified in seconds). This is
207 only used for testing purposes.
208 --next Generate the next tokencode instead of the current tokencode.
210 For a 60-second token, this is equivalent to --use-time=+60.
211 --stdin, -s
213 When generating a tokencode that requires either a password or
214 PIN, read the password or PIN as single line from standard
215 input. This is intended to allow external programs to call
216 stoken to generate single-use passwords without user
217 intervention; see NON-INTERACTIVE USE below.
218 --force, -f
220 Override token expiration date checks (for tokencode) or token
221 overwrite checks (for import).
222 --batch, -b
224 Abort with an error exit code if any user input is required.
225 Intended for automated operation and testing.
226 --file=file
228 Read a ctf string, an Android/iPhone URI, or an XML sdtid token
229 from file instead of the .stokenrc configuration. Most stoken
230 commands accept this flag, but it is expected that the typical
231 user will save his token in ~/.stokenrc instead of supplying it
232 by hand on every invocation. Typically --file and --token are
233 only used for the import command.
234 --token=token_string
236 Use a token from the command line instead of the .stokenrc file.
237 See above notes on --file.
238 --random
240 Generate a random token on the fly. Used for testing or
241 demonstrations only. These tokens should not be used for real
242 authentication.
243 --help, -h
245 Display basic usage information.
246 --version, -v
248 Display version information.
249
251 Software tokens, unlike hardware tokens, are relatively easy to
252 replicate. Systems that store soft token seeds should be carefully
253 guarded to prevent unauthorized disclosure. The use of whole-disk
254 encryption, such as TrueCrypt, is strongly recommended for laptops and
255 other portable devices that are easily lost or stolen.
256 stoken permits users to store their PIN in ~/.stokenrc to allow for
258 automated (scriptable) generation of tokencodes, but the risks of this
259 approach should be carefully weighed against the benefits.
260 Using the setpass command to encrypt the seed and PIN in ~/.stokenrc
262 provides some degree of protection against unauthorized access, but
263 does not necessarily cover all possible attack vectors. A host that is
264 already compromised (e.g. running a keylogger) will not provide
265 adequate protection for any seed(s) stored on it.
266 stoken encryption passwords may be up to 40 characters long. A longer
268 passphrase constructed from several random words can provide more
269 protection from brute-force attacks than a shorter password.
270 Entering a password or PIN on the command line is generally unsafe on
272 multiuser systems, as other users may be able to view the command line
273 arguments in ps or similar utilities. The command line could also be
274 cached in shell history files.
275 Encoding QR tokens may expose the seed data through ps, and the
277 --show-qr option writes temporary PNG files in /tmp.
278 stoken attempts to lock pages to prevent swapping out to disk, but does
280 not scrub secrets from process memory.
281
283 Other applications, such as VPN clients, may want to invoke stoken non-
284 interactively to generate single-use passwords. Three usage modes are
285 supported, depending on the level of security (and/or convenience) that
286 is required:
287 No password or PIN
289 The user configures stoken to print a tokencode immediately upon
290 invocation, with no prompts, by using setpin to store the PIN in
291 ~/.stokenrc and using setpass to set an empty password. The other
292 application can then invoke stoken --batch and read the tokencode
293 through a pipe from standard output.
294 This provides no security for the seed, but may be useful in
296 applications where (re-)authentication is frequent or unattended
297 operation is required.
298 Save the PIN and set a password
300 The user configures stoken to encrypt the ~/.stokenrc secrets with a
301 password using setpass, then saves the PIN with setpin. The PIN and
302 the seed will both be encrypted with the password. The other
303 application will request the password from the user, then call stoken
304 --stdin, write the password to stoken's standard input through a pipe,
305 and read back a tokencode from stoken's standard output.
306 No password; prompt for the PIN
308 Similar to above, but set an empty password using setpass, do not save
309 the PIN in ~/.stokenrc, and pass the PIN to stoken --stdin via standard
310 input.
311
313 sdtid support is still new and may choke on unexpected input. As a
314 short-term workaround you can try commenting out the sanity checks in
315 sdtid_decrypt() to see if the problem goes away.
316 Features under development include: hardware token seeds (and the
318 stoken split command needed to work with them), and support for
319 non-Linux hosts.
320 Patches are always welcome.
322
324 stoken-gui(1).
325
327 ~/.stokenrc
328 Default configuration file.
329
331 Kevin Cernekee <cernekee@gmail.com>
332 2012-09-09 stoken(1)