SSH Key Commands

Overview

SSH key management commands provide comprehensive functionality for generating, managing, deploying, and maintaining SSH authentication keys used for server access and repository operations. These commands integrate with user management and server configuration.

Table of Contents

• cpm ssh-key generate
• cpm ssh-key list
• cpm ssh-key show
• cpm ssh-key push
• cpm ssh-key pull
• cpm ssh-key delete

cpm ssh-key generate

Description

Generate a new ed25519 SSH key pair with secure permissions. Keys are stored in the cpm keys directory and registered in the database for tracking.

Syntax

cpm ssh-key generate <name>

Arguments

Behavior

1. Validates key name (no path separators)
2. Checks for existing key with same name
3. Generates ed25519 key pair (4096-bit strength)
4. Saves private key with 0600 permissions
5. Saves public key with 0644 permissions
6. Registers key in database
7. Displays key fingerprint and location

Examples

cpm ssh-key generate main-server

# Output:
# Generating ed25519 SSH key pair...
# Key pair 'main-server' generated successfully
#
# Private key: /home/user/.cpm/keys/main-server
# Public key:  /home/user/.cpm/keys/main-server.pub
# Fingerprint: SHA256:abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
#
# Key registered in database (ID: 1)
#
# To deploy this key to a server:
#   cpm ssh-key push main-server --to user@host

cpm ssh-key generate backup-key

# Output:
# Generating ed25519 SSH key pair...
# Key pair 'backup-key' generated successfully
#
# Private key: /home/user/.cpm/keys/backup-key
# Public key:  /home/user/.cpm/keys/backup-key.pub
# Fingerprint: SHA256:xyz789abc123def456ghi789jkl012mno345pqr678stu901
#
# Key registered in database (ID: 2)

Key Storage

Keys are stored in: ~/.cpm/keys/

~/.cpm/keys/
├── main-server (private key, 0600)
├── main-server.pub (public key, 0644)
├── backup-key (private key, 0600)
└── backup-key.pub (public key, 0644)

Common Errors

cpm ssh-key list

Description

List all managed SSH keys with their details including ID, name, path, fingerprint, and creation date.

Syntax

cpm ssh-key list [flags]

Flags

Examples

cpm ssh-key list

# Output:
# SSH KEYS
#
# ID  Name          Private Key Path                      Created
# --  ------------  ------------------------------------  -------------------
# 1   main-server   /home/user/.cpm/keys/main-server     2024-01-15 10:30:00
# 2   backup-key    /home/user/.cpm/keys/backup-key      2024-01-15 11:00:00
# 3   prod-deploy   /home/user/.cpm/keys/prod-deploy     2024-01-16 09:00:00
#
# Total: 3 keys

cpm ssh-key list --format json

# Output:
# [
#   {
#     "id": 1,
#     "name": "main-server",
#     "private_key_path": "/home/user/.cpm/keys/main-server",
#     "public_key_path": "/home/user/.cpm/keys/main-server.pub",
#     "fingerprint": "SHA256:abc123...",
#     "created_at": "2024-01-15T10:30:00Z"
#   }
# ]

cpm ssh-key show

Description

Display the public key content for a given key name. Useful for copying keys or verifying key deployment.

Syntax

cpm ssh-key show <name>

Arguments

Examples

cpm ssh-key show main-server

# Output:
# SSH PUBLIC KEY: main-server
#
# Path: /home/user/.cpm/keys/main-server.pub
# Type: ed25519
# Fingerprint: SHA256:abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
#
# Key Content:
# ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl main-server

# Copy to clipboard (Linux)
cpm ssh-key show main-server | grep "^ssh-" | xclip -selection clipboard

# Copy to clipboard (macOS)
cpm ssh-key show main-server | grep "^ssh-" | pbcopy

cpm ssh-key push

Description

Push (deploy) a public key to a remote server's authorized_keys file. Establishes authentication for future SSH connections.

Syntax

cpm ssh-key push <name> --to <server>

Arguments

Flags

Behavior

1. Reads public key from local filesystem
2. Connects to remote server via SSH (requires existing access)
3. Creates ~/.ssh directory on remote if needed (permissions: 0700)
4. Backs up existing authorized_keys file
5. Adds key to ~/.ssh/authorized_keys
6. Sets appropriate permissions (0600)
7. Verifies key deployment
8. Does not duplicate if key already exists

Examples

cpm ssh-key push main-server --to git@git.example.com

# Output:
# Pushing key 'main-server' to git@git.example.com...
# Connecting to server...
# Reading public key...
# Checking for existing key...
# Adding key to authorized_keys...
# Setting permissions...
#
# Key successfully deployed to git@git.example.com
# The key can now be used for authentication

cpm ssh-key push backup-key --to admin@192.168.1.100

# Output:
# Pushing key 'backup-key' to admin@192.168.1.100...
# Key already exists in authorized_keys
# No changes made

# Custom port
cpm ssh-key push prod-deploy --to deploy@prod.example.com:2222

# Output:
# Pushing key 'prod-deploy' to deploy@prod.example.com:2222...
# [deployment process...]
# Key successfully deployed

Common Errors

cpm ssh-key pull

Description

Retrieve and display the authorized_keys file from a remote server. Useful for auditing which keys have access to a server.

Syntax

cpm ssh-key pull --from <server>

Flags

Examples

cpm ssh-key pull --from git@git.example.com

# Output:
# Retrieving authorized_keys from git@git.example.com...
# Connected successfully
#
# AUTHORIZED KEYS (3 keys found)
#
# 1. Type: ed25519
#    Fingerprint: SHA256:abc123...
#    Comment: main-server
#    Key: ssh-ed25519 AAAAC3Nz... main-server
#
# 2. Type: ed25519
#    Fingerprint: SHA256:def456...
#    Comment: backup-key
#    Key: ssh-ed25519 AAAAC3Nz... backup-key
#
# 3. Type: rsa
#    Fingerprint: SHA256:ghi789...
#    Comment: legacy-key
#    Key: ssh-rsa AAAAB3Nz... legacy-key

# Save to file
cpm ssh-key pull --from git@git.example.com --save server-keys.txt

# Output:
# Retrieving authorized_keys from git@git.example.com...
# Saved to: server-keys.txt

cpm ssh-key delete

Description

Delete an SSH key pair from local system and database. This is a destructive operation requiring confirmation.

Syntax

cpm ssh-key delete <name>

Arguments

Behavior

1. Prompts for confirmation
2. Removes key from database
3. Deletes private key file
4. Deletes public key file
5. Cannot be undone
6. Does not remove from remote servers' authorized_keys

Examples

cpm ssh-key delete old-key

# Prompt:
# WARNING: This will permanently delete SSH key 'old-key'
# - Private key will be deleted: /home/user/.cpm/keys/old-key
# - Public key will be deleted: /home/user/.cpm/keys/old-key.pub
# - Database record will be removed
# - This action cannot be undone
# - Keys will remain in any server authorized_keys files
#
# Type the key name to confirm: old-key

# Output:
# Deleting SSH key 'old-key'...
# Removed from database
# Deleted private key: /home/user/.cpm/keys/old-key
# Deleted public key: /home/user/.cpm/keys/old-key.pub
#
# SSH key 'old-key' successfully deleted
#
# Note: You may need to manually remove this key from server authorized_keys files

SSH Key Management Workflows

Initial Server Setup

# Generate key for server
cpm ssh-key generate main-server

# Deploy to server (requires password or existing key)
cpm ssh-key push main-server --to git@git.example.com

# Verify deployment
cpm ssh-key pull --from git@git.example.com

# Test SSH connection
ssh -i ~/.cpm/keys/main-server git@git.example.com

Multi-Server Deployment

# Generate one key for multiple servers
cpm ssh-key generate infrastructure

# Deploy to all servers
cpm ssh-key push infrastructure --to git@server1.com
cpm ssh-key push infrastructure --to git@server2.com
cpm ssh-key push infrastructure --to git@server3.com

# Verify on all servers
for server in server1.com server2.com server3.com; do
  echo "Checking $server..."
  cpm ssh-key pull --from git@$server
done

Key Rotation

# Generate new key
cpm ssh-key generate main-server-new

# Deploy new key to all servers
cpm ssh-key push main-server-new --to git@server1.com
cpm ssh-key push main-server-new --to git@server2.com

# Test new key works
ssh -i ~/.cpm/keys/main-server-new git@server1.com

# Remove old key (after verification)
cpm ssh-key delete main-server

# Manually remove old key from servers
ssh git@server1.com "sed -i '/main-server$/d' ~/.ssh/authorized_keys"

Key Audit

# List all local keys
cpm ssh-key list

# Check each server
cpm ssh-key pull --from git@server1.com --save server1-keys.txt
cpm ssh-key pull --from git@server2.com --save server2-keys.txt

# Compare deployed keys
diff server1-keys.txt server2-keys.txt

Best Practices

Key Generation

• Use ed25519 keys (modern, secure, fast)
• Generate unique keys for different purposes
• Use descriptive names: prod-deploy, backup-server, dev-workstation
• Store keys only in cpm keys directory
• Never commit private keys to git

Key Deployment

• Test deployment on non-critical server first
• Keep backup of server's authorized_keys before changes
• Verify key works before removing old keys
• Document which keys are deployed where
• Use comments in keys for identification

Key Rotation

• Rotate keys every 6-12 months
• Immediately rotate if key may be compromised
• Maintain overlap period with both old and new keys
• Remove old keys after verification
• Update documentation after rotation

Security

• Set proper permissions: private (0600), public (0644)
• Never share private keys
• Use passphrases for high-security keys
• Restrict key usage with SSH authorized_keys options
• Regular audits of deployed keys
• Remove keys for departed team members

Key Organization

Development keys:
- dev-laptop
- dev-desktop

Production keys:
- prod-deploy
- prod-backup

Server-specific keys:
- git-server-1
- git-server-2
- backup-server

Integration with Other Commands

With Server Commands

# Add server with specific key
cpm servers add origin git.example.com --key ~/.cpm/keys/main-server

# Server configuration uses the key for all operations
cpm push myrepo --to origin  # Uses configured key

With User Commands

# Add user with SSH key
cpm user add alice --key-file ~/.cpm/keys/alice.pub

# User's key stored in database for access control

See Also

• Server Commands
• User Commands
• Configuration Guide
• Architecture: SSH Operations
• Troubleshooting