All of the servers that are linked to our platform need to use SSH keys. Most server providers allow you to add the public portion of the key to your account which will then be added to new servers you create. For those providers you will see a drop-down in our settings screen showing the existing keys you have uploaded and asking you to provide the private key portion.
This document will explain everything you need to know about SSH keypairs including how to properly generate them.
SSH Keys are two text files that consist of your PUBLIC KEY and your PRIVATE KEY. The data in your Public Key is uploaded to your cloud provider while your private key is entered into the WPCD configuration screens. Your cloud provider will install your public key into any servers it creates for you. Your private key in WPCD will be used to match against the public key when we try to log into to the server.
When you create a public key pair you need to decide a few things:
There are some trade-offs to your key format decision so lets discuss that before we walk you through the process of generating your key pair.
You can use your own keys if:
If you used a MAC or WSL or Ubuntu 20.04 or later to generate your keys and used the ssh-keygen defaults, there is a good chance you ended up with an OPENSSH key format. This means that if you created it with a password you will NOT be able to use it with WPCD. You should generate a new pair without the password.
We strongly recommend that you use an ssh keypair that is not in use anywhere else. It is good security practice to avoid reusing your keys across different services.
If you use different cloud providers you should use a different keypair at each of them.
Now lets talk about how to generate a new keypair. Once generated, you will upload the public key portion to your provider’s service and enter the contents of the private portion into our settings screen.
You should save both parts in a safe location!
For the purposes of this article you will need access to an ubuntu based machine. If you do not have one already, you can quickly fire up a temporary one on any of the cloud server providers such as DigitalOcean, Linode, Vultr etc. By far the easiest to use is DigitalOcean. (You can also use the Windows Subsystem for Linux (aka WSL) or a MAC.)
Once you’re logged in on the command line, use the ssh-keygen command:
$ ssh-keygen -m pem
This command will generate a 2048 bit key pair in a PKCS key format. You can generate a stronger 4096 key pair by using the -b 4096 flag.
$ ssh-keygen -b 4096 -m pem
After running the command you should see something like this in the output:
Generating public/private rsa key pair. Enter file in which to save the key (/your_home/.ssh/id_rsa):
To avoid overwriting any default existing keys, you should enter an alternate path instead of allowing use of the default .ssh/ folder in your home directory. Entering a name without a path will place the file in your current folder.
After entering a new path, you should see a prompt asking for a password:
Enter passphrase (empty for no passphrase):
It’s asking you for a password that will be used to encrypt the private portion of your key pair. You can leave it blank by just hitting the enter key or, of course, enter an alpha-numeric password. (Just make sure you remember the password otherwise the entire keypair will be useless.)
After the password prompt, your keypair will be generated and placed into the directory you specified. You can download both files from that directory onto your local machine. Add the public portion to your cloud provider’s service.
If you’re using an older OS to generate your keys – eg: Ubuntu 18.04, you might get an error using the ‘-m’ parameter shown in the above examples. If that’s the case, just drop it – usually an RSA key in PKCS format will be generated by default:
$ ssh-keygen -b 4096
The commands we gave you above generates PKCS RSA keys. You can generate OpenSSH formatted keys by dropping the ‘-m’ parameter on newer operating systems which creates OpenSSH formatted keys by default:
$ ssh-keygen -b 4096
These types of keys will work with WPCD – as long as you do NOT use a password with them. We use the PHPSecLib library to handle keys and one of its limitations is lack of support for password protected OpenSSH keys.
The videos below will help you visualize the process for generating keys. Please note that the commands you enter must use the ‘-m pem’ parameter to get RSA/PEM keys – this is not shown in the videos since they were recorded before the default ssh-keygen format was changed from RSA/PEM to OpenSSH.
Your public key file will almost always start with “ssh-rsa” which indicates an OPENSSH format. Eg:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAejKY/gtRZqjqOLx6ZTEIjAG+ X2KUh0YQOko+FD/jiHMHF25oZWUSqPVz7xQOBmdFn+8bqPnHjzc+fipJDtrA/BX0 9QNM2LRzm98dP/PkyeoFMoZLNf8NrbwLOzZAkTMyeuZYqQRlPrNszglY/AK52Drf qm2zw7t53Ux6m1btmm4DJcijaEkfkUQHtvyH1VcsDxpuYUk4hayxYeXx2jMwpcY4 JP6yRiAO+BbNjj8d4x7zSWZzEkeqe++EfSvhjXz+uibQFSdeEL8TA22NA7rqYck7 8aEyrhrKkbPydoAShrSofW37FWioX9BrtNHIkX3/nlXbUfc+OUZ2iOWW/CCL
Your private key will usually start with one of the following:
Item 1 is a PKCS1 formatted private key. Item 2 is a PKCS8 formatted private key. Item 3 is an OPEN SSH formatted private key.
If your private key file starts with a line similar to item 3 above, it must NOT have a password associated with it!
Here are some useful links to documents about generating SSH keys written by various cloud server providers:
Install an OPENSSH client on Windows 10 – useful if you want to use the command prompt to access a remote machine via SSH.
Generate key pairs using PuTTY – this is useful if you are working on a Windows machine and really don’t want to spin up a temporary cloud server.