|This site replaces the former Compute Canada documentation site, and is now being managed by the Digital Research Alliance of Canada. |
Ce site remplace l'ancien site de documentation de Calcul Canada et est maintenant géré par l'Alliance de recherche numérique du Canada.
Parent page: SSH
What are SSH keys?
SSH relies on public key cryptography (PK) for its security.
PK is based on a "keypair", which consists of a private part, to be kept secret, and a public part, which can be distributed freely. Anyone can use the public key to encode a message, but the message can only be decoded with the private part. This is why PK is sometimes described as "asymmetric encryption".
PK can also be used to verify identities: if someone is claiming to be Alice, then a second party, Bob, can send Alice a message encoded with Alice's public key. If the person claiming to be Alice can tell Bob what is in the message, then that person has access to Alice's private key. In this sense, possession of a private key establishes identity.
PK systems are the basis for the SSL and TLS protocols that protect most internet traffic, such as HTTPS websites.
On our systems, PK is used in SSH several ways:
- When connecting to our systems, your SSH client normally uses our system's public key to ensure that it has connected to the real (authentic) server.
- PK is used to establish an encrypted session so that all following traffic is secure from eavesdropping.
- The remote server can use your public key to verify your identity - that is, to allow you to log in.
We strongly recommend using PK to connect to our systems. Using PK is almost always more secure than using a password.
Generating an SSH Key
Using PK requires some initial configuration, but once this is done it is both more secure and more convenient. To use PK, you must generate a key pair and install the public key on any systems you intend to connect with.
You should generate a key pair on your own system, or a system you believe to be secure. The private part of the key pair should never be shared or copied on another computer, as is the case with any password.
When generating a key pair, you will be prompted for a "passphrase". This is a string that is used to encrypt the private key. You should provide a strong passphrase that is memorable. We recommend 15 characters or more. This passphrase offers protection if the private key file is stolen.
The specific process to generate an SSH key pair depends on the operating system you use. For the Windows PuTTY or MobaXterm clients, see Generating SSH keys in Windows. For a Unix-like environment (Linux, Mac, Windows Subsystem for Linux or Cygwin), see Using SSH keys in Linux. In addition if you are using the cloud, OpenStack provides a method for creating keypairs: See the ssh key pair section on the Cloud Quick Start page.
Installing your key
To install the key, you must make the target/destination system aware of the public part of your key. In March 2021, we added a convenient way to do this.
You should follow the steps:
STEP 1 - Go to CCDB as indicated below
STEP 2 - Grab your SSH public key
Since the public key is plain text, you can examine it under Windows by opening the file with Notepad. Under Linux/MacOS enter cat .ssh/id_rsa.pub on the command line.
In both cases, you will see something like this, as a very long single line:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC3qeojDkUShnPTq9pI3cCZe+jgD6RKA/6CPsJIWZ8MqbX6wkk6 hHgKqKd2/9d7cj8e03Cfv4JLoD++P9fUPE3UyYrP/uVi4zytp5rmIZI4Qo1LvD1Obs0e78y0Dp7pfG1EHTYdn0p8 zHa0lNLOrZMmzDP0UMVdf4WKuv3Th2K/35yQ7DVIei6X/33Dcmsqd8bTXq7aFlw2y4sa/CHs314G6WYuJ9cTXtsW Dlc9oWJuOVqILJLeGQpl3BVEM9aKcYksqLMV1UlZF8bHbry0PKCnrJrNMzVulWfnmSOZ+lPcV32OsDRkFaKsdxPy +PxywieC86mxy1v216jeOdHnhLfOJc/VYDqf4egxReSCb3WOucHBB5J1jtDt47GuamKs+F2T7obqCb0J6oTyzgVF RIZryxwvh5fQF5jk3LsBGsbhe9GYwDAk54GV6I0rWnXp56mJZjO4JCRQGbwLAJVxH4a7UrBmba2pRcZxEZmbIcBB Sjb9KPECtaxiY/aty39077DCmcLCmzeOgBdh0zIkdBYu+OJ65MFKMxzoJWPDbZIcbSRGHEVhDnBZMNj1OiJS+E2D A+F0tPH7J+xox1vUoXGAI0cNv+s/nlVRuOZoZjhk6s7tLXeVcToc+Y9Wqx8fdL7D4FegWwB9lsVhpfC4NaA9R8Ao OfJUwHSNqUc6SfIt7w== user@machine
Note that you must generate your own pair of public and private keys; you cannot copy the above example for your own use. If the format observed is different (which is the case when the key is generated with PuTTY for instance), you can open PuTTY Key Generator or MobaxTerm SSH Key Generator, go to 'File', select 'Load private key' and grab the content under 'Public key for pasting into OpenSSH authorized_keys' as shown in this image.
For instance, this is a public key in PEM format that would need to be converted before going to STEP 3:
-----BEGIN RSA PUBLIC KEY----- MIIBCgKCAQEAxFm+Fbs+szeV2Vg2T5ufg8az0jD9DD/A0iNLKef2/0gPULn1ebFQ SvQwts5ZGcza9t6l7fSKObz8FiAwXn+mdmXrxx3fQIepWa2FeCNbTkiKTTpNmERw H0v3RR3DpJd8cpg5jdJbINlqDUPdqXxZDPIyZuHbEYUiSrb1v5zscVdgVqhJYi9O OiEj7dPOLp1ko6s7TSgY8ejGnbmUL/gl+/dfhMNKdhLXMXWByucF1577rfAz3qPn 4JMWrG5TCH7Jj8NpIxFhkV9Qjy40Ml81yDqMlbuE9CUZzVhATe8MdIvcXUQej8yl ddmNnAXmfTDwUd5cJ/VSMaKeq6Gjd/XDmwIDAQAB -----END RSA PUBLIC KEY-----
STEP 3 - Upload your SSH public key into CCDB form
Once your public key is loaded into CCDB this way, you can use it to log in to any of our clusters. However, our OpenStack cloud systems cannot access the keys entered in the CCDB.
Changes to public keys will often propagate to clusters in less than a minute; in some cases however, it can take up to approximately 30 minutes.
Note: Public keys in RFC4716 or PKCS8 formats will look similar to PEM, with small variations in the header and footer lines.
Support for this method might eventually be withdrawn.
The CCDB method described above makes your public key available on all of our HPC systems. This is convenient, and is often desired.
However, there may be circumstances in which you want to install a key only on a specific system. You can do this by adding the key
to a file in your home directory on that system. For instance, to install a key that only works on Cedar,
copy your public key into the file
~/.ssh/authorized_keys on Cedar.
This will allow you to log in to any of Cedar's login nodes using PK.
On our systems (or any other with OpenSSH) the
ssh-copy-id command is the most convenient way to do this:
ssh-copy-id -i computecanada-key email@example.com
authorized_keys mechanism is standard, and almost universally used on the internet. It is however somewhat fragile:
Specifically, SSH is quite picky about the permissions on the
authorized_keys file, as well as your home directory and the
This is described further in using SSH keys in Linux.
Using a key agent
Although it's important to secure your private key by encrypting it with the passphrase, it is inconvenient to have to enter your passphrase every time you use the key. Rather than leaving the private key unencrypted, we strongly suggest using an SSH key agent. You type the passphrase when starting up the agent, after which the agent supplies the private key for new connections. This avoids storing the unencrypted private key on permanent storage, where it is more vulnerable to being stolen or copied.
Options for key generation
Note that this operation should be performed on your own computer, *not* on a shared computer, such as a cluster.
When you generate a key, the default settings are usually sufficient. However, here are a few options which may be of interest. We demonstrate these options here using
ssh-keygen as described in Using SSH keys in Linux, but the same options are available if you are using a graphical interface as described in Generating SSH keys in Windows.
- You can specify a comment for the key, which may be helpful if you have multiple keys:
ssh-keygen -C 'Alliance systems'
- You can also choose the name of the key file:
ssh-keygen -f alliance-key
This produces a file
alliance-key containing the private part, and
alliance-key.pub for the public part. If you do this, though, you may have to use the
-i option to specify the name of the key when logging in, like this:
ssh -i alliance-key user@host
- There are sometimes reasons to choose a different key type (rather than the RSA default):
ssh-keygen -t ed25519
- You can strengthen certain key types, such as RSA, by setting a longer key length:
ssh-keygen -t rsa -b 4096
SSH key constraints
The public key syntax permits you to provide a number of very useful constraints that limit what the key is allowed to do. By default, a public key installed without constraints can do anything. For instance, this public key:
restrict,command="squeue --me" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGhczaUoV6SzR2VEf9Rp4/P9xHVU8S72CKHrwKU+Yntx
can only perform one simple operation (showing whether you have any jobs in Slurm). An interesting example is:
restrict,command="/usr/libexec/openssh/sftp-server" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGhczaUoV6SzR2VEf9Rp4/P9xHVU8S72CKHrwKU+Yntx
which allows the key to be used only for SFTP, which is how sshfs works.
The key constraint can also limit which hosts can connect using the key:
restrict,from="d24-141-114-17.home.cgocable.net" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGhczaUoV6SzR2VEf9Rp4/P9xHVU8S72CKHrwKU+Yntx
Limiting by hosts is a powerful way to minimize the danger posed by a key being compromised. In this case, the "restrict" keyword turns off "pty allocation", which makes an interactive session behave peculiarly. For a source-constrained interactive session:
restrict,from="d24-141-114-17.home.cgocable.net",pty ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGhczaUoV6SzR2VEf9Rp4/P9xHVU8S72CKHrwKU+Yntx
allows pty allocation.
There are a large number of these key constraints, which are documented in the sshd man page ("man sshd" on a linux system).
Best practices for key pairs
- Always encrypt your private key with a passphrase. We recommend 15 characters or more for the passphrase.
- Do not share your private key.
- Do not copy your private key to a remote system. Your private key should not leave your workstation!
- If you have several laptops, you can create dedicated SSH key pairs for each of them.
- If you have several pairs, you may wish to name the keys. For example,
- If you name a key you must use the
-ioption to specify the key name when logging in, like this:
ssh -i Laptop_RSA4096 username@host
- If you name a key you must use the
ssh-agentto make encrypted keys convenient.
- If you use agent forwarding, use
- Apply constraints to your public key to limit its scope.
Here are some links to short videos on setting up SSH keys: