github.com 2FA login with oathtool

[bill-auger]

as some may know, github is now requiring 2FA - i do not have a mobile phone
and i use GNU/linux exclusively - as i expected, their docs are not helpful WRT
my use case - someone in the #security IRC channel suggested that oathtool may
work; so i tried it - this was my first time using 2FA or oathtool; so it was
not exactly intuitive - however, i documented the procedure for posterity - the
procedure is probably quite similar for other websites

i dont know if oath-toolkit has a wiki or some other place to put this;
but it may be useful to others - feel free to publish it anywhere -
i offer it under the 'CC0 1.0 Universal' license - no attribution required
https://creativecommons.org/publicdomain/zero/1.0/legalcode


== github.com 2FA login with oathtool ==

The initial setup is race against the clock. The entire procedure must be 
completed within 30 seconds from when the "Setup authenticator app" page 
appears. If you fail, you will need to reload the "Setup authenticator app" 
page to get a fresh key, and start over.

First, to save a few precious seconds during the initial setup, and to make the 
process more secure and easier in the future, we will be creating two text 
files (the file names and locations can be anything you like):

```
$ mkdir --mode=700 ~/private
$ install -m600 /dev/null ~/private/github-totp
$ install -m600 /dev/null ~/private/github-totp-key
```

Next, open 'github-totp' with your favorite text editor and add these contents:

```
#!/bin/sh

oathtool --totp=SHA1 --digits=6 --time-step-size=30s --base32 
@$HOME/private/github-totp-key
```

Note that the '@' character is important; and be sure to type $HOME or the 
absolute path to 'github-totp-key'. Tilde expansion '~/' will not work as 
expected.

Make the 'github-totp' file read-only, executable, and private:

```
$ chmod 500 ~/private/github-totp
```

Now, open 'github-totp-key' with your favorite text editor and don your running 
shoes.

Log into Github. If you do not see the "Setup authenticator app" page 
immediately, browse to it like so:

* Click on your profile image (top-right), then click "Settings".
* Click "Password and authentication" under the "Access" section of the 
left-side nav-bar.
* Click "Enable two-factor authentication" under the "Two-factor 
authentication" section.

Once the "Setup authenticator app" page appears, the clock is ticking. Ready, 
Set, Go!

On the "Setup authenticator app" page, click the "setup key" link beneath the 
qr-code image. Copy the cryptic number/letters shown into the 'github-totp-key' 
file and save it. The number/letters should have no spaces and no new-line at 
the end. If you type it by hand, not that there are no zero '0' characters. If 
you see any, those are the capital letter 'O' characters.

Now, execute the 'github-totp' script.

```
$ ~/private/github-totp
```

The command output should be a 6-digit number. Copy that number into the 
"Verify the code from the app" text-box on the "Setup authenticator app" page.

With any luck, you did all that quickly enough; and yer good to go. Well, 
almost.

Next you should see bunches of number/letters on a "Save your recovery codes" 
page. At the very least, you will need to click the "I have saved my recovery 
codes" button to complete the process. You should probably print those recovery 
codes now though, or download them and store them securely/privately on another 
computer, CD/DVD, or USB stick.

The next time you login to Github, and forever into the future, you will need a 
TOTP (a 6-digit number) for login. Simply execute the 'github-totp' script 
again, and use the 6-digit number it generates to log in. Again, you have only 
30 seconds to complete the login. Each time the 'github-totp' script is run, it 
will produce a different 6-digit number, which expires in 30 seconds. Copy that 
number into the Github login page and press the "Sign-in" button.

I suggest trying that now, in a different web browser, without logging out of 
your current session, just to make sure it all works. If you logout now and 
something went wrong, you may have created a major problem, especially if you 
did not save those recovery codes. Please don't blame me or the oath-toolkit 
team if things go awry. Blame Github for imposing this extra rigamarole on you.

Lastly, make the 'github-totp-key' file read-only and private:

```
$ chmod 400 ~/private/github-totp-key
```

Congratulations. You are safe now. Here a few a few more things you can do for 
extra peace of mind.

In full discloser, security nuts will indeed tell you that this is insecure; 
because the auth key is stored on the same machine as your web browser. 
However, it is no less secure than how I have been logging into Github for the 
past 15 years until today, before 2FA was required (and every other website 
since forever). Yer a big kid. Decide for yourself.

Optionally, you could encrypt the 'github-totp-key' file now with GPG, 
decrypting it on each use in the 'github-totp' script; but this guide will not 
explain that. Suffice it to say, if you do so, use a dash '-' character in 
place of the '@FILE' in the `oathtool` command, to accept the clear-text key 
via STDIN.

Optionally, you could keep the 'github-totp' script on a USB stick for decent 
level of security, replacing '@$HOME/private/github-totp-key' with the literal 
key. Let's call that "1.5FA". In the words of Sir Paul, "Close enough for the 
Skiffle!". The 'github-totp-key' file is not strictly needed. I demonstrated 
it; because you also may want encrypt that file for an extra decent level of 
security. Can never be too safe ya' know.