Minor name and documentation edits (trailofbits#327)

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 * Check that your issue is not already described in the [FAQ](docs/FAQ.md) or [troubleshooting](docs/TROUBLESHOOTING.md) docs
 * Did you remember to install the dependencies for your operating system prior to installing Algo?
-* Client supported is limited to only modern operating systems, e.g. macOS 10.11+, iOS 9+, Windows 8+, Ubuntu 16.04+, etc.
+* Client support is limited to modern operating systems, e.g. macOS 10.11+, iOS 9+, Windows 8+, Ubuntu 16.04+, etc.
 * If you need to file an issue, fill out any relevant fields in the Issue Template
 
 ### Pull Requests

README.md

@@ -7,13 +7,13 @@
 [![PayPal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=CYZZD39GXUJ3E)
 [![Patreon](https://img.shields.io/badge/back_on-patreon-red.svg)](https://www.patreon.com/algovpn)
 
-Algo VPN is a set of Ansible scripts that simplifies the setup of a personal IPSEC VPN. It contains the most secure defaults available, works with common cloud providers, and does not require client software on most devices.
+Algo VPN is a set of Ansible scripts that simplify the setup of a personal IPSEC VPN. It uses the most secure defaults available, works with common cloud providers, and does not require client software on most devices.
 
 ## Features
 
-* Supports only IKEv2 w/ a single cipher suite: AES-GCM, HMAC-SHA2, and P-256 DH
-* Generates Apple Profiles to auto-configure iOS and macOS devices
-* Provides helper scripts to add and remove users
+* Supports only IKEv2, with a single cipher suite: AES-GCM, HMAC-SHA2, and P-256 DH
+* Generates Apple profiles to auto-configure iOS and macOS devices
+* Includes helper scripts to add and remove users
 * Blocks ads with a local DNS resolver and HTTP proxy (optional)
 * Sets up limited SSH users for tunneling traffic (optional)
 * Based on current versions of Ubuntu and strongSwan
@@ -34,16 +34,16 @@ The easiest way to get an Algo server running is to let it set up a _new_ virtua
 
 1. **Setup an account on a cloud hosting provider.** Algo supports [DigitalOcean](https://www.digitalocean.com/) (most user friendly), [Amazon EC2](https://aws.amazon.com/), [Google Compute Engine](https://cloud.google.com/compute/), and [Microsoft Azure](https://azure.microsoft.com/).
 
-2. [Download Algo](https://github.com/trailofbits/algo/archive/master.zip) and decompress it in a convenient location on your local machine.
+2. [Download Algo](https://github.com/trailofbits/algo/archive/master.zip) and unzip it in a convenient location on your local machine.
+
+3. Install Algo's core dependencies. Open the Terminal. The `python` interpreter you use to deploy Algo must be python2. If you don't know what this means, you're probably fine. `cd` into the `algo-master` directory where you unzipped Algo, then run:
 
-3. Install Algo's core dependencies. Open the Terminal. The `python` interpreter you use to deploy Algo must be python2. If you don't know what this means, you're probably fine. `cd` into the directory where you downloaded Algo, then run:
-
     - macOS:
       ```bash
       $ python -m ensurepip --user
       $ python -m pip install --user --upgrade virtualenv
       ```
-    - Linux (deb-based): 
+    - Linux (deb-based):
       ```bash
       $ sudo apt-get update && sudo apt-get install \
           build-essential \
@@ -59,7 +59,7 @@ The easiest way to get an Algo server running is to let it set up a _new_ virtua
 
 4. Install Algo's remaining dependencies for your operating system. Using the same terminal window as the previous step run the command below.
     ```bash
-    $ python -m virtualenv env && source env/bin/activate && python -m pip install -r requirements.txt 
+    $ python -m virtualenv env && source env/bin/activate && python -m pip install -r requirements.txt
     ```
     On macOS, you may be prompted to install `cc` which you should accept.
 
@@ -89,15 +89,15 @@ Advanced users who want to install Algo on top of a server they already own or w
 
 ## Configure the VPN Clients
 
-Certificates and configuration files that users will need are placed in the `configs` directory. Make sure to secure these files since many contain private keys. All files are prefixed with the IP address of your new Algo VPN server.
+Distribute the configuration files to your users, so they can connect to the VPN.  Certificates and configuration files that users will need are placed in the `configs` directory. Make sure to secure these files since many contain private keys. All files are saved under a subdirectory named with the IP address of your new Algo VPN server.
 
 ### Apple Devices
 
 Find the corresponding mobileconfig (Apple Profile) for each user and send it to them over AirDrop or other secure means. Apple Configuration Profiles are all-in-one configuration files for iOS and macOS devices. On macOS, double-clicking a profile to install it will fully configure the VPN. On iOS, users are prompted to install the profile as soon as the AirDrop is accepted.
 
 ### Android Devices
 
-You need to install the [StrongSwan VPN Client for Android 4 and newer](https://play.google.com/store/apps/details?id=org.strongswan.android) because no version of Android supports IKEv2. Import the corresponding user.p12 certificate to your device. See the [Android setup instructions](/docs/ANDROID.md) for more detailed steps.
+You need to install the [strongSwan VPN Client for Android 4 and newer](https://play.google.com/store/apps/details?id=org.strongswan.android) because no version of Android supports IKEv2. Import the corresponding user.p12 certificate to your device. See the [Android setup instructions](/docs/ANDROID.md) for more detailed steps.
 
 ### Windows
 
@@ -117,8 +117,8 @@ Install strongSwan, then copy the included user_ipsec.conf, user_ipsec.secrets,
 Depending on the platform, you may need one or multiple of the following files.
 
 * ca.crt: CA Certificate
-* user_ipsec.conf: StrongSwan client configuration
-* user_ipsec.secrets: StrongSwan client configuration
+* user_ipsec.conf: strongSwan client configuration
+* user_ipsec.secrets: strongSwan client configuration
 * user.crt: User Certificate
 * user.key: User Private Key
 * user.mobileconfig: Apple Profile

algo

@@ -7,27 +7,27 @@ SKIP_TAGS="_null encrypted"
 additional_roles () {
 
 read -p "
-Do you want to enable VPN On Demand when connected to cellular networks?
+Do you want macOS/iOS clients to enable \"VPN On Demand\" when connected to cellular networks?
 [y/N]: " -r OnDemandEnabled_Cellular
 OnDemandEnabled_Cellular=${OnDemandEnabled_Cellular:-n}
 if [[ "$OnDemandEnabled_Cellular" =~ ^(y|Y)$ ]]; then EXTRA_VARS+=" OnDemandEnabled_Cellular=Y"; fi
 
 read -p "
-Do you want to enable VPN On Demand when connected to Wi-Fi?
+Do you want macOS/iOS clients to enable \"VPN On Demand\" when connected to Wi-Fi?
 [y/N]: " -r OnDemandEnabled_WIFI
 OnDemandEnabled_WIFI=${OnDemandEnabled_WIFI:-n}
 if [[ "$OnDemandEnabled_WIFI" =~ ^(y|Y)$ ]]; then EXTRA_VARS+=" OnDemandEnabled_WIFI=Y"; fi
 
 if [[ "$OnDemandEnabled_WIFI" =~ ^(y|Y)$ ]]; then
   read -p "
-Do you want to exclude trusted Wi-Fi networks from using the VPN? (e.g., your home network. Comma-separated value, e.g., HomeNet,OfficeWifi,AlgoWiFi)
+List the names of trusted Wi-Fi networks (if any) that macOS/iOS clients exclude from using the VPN (e.g., your home network. Comma-separated value, e.g., HomeNet,OfficeWifi,AlgoWiFi)
 : " -r OnDemandEnabled_WIFI_EXCLUDE
   OnDemandEnabled_WIFI_EXCLUDE=${OnDemandEnabled_WIFI_EXCLUDE:-_null}
   EXTRA_VARS+=" OnDemandEnabled_WIFI_EXCLUDE=\"$OnDemandEnabled_WIFI_EXCLUDE\""
 fi
 
 read -p "
-Do you want to install a local DNS resolver to block ads while surfing?
+Do you want to install a DNS resolver on this VPN server, to block ads while surfing?
 [y/N]: " -r dns_enabled
 dns_enabled=${dns_enabled:-n}
 if [[ "$dns_enabled" =~ ^(y|Y)$ ]]; then ROLES+=" dns"; EXTRA_VARS+=" local_dns=Y"; fi
@@ -51,7 +51,7 @@ Win10_Enabled=${Win10_Enabled:-n}
 if [[ "$Win10_Enabled" =~ ^(y|Y)$ ]]; then EXTRA_VARS+=" Win10_Enabled=Y"; fi
 
 read -p "
-Do you want to store the CA key? (required for update-users script, but less secure)
+Do you want to retain the CA key? (required to add users in the future, but less secure)
 [y/N]: " -r Store_CAKEY
 Store_CAKEY=${Store_CAKEY:-N}
 if [[ "$Store_CAKEY" =~ ^(n|N)$ ]]; then EXTRA_VARS+=" Store_CAKEY=N"; fi

config.cfg

@@ -1,6 +1,7 @@
 ---
 
-# Add as many users as you want for your VPN server here
+# Add as many users as you want for your VPN server here.
+# Access credentials will be generated for each one.
 users:
   - dan
   - jack

deploy.yml

@@ -23,7 +23,7 @@
     - { role: local, tags: ['local'] }
 
   post_tasks:
-    - name: Local pre-tasks
+    - name: Local post-tasks
       include: playbooks/post.yml
       become: false
       tags: [ 'cloud' ]

docs/ADVANCED.md

@@ -1,6 +1,6 @@
 # Advanced Usage
 
-Make sure you have installed all the dependencies necessary for your operating system as described in the README.
+Make sure you have installed all the dependencies necessary for your operating system as described in the [README](../README.md).
 
 ## Local Deployment
 
@@ -38,7 +38,7 @@ Required tags:
 - cloud
 
 Cloud roles:
- 
+
 - role: cloud-digitalocean, tags: digitalocean
 - role: cloud-ec2, tags: ec2
 - role: cloud-gce, tags: gce

docs/ANDROID.md

@@ -1,9 +1,9 @@
-**NOTE:** If you are a Project Fi user, you must disable WiFi Assistant before continuing. See the [StrongSwan documentation](https://wiki.strongswan.org/projects/strongswan/wiki/AndroidVPNClient) for details.
+**NOTE:** If you are a Project Fi user, you must disable WiFi Assistant before continuing. See the [strongSwan documentation](https://wiki.strongswan.org/projects/strongswan/wiki/AndroidVPNClient) for details.
 
 | Instruction | Screenshot(s) |
 | ----------- | ---------- |
 | 1. Copy your `{username}.p12` certificate to your phone's internal storage. | |
-| 2. [Install the StrongSwan VPN Client](https://play.google.com/store/apps/details?id=org.strongswan.android) (Android 4+) | |
+| 2. [Install the strongSwan VPN Client](https://play.google.com/store/apps/details?id=org.strongswan.android) (Android 4+) | |
 | 3. Open the app and tap "ADD VPN PROFILE" in the top right.  | [![step3-thumb]][step3-screen]  |
 | 4. Enter the IP address or hostname of your Algo server and set the "VPN Type" to "IKEv2 Certificate". | [![step4-thumb]][step4-screen] |
 | 5. Tap "Select user certificate". You will be shown a prompt, tap "INSTALL". | [![step5-thumb]][step5-screen] |
@@ -14,8 +14,8 @@
 | 10. You will be returned to the main menu, and your newly-configured VPN profile should be listed. Tap the profile to connect. | [![step10-thumb]][step10-screen] |
 
 ## Troubleshooting
-### Tapping the VPN profile in StrongSwan has no effect.
-Ensure that "WiFi Assistant" and any other always-on VPNs are disabled before attempting to enable a StrongSwan VPN. If any other VPN is active, StrongSwan may silently fail to initialize a VPN connection. On Android 7, your can manage your VPNs by going to: Settings > Tap "More" under "Wireless & networks" > VPN > tap the gear icon next to any non-strongSwan VPNs listed and ensure they are disabled.
+### Tapping the VPN profile in strongSwan has no effect.
+Ensure that "WiFi Assistant" and any other always-on VPNs are disabled before attempting to enable a strongSwan VPN. If any other VPN is active, strongSwan may silently fail to initialize a VPN connection. On Android 7, your can manage your VPNs by going to: Settings > Tap "More" under "Wireless & networks" > VPN > tap the gear icon next to any non-strongSwan VPNs listed and ensure they are disabled.
 
 
 [step3-thumb]: https://i.imgur.com/LPwIGJE.png

docs/FAQ.md

@@ -18,11 +18,11 @@ The goal of this project is not to provide anonymity, but to ensure confidential
 
 ### 3. Why aren't you using Racoon, LibreSwan, or OpenSwan?
 
-Racoon does not support IKEv2. Racoon2 supports IKEv2 but is not actively maintained. When we looked, the documentation for StrongSwan was better than the corresponding documentation for LibreSwan or OpenSwan. StrongSwan also has the benefit of a from-scratch rewrite to support IKEv2. I consider such rewrites a positive step when supporting a major new protocol version.
+Racoon does not support IKEv2. Racoon2 supports IKEv2 but is not actively maintained. When we looked, the documentation for strongSwan was better than the corresponding documentation for LibreSwan or OpenSwan. strongSwan also has the benefit of a from-scratch rewrite to support IKEv2. I consider such rewrites a positive step when supporting a major new protocol version.
 
 ### 4. Why aren't you using a memory-safe or verified IKE daemon?
 
-I would, but I don't know of any [suitable ones](https://github.com/trailofbits/algo/issues/68). If you're in the position to fund the development of such a project, [contact us](mailto:[email protected]). We would be interested in leading such an effort. At the very least, I plan to make modifications to StrongSwan and the environment it's deployed in that prevent or significantly complicate exploitation of any latent issues.
+I would, but I don't know of any [suitable ones](https://github.com/trailofbits/algo/issues/68). If you're in the position to fund the development of such a project, [contact us](mailto:[email protected]). We would be interested in leading such an effort. At the very least, I plan to make modifications to strongSwan and the environment it's deployed in that prevent or significantly complicate exploitation of any latent issues.
 
 ### 5. Why aren't you using OpenVPN?
 

docs/ROLES.md

@@ -4,9 +4,9 @@
 
 * **Common**
   * Installs several required packages and software updates, then reboots if necessary
-  * Configures network interfaces and enables packet forwarding on them
+  * Configures network interfaces, and enables packet forwarding on them
 * **VPN**
-  * Installs [StrongSwan](https://www.strongswan.org/), enables AppArmor, limits CPU and memory access, and drops user privileges
+  * Installs [strongSwan](https://www.strongswan.org/), enables AppArmor, limits CPU and memory access, and drops user privileges
   * Builds a Certificate Authority (CA) with [easy-rsa-ipsec](https://github.com/ValdikSS/easy-rsa-ipsec) and creates one client certificate per user
   * Bundles the appropriate certificates into Apple mobileconfig profiles for each user
   * Configures IPtables to block traffic that might pose a risk to VPN users, such as [SMB/CIFS](https://medium.com/@ValdikSS/deanonymizing-windows-users-and-capturing-microsoft-and-vpn-accounts-f7e53fe73834)

docs/TROUBLESHOOTING.md

@@ -99,4 +99,4 @@ You did not finish step 4 in the installation instructions, "[Install Algo's rem
 
 ### I have a problem not covered here
 
-If you have an issue that you cannot solve with the guidance here, [join our Slack](https://empireslacking.herokuapp.com/) and ask for help in the #tool-algo channel or [file an issue](https://github.com/trailofbits/algo/issues/new) that describes the problem and we'll do our best to help you.
+If you have an issue that you cannot solve with the guidance here, [join our Slack](https://empireslacking.herokuapp.com/) and ask for help in the #tool-algo channel. You may also [file an issue](https://github.com/trailofbits/algo/issues/new) that describes the problem and we'll do our best to help you.

roles/client/tasks/main.yml

@@ -22,7 +22,7 @@
   with_items:
     - "{{ prerequisites }}"
 
-- name: Install StrongSwan
+- name: Install strongSwan
   package: name=strongswan state=present
 
 - name: Setup the ipsec config

roles/security/templates/sshd_config.j2

@@ -9,7 +9,7 @@ SyslogFacility AUTH
 LogLevel VERBOSE
 
 # Use kernel sandbox mechanisms where possible
-# Systrace on OpenBSD, Seccomp on Linux, seatbelt on MacOSX/Darwin, rlimit elsewhere.
+# Systrace on OpenBSD, Seccomp on Linux, seatbelt on macOS X (Darwin), rlimit elsewhere.
 UsePrivilegeSeparation sandbox
 
 # Handy for keeping network connections alive

roles/vpn/tasks/main.yml

@@ -33,7 +33,7 @@
 - include: freebsd.yml
   when: ansible_distribution == 'FreeBSD'
 
-- name: Install StrongSwan
+- name: Install strongSwan
   package: name=strongswan state=present
 
 - include: ipec_configuration.yml
@@ -43,5 +43,5 @@
 
 - meta: flush_handlers
 
-- name: StrongSwan started
+- name: strongSwan started
   service: name=strongswan state=started

roles/vpn/tasks/ubuntu.yml

@@ -3,7 +3,7 @@
 - set_fact:
     strongswan_additional_plugins: []
 
-- name: Ubuntu | Install StrongSwan
+- name: Ubuntu | Install strongSwan
   apt: name=strongswan state=latest update_cache=yes install_recommends=yes
 
 - name: Ubuntu | Enforcing ipsec with apparmor