ShardVPN

This tool allows for the temporary creation of a VPN server. You can create it, use it for however long you need, and then promptly destroy it.

ShardVPN has only been tested on macOS, and may or may not work as expected with other operating systems. It is still under development, and may change drastically over time.

ShardVPN is named for the Shards in Brandon Sanderson's series The Stormlight Archive.

Ten heartbeats.
One.
That was how long it took to summon a Shardblade. If Dalinar's heart was racing, the time was shorter. If he was relaxed, it took longer. Two.

- The Way of Kings by Brandon Sanderson, p. 202.

Contents

• Dependencies
  • Setting up AWS Credentials
  • Installing Terraform
  • Setting up the Key Pair
• Using ShardVPN
  • Running ShardVPN
  • Stopping ShardVPN
• Security
• Troubleshooting

Dependencies

Before you are able to use ShardVPN, you will need to have the following required dependencies.

1. A copy of this repository on your local machine
2. An AWS account, with the proper credentials (see Setting up AWS Credentials)
3. Terraform installed on your local machine (see Installing Terraform)
4. An RSA key pair stored on your local machine at ~/.ssh/terraform_rsa (see Setting up the Key Pair)

Setting up AWS Credentials

ShardVPN uses Terraform to create, set up, and tear down the necessary AWS resources on which the VPN runs. Terraform can only operate with the resources on your account that you grant it access to. At this time, the following permissions are required:

• AmazonS3FullAccess
• AmazonEC2FullAccess
• IAMFullAccess
• CloudWatchLogsFullAccess
• AmazonEC2ContainerServiceFullAccess

In the end, your local AWS credentials file must grant ShardVPN the above permissions. I recommend setting up these permissions in the following manner:

1. Go to the IAM service in your AWS account.
2. Create a user. You may name it whatever you like.
3. Create a group. You may name this whatever you like, but I recommend giving it an identifiable name, like 'shard_vpn'.
4. Assign the user to the group.
5. In the group, attach the permission policies listed above.
6. In the user, go to the 'Security Credentials' page and create an access key.
7. Open your local AWS credentials file at ~/.aws/credentials. If you do not yet have this file, create it. You can learn more about this here.
8. Include the credentials you created under a profile for ShardVPN, like so:

   [shard_vpn]
   aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
   aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY
   

   Note: If you want to name the profile something else, you can - but you must change the aws_credentials_profile variable in settings.tfvars, in the main repository folder.

Installing Terraform

On macOS, I find using Homebrew to be the easiest way to install Terraform:

brew install terraform

Otherwise, see https://www.terraform.io/ for installation instructions.

Setting up the Key Pair

At one point, Terraform needs to SSH into an EC2 instance in order to upload and run a script. It does this using an RSA key. The key pair must be stored on your local system at ~/.ssh/terraform_rsa. If you need instructions for generating this key, I have always found this link to be helpful.

Using ShardVPN

Running ShardVPN

Once you have all of the dependencies set up, you can run ShardVPN as follows:

1. Navigate to the main ShardVPN folder.
2. If you are running ShardVPN for the first time, run initialize_terraform.sh.
3. Run build_vpn_from_scratch.sh.
4. Once the script has finished running, go to the S3 service in your AWS account.
5. In the 'shard-vpn-keys' bucket, you will see a number of files. Once your VPN server has initialized, a file with the name shard-vpn-client.ovpn will appear. This takes ~3 minutes.
6. Download the shard-vpn-client.ovpn file.
7. Use the shard-vpn-client.ovpn file with your favourite OpenVPN-compatible VPN software to establish a connection with the server.
   • If you are using macOS, I recommend Tunnelblick
8. Presto! You should now be connected to your own private VPN server!

More about the build_vpn_from_scratch.sh script

This script does the following:

1. Runs terraform apply from the main folder, which create the S3 bucket where the certificates and keys are stored.
2. Runs terraform apply from the folder certifier, which creates an EC2 instance that generates all of the necessary keys and certificates required for a client - server VPN connection.
3. Runs terraform destroy from the folder certifier to tear down that EC2 server, as it is no longer needed.
4. Runs terraform apply from the folder drive, which creates the VPN server that your local machine will connect to.

If you wish, you may run these commands manually to achieve the same result. You can even SSH into the servers yourself using the RSA key you generated, if you want to have a look around.

Settings

In the root folder, there is a settings.tfvars file where user settings may be defined. At this point, the following settings may be defined:

• aws_credentials_profile
  • The profile in your aws credentials file that ShardVPN should use
• traffic_protocol
  • The protocol (udp or tcp) that you want ShardVPN to use. Default: udp
  • UDP protocol will use port 1194, while TCP will use port 443

Stopping ShardVPN

1. If you started ShardVPN using the build_vpn_from_scratch.sh script, then run destroy_drive.sh from the main folder.

More about the destroy_drive.sh script

This script does the following:

1. Runs terraform destroy from the main folder, to remove the 'shard-vpn-keys' bucket.
2. Runs terraform destroy from the folder drive, which tears down the VPN server.

If you wish, you may run these commands manually to achieve the same result.

Security

Below are some of the security measures that ShardVPN is built with.

Separation of the Certificate Authority from the VPN server

The Certificate Authority (CA) is used to sign the server and client keys and certificates. This identifies them as trustworthy (i.e. the server knows the client is trustworthy, and vice versa). If an outside source were to gain access to the CA key, new keys could be generated to gain access to the VPN.

In order to mitigate this risk, once the keys and certificates are generated, the certifier server, which contains the CA key, is torn down. No further keys or certificates can be generated at this point beyond what has been placed in the S3 bucket.

Note that while there is a CA certificate placed in the S3 bucket, this is NOT the CA key. The CA certificate is only used to verify that other certificates were signed by the CA key, and cannot itself sign anything.

SHA256 Authentication of all Data

All data packets passing between the ShardVPN client and server are signed and authenticated using the SSL SHA-256 cryptographic hash algorithm.

SHA256 Encryption of all Control Channel Packets

A control channel packet is a packet of data sent between the client and server during the initial connection and later shutdown phases.

All control channel packets are encrypted using a SSL SHA-256 hash algorithm in order to mask their contents. This helps to prevent Man-in-the-Middle attacks, and also helps to keep these packets from being identified as being part of a VPN.

Encryption of all Data Channel Packets

A data channel packet is any packet of data sent over the VPN after a connection has been initialized.

All data channel packets are encrypted with one of the following ciphers, in order of descending preference:

1. AES-256-GCM
2. AES-128-GCM
3. AES-256-CBC

If your OpenVPN software is using OpenVPN 2.4 or higher, AES-256-GCM will be the default. For older versions, AES-256-CBC will be used.

Troubleshooting

DNS options are not being set properly

You must ensure that the client configuration file has permission to manually set network settings on your local machine. This is because ShardVPN will set your machine to use Google's DNS servers.

To fix this in Tunnelblick, simply open Tunnelblick, go to "Advanced", and make sure that "Allow changes to manually-set network settings" is selected.