Clarify language and procedure

Multi-factorAuthentication.md

@@ -11,12 +11,10 @@ Using Multi-factor Authentication with Qubes
 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
+[Multi-factor authentication (MFA)][MFA] today most commonly takes the form of a
-which a user can pass by successfully presenting several separate authentication
+numerical code generated by a smartphone app or sent via SMS (text message)
-stages. Nowadays, this most commonly takes the form of a numerical code
+which the user must enter in addition to a password in order to log in to a
-generated by a smartphone app or sent via SMS (text message) which the user must
+website or other service.
-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
@@ -24,13 +22,14 @@ 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-
+This guide will show you how to set up a VM which uses [oathtool][], an
-source one-time password tool, to generate authentication codes. This method
+open-source one-time password tool, to generate authentication codes. This
-presents several benefits over relying on a consumer smartphone app or SMS:
+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
+   algorithm, which is the same algorithm used by [Google Authenticator][], one
-   the most commonly used authenticator apps. This means that we can use
+   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).
 
@@ -47,9 +46,9 @@ presents several benefits over relying on a consumer smartphone app or SMS:
    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
+   provider, the service provider itself still has full access, which means that
-   means that the contents of such messages could be read by unscrupulous admins
+   the contents of such messages could be read by unscrupulous admins or turned
-   or turned over to government agencies.)
+   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
@@ -73,34 +72,40 @@ Optional Preparation Steps
         [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:
+    from the command line, we'll install only a couple of packages:
 
         [user@fedora-21-min-mfa ~]$ su -
         [user@fedora-21-min-mfa ~]# yum install oathtool vim-minimal
+        [user@fedora-21-min-mfa ~]$ poweroff
 
- 4. Create an AppVM and set it to use `fedora-21-min-mfa` as its TemplateVM.
+ 4. Create an AppVM and set it to use the TemplateVM we just created:
  
- 5. Ensure that the new AppVM's netvm is set to `none`.
+        [user@dom0 ~]$ qvm-create -l black mfa
+        [user@dom0 ~]$ qvm-prefs -s mfa template fedora-21-min-mfa
+
+ 5. Isolate the new AppVM from the network:
+ 
+        [user@dom0 ~]$ qvm-prefs -s mfa netvm none
 
 
-Using `oathtool` in an AppVM
+Using the MFA 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
+    If you are prompted to scan a QR code, instead select the option (if
-    the option (if available) to view the secret key as text:
+    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:
+    You should then see the secret key as text:
 
     ![Secret Key Example 1](/attachment/wiki/UserDoc/Multi-factorAuthentication/secret-key-example-1.png)
 
-    Note that the length of the secret key may vary:
+    Note that the length and format of the secret key may vary by service:
 
     ![Secret Key Example 2](/attachment/wiki/UserDoc/Multi-factorAuthentication/secret-key-example-2.png)
 
@@ -120,9 +125,9 @@ is largely the same.
     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, using the
+    script for each service we use. (The example service here is a Google
-    example key from above. You'll get a different secret key from each service
+    account, using the example key from above. You'll get a unique secret key
-    which is unique to you.) Create the script like so:
+    from each service.) Create the script like so:
 
         [user@mfa ~]$ > google
         [user@mfa ~]$ vi google
@@ -145,9 +150,9 @@ is largely the same.
         
     Done!
 
- 5. Create similar scripts for other services you use, and enjoy the security
+ 5. Now you can create scripts for any other TOTP-supporting services you use,
-    and ease of quickly generating TOTP tokens right from your Qubes VM
+    and enjoy the security and ease of quickly generating authentication tokens
-    command-line:
+    right from your Qubes VM command-line:
 
         [user@mfa ~]$ ./github
         495272
@@ -173,5 +178,6 @@ is largely the same.
 [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
+[Google Authenticator]: https://en.wikipedia.org/wiki/Google_Authenticator
 [FedoraMinimal]: /doc/Templates/FedoraMinimal/
 [usage]: https://en.wikipedia.org/wiki/Google_Authenticator#Usage