aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 9cec855ecee1fa26a82dde8a3011be28eecff448 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# totp

`totp` is a command-line utility to generate TOTP keys from the command-line.
This is very useful for integrating 2-factor authentication support into your
existing password-management setup.  `totp` supports both TOTP secret keys and
OTP URIs as input.  This means you can also integrate `totp` together with
`zbarimg` to generate TOTP codes from scannable QR codes.

## Installation

Installation is made easy with the provided Makefile:

    $ make
    $ make install

## Usage

The `totp` utility reads TOTP secret keys from the standard input and prints the
corresponding codes to the standard output.  You can use multiple keys:

    $ printf '7KFSJ562KJDK23KD\n7YNEG7J3XBIVYR54' | totp
    546316
    942303

You can also provide the keys as arguments:

    $ totp 7KFSJ562KJDK23KD 7YNEG7J3XBIVYR54
    546316
    942303

By default it is assumed that the TOTP codes have a length of 6 and are valid
for 30 seconds.  You can change both of these parameters using the `-d` and `-p`
respectively, if required:

    $ totp -d8 -p60 7KFSJ562KJDK23KD 7YNEG7J3XBIVYR54
    71696020
    18335070

It might be useful however to instead use an OTP URI.  These are the URIs
embedded within 2-factor authentication QR codes, and often contain the metadata
specifying the length and period of the generated codes.  To use URIs, use the
`-u` flag:

    $ totp -u 'otpauth://totp/GitHub:Mango0x45?secret=7YNEG7J3XBIVYR54'
    942303

This also works with the standard input:

    $ echo 'otpauth://totp/GitHub:Mango0x45?secret=7YNEG7J3XBIVYR54' | totp -u
    942303

## Integration with `zbarimg`

`zbarimg` is a helpful CLI utility that we can use to get an OTP URI from a QR
code.  Here is an example of how we can use it to generate a TOTP code from a
2-factor authentication QR code:

    $ zbarimg -q qr-code.png | sed 's/QR-Code://' | totp
    546316