From 09e5d87c7b12eb5b3fe23bcb5d1e0c1237b5d8c9 Mon Sep 17 00:00:00 2001 From: brad2014 Date: Fri, 31 Mar 2017 21:19:10 -0700 Subject: [PATCH] Minor name and documentation edits (#327) --- CONTRIBUTING.md | 2 +- README.md | 26 ++++++++++++------------- algo | 10 +++++----- config.cfg | 3 ++- deploy.yml | 2 +- docs/ADVANCED.md | 4 ++-- docs/ANDROID.md | 8 ++++---- docs/FAQ.md | 4 ++-- docs/ROLES.md | 4 ++-- docs/TROUBLESHOOTING.md | 2 +- roles/client/tasks/main.yml | 2 +- roles/security/templates/sshd_config.j2 | 2 +- roles/vpn/tasks/main.yml | 4 ++-- roles/vpn/tasks/ubuntu.yml | 2 +- 14 files changed, 38 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b37f56..41b0be9 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index ff4f732..347ac57 100644 --- a/README.md +++ b/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,7 +89,7 @@ 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 @@ -97,7 +97,7 @@ Find the corresponding mobileconfig (Apple Profile) for each user and send it to ### 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 diff --git a/algo b/algo index 39a75e8..ecf33a1 100755 --- a/algo +++ b/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 diff --git a/config.cfg b/config.cfg index a8c86e8..d4e9a3d 100644 --- a/config.cfg +++ b/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 diff --git a/deploy.yml b/deploy.yml index 4f967b7..c1adc4b 100644 --- a/deploy.yml +++ b/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' ] diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md index ab1bc1a..6b58a10 100644 --- a/docs/ADVANCED.md +++ b/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 diff --git a/docs/ANDROID.md b/docs/ANDROID.md index ba42bdb..1f6faba 100644 --- a/docs/ANDROID.md +++ b/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 diff --git a/docs/FAQ.md b/docs/FAQ.md index 10fb6f3..e18f852 100644 --- a/docs/FAQ.md +++ b/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:info@trailofbits.com). 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:info@trailofbits.com). 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? diff --git a/docs/ROLES.md b/docs/ROLES.md index 1f438c3..f43e6f8 100644 --- a/docs/ROLES.md +++ b/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) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 87fb704..326afc5 100644 --- a/docs/TROUBLESHOOTING.md +++ b/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. diff --git a/roles/client/tasks/main.yml b/roles/client/tasks/main.yml index c5b6997..ae340d3 100644 --- a/roles/client/tasks/main.yml +++ b/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 diff --git a/roles/security/templates/sshd_config.j2 b/roles/security/templates/sshd_config.j2 index c014eb4..ebc93ee 100644 --- a/roles/security/templates/sshd_config.j2 +++ b/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 diff --git a/roles/vpn/tasks/main.yml b/roles/vpn/tasks/main.yml index a11e212..5ec7f3d 100644 --- a/roles/vpn/tasks/main.yml +++ b/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 diff --git a/roles/vpn/tasks/ubuntu.yml b/roles/vpn/tasks/ubuntu.yml index dbd459f..4856a97 100644 --- a/roles/vpn/tasks/ubuntu.yml +++ b/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