% ssp
% ssp-get(1)
% ssp 0.1.0
% 2024-01-09

# NAME

ssp-get - get a One-Time Password

# SYNOPSIS

*ssp* get -e `ENTRY` | -s `SECRET` [`OPTION`..]

# DESCRIPTION

The *get* command is the "main" command, as it's the one allowing you to get a
One-Time Password (OTP). Other commands are mainly about database/entries
management.

Usually you will want to get an OTP for an existing entry, using its parameters
as set in the database. However, it is possible to override such values using
command-line options.

You can also get an OTP without using any entry, and therefore without the need
for a database, by specifying all the needed settings via command-line options.

As such, you need to specify at least one of *--entry* or *--secret*. Other
options are optional and only needed to override entry/default values.

By default the password will be written to *stdout* with either "HOTP: " or
"TOTP: " as prefix, depending on whether it is a counter-based or time-based
password, respectively.

To remove said prefix and only have the generated password itself written out,
use general option *--quiet*.

# OPTIONS

: *-a*, *--algo* `ALGO`
:: Use `ALGO` as hashing algorithm; Defaults to sha1 unless *--entry* is used.
:: Use `ssp add --algo=list` to list available algorithms.

: *-C*, *--counter-val* `NUM`
:: Same as *--counter* but don't update entry in the database.

: *-c*, *--counter*[=`NUM`]
:: Return a counter-based password (HOTP) using `NUM` as value for the counter;
:: Defaults to 1.
:: Note that when using an entry (specified via *--entry*) the entry will be
:: updated in order to increment its counter value (unless the entry is /not/
:: counter-based). If for some reason you want the database/entry /not/ to be
:: updated, use *--counter-val* instead.

: *-d*, *--digits* `NUM`
:: Return an OTP of `NUM` digits. Valid values are from 5 to 9 (both
:: included); Defaults to 6 unless *--entry* is used.

: *-e*, *--entry* `ENTRY`
:: Get a password for `ENTRY`. This means the database will be looked for an
:: entry named `ENTRY` and its settings will be used as default. Any option
:: specified on command-line /after/ will then override said values.
:: In other words, any options given /before/ *--entry* will be ignored.
::
:: Additionally, when the entry is counter-based, the database will be updated
:: with the entry's counter value incremented (unless *--counter-val* was used).
::
:: (Note that if the entry is /not/ counter-based but *--counter* is used, the
:: database will obviously not be updated, leaving the entry as it was, e.g.
:: time-based.)

: *-s*, *--secret* `SECRET`
:: Use `SECRET` as secret. `SECRET` must be base32-encoded. Note that this can
:: be used after *--entry* in order to use a different secret but keep/re-use
:: all other settings as defaults, or it can be used /instead/ of *--entry* to
:: get a password without using an entry/database at all.

: *-T*, *--use-time* `TS`
:: Use `TS` as unix timestamp instead of the current time. This only applies
:: when getting a time-based password.

: *-t*, *--time*[=`SECS`]
:: Return a time-based password (TOTP) using a precision of `SECS` seconds.
:: Valid values are from 10 to 59 (both included); Default to 30 unless *--entry*
:: is used.

# EXAMPLES

To get an OTP from entry "foo" but using a counter value of 23 /without/
updating the database, without the "HOTP: " prefix (i.e. only write the actual
OTP on stdout) :

    $ ssp -q get -e foo -C23


To get an OTP using GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ as (base32-encoded) secret
and a counter of 5 :

    $ ssp get -s GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ -c5


To get a TOTP from entry named "time" using Unix timestamp 1234567890 (i.e.
2009-02-13 23:31:30) :

    $ ssp g -e time -T1234567890


To get an 8-digit TOTP using GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ as secret and the
current time minus 55 minutes : \
(/refer to your shell's documentation for actual syntax/)

    $ ssp get -s GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ -td8
        --use-time=$(date --date="55 minutes ago" +%s)