Provided by: stoken_0.92-1_amd64 bug

NAME

       stoken - software token for cryptographic authentication

SYNOPSIS

       stoken [tokencode] [--stdin] [--force] [--next] [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 | --qr=file.png |
       --show-qr}] [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.

       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.

       --devid=devid
              Use  a  device ID supplied from the command line to decrypt the token.  A token can
              be bound to a class GUID device ID (i.e. a certain type of device, such as "iPhone"
              or  "Android"),  a  unique  device ID (one specific unit), or nothing.  stoken will
              attempt to autodetect matches with a class GUID, but on rare occasions this results
              in  false  positives  due  to hash collisions.  In these cases, the bound device ID
              should be specified on the command line to override autodetection.

EXPORT 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.

       --qr=file.png
              Encode the token as a QR code and write it to file.png.  This requires the qrencode
              program to be installed.

       --show-qr
              Encode the token as a QR code and immediately  display  it  on  the  screen.   This
              requires  the  qrencode  program  to  be  installed.   If the QR_VIEWER environment
              variable is set, stoken will use that program as the preferred  viewer.   Otherwise
              it  will  try  to  execute a few common Linux image viewers, and give up if none of
              them exist.

       --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.

OTHER OPTIONS

       --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.

       --next Generate  the  next  tokencode  instead  of the current tokencode.  For a 60-second
              token, this is equivalent to --use-time=+60.

       --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.

       Encoding  QR  tokens  may expose the seed data through ps, and the --show-qr option writes
       temporary PNG files in /tmp.

       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: 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>

                                            2012-09-09                                  stoken(1)