diff --git a/Multi-factorAuthentication.md b/Multi-factorAuthentication.md new file mode 100644 index 00000000..bdd1d5f0 --- /dev/null +++ b/Multi-factorAuthentication.md @@ -0,0 +1,170 @@ +--- +layout: doc +title: Multi-factorAuthentication +permalink: /doc/Multi-factorAuthentication/ +--- + +Using Multi-factor Authentication with Qubes +============================================ + +(Note: This page concerns multi-factor authentication for logging into external +severices, not for logging into Qubes itself. For the latter, see +[here][YubiKey].) + +[Multi-factor authentication (MFA)][MFA] is a method of computer access control +which a user can pass by successfully presenting several separate authentication +stages. Nowadays, this most commonly takes the form of a numerical code +generated by a smartphone app or sent via SMS (text message) which the user must +enter in addition to a password in order to log in to a website or other +service. + +One of the primary features of Qubes is that it allows us to create securely +isolated VMs which can run arbitrary programs. (These VMs are securely isolated +not only from each other but also, optionally, from the network.) This means +that we can create a dedicated, network-isolated VM to function as a secure +authenticator. + +This guide will show you how to set up a VM which uses [oathtool][], an open- +source one-time password tool, to generate authentication codes. This method +presents several benefits over relying on a consumer smartphone app or SMS: + + * `oathtool` includes the [time-based one-time password (TOTP)][TOTP] + algorithm, which is the same algorithm used by Google Authenticator, one of + the most commonly used authenticator apps. This means that we can use + `oathtool` as a complete open-source replacement for Google Authenticator + (which became propriety (closed-source) in May 2013 after version 2.21). + + * By keeping all of our authenticator data as plain text files in a dedicated + VM, we have complete control over the secret keys used to generate our + authentication tokens, and we can back up, copy, and transfer our + authenticator data at will. + + * By creating a minimal environment in which to run `oathtool` from the command + line, we can minimize our attack surface relative to most smartphone apps and + SMS. Consumer smartphones are typically internet-facing devices which are + increasingly targeted by malware. Most smartphones are bundled with + proprietary software which allows service providers almost complete control + over the device. Likewise, consumer SMS messages are often cleartext + communications which can feasibly be intercepted and read by third parties. + (In cases in which SMS messages are encrypted on the network by the service + provider, the service provider itself of course still has full access, which + means that the contents of such messages could be read by unscrupulous admins + or turned over to government agencies.) + + * Using `oathtool` in a dedicated, network-isolated Qubes VM allows us to + achieve a unqiue combination of security and convenience. The strong isolation + Qubes provides allows us to reap the full security benefits of MFA, while + virtualization frees us from having to worry about finding and handling a + second physical device. + + +Optional Preparation Steps +-------------------------- + + 1. Start with a minimal template. In this example, we'll use the + [minimal Fedora template][FedoraMinimal]. Download it if you haven't already + done so: + + [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-21-minimal + + 2. Since we'll be making some modifications, you may want to clone the minimal + template: + + [user@dom0 ~]$ qvm-clone fedora-21-minimal fedora-21-min-mfa + + 3. Since this is going to be a minimal environment in which we run `oathtool` + from the command line, we need to install only a couple of packages: + + [user@fedora-21-min-mfa ~]$ su - + [user@fedora-21-min-mfa ~]# yum install oathtool vim-minimal + + 4. Create an AppVM and set it to use `fedora-21-min-mfa` as its TemplateVM. + + 5. Ensure that the new AppVM's netvm is set to `none`. + + +Using `oathtool` in an AppVM +---------------------------- + +Now that we have an AppVM set up to use `oathtool` securely, let's use it with +an external service. This process will vary slightly from service to service but +is largely the same. + + 1. Proceed with setting up multi-factor authentication as you normally would. + If you are prompted to scan a QR code with your smartphone, instead select + the option (if available) to view the secret key as text: + + ![Secret Key Example 0](/attachment/wiki/UserDoc/Multi-factorAuthentication/secret-key-example-0.png) + + You should then see something like this: + + ![Secret Key Example 1](/attachment/wiki/UserDoc/Multi-factorAuthentication/secret-key-example-1.png) + + Note that the length of the secret key may vary: + + ![Secret Key Example 2](/attachment/wiki/UserDoc/Multi-factorAuthentication/secret-key-example-2.png) + + 2. In your MFA AppVM, you can now use `oathtool` to generate base32 TOTP + authentication tokens just like Google Authenticator would: + + [user@mfa ~]$ oathtool --base32 --totp "xd2n mx5t ekg6 h6bi u74d 745k n4m7 zy3x" + 279365 + + In this case, the token you would enter is `279365`. (Note that this is a + *time*-based one-time password, which means that your VM's clock must be + sufficiently accurate in order to generate a valid token and that the token + will change after a short period of time.) + + 3. To make this easier on ourselves in the future, we can create a simple shell + script for each service we use (the example here is Google): + + [user@mfa ~]$ > google + [user@mfa ~]$ vi google + + #!/bin/bash + ##My Google Account + ##me@gmail.com + oathtool --base32 --totp "xd2n mx5t ekg6 h6bi u74d 745k n4m7 zy3x" + + [user@mfa ~]$ chmod +x google + + Since the secret key stored in our script never changes, we should never + have to update this script. + + 4. Now, whenever a service prompts us for an authenticator code, all we have to + do is this: + + [user@mfa ~]$ ./google + 640916 + + Done! + + 5. Create similar scripts for other services you use, and enjoy the security + and ease of quickly generating TOTP tokens from a Qubes VM command-line: + + [user@mfa ~]$ ./github + 495272 + [user@mfa ~]$ ./aws + 396732 + [user@mfa ~]$ ./facebook + 851956 + [user@mfa ~]$ ./dropbox + 294106 + [user@mfa ~]$ ./microsoft + 295592 + [user@mfa ~]$ ./slack + 501731 + [user@mfa ~]$ ./wordpress + 914625 + [user@mfa ~]$ ./tumblr + 701463 + + For a more complete list of compatible services, see [here][usage]. + + +[YubiKey]: /doc/YubiKey/ +[MFA]: https://en.wikipedia.org/wiki/Multi-factor_authentication +[oathtool]: http://www.nongnu.org/oath-toolkit/man-oathtool.html +[TOTP]: https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm +[FedoraMinimal]: /doc/Templates/FedoraMinimal/ +[usage]: https://en.wikipedia.org/wiki/Google_Authenticator#Usage