WPCloud Deploy Documentation

How To Generate an SSH Key Pair

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.

About SSH Keys

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:

  1. The strength of the keypair – most operating systems default to 2048 bits but you can increase this size.
  2. The encryption you will use – RSA, an Elliptic Curve or one of the many other options available
  3. The key format for the data stored in the private key file (we also refer to this as the file format but the precise terminology is “key format”).  Some common key formats are PKCS1, PKCS8 and OPENSSH.  (Your public key will usually be in OPENSSH format regardless of the private key format .)

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.

  • If you choose a PKCS1 or PKCS8 key format you can optionally use a password for the private key.  However, the password must consist of alpha-numeric characters only.
  • If you choose an OPENSSH key format for your private keys, you CANNOT use a password for it. This is because we use the PHPSecLib library to handle keys and one of its limitations is lack of support for password protected OpenSSH keys.

What If I Have Existing Keys?

You can use your own keys if:

  1. The private key is in PKCS format without a password
  2. The private key is in PKCS format with a password consisting of only alphanumeric characters
  3. The private key is in OPENSSH format without a password (As mentioned above we use the PHPSecLib library to handle keys and one of its limitations is lack of support for password protected OpenSSH keys.)

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.

Other Recommendations

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.


How To Generate Keys

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!

What You Will Need

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 Digital Ocean, Linode, Vultr etc.  By far the easiest to use is Digital Ocean.  (You can also use 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 directory.

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.)

  • Your password should consist of only alpha-numeric characters – no “special” characters should be used.

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.

Generating Keys on Older Operating Systems

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

Some Important Notes about SSH Keys

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.


Related Videos

How to generate an SSH key-pair in Windows and upload to DigitalOcean, Linode & Vultr

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.

How to generate an SSH key-pair on a Mac and upload to DigitalOcean, Linode & Vultr

How to generate an SSH key-pair on Linux and upload to DigitalOcean, Linode & Vultr

Important Notes

  1. If you add a password to your private key, keep it to letters and numbers only.  It reduces the chances that you inadvertently use a special character than means something to the Linux command line.
  2. If you use a MAC or the WSL to generate your keys using just the default parameters, do NOT add a password to the private key.

How To Determine The Format Of Your Private Key

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:

  1. —–BEGIN RSA PRIVATE KEY—–
  2. —–BEGIN PRIVATE KEY—–
  3. —–BEGIN OPENSSH PRIVATE KEY—–

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!


Add Keys To Your Cloud Providers’ Dashboard

Add your public key to Digital Ocean

Add your public key to Vultr

Add your public key to UpCloud

Resources

Here are some useful links to documents about generating SSH keys written by various cloud server providers:

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.

Generating key pairs on MacOS

Generating and using SSH Keys on Vultr

More information about key format differences

Share: