SSH Key Management and Setup Tutorial for Windows

This tutorial will guide you through setting up SSH keys for GitHub on Windows, focusing on best practices and how to configure SSH to use keys located in a non-default path. For broader tooling context, see Tool hierarchy.

SSH Key Best Practices

Before we dive into the setup, understanding SSH key best practices is crucial for maintaining a secure development environment.

Use SSH Keys over Passwords: SSH keys provide a significantly more secure authentication method than passwords, making them highly resistant to brute-force attacks. Disable password authentication on your servers if possible.
Use Strong Key Types and Lengths:
- Ed25519: This is the recommended algorithm due to its strong security and smaller key sizes.
- RSA: If Ed25519 is not supported by your systems, use RSA with at least 2048 bits, preferably 4096 bits for more sensitive connections.
Always Use a Passphrase: Encrypt your private key with a strong, unique passphrase. This adds an extra layer of security, protecting your private key even if it falls into the wrong hands. The passphrase only decrypts the key on your local machine; it’s never transmitted over the network.
Secure Private Key Permissions: The private key file should never be readable by anyone other than you. Incorrect permissions are a common cause of SSH connection failures.
- Windows: You need to explicitly set file permissions to allow only your user account to have full control. Remove inheritance and all other user/group permissions.
- Linux+GNU+GNU/macOS: The private key should have 600 permissions (-rw-------).
Keep Private Keys Private: Never share your private key with anyone or upload it to insecure locations (e.g., public code repositories).
Use ssh-agent: The ssh-agent is a program that holds private keys used for public key authentication. It reduces the need to enter your passphrase repeatedly by keeping the decrypted key in memory for the duration of your session (or until a specified timeout).
Monitor Key Usage and Rotate Keys: Regularly review your SSH keys and remove any that are no longer needed. Consider rotating your keys periodically, similar to how you would change passwords.
Use Separate Keys for Different Purposes: For enhanced security, consider using different SSH keys for different services or environments (e.g., one for GitHub, one for a work server, one for personal projects). This limits the blast radius if one key is compromised.

Setup Instructions: SSH Keys on a Different Drive/Path (Windows)

This tutorial assumes you have OpenSSH client installed on Windows (it’s usually a default feature on modern Windows versions).

Step 1: Generate a New SSH Key Pair

Open PowerShell
Generate the Key:

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

-t ed25519: Specifies the Ed25519 algorithm, which is recommended. If you need RSA for legacy reasons, use -t rsa -b 4096.
-C "your_email@example.com": Adds a comment to the public key, typically your email, which helps identify the key.
1. Specify the Key Location when prompted, e.g. D:\SSHKeys\github_ed25519.
2. Enter a passphrase when prompted.

Step 2: Set Correct Permissions for the Private Key

Windows requires specific permissions for private key files. If the permissions are too broad, SSH will refuse to use the key.

Follow the steps in File Explorer to disable inheritance, remove other principals, and grant only your user Full control.

Step 3: Add the Key to ssh-agent

Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
Get-Service ssh-agent

Add your key:

ssh-add D:/SSHKeys/github_ed25519

Step 4: Configure SSH Client (`~/.ssh/config`)

Host github.com
  HostName github.com
  User git
  IdentityFile D:/SSHKeys/github_ed25519
  AddKeysToAgent yes
  UseKeychain yes

Step 5: Add Your Public Key to GitHub

Copy the .pub file contents and add it under GitHub Settings → SSH and GPG keys.

Step 6: Test Your SSH Connection to GitHub

ssh -T git@github.com