Skip to content

SSH

SSH public-private key pairs are the recommended method of authenticated on remote servers.

The public key is safe to share with anyone. It will be copied to the remote servers to which you connect.

The private key must be kept secret and must never be shared with anyone.

Keep your private key safe

Do not save your private key on a cloud drive on aon a USB thumbdrive. Do not copy your private key from one computer to another. Use one key pair per device.

Create a public/private key pair

Create your own SSH public-private key pair with this command:

ssh key-gen -t ed25519 -a 200 -C "[email protected]"

This will generate 2 files under the /.ssh folder:

  • id_ed25519: your private key — keep this safe!
  • id_ed25519.pub: your public key

Important

Always use a non-trivial passphrase!

ed25519s public-key algorithm

Use the ed25519 algorith for your key. It's the recommended algorithm. It provides the highest security while keeping your keys short. Some servers may not support ed25519 keys. In that case, use the ecdsa algorigthm.

See the ssh-keygen docs.

SSH key comment

The -C option in the command above adds a comment to your public key. While optional, this provides valuable info about the key, especially to the poor sysadmin of a remote server, who only sees a collection of anonymous public keys. Our policy at Dzango is that any key found on a server without any means of identification of its owner will be removed immediately.

We recommend using your professional email address with an extra +<device> suffix to identify the device which is identified by the key. For example: [email protected], [email protected], etc.

Using multiple SSH keys

You can create as many SSH keys (strictly speaking, key pairs). In that case you need to give it a different filename.

ssh-keygen -t ed25519 -f otherkey -C "..."

SSH key permissions

Do not change the permissions of the SSH key files on your device. if you do, you may not be able to connect to the remote host.

The permissions should be:

  • .ssh/ directory: 700 (drwx------)
  • Public key (.pub file): 644 (-rw-r--r--)
  • Private key (id_ed25519 file): 600 (-rw-------)
  • Your home directory should not be writeable by the group or others: 755 (drwxr-xr-x).
  • Configuration file (~/.ssh/config): 600 (-rw-------)

Add your key to SSH agent

In order to avoid having to type your passphrase every time you use your key, add your key to ssh-agent.

Linux

ssh-add -K ~/.ss/id_ed25519

MacOS

ssh-add ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Add known hosts

Remote hosts also have a public-pricate key pair. When you connect to a remote host, it will send its public key to your device for checking.

  • If your device does not recognize this public key, you will asked whether the remote host can be trusted. If you approve, the host's public key will be stored in ~/.ssh.known_hosts.
  • If your device recognizes the public key as a known host (ie the public key is present in the ~/.ssh.known_hosts file), the host will be trusted and the connection attempt will proceed.
  • If the host's public key is different from the public key stored in your device's ~/.ssh/known_hosts file, you will see an alert warning of a potential "man-in-the-middle" attack, ie someone may be spoofing (pretending to be) the host. If the host has changed its key for a legitimate reason, you will need to delete the old public key (in ~/.ssh/known_hosts) and accept the new key.

You can add frequently used hosts right away to your ~/.ssh/known_hosts file:

ssh-keyscan github.com 2>&1 | grep -vE '^#' >> ~/.ssh/known_hosts
...

Using your key

Your public key must be present on the remote server. This is normally done either:

  • when you create the server; most cloud providers offer a way to specify the key to be set at that time.
  • by someone else who already has access to the server and will add your key.

Connecting to a remote host

ssh [-i ~/.ssh/id_ed25519] user@host

See ssh docs.

Copying files to a remote host

scp [-i ~/.ssh/id_ed25519] path/to/file user@host:path/to/file

See scp docs.

Adding your key to remote servers

Some remote hosts require you to add your public key via a graphical user interface. A familiar example is github.com.

If you have a github account, you should add your key to it (Accounts, Settings then SSH and GPG keys).