A developer’s guide to SSH: Secure Shell explained

If you have worked with remote servers, cloud infrastructure, or version control platforms like GitHub, you have almost certainly used SSH without necessarily thinking much about what it is or how it works. This article explains what the Secure Shell protocol is, why it exists, and how to use it in practice.

What is SSH?

A shell is software that exposes the services of an operating system, allowing a user to execute commands. One of the things an operating system can provide is the ability to log into a remote computer and use its command-line. Without any form of authentication or encryption, this would be a serious security risk: anyone on the network could intercept the connection or gain unauthorised access.

The Secure Shell protocol (SSH) was developed to solve this problem. It provides two important things:

Authentication — a way to verify the identity of the user connecting to the remote machine, using encryption keys rather than passwords alone.
Encryption — all data travelling between the two computers is encrypted. Even if the connection is intercepted, the data cannot easily be read.

SSH is most commonly used to access shell accounts on Unix-like operating systems such as Linux and macOS. Since Windows 10 in 2018, Windows also provides a native SSH client. Before that, Windows users relied on third-party tools such as PuTTY or Cygwin.

SSH and cloud computing

SSH is particularly important in cloud computing. Virtual machines running in the cloud are not physically accessible, and exposing them directly to the internet without protection would be a significant security risk. SSH provides a secure, encrypted path to a remote machine over the internet, allowing developers and system administrators to manage cloud servers as if they were sitting at the machine directly. Many cloud providers require SSH key authentication as the default method of access.

Connecting to a remote machine

The basic command for connecting to a remote machine over SSH is:

ssh username@hostname

Where username is your account on the remote machine and hostname is either the IP address or domain name of the remote server. On the first connection to a new server, SSH will ask you to verify the server’s fingerprint. Once accepted, the server is added to your ~/.ssh/known_hosts file and subsequent connections proceed automatically.

Password vs key-based authentication

SSH supports two main methods of authentication: password-based and key-based.

Password authentication works as you would expect: you enter a password when prompted. It is straightforward but less secure, as passwords can be guessed, intercepted, or brute-forced.

Key-based authentication uses a pair of cryptographic keys: a private key that stays on your local machine and is never shared, and a public key that is placed on the remote server. When you connect, the server issues a cryptographic challenge that can only be solved by someone holding the matching private key. The private key itself is never transmitted over the network. This approach is significantly more secure than passwords and is the recommended method for most use cases.

Generating an SSH key pair

Keys are generated using the ssh-keygen command. The current recommended algorithm is Ed25519, which offers strong security and good performance.

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

The -C flag adds a comment to the key, typically your email address, to help identify it later. When prompted, you can accept the default file location (~/.ssh/id_ed25519) or specify a different path. You will also be asked to set a passphrase, which adds an extra layer of protection to the private key file itself. Using a passphrase is recommended.

This generates two files:

~/.ssh/id_ed25519 — your private key. Keep this secure and never share it.
~/.ssh/id_ed25519.pub — your public key. This is what you share with remote servers.

Adding your public key to a remote server

To use key-based authentication, your public key needs to be added to the ~/.ssh/authorized_keys file on the remote server. The easiest way to do this is with the ssh-copy-id command:

ssh-copy-id username@hostname

This copies your public key to the correct location on the remote server automatically. After running it, you can connect using your key without being prompted for a password.

On platforms like GitHub and GitLab, you add your public key via the account settings in the web interface rather than using ssh-copy-id.

The ~/.ssh directory

All SSH-related files on your local machine are stored in the ~/.ssh directory. The key files you will encounter are:

id_ed25519 — private key (or id_rsa for older RSA keys)
id_ed25519.pub — public key
known_hosts — a record of remote servers you have connected to and verified
authorized_keys — public keys that are permitted to connect to this machine
config — optional configuration file for defining shortcuts and settings for specific hosts