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

# NAME

ssp - One-Time Password management

# SYNOPSIS

*ssp* [*-q*] [*-D* `FILE`] `<command>`

# DESCRIPTION

*ssp* is a simple, fast & secure command-line tool to manage your One-Time
Passwords (OTPs), whether you want to handle them from your computer or as a
backup solution.

It supports HOTP (An HMAC-Based One-Time Password Algorithm; as per [RFC 4226])
as well as TOTP (Time-Based One-Time Password Algorithm; as per [RFC 6238]).

[RFC 4226]: https://datatracker.ietf.org/doc/html/rfc4226
[RFC 6238]: https://datatracker.ietf.org/doc/html/rfc6238


# OPTIONS

: *-D*, *--database* `FILE`
:: Use `FILE` as database. Defaults to `$HOME/ssp.db`

: *--debug* [[@[`level`]:]+`FD`|`FILE`]
<inc autoopt_debug.md>
<inc autoopt_logdbg_level.md>

<inc opt_help.md>

: *-I*, *--iter* `ITER`
:: Use `ITER` iterations when performing key derivation to write database. See
:: [[DATABASE]] below for more. Must be at least 50 000; Defaults to 500 000.
::
:: Note that this only applies when writing database, not reading it - since the
:: number of iterations used is stored within the file.
::
:: In addition, when re-writing (i.e. updating/editing) a database, and unless
:: this option is used, the number of iterations previously used (as read from
:: the file during opening) will be re-used by default.

: *-q*, *--quiet*
<inc autoopt_quiet.md>

<inc opt_version.md>

# COMMANDS

The following commands are available through *ssp*. Note that you can abbreviate
a command's name so long as there's no other match possible.

: *add*
:: Add a new entry

: *edit*
:: Edit an existing entry

: *export*
:: Export entries to file

: *get*
:: Get a One-Time Password

: *import*
:: Import entries from file

: *list*
:: List entries

: *remove*
:: Remove an entry

: *rename*
:: Rename an entry

: *show*
:: Show an entry

To get more information about any of them and their supported options, refer to
the command's own page ( *ssp-`<command>`* ).

# HOW TO WRITE ARGUMENTS

Whenever you need to specify text, such as file/entry names or comments, the
same rule apply.

There are no restrictions of length or acceptable characters imposed by *ssp*
(e.g. file names obviously need to be valid filenames, i.e. no slashes or NUL
byte).
Specifically, inputs are treated as byte streams and processed as such.

Note however that in order to use specific characters you might have to put
argument within double-quotes (`"`).

! NOTE: Don't forget about your shell's own escaping
! In order to give *ssp* an argument within double-quotes, remember that you'll
! probably need to account for your shell's own escaping, e.g. put the whole
! thing in between single-quotes.

The content within double-quotes can be escaped as needed, according the the
following rules.

## Escaping rules

<inc esc.md>

# DATABASE

The database is written as a password-protected file.

More specifically, PBKDF2-HMAC-SHA3-256 is used with 500,000 iterations (by
default, can be changed using *--iter*) to derive a key from the password and a
randomly generated salt, said key is then used to encrypt the database using
ChaCha20-Poly1305.

Whenever writing to the database, the actual file is not changed. Instead a new
file is created, encrypted data is written to it and only once successfully
written the file is renamed, thusly replacing the original/old one (if any).

As such, should any error occur during the (re-)writing process, your current
database file will remain untouched and no data will be lost.

<inc bugs.md>

# REPOSITORY

You can find the latest about *ssp* from its official site at https://lila.oss/ssp
Latest source code can be browsed online at https://lila.oss/code/ssp; or you can close
its [git](1) repo from git://lila.oss/ssp.git

<inc author.md>