From ad48b274e4a67cdb4936e3fe7614cf3043b0f6ce Mon Sep 17 00:00:00 2001 From: Axon Date: Mon, 21 Sep 2015 13:15:22 +0000 Subject: [PATCH] Clarify language and procedure --- Multi-factorAuthentication.md | 64 +++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/Multi-factorAuthentication.md b/Multi-factorAuthentication.md index d9286cf5..4a37950f 100644 --- a/Multi-factorAuthentication.md +++ b/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 -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. +[Multi-factor authentication (MFA)][MFA] today 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 @@ -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- -source one-time password tool, to generate authentication codes. This method -presents several benefits over relying on a consumer smartphone app or SMS: +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 + 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). @@ -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 - means that the contents of such messages could be read by unscrupulous admins - or turned over to government agencies.) + provider, the service provider itself 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 @@ -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: + + [user@dom0 ~]$ qvm-create -l black mfa + [user@dom0 ~]$ qvm-prefs -s mfa template fedora-21-min-mfa - 5. Ensure that the new AppVM's netvm is set to `none`. + 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 - the option (if available) to view the secret key as text: + If you are prompted to scan a QR code, 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: + 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 - example key from above. You'll get a different secret key from each service - which is unique to you.) Create the script like so: + script for each service we use. (The example service here is a Google + account, using the example key from above. You'll get a unique secret key + 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 - and ease of quickly generating TOTP tokens right from your Qubes VM - command-line: + 5. Now you can create scripts for any other TOTP-supporting services you use, + and enjoy the security and ease of quickly generating authentication tokens + 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