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.
