aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md59
1 files changed, 59 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9cec855
--- /dev/null
+++ b/README.md
@@ -0,0 +1,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