Complete Guide to SSH Key Configuration

SSH Key Configuration Guide#

Quick configuration of SSH keys for passwordless login to servers, Git authentication, and commit signing

1. Generate SSH Key Pair#

# Generate Ed25519 key pair (recommended)
ssh-keygen -t ed25519 -C "[email protected]"

# Interactive prompts:
# Enter file: Press Enter (use default path ~/.ssh/id_ed25519)
# Enter passphrase: Optional password protection or press Enter to skip

Generation Result:

Private Key: ~/.ssh/id_ed25519 (⚠️ Keep secret)
Public Key: ~/.ssh/id_ed25519.pub (can be shared)

2. Configure SSH Config File#

# Create/edit config file
touch ~/.ssh/config
chmod 600 ~/.ssh/config
nano ~/.ssh/config

Configuration Template:

# Development server
Host dev-server
    HostName 192.168.1.100
    User your_username
    Port 22
    IdentityFile ~/.ssh/id_ed25519

# Production server
Host prod-server
    HostName prod.example.com
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

# GitHub
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519

Configuration Item Explanation:

Host: Alias (custom)
HostName: Actual server address
User: Login username
Port: SSH port (default 22)
IdentityFile: Private key path

Usage Effect:

# Before configuration
ssh [email protected]

# After configuration
ssh dev-server

Method 1: Using ssh-copy-id (recommended)#

# Using full address
ssh-copy-id [email protected]

# Or using alias
ssh-copy-id dev-server

Method 2: Manual Copy#

# 1. Copy public key content
cat ~/.ssh/id_ed25519.pub

# 2. Log in to the server
ssh [email protected]

# 3. Execute on the server
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "public key content" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
exit

4. Configure Git Commit Signing#

# Configure user information
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Configure SSH signing
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Configuration File Effect (~/.gitconfig):

[user]
    email = [email protected]
    name = Your Name
    signingkey = /Users/username/.ssh/id_ed25519.pub
[gpg]
    format = ssh
[commit]
    gpgsign = true

5. Add Public Key to Git Platforms#

GitHub#

# Copy public key to clipboard (macOS)
cat ~/.ssh/id_ed25519.pub | pbcopy

Visit: https://github.com/settings/keys
Click New SSH key
Add twice:
- Key type: Authentication Key → Title: MacBook Pro → Paste public key
- Key type: Signing Key → Title: MacBook Pro Signing → Paste public key

💡 The same public key can be used for both authentication and signing

GitLab#

Copy public key: cat ~/.ssh/id_ed25519.pub | pbcopy
Visit: https://gitlab.com/-/profile/keys
Paste public key, select Usage type: Authentication & Signing

Gitee#

Copy public key: cat ~/.ssh/id_ed25519.pub | pbcopy
Visit: https://gitee.com/profile/sshkeys
Paste public key and click confirm

6. Common Issues#

Q1: Permission denied (publickey)#

# Check key permissions
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Re-copy public key
ssh-copy-id username@server

Q2: Commit does not have Verified tag#

# Check email (must match GitHub account)
git config user.email

# Check signing configuration
git config --list | grep sign

# Confirm Signing Key has been added to GitHub

Q3: Password prompt when signing#

# Add to ssh-agent (macOS)
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# Or configure auto-load (edit ~/.ssh/config)
Host *
    AddKeysToAgent yes
    UseKeychain yes
    IdentityFile ~/.ssh/id_ed25519

Q4: Managing Multiple Keys#

# ~/.ssh/config

# Personal GitHub
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal

# Work GitHub
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work

🎯 Overall Process#

# 1. Generate key
ssh-keygen -t ed25519 -C "[email protected]"

# 2. Configure Git signing
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# 3. Copy public key
cat ~/.ssh/id_ed25519.pub | pbcopy

# 4. Add to GitHub
# Settings → SSH and GPG keys → New SSH key
# Add twice: Authentication Key + Signing Key

# 5. Test
ssh -T [email protected]

📋 Common Commands#

# Key management
ssh-keygen -t ed25519 -C "email"          # Generate key
cat ~/.ssh/id_ed25519.pub | pbcopy        # Copy public key
ssh-keygen -p -f ~/.ssh/id_ed25519        # Change key password

# SSH connection
ssh-copy-id user@host                     # Copy public key to server
ssh -T [email protected]                     # Test GitHub connection
ssh dev-server                            # Log in using alias

# SSH Agent
ssh-add --apple-use-keychain ~/.ssh/id_ed25519  # Add key (macOS)
ssh-add -l                                       # List added keys

# Git configuration
git config --list | grep -E "(user|gpg|sign)"   # View signing configuration
git log --show-signature                         # View commit signature
git commit --no-gpg-sign -m "msg"                # Temporarily disable signing

# Permission fixes
chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

📚 Appendix#

SSH Key Type Comparison#

Algorithm	Key Length	Recommendation
Ed25519	256 bits	⭐⭐⭐⭐⭐ Preferred (most secure, fastest)
RSA	4096 bits	⭐⭐⭐ Good compatibility
ECDSA	256/384/521 bits	⭐⭐⭐ Some older systems do not support
DSA	1024 bits	❌ Outdated, not recommended

Security Recommendations#

✅ Set password protection for private keys
✅ Set private key permissions to 600
✅ Regularly back up keys to a secure location
❌ Do not upload private keys to cloud storage
❌ Do not send private keys via chat tools

Blog Version: 1.0
Applicable Platforms: macOS / Linux / Windows (WSL)