description | one time password command line interface |
owner | mackyle+repogit@gmail.com |
last change | Sat, 2 Sep 2023 09:12:41 +0000 (2 02:12 -0700) |
URL | git://repo.or.cz/otpcli.git |
https://repo.or.cz/otpcli.git | |
push URL | ssh://repo.or.cz/otpcli.git |
https://repo.or.cz/otpcli.git (learn more) | |
bundle info | otpcli.git downloadable bundles |
content tags |
The otpcli
utility provides a command line interface to generate
one time hash-based or time-based passwords using the techniques
specified in [RFC 4226] and [RFC 6238].
This suffices to provide an "Authentication App" service using
solely the otpcli
command line utility.
The otpcli
utility is completely standalone with no dependencies
(other than a POSIX make and C99 compiler to build it).
It does NOT include a QR code decoder!
If the service you are attempting to use otpcli
with as an
"Authentication App" provides only a QR code to set up your
"Authentication App", then you will need a separate QR code decoder
to decode that QR code into the otpauth:
URI that contains the
shared secret you will need in order to use otpcli
.
In other words, if all you have to set up your "Authentication App" is a QR code like this:
It must first be decoded using a QR code decoding helper program. In this case it decodes to this:
otpauth://totp/ACME%20Co:bob@otp.example?secret=JBSWY3DPWIZR4IFU&issuer=ACME%20Co
Details regarding the otpauth:
URI format can be found via reference
[3] of https://www.iana.org/assignments/uri-schemes/prov/otpauth.
In almost every case, only the value of the secret
parameter is
actually needed. (Some enlightened services provide a link next
to the QR code image that allows the Base 32 shared secret to be
copied without needing to use a QR code decoder.)
In the unlikely event that you have a URI that starts with
otpauth://hotp/
instead of otpauth://totp/
then you will also
need the value of the counter
parameter (which can only be used
with hotp URIs) and it must be provided to otpcli
using the -c
option.
(See the output of otpcli -hh
for a complete list of all available
otpcli
options.) The default values of sha1, 30 second period
and 6 digits mean that in almost every case, only the shared secret
needs to be supplied.
The shared secret from an otpauth:
URI secret
parameter is
always supplied in Base 32 (see [RFC 3548]) and in the above example,
the Base 32 shared secret is JBSWY3DPWIZR4IFU
.
To use otpcli
with this shared secret, this is the command (-3
indicates that the shared secret is being provided in Base 32):
otpcli -3 JBSWY3DPWIZR4IFU
It will output something like this:
187877 23s
The 187877
part is the 6-digit pass code to use and it is valid
for the next 23 seconds. If the -i
option is added like so:
otpcli -i -3 JBSWY3DPWIZR4IFU
Then otpcli
will continually update the time remaining and update
the pass code to the next one once the current pass code has expired
(the -i
interactive mode can be exited by simply pressing <return>
or by pressing <Ctrl-C>).
Specifying your shared secret on the command line can expose it via a list of running processes. In other words, not the best idea.
However, otpcli
can read the shared secret from a file by simply
prepending an @
sign to the file name.
Suppose that we want to save our shared secrets in a .otpcli
directory in our "$HOME" directory and prevent any other users from
being able to read the files in that directory.
We can do that like so:
mkdir -p "$HOME/.otpcli" # create directory if it does not exist
chmod 0700 "$HOME/.otpcli" # make sure only we can read and search it
Now we add our above shared secret to the file "acme" in the new directory:
echo JBSWY3DPWIZR4IFU > "$HOME/.otpcli/acme"
chmod 0600 "$HOME/.otpcli/acme" # make sure only we can read it
Of course there's the shared secret on the command line again --
using a file editor to save the shared secret in the file instead
will avoid that. (Note that the otpcli
utility ignores whitespace
in the file when reading a Base 32 shared secret.)
To use otpcli
with the "acme" shared secret file we just created,
we can do this:
otpcli -3 "@$HOME/.otpcli/acme"
Or using the -i
interactive mode like so:
otpcli -i -3 "@$HOME/.otpcli/acme"
For scripting purposes, using a file name of -
(e.g. -3 @-
)
will cause the Base 32 shared secret to be read from standard input.
To build otpcli
a POSIX make utility and a C99 compiler are required.
That's it. Just type make
in the top-level directory and the
otpcli
utility will be built. It is completely standalone.
(If for some reason your C99 compiler is not available as cc
then
use make CC=c99
instead where c99
is the name of your C99
compiler.)
It's a good idea to test otpcli
before using it and to do that
type make test
in the top-level directory which will run a few
hashing and otpcli
tests to make sure they're producing the
expected output. (For anyone automating the tests, make test
will fail with a non-zero exit code if any of the tests fail.)
The license can be found in the top-level LICENSE.txt file -- it is the three clause BSD license. Note that the functions providing the sha1, sha256 and sha512 functionality are from the LibTomCrypt library and have an even more flexible license which can be found in the lt/lt-LICENSE.txt file.
8 months ago | otpcli-1.0 | otpcli version 1.0 | tag | commitlog |
8 months ago | mackyle-gpg-pub | GPG key used to sign otpcli stuff | tag | blobraw |
8 months ago | frabjous | logtree |