DEV Community

dpm_bush
dpm_bush

Posted on Originally published at sshflow.com

Generate an SSH Key: A Practical OpenSSH Walkthrough

#devops #beginners #productivity #architecture

An SSH key pair gives you a way to authenticate to servers and Git hosting without sending your account password. The key-generation command is the same on Windows, macOS, and Linux; the important parts are choosing a safe file path, protecting the private key, and installing only the public key.

Check before you generate

If you already have an SSH key, creating another one with the default filename could prompt you to overwrite it. That old key may be the only credential a server trusts, so don't replace it unless you mean to.

On macOS or Linux, inspect your SSH directory with:

ls -la ~/.ssh
Enter fullscreen mode Exit fullscreen mode

In PowerShell, use:

Get-ChildItem ~\.ssh
Enter fullscreen mode Exit fullscreen mode

A pair such as id_ed25519 and id_ed25519.pub is an Ed25519 key: the file without .pub is private, and the .pub file is public. If you need a new key while keeping an existing one, give the new key a different filename.

Generate a key pair

For most modern systems, Ed25519 is a good default:

ssh-keygen -t ed25519
Enter fullscreen mode Exit fullscreen mode

Run this in Terminal on macOS, a shell on Linux, or PowerShell or Command Prompt on Windows if the OpenSSH Client is installed. When prompted for a file location, press Enter to use the default. The command creates:

  • ~/.ssh/id_ed25519 — your private key
  • ~/.ssh/id_ed25519.pub — your public key

On Windows, the default directory is typically C:\Users\<you>\.ssh.

When prompted for a passphrase, enter one to encrypt the private key on disk. If you leave it empty, anyone who obtains the private-key file can use it without knowing an additional secret. For ordinary day-to-day keys, a passphrase is a useful layer of protection. An SSH agent can hold the unlocked key in memory so you don't have to type the passphrase for every connection; see this guide to using ssh-agent for platform-specific setup.

If Windows says ssh-keygen isn't recognized, the OpenSSH Client optional feature may not be installed. You can add it from Settings → Apps → Optional features → Add a feature → OpenSSH Client, or from an elevated PowerShell prompt:

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
Enter fullscreen mode Exit fullscreen mode

Use a custom filename when needed

A custom filename avoids disturbing an existing default key and can make separate credentials easier to manage. On macOS or Linux:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_work
Enter fullscreen mode Exit fullscreen mode

In PowerShell, you can specify a path under your profile:

ssh-keygen -t ed25519 -f $env:USERPROFILE\.ssh\id_ed25519_work
Enter fullscreen mode Exit fullscreen mode

The public key will use the same name with .pub appended. OpenSSH does not automatically try every custom filename, so specify it when connecting:

ssh -i ~/.ssh/id_ed25519_work user@host
Enter fullscreen mode Exit fullscreen mode

Or configure the key for a host in ~/.ssh/config using IdentityFile. That way, you can connect without adding -i each time.

Copy the public key—not the private key

The private key stays on your device. Do not upload it to a server, paste it into an account form, or send it to someone else. To register access, copy the contents of the .pub file.

On macOS, copy the default public key to the clipboard with:

pbcopy < ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

On Linux, display it and copy the output:

cat ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

In PowerShell:

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard
Enter fullscreen mode Exit fullscreen mode

Paste that public key into the SSH key settings for a Git hosting account, or add it to the remote user's ~/.ssh/authorized_keys file. On macOS or Linux, ssh-copy-id user@host can install the public key when the command is available. This ssh-copy-id walkthrough covers the command and alternatives.

Test the connection

Once the public key is registered, try connecting:

ssh user@host
Enter fullscreen mode Exit fullscreen mode

If you used a custom filename, include -i or configure IdentityFile first. A successful key-based login should authenticate with the key rather than asking for the server account password; you may still be asked for the key's passphrase if it is not loaded in an agent.

If the server rejects the key, first check that you installed the contents of the correct .pub file for the account you're logging into. File permissions on the SSH directory and authorized_keys can also cause public-key authentication to fail.

The short version

For a typical modern setup, run ssh-keygen -t ed25519, choose a passphrase, and keep the private key on your own device. Register the matching .pub key with the server or service, then test with ssh user@host. If you already have a key, check before accepting an overwrite prompt.

I originally published a more detailed version of this guide on the SSHFlow blog.

I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.

Top comments (0)