tok

tok
===

*tok* is a two-factor authentication (2FA) command-line utility. You can use it instead of a mobile app to generate 2FA tokens.

Usage
-----

Add a token:

.. code-block:: bash

    $ tok add
    Enter name: gibsons
    Enter secret: VBWA FMHK U522 CBPO
    Enter note:
    Please enter database password: *****

    Token 'gibsons', added 2025-01-01 00:00:00
    123 456


Use a token:

.. code-block:: bash

    $ tok gibsons
    Please enter database password: *****

    Token 'gibsons', added 2025-01-01 00:00:00:
    123 456


Adding and exporting tokens using the key-uri format:

.. code-block:: bash

    $ tok import "otpauth://totp/gibsons?secret=VBWAFMHKU522CBPO&issuer=issuer&algorithm=SHA1&digits=6&period=30"
    ...
    $ tok export gibsons
      1 - otpauth://totp/gibsons?secret=...


How to install
--------------

Build from source code:

.. code-block:: bash

    sudo apt install golang
    go install github.com/avahidi/tok@latest

This will install *tok* to your ~/go/bin/ folder.

Security note
~~~~~~~~~~~~~

The *tok* security strategy is quite simple:

 * *tok* is a minimal Go implementation of RFC 6238 (`TOTP`_).
 * *tok* does not use any third-party libraries.
 * The database is GCM-AES-256 encrypted.
 * The encryption key is derived using PBKDF2-SHA-256 with a 256-bit salt.

Note that it is generally advised against storing both passwords and 2FA tokens on the same computer.

*On a possibly related note, "tok" is not only shorthand for "token" but also the Swedish word for "fool"...*

.. _TOTP: https://en.wikipedia.org/wiki/Time-based_one-time_password

License
-------

This project is licensed under the GNU General Public License version 2. See the `LICENSE <LICENSE>`_ file for details.