SSH Key-Based Authentication

SSH Key-Based Authentication

Purpose

Implement secure SSH key-based authentication for remote server access. This skill covers generating cryptographic key pairs, deploying public keys to servers, configuring SSH clients for multiple servers, and applying security best practices. Essential for DevOps automation, secure system administration, and eliminating password-based authentication vulnerabilities.

Prerequisites

• Access to client and server systems with SSH installed
• User account on remote server with home directory access
• Terminal or command-line interface familiarity
• Understanding of file permissions concepts
• Root or sudo access for server-side configuration (optional)

Outputs and Deliverables

• Generated RSA/ED25519 SSH key pairs
• Configured remote server authorized_keys file
• SSH client configuration file for multiple servers
• Secure passwordless authentication setup
• Documentation of key management procedures

Core Workflow

Phase 1: Understand SSH Key Architecture

Master the fundamentals of SSH key-based authentication:

Key Pair Components

Why Keys Over Passwords

• Enhanced Security: Private keys are cryptographically strong (2048-4096 bits)
• Brute Force Resistant: Practically impossible to guess key values
• Automation Ready: Enables scripted/CI/CD server access
• Convenience: No password entry required after setup
• Audit Trail: Keys can be individually tracked and revoked

Key Algorithms

# RSA - widely compatible, use 4096 bits
ssh-keygen -t rsa -b 4096

# ED25519 - modern, smaller, faster (recommended)
ssh-keygen -t ed25519

# ECDSA - elliptic curve alternative
ssh-keygen -t ecdsa -b 521

Phase 2: Generate SSH Key Pairs

Create cryptographic key pairs on the client machine:

Standard Key Generation

# Generate RSA 4096-bit key with email identifier
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Interactive prompts:
# 1. File location: Press Enter for default (~/.ssh/id_rsa)
# 2. Passphrase: Enter strong passphrase (recommended)

Advanced Key Generation Options

# Generate ED25519 key (modern, recommended)
ssh-keygen -t ed25519 -C "user@hostname" -f ~/.ssh/myserver_ed25519

# Generate key with specific filename
ssh-keygen -t rsa -b 4096 -f ~/.ssh/production_key -C "production-access"

# Generate key without passphrase (automation only)
ssh-keygen -t ed25519 -N "" -f ~/.ssh/automation_key -C "automation"

Parameter Reference

Generated Files

~/.ssh/id_rsa        # Private key (PROTECT THIS)
~/.ssh/id_rsa.pub    # Public key (share with servers)

Phase 3: Deploy Public Keys to Servers

Install public key on remote servers for authentication:

Method 1: ssh-copy-id (Recommended)

# Copy public key to remote server
ssh-copy-id username@remote_server

# Specify a particular key
ssh-copy-id -i ~/.ssh/mykey.pub username@remote_server

# Use non-standard port
ssh-copy-id -p 2222 username@remote_server

Method 2: Manual Installation

# Display public key on client
cat ~/.ssh/id_rsa.pub

# On remote server, add to authorized_keys
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "ssh-rsa AAAA..." >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Method 3: One-liner (pipe method)

# Combine into single command
cat ~/.ssh/id_rsa.pub | ssh username@server "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Verify Deployment

# Test key-based authentication
ssh username@remote_server

# Verify with verbose output
ssh -v username@remote_server

Phase 4: Configure SSH Client

Streamline connections with SSH config file:

Create Configuration File

# Edit or create SSH config
nano ~/.ssh/config

# Set proper permissions
chmod 600 ~/.ssh/config

Basic Configuration Example

# Production Web Server
Host prod-web
    HostName 192.168.1.100
    User admin
    IdentityFile ~/.ssh/production_key
    Port 22

# Development Server
Host dev
    HostName dev.example.com
    User developer
    IdentityFile ~/.ssh/dev_key
    Port 2222

# Jump Host Configuration
Host bastion
    HostName bastion.example.com
    User jumpuser
    IdentityFile ~/.ssh/bastion_key

Host internal-*
    ProxyJump bastion
    User admin
    IdentityFile ~/.ssh/internal_key

Configuration Options Reference

Connect Using Aliases

# Instead of: ssh -i ~/.ssh/production_key admin@192.168.1.100
ssh prod-web

# Instead of complex jump commands
ssh internal-db

Phase 5: Manage SSH Agent

Use SSH agent for key passphrase caching:

Start SSH Agent

# Start agent (Bash)
eval "$(ssh-agent -s)"

# Start agent (Fish shell)
eval (ssh-agent -c)

Add Keys to Agent

# Add default key
ssh-add

# Add specific key
ssh-add ~/.ssh/production_key

# Add key with time limit (seconds)
ssh-add -t 3600 ~/.ssh/sensitive_key

# List loaded keys
ssh-add -l

# Remove specific key
ssh-add -d ~/.ssh/oldkey

# Remove all keys
ssh-add -D

Persistent Agent Setup

# Add to ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_ed25519
fi

Keychain for Persistence (Linux)

# Install keychain
sudo apt install keychain

# Add to shell profile
eval $(keychain --eval --agents ssh id_ed25519 production_key)

Phase 6: Restrict Key Usage

Implement security restrictions on SSH keys:

Command Restrictions

# In authorized_keys, prefix key with command restriction
command="/usr/bin/backup.sh" ssh-ed25519 AAAA... backup@server

# Restrict to specific commands with options
command="/usr/bin/rsync --server",no-port-forwarding,no-X11-forwarding ssh-rsa AAAA...

Available Restrictions

IP Restrictions

# Allow only from specific IP
from="192.168.1.50" ssh-ed25519 AAAA... user@host

# Allow from IP range
from="192.168.1.0/24" ssh-ed25519 AAAA... user@host

# Allow from multiple sources
from="192.168.1.50,10.0.0.0/8,*.example.com" ssh-ed25519 AAAA... user@host

Combined Restrictions Example

from="10.0.0.0/8",command="/usr/local/bin/deploy.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAA... deploy@ci-server

Phase 7: Set Proper Permissions

Ensure correct file permissions for SSH:

Client-Side Permissions

# SSH directory
chmod 700 ~/.ssh

# Private keys (CRITICAL)
chmod 600 ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_ed25519
chmod 600 ~/.ssh/*_key

# Public keys
chmod 644 ~/.ssh/*.pub

# Config file
chmod 600 ~/.ssh/config

# Known hosts
chmod 644 ~/.ssh/known_hosts

Server-Side Permissions

# SSH directory
chmod 700 ~/.ssh

# Authorized keys file
chmod 600 ~/.ssh/authorized_keys

# Home directory (should not be group/world writable)
chmod 755 ~
# or
chmod 700 ~

Verify Permissions

# Check all SSH file permissions
ls -la ~/.ssh/

# Expected output:
# drwx------  .ssh/
# -rw-------  id_rsa
# -rw-r--r--  id_rsa.pub
# -rw-------  config
# -rw-------  authorized_keys

Phase 8: Multiple Key Management

Organize and manage multiple SSH keys:

Key Organization Strategy

~/.ssh/
├── id_ed25519              # Default personal key
├── id_ed25519.pub
├── work_rsa                # Work servers
├── work_rsa.pub
├── production_ed25519      # Production systems
├── production_ed25519.pub
├── github_ed25519          # GitHub/GitLab
├── github_ed25519.pub
├── config                  # SSH configuration
└── known_hosts             # Known host keys

Configuration for Multiple Keys

# GitHub
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_ed25519
    IdentitiesOnly yes

# GitLab
Host gitlab.com
    HostName gitlab.com
    User git
    IdentityFile ~/.ssh/gitlab_ed25519
    IdentitiesOnly yes

# Work servers (pattern matching)
Host *.work.example.com
    User workuser
    IdentityFile ~/.ssh/work_rsa
    IdentitiesOnly yes

# Default for unknown hosts
Host *
    IdentityFile ~/.ssh/id_ed25519
    AddKeysToAgent yes

Test Specific Key Usage

# Test GitHub connection
ssh -T git@github.com

# Verify which key is being used
ssh -v git@github.com 2>&1 | grep "Offering"

Phase 9: Key Rotation and Backup

Implement key lifecycle management:

Key Rotation Procedure

# 1. Generate new key pair
ssh-keygen -t ed25519 -f ~/.ssh/newkey_$(date +%Y%m%d) -C "rotated-$(date +%Y%m%d)"

# 2. Deploy new public key to all servers
ssh-copy-id -i ~/.ssh/newkey_*.pub user@server1
ssh-copy-id -i ~/.ssh/newkey_*.pub user@server2

# 3. Test new key
ssh -i ~/.ssh/newkey_* user@server1

# 4. Update SSH config
# 5. Remove old key from servers' authorized_keys
# 6. Securely delete old private key
shred -u ~/.ssh/oldkey

Backup Private Keys Securely

# Encrypt backup with GPG
gpg --symmetric --cipher-algo AES256 -o ssh_keys_backup.gpg ~/.ssh/id_ed25519

# Store encrypted backup in secure location
# NEVER store unencrypted private keys in cloud storage

# Restore from backup
gpg --decrypt ssh_keys_backup.gpg > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519

Key Inventory Documentation

| Key Name | Algorithm | Created | Servers | Purpose | Expires |
|----------|-----------|---------|---------|---------|---------|
| id_ed25519 | ED25519 | 2024-01 | personal | Default | 2025-01 |
| prod_key | RSA-4096 | 2024-01 | prod-* | Production | 2024-07 |
| deploy_key | ED25519 | 2024-02 | ci/cd | Automation | 2024-08 |

Phase 10: Troubleshoot SSH Key Issues

Diagnose and resolve common problems:

Debug Connection

# Verbose output (1-3 v's for increasing detail)
ssh -v username@server
ssh -vv username@server
ssh -vvv username@server

# Check what keys are being offered
ssh -v user@server 2>&1 | grep -E "Offering|Trying"

Common Issues and Solutions

Fix Permission Issues

# Fix all SSH permissions at once
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_* ~/.ssh/config ~/.ssh/authorized_keys
chmod 644 ~/.ssh/*.pub ~/.ssh/known_hosts

Check Server-Side Logs

# View SSH authentication logs
sudo tail -f /var/log/auth.log        # Debian/Ubuntu
sudo tail -f /var/log/secure          # RHEL/CentOS
sudo journalctl -u sshd -f            # Systemd systems

Force Password Authentication (Testing)

# Bypass keys temporarily for troubleshooting
ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no user@server

Quick Reference

Key Generation Commands

ssh-keygen -t ed25519 -C "comment"              # ED25519 (recommended)
ssh-keygen -t rsa -b 4096 -C "comment"          # RSA 4096-bit
ssh-keygen -p -f ~/.ssh/keyfile                 # Change passphrase
ssh-keygen -y -f ~/.ssh/private_key             # Show public key
ssh-keygen -l -f ~/.ssh/key.pub                 # Show key fingerprint

Key Deployment

ssh-copy-id user@server                          # Copy default key
ssh-copy-id -i ~/.ssh/key.pub user@server       # Copy specific key
cat key.pub | ssh user@server "cat >> ~/.ssh/authorized_keys"

SSH Agent Commands

eval "$(ssh-agent -s)"                          # Start agent
ssh-add                                          # Add default key
ssh-add ~/.ssh/keyfile                          # Add specific key
ssh-add -l                                       # List loaded keys
ssh-add -D                                       # Remove all keys

Required Permissions

~/.ssh/           700 (drwx------)
id_rsa            600 (-rw-------)
id_rsa.pub        644 (-rw-r--r--)
authorized_keys   600 (-rw-------)
config            600 (-rw-------)

Constraints and Limitations

• Private keys must never be shared or transmitted insecurely
• Keys without passphrases create security risk if system compromised
• Some legacy systems may not support ED25519 (use RSA)
• Jump hosts require additional configuration for agent forwarding
• Key rotation requires coordination across all systems
• Lost private keys with no backup result in permanent access loss
• SSH agent forwarding carries security risks on untrusted systems

Troubleshooting

Quick Diagnostics

# Check key permissions
ls -la ~/.ssh/

# Test key authentication explicitly
ssh -i ~/.ssh/keyfile -o IdentitiesOnly=yes user@server

# Verify agent has key loaded
ssh-add -l

# View offered authentication methods
ssh -o PreferredAuthentications=publickey -v user@server 2>&1 | grep "Authentications"

Error Resolution Table

References

• OpenSSH Documentation: https://www.openssh.com/manual.html
• SSH Academy: https://www.ssh.com/academy/ssh
• NIST Guidelines for SSH Key Management
• Author: Zayan Ahmed - SSH Access Through Keys