Add a README

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