This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

English | 中文

English

SSH Certificate Authentication Guide for electerm

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

Overview

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.

Why Use SSH Certificates?

Problems with Traditional SSH Keys

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.
No Expiration: SSH keys never expire. When an employee leaves, you must manually remove their key from every server—easy to miss one.
No Central Control: There's no way to instantly revoke access across all servers. Each server maintains its own list of authorized keys.
Difficult Auditing: Hard to track who has access to what, when access was granted, and by whom.

Benefits of SSH Certificates

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.
Built-in Expiration: Certificates have validity periods. After expiration, access is automatically revoked—no manual cleanup needed.
Easy Revocation: Revoke a certificate centrally, and access is denied across all servers immediately.
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.
Audit Trail: Each certificate has a unique ID and serial number, making it easy to track in logs.
Simplified Onboarding/Offboarding:
- New employee? Sign their key once, they can access all authorized servers.
- Employee leaves? Revoke their certificate or let it expire.

When to Use Certificates

Scenario	Recommendation
Personal use, few servers	Traditional SSH keys are fine
Small team, < 10 servers	Either works
Enterprise, many servers	Certificates strongly recommended
Compliance requirements	Certificates (for audit trails)
Contractor/temporary access	Certificates (short validity)
Automated systems	Certificates (can restrict to specific commands)

Part 1: Setting Up the Certificate Authority (CA)

Step 1: Create the CA Key Pair

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

Step 2: Configure the SSH Server to Trust the CA

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

Part 2: Generating User Certificates

Step 1: Generate a User Key Pair

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 "user@example.com"

# Or use RSA
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_cert -C "user@example.com"

Step 2: Sign the User's Public Key with the CA

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 "john.doe@company.com" \
  -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)

Step 3: Verify the Certificate

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

Output example:

id_ed25519_cert-cert.pub:
        Type: ssh-ed25519-cert-v01@openssh.com user certificate
        Public key: ED25519-CERT SHA256:...
        Signing CA: ED25519 SHA256:...
        Key ID: "john.doe@company.com"
        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

Part 3: Using SSH Certificates in electerm

Step-by-Step Configuration

Open electerm and create a new bookmark (click the "+" button) or edit an existing one
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
Switch to PrivateKey/Certificate Section:
- In the bookmark form, locate the authentication section
- Click on "PrivateKey/Certificate" tab/section to expand it
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
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
Save and Connect:
- Click "Save" to store the bookmark
- Double-click the bookmark or click "Connect" to establish the connection

Alternative: Using SSH Config

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:

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

Files Required on Client

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)

Part 4: Advanced Configuration

Restricting Certificate Capabilities

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

Certificate Revocation

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

Part 5: Host Certificates (Optional)

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

Troubleshooting

Common Issues

"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
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
Debug connection
```
ssh -vvv user@server
```

Verify Server Configuration

# Test SSH config syntax
sudo sshd -t

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

Quick Reference

Task	Command
Generate CA key	`ssh-keygen -t ed25519 -f ca_key`
Generate user key	`ssh-keygen -t ed25519 -f user_key`
Sign user key	`ssh-keygen -s ca_key -I "id" -n user -V +52w user_key.pub`
View certificate	`ssh-keygen -L -f user_key-cert.pub`
Test connection	`ssh -i user_key user@server`

Security Best Practices

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

For more information, see:

Chinese

electerm SSH 证书认证指南

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

概述

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

为什么使用 SSH 证书？

传统 SSH 密钥的问题

密钥分发噩梦：使用传统 SSH 密钥，您必须将每个用户的公钥添加到他们需要访问的每个服务器的 ~/.ssh/authorized_keys 中。对于 100 个用户和 50 个服务器，可能需要管理 5000 个密钥条目。
无过期时间：SSH 密钥永不过期。当员工离职时，您必须手动从每个服务器上删除他们的密钥——很容易遗漏一个。
无集中控制：无法即时撤销所有服务器的访问权限。每台服务器维护自己的授权密钥列表。
审计困难：很难跟踪谁有权访问什么、何时授予访问权限以及由谁授予。

SSH 证书的好处

集中信任：服务器信任 CA，而不是单个密钥。将一个 CA 公钥添加到服务器，它会自动信任该 CA 签署的所有证书。
内置过期：证书具有有效期。过期后，访问权限自动撤销——无需手动清理。
易于撤销：集中撤销证书，立即拒绝所有服务器的访问权限。
细粒度控制：证书可以限制：
- 可以使用哪些用户名（主体）
- 允许的源 IP 地址
- 可以运行的特定命令
- 端口转发、代理转发等。
审计跟踪：每个证书都有唯一的 ID 和序列号，便于日志跟踪。
简化入职/离职：
- 新员工？签署他们的密钥一次，他们就可以访问所有授权服务器。
- 员工离职？撤销他们的证书或让其过期。

何时使用证书

场景	建议
个人使用，少量服务器	传统 SSH 密钥即可
小团队，< 10 个服务器	任一方式都行
企业，许多服务器	强烈推荐证书
合规要求	证书（用于审计跟踪）
承包商/临时访问	证书（短期有效期）
自动化系统	证书（可以限制为特定命令）

第1部分：设置证书颁发机构 (CA)

第1步：创建 CA 密钥对

在您的 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 公钥

第2步：配置 SSH 服务器信任 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

第2部分：生成用户证书

第1步：生成用户密钥对

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

# 为用户生成新的密钥对
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_cert -C "user@example.com"

# 或使用 RSA
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_cert -C "user@example.com"

第2步：使用 CA 签署用户的公钥

在 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 "john.doe@company.com" \
  -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（证书文件）

第3步：验证证书

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

输出示例：

id_ed25519_cert-cert.pub:
        Type: ssh-ed25519-cert-v01@openssh.com user certificate
        Public key: ED25519-CERT SHA256:...
        Signing CA: ED25519 SHA256:...
        Key ID: "john.doe@company.com"
        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

第3部分：在 electerm 中使用 SSH 证书

逐步配置

打开 electerm 并创建新书签（点击 "+" 按钮）或编辑现有书签
填写基本连接详情：
- 主机：您的服务器 IP 或主机名
- 端口：SSH 端口（默认：22）
- 用户名：必须与证书中的某个主体匹配
切换到私钥/证书部分：
- 在书签表单中，找到认证部分
- 点击 "私钥/证书" 标签/部分展开
导入私钥：
- 点击私钥字段旁边的 "导入" 或 "浏览" 按钮
- 导航并选择您的私钥文件
  - 例如，~/.ssh/id_ed25519_cert
- 如果您的密钥有密码，请在 "密码" 字段中输入
导入证书：
- 点击证书字段旁边的 "导入" 或 "浏览" 按钮
- 导航并选择您的证书文件
  - 例如，~/.ssh/id_ed25519_cert-cert.pub
- 注意：您必须手动导入两个文件；electerm 不会自动检测它们
保存并连接：
- 点击 "保存" 保存书签
- 双击书签或点击 "连接" 建立连接

替代方案：使用 SSH 配置

如果您更喜欢使用 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 中：

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

客户端所需文件

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

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

第4部分：高级配置

限制证书能力

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

# 限制为特定源地址
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

第5部分：主机证书（可选）

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

# 在 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

故障排除

常见问题

"权限被拒绝"错误
- 验证用户名与证书中的主体匹配
- 检查证书有效性：ssh-keygen -L -f cert-file.pub
- 确保 CA 公钥在 TrustedUserCAKeys 中
证书未被识别
- 验证文件权限：私钥应为 600
- 确保证书文件以 -cert.pub 结尾
- 检查 SSH 服务器日志：journalctl -u sshd -f
调试连接
```
ssh -vvv user@server
```

验证服务器配置

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

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

快速参考

任务	命令
生成 CA 密钥	`ssh-keygen -t ed25519 -f ca_key`
生成用户密钥	`ssh-keygen -t ed25519 -f user_key`
签署用户密钥	`ssh-keygen -s ca_key -I "id" -n user -V +52w user_key.pub`
查看证书	`ssh-keygen -L -f user_key-cert.pub`
测试连接	`ssh -i user_key user@server`

安全最佳实践

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

更多信息，请参阅：