ReadMe.txt

   1 otpcli - One Time Password Command Line Interface
   2 =================================================
   3
   4 The `otpcli` utility provides a command line interface to generate
   5 one time hash-based or time-based passwords using the techniques
   6 specified in [RFC 4226] and [RFC 6238].
   7
   8 This suffices to provide an "Authentication App" service using
   9 solely the `otpcli` command line utility.
  10
  11
  12 Limitations
  13 -----------
  14
  15 The `otpcli` utility is completely standalone with no dependencies
  16 (other than a POSIX make and C99 compiler to build it).
  17
  18 It does *NOT* include a QR code decoder!
  19
  20
  21 Using otpcli
  22 ------------
  23
  24 If the service you are attempting to use `otpcli` with as an
  25 "Authentication App" provides only a QR code to set up your
  26 "Authentication App", then you will need a separate QR code decoder
  27 to decode that QR code into the `otpauth:` URI that contains the
  28 shared secret you will need in order to use `otpcli`.
  29
  30 In other words, if all you have to set up your "Authentication App"
  31 is a QR code like this:
  32
  33 ![Example QR Code Image](qrexample.png "Example QR Code")
  34
  35 It must first be decoded using a QR code decoding helper program.
  36 In this case it decodes to this:
  37
  38     otpauth://totp/ACME%20Co:bob@otp.example?secret=JBSWY3DPWIZR4IFU&issuer=ACME%20Co
  39
  40 Details regarding the `otpauth:` URI format can be found via reference
  41 [3] of https://www.iana.org/assignments/uri-schemes/prov/otpauth.
  42
  43 In almost every case, only the value of the `secret` parameter is
  44 actually needed.  (Some enlightened services provide a link next
  45 to the QR code image that allows the Base 32 shared secret to be
  46 copied without needing to use a QR code decoder.)
  47
  48 In the unlikely event that you have a URI that starts with
  49 `otpauth://hotp/` instead of `otpauth://totp/` then you will also
  50 need the value of the `counter` parameter (which can only be used
  51 with hotp URIs) and it must be provided to `otpcli` using the `-c`
  52 option.
  53
  54 (See the output of `otpcli -hh` for a complete list of all available
  55 `otpcli` options.)  The default values of sha1, 30 second period
  56 and 6 digits mean that in almost every case, only the shared secret
  57 needs to be supplied.
  58
  59 The shared secret from an `otpauth:` URI `secret` parameter is
  60 always supplied in Base 32 (see [RFC 3548]) and in the above example,
  61 the Base 32 shared secret is `JBSWY3DPWIZR4IFU`.
  62
  63 To use `otpcli` with this shared secret, this is the command (`-3`
  64 indicates that the shared secret is being provided in Base 32):
  65
  66     otpcli -3 JBSWY3DPWIZR4IFU
  67
  68 It will output something like this:
  69
  70     187877 23s
  71
  72 The `187877` part is the 6-digit pass code to use and it is valid
  73 for the next 23 seconds.  If the `-i` option is added like so:
  74
  75     otpcli -i -3 JBSWY3DPWIZR4IFU
  76
  77 Then `otpcli` will continually update the time remaining and update
  78 the pass code to the next one once the current pass code has expired
  79 (the `-i` interactive mode can be exited by simply pressing <return>
  80 or by pressing <Ctrl-C>).
  81
  82
  83 Protecting Your Secrets
  84 -----------------------
  85
  86 Specifying your shared secret on the command line can expose it via
  87 a list of running processes.  In other words, not the best idea.
  88
  89 However, `otpcli` can read the shared secret from a file by simply
  90 prepending an `@` sign to the file name.
  91
  92 Suppose that we want to save our shared secrets in a `.otpcli`
  93 directory in our "$HOME" directory and prevent any other users from
  94 being able to read the files in that directory.
  95
  96 We can do that like so:
  97
  98     mkdir -p "$HOME/.otpcli"    # create directory if it does not exist
  99     chmod 0700 "$HOME/.otpcli"  # make sure only we can read and search it
 100
 101 Now we add our above shared secret to the file "acme" in the new directory:
 102
 103     echo JBSWY3DPWIZR4IFU > "$HOME/.otpcli/acme"
 104     chmod 0600 "$HOME/.otpcli/acme"  # make sure only we can read it
 105
 106 Of course there's the shared secret on the command line again --
 107 using a file editor to save the shared secret in the file instead
 108 will avoid that.  (Note that the `otpcli` utility ignores whitespace
 109 in the file when reading a Base 32 shared secret.)
 110
 111 To use `otpcli` with the "acme" shared secret file we just created,
 112 we can do this:
 113
 114     otpcli -3 "@$HOME/.otpcli/acme"
 115
 116 Or using the `-i` interactive mode like so:
 117
 118     otpcli -i -3 "@$HOME/.otpcli/acme"
 119
 120 For scripting purposes, using a file name of `-` (e.g. `-3 @-`)
 121 will cause the Base 32 shared secret to be read from standard input.
 122
 123
 124 Building otpcli
 125 ---------------
 126
 127 To build `otpcli` a POSIX make utility and a C99 compiler are required.
 128
 129 That's it.  Just type `make` in the top-level directory and the
 130 `otpcli` utility will be built.  It is completely standalone.
 131
 132 (If for some reason your C99 compiler is not available as `cc` then
 133 use `make CC=c99` instead where `c99` is the name of your C99
 134 compiler.)
 135
 136 It's a good idea to test `otpcli` before using it and to do that
 137 type `make test` in the top-level directory which will run a few
 138 hashing and `otpcli` tests to make sure they're producing the
 139 expected output.  (For anyone automating the tests, `make test`
 140 will fail with a non-zero exit code if any of the tests fail.)
 141
 142
 143 License
 144 -------
 145
 146 The license can be found in the top-level LICENSE.txt file -- it is
 147 the three clause BSD license.  Note that the functions providing the
 148 sha1, sha256 and sha512 functionality are from the [LibTomCrypt][]
 149 library and have an even more flexible license which can be found in
 150 the lt/lt-LICENSE.txt file.
 151
 152 [LibTomCrypt]: https://www.libtom.net/LibTomCrypt/ "LibTomCrypt"