Generating, importing and authorising SSH keys in cPanel

This article is in progress, please check back soon.

Basics about SSH Keys

SSH keys allow you to connect to your cPanel account via SSH, SFTP and Git, and are considered significantly more secure than account passwords. We strongly recommend using SSH keys instead of passwords whenever possible.

Please note: The SSH keys are only usable with the cPanel user/account. They cannot be used for FTP sub-accounts created in cPanel under Files -> FTP Accounts or Preferences -> User Manager. Those accounts can only be used for FTP and FTPS using their respective password, but not with SSH keys, SFTP or SSH.

When you generate an SSH key, you get two types of keys:

• Public SSH Key
  
  • The public key is always stored on your server or account to which you want to connect.
  • It tells the server that the owner of the related private key can access the server, provided that the public key is marked as aurhorised.
  • You can keep the public key just saved for future use and not authorise it.
    For example, this is useful when someone outside of your organisation (e.g., a developer) connects to your server from time to time, but you want to give only temporary access.
  • If the public key is not authorised, you will not be able to connect using the related private key.
• Private SSH Key
  • The private key is used to access the server or account on which the related public key is authorised.
  • If the public key is only saved, but not authorised, access will be denied.
  • The password is optional for private keys, as there are some scripts and programs that may not support key passwords. When possible, we recommend setting a password for your private key as an additional layer of protection.
  • The cPanel SSH key generator enforces passwords for private keys, but you can generate passwordless keys through the Terminal or on your own computer using OpenSSH (with the ssh-keygen tool), then import to cPanel.
  • SSH keys are generated in OpenSSH format by default. Some scripts and programs (e.g. FileZilla) may only support the PPK (PuTTY Private Key) format. cPanel allows you to convert the private key to PPK format (later in this guide) or you can use other tools to convert.
  • It's recommended not to keep the private key on the same server or account on which the public key is saved/authorised. Please save the private key and its password (if applicable) in a safe place.

Public and private SSH keys are not necessarily tied to your hosting account. They can be used on multiple servers, accounts and devices. You can generate a set of SSH keys and add the public key to all servers and hosting accounts that you own and/or add the private key to all devices from which you want to connect (e.g., your computer, laptop, mobile device, etc.). The keys can also be shared with trusted parties (e.g., with your team). However, we recommend using separate SSH keys when possible for better security.

Generate a New SSH Key in cPanel

To generate a new SSH key through the cPanel interface:

1. Login to cPanel (e.g., https://yourdomain.tld/cpanel)
2. Navigate to Security -> SSH Access
3. Click on the "Manage SSH Keys" button
4. Click on the "Generate a New Key" button
5. Enter the details for your new key
   • Key Name (defaults to "id_rsa")
     • Enter a name for your keys (e.g. johndoe-desktop)
   • Key Password
     • Enter a strong password for the private key
   • Key Type
     
     • The default setting (RSA) is recommended.
     • DSA is faster at decrypting and signing, while RSA is faster at encrypting and verifying.
   • Key Size
     
     • 1024-bit keys are not future-proof and easier to compromise.
     • 2048-bit keys currently provide the best combination of security and performance.
     • 4096-bit keys are more secure, but may result a slightly lower performance.
6. Click on the "Generate Key" button.
7. The SSH keys will generate and give you the raw output, including the fingerprint and randomart image. These two are useful to identify and verify the keys, but aren't necessary to use the keys.

Your new SSH keys will be ready for use after you authorise the public SSH key (see the steps below).

Import an SSH Key in cPanel

If you already have a set of SSH keys, you can import them to cPanel, as follows:

1. Login to cPanel (e.g., https://yourdomain.tld/cpanel)
2. Navigate to Security -> SSH Access
3. Click on the "Manage SSH Keys" button
4. Click on the "Import Key" button
5. Enter the key name and paste the keys in the appropriate text fields
   • You can import the public or private key only (or both), as needed
   • The passphrase field is not required when importing a public key or a passwordless private key
6. Click on the "Import" button

When importing public SSH keys, please remember to authorise them (see the steps below).

Authorising or Deauthorising a Public SSH Key

To manage the authorisation of a public SSH key, please follow these steps:

1. Login to cPanel (e.g., https://yourdomain.tld/cpanel)
2. Navigate to Security -> SSH Access
3. Click on the "Manage SSH Keys" button
4. Under the "Public Keys" section, click on the "Manage" button near the key that you wish to authorise
5. Click on the "Authorize" or "Deauthorize" button

When a public key is authorised, you are able to connect to your hosting account using the related private key. It's recommended to deauthorise a key if it's not actively used (e.g. keys of third-parties).

Removing SSH Keys

To remove SSH keys from your account, please follow these steps:

1. Login to cPanel (e.g., https://yourdomain.tld/cpanel)
2. Navigate to Security -> SSH Access
3. Click on the "Manage SSH Keys" button
4. Under the "Actions" column, click on the "Delete" button near the key that you want to remove

Please note: When removing a public key, please make sure to deauthorise it first (in case it's authorised), otherwise it may still remain added to the authorised keys, even if you no longer see it in cPanel.

Converting a Private SSH Key to PPK Format

Some applications and scripts don't support the OpenSSH format and require the private key to be converted to PPK (PuTTY Private Key) format. You can do this through the command line, but also through cPanel, as follows:

1. Login to cPanel (e.g., https://yourdomain.tld/cpanel)
2. Navigate to Security -> SSH Access
3. Click on the "Manage SSH Keys" button
4. Under the "Private Keys" section, click on the "View/Download" button near the key that you wish to convert
5. Scroll down to the "Convert the [...] key to PPK format:" section
6. Enter the passphrase for the private key or leave the field empty if it's a passwordless private key
7. Click on the "Convert" button
8. Click on the "Download Key" button to download the key in PPK format
   • If you haven't downloaded the key and need it later, you can repeat the above steps or find it under the ~/.ssh/putty folder

SSH Key Files and Locations

If you need the SSH key as files, you can simply download them from cPanel by clicking on the "View/Download" button near the key that you wish to download and then on the "Download" button. Sometimes it can be easier to access the keys directly, for example if you need to manage multiple keys.

• The private and public SSH keys are located under the ~/.ssh folder
• Public keys have the .pub file extension
• Private keys have no file extension
• Authorised public keys are saved under the ~/.ssh/authorized_keys file

Troubleshooting

If you're unable to connect using the related private key, please check the following:

• Assure that the public key (related to the private key) is authorised (see above steps)
• Assure that the permissions are correct, as incorrect permissions would cause the SSH server to deny connections:
  • The ~/.ssh folder and its sub-folders (if any) must have permissions set to 700
  • The public key files (*.pub) and the authorised keys file (~/.ssh/authorized_keys) file must have permissions set to 644
  • The private keys (without file extensions) must have permissions set to 600
• Assure that connections with SSH keys are permitted on the SSH server
• Assure that you're using the correct passphrase for the private key (unless the key is passwordless)

Should you still be unable to connect, please contact our support department and provide the error message and/or screenshots. For security reasons, please do not send us the private key or its passphrase.

Updated by SP on 15/12/2022