English | 中文

This guide explains how to generate SSH certificates on a Linux server and use them in electerm for secure connections.

SSH certificates provide a more scalable and manageable alternative to traditional SSH key authentication. Instead of distributing public keys to each server, you use a Certificate Authority (CA) to sign user keys.

1. Key Distribution Nightmare: With traditional SSH keys, you must add each user's public key to ~/.ssh/authorized_keys on every server they need access to. For 100 users and 50 servers, that's potentially 5,000 key entries to manage.

2. No Expiration: SSH keys never expire. When an employee leaves, you must manually remove their key from every server—easy to miss one.

3. No Central Control: There's no way to instantly revoke access across all servers. Each server maintains its own list of authorized keys.

4. Difficult Auditing: Hard to track who has access to what, when access was granted, and by whom.

1. Centralized Trust: Servers trust the CA, not individual keys. Add one CA public key to a server, and it automatically trusts all certificates signed by that CA.

2. Built-in Expiration: Certificates have validity periods. After expiration, access is automatically revoked—no manual cleanup needed.

3. Easy Revocation: Revoke a certificate centrally, and access is denied across all servers immediately.

4. Fine-grained Control: Certificates can restrict:

   • Which usernames can be used (principals)
   • Source IP addresses allowed
   • Specific commands that can be run
   • Port forwarding, agent forwarding, etc.

5. Audit Trail: Each certificate has a unique ID and serial number, making it easy to track in logs.

6. Simplified Onboarding/Offboarding:

   • New employee? Sign their key once, they can access all authorized servers.
   • Employee leaves? Revoke their certificate or let it expire.

On your Linux server (or a dedicated CA machine), generate the CA key pair:

# Create a directory for CA files
mkdir -p ~/.ssh/ca
cd ~/.ssh/ca

# Generate the CA key pair (use a strong passphrase)
ssh-keygen -t ed25519 -f ca_key -C "SSH Certificate Authority"

# Or use RSA for broader compatibility
ssh-keygen -t rsa -b 4096 -f ca_key -C "SSH Certificate Authority"

This creates:

• ca_key - The private CA key (keep this very secure!)
• ca_key.pub - The public CA key

On each SSH server that should accept certificate authentication:

# Copy the CA public key to the server
sudo cp ca_key.pub /etc/ssh/ca_key.pub

# Edit SSH server configuration
sudo nano /etc/ssh/sshd_config

Add this line to sshd_config:

TrustedUserCAKeys /etc/ssh/ca_key.pub

Restart the SSH service:

# For systemd-based systems
sudo systemctl restart sshd

# For older systems
sudo service ssh restart

On the client machine (or for the user):

# Generate a new key pair for the user
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_cert -C "[email protected]"

# Or use RSA
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_cert -C "[email protected]"

On the CA machine, sign the user's public key:

# Basic signing (valid for 52 weeks)
ssh-keygen -s ca_key -I "user_identifier" -n username -V +52w ~/.ssh/id_ed25519_cert.pub

# More detailed example with multiple principals
ssh-keygen -s ca_key \
  -I "[email protected]" \
  -n "john,admin,deploy" \
  -V +30d \
  -z 1 \
  ~/.ssh/id_ed25519_cert.pub

Parameters explained:

• -s ca_key - Path to the CA private key
• -I "identifier" - Key identifier (appears in logs)
• -n "principals" - Comma-separated list of allowed usernames
• -V +52w - Validity period (52 weeks, can use +1d, +1m, etc.)
• -z 1 - Serial number (optional, for tracking)

This creates: id_ed25519_cert-cert.pub (the certificate file)

# View certificate details
ssh-keygen -L -f ~/.ssh/id_ed25519_cert-cert.pub

Output example:

id_ed25519_cert-cert.pub:
        Type: [email protected] user certificate
        Public key: ED25519-CERT SHA256:...
        Signing CA: ED25519 SHA256:...
        Key ID: "[email protected]"
        Serial: 1
        Valid: from 2024-01-01T00:00:00 to 2024-12-31T23:59:59
        Principals:
                john
                admin
                deploy
        Critical Options: (none)
        Extensions:
                permit-agent-forwarding
                permit-pty
                permit-user-rc

1. Open electerm and create a new bookmark (click the "+" button) or edit an existing one

2. Fill in the basic connection details:

   • Host: Your server IP or hostname
   • Port: SSH port (default: 22)
   • Username: Must match one of the principals in the certificate

3. Switch to PrivateKey/Certificate Section:

   • In the bookmark form, locate the authentication section
   • Click on "PrivateKey/Certificate" tab/section to expand it

4. Import Private Key:

   • Click the "Import" or "Browse" button next to the Private Key field
   • Navigate to and select your private key file
     • e.g., ~/.ssh/id_ed25519_cert
   • If your key has a passphrase, enter it in the "Passphrase" field

5. Import Certificate:

   • Click the "Import" or "Browse" button next to the Certificate field
   • Navigate to and select your certificate file
     • e.g., ~/.ssh/id_ed25519_cert-cert.pub
   • Note: You must manually import both files; electerm does not auto-detect them

6. Save and Connect:

   • Click "Save" to store the bookmark
   • Double-click the bookmark or click "Connect" to establish the connection

If you prefer using SSH config, create or edit ~/.ssh/config:

Host myserver
    HostName 192.168.1.100
    User john
    IdentityFile ~/.ssh/id_ed25519_cert
    CertificateFile ~/.ssh/id_ed25519_cert-cert.pub

Then in electerm:

1. Use the Host alias (myserver) as the hostname
2. electerm will use your SSH config automatically

Ensure these files are in your ~/.ssh/ directory:

~/.ssh/
├── id_ed25519_cert          # Private key
├── id_ed25519_cert.pub      # Public key
└── id_ed25519_cert-cert.pub # Certificate (signed by CA)

When signing, you can limit what the certificate allows:

# Restrict to specific source addresses
ssh-keygen -s ca_key -I "user" -n username \
  -O source-address=192.168.1.0/24 \
  -V +1w user_key.pub

# Disable certain features
ssh-keygen -s ca_key -I "user" -n username \
  -O no-agent-forwarding \
  -O no-port-forwarding \
  -O no-x11-forwarding \
  -V +1w user_key.pub

# Force a specific command
ssh-keygen -s ca_key -I "backup-user" -n backup \
  -O force-command="/usr/local/bin/backup-script" \
  -V +1w user_key.pub

Create a Key Revocation List (KRL):

# Create initial KRL
ssh-keygen -k -f /etc/ssh/revoked_keys

# Revoke a certificate by serial number
ssh-keygen -k -f /etc/ssh/revoked_keys -z 1

# Revoke by key ID
ssh-keygen -k -f /etc/ssh/revoked_keys -s ca_key id_to_revoke

Add to sshd_config:

RevokedKeys /etc/ssh/revoked_keys

Sign host keys to prevent "unknown host" warnings:

# On the CA machine, sign the host's public key
ssh-keygen -s ca_key -I "server.example.com" \
  -h -n "server.example.com,192.168.1.100" \
  -V +52w /etc/ssh/ssh_host_ed25519_key.pub

Configure the server in /etc/ssh/sshd_config:

HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

On clients, add to ~/.ssh/known_hosts or /etc/ssh/ssh_known_hosts:

@cert-authority *.example.com ssh-ed25519 AAAA... CA_PUBLIC_KEY_HERE

1. "Permission denied" errors

   • Verify the username matches a principal in the certificate
   • Check certificate validity: ssh-keygen -L -f cert-file.pub
   • Ensure CA public key is in TrustedUserCAKeys

2. Certificate not recognized

   • Verify file permissions: private key should be 600
   • Ensure certificate file ends with -cert.pub
   • Check SSH server logs: journalctl -u sshd -f

3. Debug connection

   ssh -vvv user@server

# Test SSH config syntax
sudo sshd -t

# Check if CA key is readable
sudo cat /etc/ssh/ca_key.pub

1. Protect the CA private key - Store offline or in HSM
2. Use short validity periods - Rotate certificates regularly
3. Use unique serial numbers - For audit trails and revocation
4. Implement revocation - Have a KRL in place
5. Limit principals - Only allow necessary usernames
6. Use restrictions - Apply source-address and command limits where possible

For more information, see:

• OpenSSH Certificates Documentation
• electerm Documentation

本指南介绍如何在 Linux 服务器上生成 SSH 证书，并在 electerm 中使用它们进行安全连接。

SSH 证书提供了一种更具可扩展性和可管理性的替代传统 SSH 密钥认证的方式。与分发公钥到每个服务器不同，您可以使用证书颁发机构 (CA) 来签署用户密钥。

1. 密钥分发噩梦：使用传统 SSH 密钥，您必须将每个用户的公钥添加到他们需要访问的每个服务器的 ~/.ssh/authorized_keys 中。对于 100 个用户和 50 个服务器，可能需要管理 5000 个密钥条目。

2. 无过期时间：SSH 密钥永不过期。当员工离职时，您必须手动从每个服务器上删除他们的密钥——很容易遗漏一个。

3. 无集中控制：无法即时撤销所有服务器的访问权限。每台服务器维护自己的授权密钥列表。

4. 审计困难：很难跟踪谁有权访问什么、何时授予访问权限以及由谁授予。

1. 集中信任：服务器信任 CA，而不是单个密钥。将一个 CA 公钥添加到服务器，它会自动信任该 CA 签署的所有证书。

2. 内置过期：证书具有有效期。过期后，访问权限自动撤销——无需手动清理。

3. 易于撤销：集中撤销证书，立即拒绝所有服务器的访问权限。

4. 细粒度控制：证书可以限制：

   • 可以使用哪些用户名（主体）
   • 允许的源 IP 地址
   • 可以运行的特定命令
   • 端口转发、代理转发等。

5. 审计跟踪：每个证书都有唯一的 ID 和序列号，便于日志跟踪。

6. 简化入职/离职：

   • 新员工？签署他们的密钥一次，他们就可以访问所有授权服务器。
   • 员工离职？撤销他们的证书或让其过期。

在您的 Linux 服务器（或专用 CA 机器）上，生成 CA 密钥对：

# 创建 CA 文件目录
mkdir -p ~/.ssh/ca
cd ~/.ssh/ca

# 生成 CA 密钥对（使用强密码）
ssh-keygen -t ed25519 -f ca_key -C "SSH Certificate Authority"

# 或使用 RSA 以获得更广泛的兼容性
ssh-keygen -t rsa -b 4096 -f ca_key -C "SSH Certificate Authority"

这将创建：

• ca_key - CA 私钥（保持高度安全！）
• ca_key.pub - CA 公钥

在每个应接受证书认证的 SSH 服务器上：

# 将 CA 公钥复制到服务器
sudo cp ca_key.pub /etc/ssh/ca_key.pub

# 编辑 SSH 服务器配置
sudo nano /etc/ssh/sshd_config

在 sshd_config 中添加此行：

TrustedUserCAKeys /etc/ssh/ca_key.pub

重启 SSH 服务：

# 对于基于 systemd 的系统
sudo systemctl restart sshd

# 对于旧系统
sudo service ssh restart

在客户端机器（或为用户）上：

# 为用户生成新的密钥对
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_cert -C "[email protected]"

# 或使用 RSA
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_cert -C "[email protected]"

在 CA 机器上，签署用户的公钥：

# 基本签署（有效期 52 周）
ssh-keygen -s ca_key -I "user_identifier" -n username -V +52w ~/.ssh/id_ed25519_cert.pub

# 更详细的示例，使用多个主体
ssh-keygen -s ca_key \
  -I "[email protected]" \
  -n "john,admin,deploy" \
  -V +30d \
  -z 1 \
  ~/.ssh/id_ed25519_cert.pub

参数说明：

• -s ca_key - CA 私钥路径
• -I "identifier" - 密钥标识符（出现在日志中）
• -n "principals" - 逗号分隔的允许用户名列表
• -V +52w - 有效期（52 周，可以使用 +1d、+1m 等）
• -z 1 - 序列号（可选，用于跟踪）

这将创建：id_ed25519_cert-cert.pub（证书文件）

# 查看证书详情
ssh-keygen -L -f ~/.ssh/id_ed25519_cert-cert.pub

输出示例：

id_ed25519_cert-cert.pub:
        Type: [email protected] user certificate
        Public key: ED25519-CERT SHA256:...
        Signing CA: ED25519 SHA256:...
        Key ID: "[email protected]"
        Serial: 1
        Valid: from 2024-01-01T00:00:00 to 2024-12-31T23:59:59
        Principals:
                john
                admin
                deploy
        Critical Options: (none)
        Extensions:
                permit-agent-forwarding
                permit-pty
                permit-user-rc

1. 打开 electerm 并创建新书签（点击 "+" 按钮）或编辑现有书签

2. 填写基本连接详情：

   • 主机：您的服务器 IP 或主机名
   • 端口：SSH 端口（默认：22）
   • 用户名：必须与证书中的某个主体匹配

3. 切换到私钥/证书部分：

   • 在书签表单中，找到认证部分
   • 点击 "私钥/证书" 标签/部分展开

4. 导入私钥：

   • 点击私钥字段旁边的 "导入" 或 "浏览" 按钮
   • 导航并选择您的私钥文件
     • 例如，~/.ssh/id_ed25519_cert
   • 如果您的密钥有密码，请在 "密码" 字段中输入

5. 导入证书：

   • 点击证书字段旁边的 "导入" 或 "浏览" 按钮
   • 导航并选择您的证书文件
     • 例如，~/.ssh/id_ed25519_cert-cert.pub
   • 注意：您必须手动导入两个文件；electerm 不会自动检测它们

6. 保存并连接：

   • 点击 "保存" 保存书签
   • 双击书签或点击 "连接" 建立连接

如果您更喜欢使用 SSH 配置，创建或编辑 ~/.ssh/config：

Host myserver
    HostName 192.168.1.100
    User john
    IdentityFile ~/.ssh/id_ed25519_cert
    CertificateFile ~/.ssh/id_ed25519_cert-cert.pub

然后在 electerm 中：

1. 使用主机别名（myserver）作为主机名
2. electerm 将自动使用您的 SSH 配置

确保这些文件在您的 ~/.ssh/ 目录中：

~/.ssh/
├── id_ed25519_cert          # 私钥
├── id_ed25519_cert.pub      # 公钥
└── id_ed25519_cert-cert.pub # 证书（由 CA 签署）

签署时，您可以限制证书允许的内容：

# 限制为特定源地址
ssh-keygen -s ca_key -I "user" -n username \
  -O source-address=192.168.1.0/24 \
  -V +1w user_key.pub

# 禁用某些功能
ssh-keygen -s ca_key -I "user" -n username \
  -O no-agent-forwarding \
  -O no-port-forwarding \
  -O no-x11-forwarding \
  -V +1w user_key.pub

# 强制特定命令
ssh-keygen -s ca_key -I "backup-user" -n backup \
  -O force-command="/usr/local/bin/backup-script" \
  -V +1w user_key.pub

创建密钥撤销列表 (KRL)：

# 创建初始 KRL
ssh-keygen -k -f /etc/ssh/revoked_keys

# 通过序列号撤销证书
ssh-keygen -k -f /etc/ssh/revoked_keys -z 1

# 通过密钥 ID 撤销
ssh-keygen -k -f /etc/ssh/revoked_keys -s ca_key id_to_revoke

添加到 sshd_config：

RevokedKeys /etc/ssh/revoked_keys

签署主机密钥以防止"未知主机"警告：

# 在 CA 机器上，签署主机公钥
ssh-keygen -s ca_key -I "server.example.com" \
  -h -n "server.example.com,192.168.1.100" \
  -V +52w /etc/ssh/ssh_host_ed25519_key.pub

在 /etc/ssh/sshd_config 中配置服务器：

HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

在客户端，添加到 ~/.ssh/known_hosts 或 /etc/ssh/ssh_known_hosts：

@cert-authority *.example.com ssh-ed25519 AAAA... CA_PUBLIC_KEY_HERE

1. "权限被拒绝"错误

   • 验证用户名与证书中的主体匹配
   • 检查证书有效性：ssh-keygen -L -f cert-file.pub
   • 确保 CA 公钥在 TrustedUserCAKeys 中

2. 证书未被识别

   • 验证文件权限：私钥应为 600
   • 确保证书文件以 -cert.pub 结尾
   • 检查 SSH 服务器日志：journalctl -u sshd -f

3. 调试连接

   ssh -vvv user@server

# 测试 SSH 配置语法
sudo sshd -t

# 检查 CA 密钥是否可读
sudo cat /etc/ssh/ca_key.pub

1. 保护 CA 私钥 - 离线存储或在 HSM 中
2. 使用短期有效期 - 定期轮换证书
3. 使用唯一序列号 - 用于审计跟踪和撤销
4. 实施撤销 - 准备 KRL
5. 限制主体 - 只允许必要的用户名
6. 使用限制 - 在可能的地方应用源地址和命令限制

更多信息，请参阅：

• OpenSSH 证书文档
• electerm 文档