Create Multi-factor Authentication page

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