SSH Key Access

SSH keys are the standard way to authenticate to VMs on OURcloud. While the mechanics of using them are straightforward, there are some common pitfalls that many users encounter which this page will help you navigate.

This is the most important thing to understand: your private key is functionally a password. Anyone who has it can log in as you. Unlike a password, you can’t change it without also updating every server that trusts it. Also unlike a password, you can have more than one. When logging in with a password, there is only one correct password, but with SSH, the correct key is any key that is trusted by the system you’re trying to authenticate to. That trust is established by placing that key in the authorized_keys file as described below. Note that the use of a private key as a “password” only pertains to logging in, and actions that would normally require a password (such as the use of sudo) will still need one unless configured not to.

One common source of confusion is that the public key works the opposite way - you’re supposed to give it out freely. The public key goes on the server, the private key stays on your machine. If you accidentally put your private key on a server, generate a new keypair immediately.

It’s worth noting that you can encrypt your private key with a passphrase, and it is generally a good idea to do so, but that passphrase only unlocks the key and has nothing to do with the system you are logging into. Make sure to remember it or keep it written down somewhere safe, as without it your private key will be unrecoverable. While outside the scope of this document, SSH agents can help manage encrypted keys.

The name of a key is arbitrary, but since the SSH client only checks for keys with default names, you need to be conscious of the name you choose. If you named your key myserver_key or id_rsa_work, the client won’t find it unless you tell it to (see the config section below). Choosing a custom name isn’t a bad choice though, as it makes it easier to keep track of which key serves what purpose, and means you’re less likely to accidentally overwrite it. A typical public private key pair will look something like id_rsa, id_rsa.pub, where the key ending in .pub is the public key. Again this naming scheme is the default, but ultimately arbitrary.

If you need to generate a new keypair:

ssh-keygen -t ed25519 -C "your_email@example.com"

This creates id_ed25519 (private) and id_ed25519.pub (public) in your .ssh directory. The -C flag is just a comment to help you identify the key later. The algorithm you chose (-t) is mostly personal preference, but ed25519 is a good general purpose choice.

On Unix-like systems, SSH will refuse to use your private key if the permissions are too open. This is a security feature, but the error message isn’t always obvious.

Your .ssh directory should be 700 (only you can read/write/execute), and your private key should be 600 (only you can read/write). If you get a “permissions too open” error or SSH just silently ignores your key:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa    # or whatever your key is named

This is not an issue on Windows.

The SSH config file (~/.ssh/config on Linux/macOS, C:\Users\<you>\.ssh\config on Windows) is extremely useful and makes SSH much easier to use.

A basic entry looks like this:

Host mycoolvm
       HostName 192.168.1.100
       User research_user
       IdentityFile ~/.ssh/my_project_key

This lets you type ssh mycoolvm instead of ssh -i ~/.ssh/my_project_key research_user@192.168.1.100.

More importantly, this is how you tell SSH to use a non-default key name or location. Without a config entry (or the -i flag), SSH won’t find keys with custom names. ## $USER is you

When you SSH to a server, you need to specify a username. If you don’t, SSH assumes your local username, which almost never matches your username on the server.

If your local username is jsmith but your account on the VM is john.smith, you need to either:

- Specify it on the command line: ssh john.smith@server 

- Put it in your config file (as shown above)

The error you get when the username is wrong can be confusing - it often looks like an authentication failure rather than a “user doesn’t exist” error. For example:

ssh notarealuser@mycoolvm

notarealuser@mycoolvm's password:

Permission denied, please try again.

Your username is case sensitive as well, and typically all lowercase letters.

The name of a key is arbitrary, but since the SSH client only checks for keys with default names, you need to be conscious of the name you choose. If you named your key myserver_key or id_rsa_work, the client won’t find it unless you tell it to (see the config section below). Choosing a custom name isn’t a bad choice though, as it makes it easier to keep track of which key serves what purpose, and means you’re less likely to accidentally overwrite it. A typical public private key pair will look something like id_rsa, id_rsa.pub, where the key ending in .pub is the public key. Again this naming scheme is the default, but ultimately arbitrary.

Another common point of confusion is the relationship between public and private keys. They are a pair and if you put public key A on a server, you must use private key A to connect. You can’t use private key B.

If you have multiple keypairs (one for work, one for personal use, etc.), you need to make sure you’re using the right one. The config file helps here, as you can specify which key to use for which host.

Public keys can be created from the private key using the command ssh-keygen -y -f ~/.ssh/yourprivatekey, and this can also be used to verify that an existing public key matches your private key.

On the server side, public keys go in ~/.ssh/authorized_keys. Each line is one public key. A few things can go wrong, so if you’re adding a key and it doesn’t work, check these first:

- The file or directory has wrong permissions (same rules as the client side - 700 for .ssh, 600 for authorized_keys)

- The key was pasted incorrectly (extra line breaks, missing characters, etc.)

- The key is on the wrong line or has extra whitespace

- You edited the file on Windows and it has CRLF line endings instead of LF

If you already have a password and would like to easily switch to key based authentication, you can do so with the ssh-copy-id command. For example, running ssh-copy-id mycooluser@mycoolvm, then signing in with your password will create the authorized_keys file if it doesn’t exist, and place your public key in it.

The first time you connect to a server, SSH asks you to verify the “host key fingerprint.” This is a security feature - it’s how you verify you’re connecting to the right server and not an impostor. You should only accept it if you are confident the system you are accessing is legitimate.

After you accept, SSH remembers the host key. If the server’s key changes (because the server was reinstalled, or because someone is doing something malicious), SSH will refuse to connect and give you an intentionally scary warning. If you know the host key was regenerated for legitimate reasons, you can remove the old key with:

ssh-keygen -R hostname

If you didn’t expect the key to change, investigate before proceeding.

Windows has had a built-in OpenSSH client since 2018. It works the same as the Linux/macOS client, uses the same key format, and the same config file syntax. Unless you need some specific feature of PuTTY, the default SSH client should be sufficient.

The Windows SSH client is available from any PowerShell or Command Prompt window - just type ssh. If it’s not installed, you can enable it in Settings > Apps > Optional Features > OpenSSH Client. For a cleaner, more modern experience, install the Windows Terminal app. https://github.com/microsoft/terminal

If you choose to use PuTTY, bear in mind that PuTTY uses .ppk files, which are not compatible with other clients. If you generated a key in PuTTY, you’ll need to convert it using PuTTYgen to use it with the built-in Windows SSH client (or vice versa).