密码学与证书 / 知识点
OpenSSL 证书操作手册
手册条目
确认当前 OpenSSL 版本、构建参数、配置目录和可用能力。
检查 OpenSSL 版本
用于确认当前命令行实际调用的 OpenSSL、命令与库版本是否一致,以及编译平台、默认配置目录和模块目录。排查“本机支持、目标机不支持”、配置未生效或同名命令冲突时,先执行本条目。
命令定位
先确认 PATH 中命中的可执行文件,再查看完整构建信息。command -v 适用于常见 POSIX Shell;脚本中不要只记录版本号,否则容易漏掉多版本并存问题。
command -v openssl
openssl version -a预期输出
/usr/bin/openssl
OpenSSL <VERSION> <DATE> (Library: OpenSSL <VERSION> <DATE>)
built on: <BUILD_TIME>
platform: <PLATFORM>
options: <BUILD_OPTIONS>
OPENSSLDIR: "<OPENSSL_CONFIG_DIR>"
ENGINESDIR: "<ENGINE_DIR>"
MODULESDIR: "<MODULE_DIR>"
Seeding source: os-specific第一行是实际执行路径;首行中的 OpenSSL 表示命令版本,括号内 Library 表示运行时库版本。两者不一致时,优先怀疑 PATH、动态库搜索路径或容器挂载导致混用。不同发行版可能省略部分字段。
高频用法
只看简短版本、默认配置目录,以及 OpenSSL 3.x 已加载的 provider,可使用:
openssl version
openssl version -d
openssl list -providers预期输出
OpenSSL <VERSION> <DATE>
OPENSSLDIR: "<OPENSSL_CONFIG_DIR>"
Providers:
default
name: OpenSSL Default Provider
version: <VERSION>
status: activeopenssl version -d 输出的目录通常包含或指向 openssl.cnf。openssl list -providers 主要用于 OpenSSL 3.x;若返回未知选项,说明当前版本较旧,应改查版本和发行版文档,不要据此判断安装损坏。
常用参数
-a 显示版本、构建时间、平台、编译选项和目录;-v 仅显示版本;-d 显示默认配置目录;-e 显示 engines 目录;-m 显示 provider modules 目录。部分目录参数仅在相应版本或构建中可用。
风险与边界
版本输出只能证明当前进程加载到的 OpenSSL,不能证明应用程序一定使用同一套库。触发条件是应用静态链接、使用语言运行时自带 TLS 库,或服务进程拥有不同环境变量;后果是命令行测试正常而应用仍失败。安全替代方案是同时检查应用依赖、服务环境和实际握手日志。
不要把“版本较新”直接等同于“算法可用”。OpenSSL 3.x 的旧算法可能位于 legacy provider,FIPS 环境还会进一步限制能力。应通过 openssl list 查询算法,并在目标服务相同配置下验证。
排障清单
openssl: command not found:检查软件包是否安装,并确认 PATH;不要随意创建指向未知二进制的软链接。- 路径与预期不符:使用
type -a openssl枚举同名命令,清理 Shell 缓存后重试。 - 命令版与 Library 版不一致:检查
LD_LIBRARY_PATH、DYLD_LIBRARY_PATH、容器挂载和自定义安装目录。 - 配置疑似未加载:核对
OPENSSL_CONF与OPENSSLDIR,再用目标命令验证 provider 或算法是否可见。
兼容性
Linux、macOS 和类 Unix 系统可直接使用以上命令。Windows PowerShell 用 Get-Command openssl 定位程序;系统自带的 LibreSSL、BoringSSL 工具或厂商裁剪版本,其字段和子命令可能与 OpenSSL 不完全一致。
解析 PEM 或 DER 证书的主题、颁发者、有效期、公钥和扩展字段。
查看证书完整信息
用于解析本地 X.509 证书,快速确认主题、颁发者、序列号、有效期、公钥算法、签名算法和扩展字段。该操作只读取证书,不会验证信任链、域名匹配或私钥是否对应。
基本语法
PEM 证书通常以 -----BEGIN CERTIFICATE----- 开头,直接使用 -in;DER 是二进制编码,必须显式指定 -inform DER。-noout 用于禁止再次输出编码后的证书正文。
openssl x509 -in server.crt -noout -text预期输出
Certificate:
Data:
Version: 3 (0x2)
Serial Number: <SERIAL>
Signature Algorithm: sha256WithRSAEncryption
Issuer: C = CN, O = Example CA, CN = Example Intermediate CA
Validity
Not Before: <TIME>
Not After : <TIME>
Subject: CN = api.example.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
X509v3 extensions:
X509v3 Subject Alternative Name:
DNS:api.example.com, DNS:www.api.example.com读取时先看 Issuer 与 Subject,再看 Not Before、Not After,最后检查 Subject Alternative Name、Key Usage、Extended Key Usage 和 Basic Constraints。时间通常以 GMT/UTC 显示,实际值因证书而异。
高频用法
只提取排障常用字段并生成 SHA-256 指纹,可避免在长输出中查找:
openssl x509 -in server.crt -noout \
-subject -issuer -serial -dates \
-fingerprint -sha256预期输出
subject=CN = api.example.com
issuer=C = CN, O = Example CA, CN = Example Intermediate CA
serial=<SERIAL>
notBefore=<TIME>
notAfter=<TIME>
sha256 Fingerprint=<SHA256_FINGERPRINT>解析 DER 证书时改用:
openssl x509 -inform DER -in server.cer -noout -text预期输出
Certificate:
Data:
Version: 3 (0x2)
Serial Number: <SERIAL>
Signature Algorithm: <SIGNATURE_ALGORITHM>
Issuer: <ISSUER_DN>
Subject: <SUBJECT_DN>输出字段说明
Subject 是证书主体,主机名校验应以 Subject Alternative Name 为准;Issuer 是签发者;Serial Number 用于唯一标识证书并配合吊销查询;Public Key Algorithm 和位数反映公钥类型与强度;最外层与 Data 内的签名算法通常应一致。
Basic Constraints 中 CA:TRUE 表示可作为 CA 证书;服务器叶子证书通常为 CA:FALSE。Key Usage 限制密钥用途,Extended Key Usage 中服务器证书通常需要 TLS Web Server Authentication。缺失或组合错误可能导致客户端拒绝握手。
风险与边界
openssl x509 -text 只做语法解析。触发条件是把“能解析”误认为“可信可用”;后果是过期、自签名、链不完整或域名不匹配的证书仍被错误上线。安全替代方案是另外执行链验证,并对远端服务做主机名和握手检查。
证书文件可能与私钥放在同一 PEM 文件中。读取前若发现 PRIVATE KEY 标记,不要上传、粘贴或写入工单;应复制出仅含证书的文件后再分析。生成指纹时显式指定 -sha256,避免依赖不同版本的默认摘要算法。
排障清单
Could not read certificate:确认文件路径、权限和内容是否真的是证书,而不是 CSR、PKCS#7 或私钥。Expecting: TRUSTED CERTIFICATE:常见原因是 PEM 头尾损坏、文件为空或实际为 DER;用file server.crt辅助判断编码。- 字段能读但服务仍报错:继续检查完整链、SAN、用途扩展、证书与私钥匹配,以及服务是否已重新加载证书。
- 多证书 PEM:
openssl x509默认只处理读到的第一张证书;需要逐张拆分后分别检查。
兼容性
OpenSSL 1.1.1 与 3.x 均支持上述核心参数,但 DN 的显示格式、算法名称和扩展输出细节可能不同。LibreSSL 或厂商裁剪版本可能缺少个别选项;自动化脚本应匹配字段语义,不要依赖固定缩进或整行文本。
快速查看证书起止时间并判断是否即将过期。
检查证书有效期
用于读取证书的生效时间与到期时间,并用 -checkend 把“是否会在指定窗口内过期”转换为退出码,适合人工巡检、发布前检查和监控脚本。命令输出中的 GMT 表示 UTC,实际展示时间会随证书变化。
基本语法
openssl x509 -in <CERT_FILE> -noout -dates
openssl x509 -in <CERT_FILE> -noout -checkend <SECONDS>-dates 同时输出 notBefore 和 notAfter;-checkend 的参数是秒数。证书在该秒数内不会过期时退出码为 0,已经过期或将在窗口内过期时返回非零;解析失败也可能返回非零,因此监控脚本应先验证证书能否读取。
高频用法
查看本地 PEM 证书的起止时间:
openssl x509 -in server.crt -noout -dates预期输出:
notBefore=<UTC_TIME>
notAfter=<UTC_TIME>判断证书是否会在 30 天内过期,并区分“即将过期”和“文件无法解析”:
CERT_FILE=server.crt
THRESHOLD_SECONDS=$((30 * 24 * 60 * 60))
# 先验证文件可解析,避免把格式错误误报为到期。
if ! openssl x509 -in "$CERT_FILE" -noout >/dev/null 2>&1; then
echo "ERROR: cannot parse certificate"
elif openssl x509 -in "$CERT_FILE" -noout -checkend "$THRESHOLD_SECONDS" >/dev/null; then
echo "OK: certificate is valid for more than 30 days"
else
echo "ALERT: certificate expires within 30 days"
fi预期输出(剩余有效期超过 30 天时):
OK: certificate is valid for more than 30 days直接检查远端 HTTPS 服务当前返回的叶子证书:
HOST=example.com
PORT=443
openssl s_client -connect "${HOST}:${PORT}" -servername "$HOST" </dev/null 2>/dev/null \
| openssl x509 -noout -dates预期输出:
notBefore=<UTC_TIME>
notAfter=<UTC_TIME>输出与判断
notBefore 晚于当前时间表示证书尚未生效;notAfter 早于当前时间表示证书已经过期。日常告警不要只比较日期字符串,优先使用 -checkend 的退出码,并为续期、审批、发布和回滚预留足够窗口。
远端命令只读取服务实际返回的第一张证书,通常是叶子证书。它不等同于完整验证:证书链是否可信、域名是否匹配、是否被吊销,需要分别使用链验证、主机名检查或应用侧握手结果确认。
风险与边界
未给 s_client 指定 -servername 时,命中多域名服务器的默认虚拟主机证书,可能误判目标域名的有效期;安全做法是始终传入与业务请求一致的 SNI 主机名。系统时钟错误会让 -checkend 产生错误结论,应先确认 NTP 同步。
直接把 -checkend 的任意非零退出码都当作“即将过期”,会把文件不存在、权限不足、格式错误等故障混入到期告警。生产脚本应先执行解析检查,并记录标准错误,必要时把“证书不可读”和“证书临期”拆成不同告警。
排障清单
- 出现
Could not open file:检查路径、容器挂载和读取权限。 - 出现
Unable to load certificate:确认文件是证书而不是私钥或 CSR;DER 文件增加-inform DER。 - 远端没有证书输出:检查 DNS、端口、防火墙、代理和 TLS 服务是否正常,再确认 SNI 是否正确。
- 时间结论与浏览器不一致:确认检查的是同一入口、同一负载均衡节点,并核对系统时间。
兼容性
OpenSSL 1.1.1 与 3.x 常用版本均支持上述核心参数;不同版本的日期排版和错误文本可能略有差异,自动化应依赖退出码而不是匹配完整英文句子。部署前可运行 openssl version 和 openssl x509 -help 确认目标环境参数。
提取证书中的 Subject 和 Subject Alternative Name 域名列表。
查看证书域名
用于提取证书的 Subject 和 Subject Alternative Name(SAN),确认服务实际覆盖哪些 DNS 名称或 IP,并用 -checkhost 判断指定主机名是否匹配。排查“证书名称不匹配”时,应优先读取 SAN,而不是只看 Subject 中的 CN。
基本语法
openssl x509 -in <CERT_FILE> -noout -subject -ext subjectAltName
openssl x509 -in <CERT_FILE> -noout -checkhost <HOSTNAME>-subject 输出证书主体的完整 Distinguished Name;-ext subjectAltName 只打印 SAN 扩展;-checkhost 按证书主机名匹配规则检查目标域名,并通过退出码表示成功或失败。
高频用法
查看本地证书中的 Subject 与 SAN:
openssl x509 -in server.crt -noout -subject -ext subjectAltName预期输出:
subject=C = US, O = Example Corp, CN = www.example.com
X509v3 Subject Alternative Name:
DNS:www.example.com, DNS:example.com, IP Address:192.0.2.10读取远端 HTTPS 服务实际返回的域名列表:
HOST=api.example.com
PORT=443
openssl s_client -connect "${HOST}:${PORT}" -servername "$HOST" </dev/null 2>/dev/null \
| openssl x509 -noout -subject -ext subjectAltName预期输出:
subject=<DISTINGUISHED_NAME>
X509v3 Subject Alternative Name:
DNS:<HOSTNAME>, DNS:<OTHER_HOSTNAME>用退出码直接验证指定域名,适合部署检查:
CERT_FILE=server.crt
HOST=api.example.com
if openssl x509 -in "$CERT_FILE" -noout -checkhost "$HOST" >/dev/null; then
echo "MATCH: $HOST"
else
echo "NO_MATCH: $HOST"
fi预期输出(证书覆盖该域名时):
MATCH: api.example.com输出字段说明
subject=... 是证书主体信息,其中 CN 可能包含一个主机名,但不能代表全部覆盖范围。X509v3 Subject Alternative Name 下的 DNS: 才是 DNS 名称列表,IP Address: 是证书明确覆盖的 IP;应用通过 IP 访问时,DNS 类型的同数字字符串不能替代 IP 类型 SAN。
存在 SAN 时,现代主机名校验通常以 SAN 为准。通配符如 *.example.com 一般只覆盖左侧一个标签,例如可匹配 api.example.com,不能匹配 v1.api.example.com。不要用字符串包含关系自行判断,直接使用 -checkhost 更安全。
风险与边界
远端检查省略 -servername 会拿到默认虚拟主机证书,导致域名列表和实际业务入口不一致;安全替代方案是把 SNI 设置为请求中的主机名。只看 Subject/CN 可能把已迁移到 SAN 的证书误判为缺少域名,应同时输出 SAN。
-checkhost 只检查名称匹配,不验证证书链可信性、有效期或吊销状态。生产验证应把域名匹配与 -checkend、证书链验证和真实客户端握手结果组合使用。用 grep DNS 解析输出还可能遗漏换行后的条目或 IP SAN,尽量保留 OpenSSL 原始结构化输出。
排障清单
- 输出
No extensions in certificate:证书没有 SAN;面向现代 TLS 客户端时应重新签发包含 SAN 的证书。 - 远端结果不是预期证书:确认访问的域名、端口、SNI、代理和负载均衡入口一致。
- 通配符检查失败:核对域名层级,
*.example.com不覆盖多级子域。 - 本地可匹配但应用仍报错:检查应用实际连接名、证书链、信任库、有效期和是否使用 IP 访问。
兼容性
OpenSSL 1.1.1 与 3.x 常用版本支持 -ext 和 -checkhost。较旧环境若不支持 -ext,可用 openssl x509 -in server.crt -noout -text 查看完整扩展,但自动化解析容易受缩进和换行影响;升级 OpenSSL 或使用专用证书解析库更稳妥。
生成 SHA-256 等证书指纹,用于证书比对和变更确认。
计算证书指纹
用于确认两份证书是否为同一张证书,或在证书轮换前后记录变更。优先生成 SHA-256 指纹;指纹相同通常表示证书 DER 编码完全一致,指纹不同则说明证书内容发生了变化。
基本语法
PEM 证书直接使用 openssl x509 读取,并通过 -fingerprint 输出摘要:
openssl x509 -in cert.pem -noout -fingerprint -sha256预期输出:
sha256 Fingerprint=<SHA256_FINGERPRINT><SHA256_FINGERPRINT> 是以冒号分隔的十六进制摘要,实际值随证书变化。复制比对时应保留完整摘要,不要只比较开头或结尾几组字符。
高频用法
查看 DER 格式证书时显式指定输入格式:
openssl x509 -in cert.der -inform DER -noout -fingerprint -sha256预期输出:
sha256 Fingerprint=<SHA256_FINGERPRINT>从远端 TLS 服务读取当前叶子证书并计算指纹:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256预期输出:
sha256 Fingerprint=<REMOTE_SHA256_FINGERPRINT>-servername 用于发送 SNI;同一 IP 承载多个站点时缺少该参数可能取得默认证书,而不是目标域名证书。
结果比对
需要脚本判断两份证书是否一致时,只提取等号后的指纹并比较:
old_fp=$(openssl x509 -in old.pem -noout -fingerprint -sha256 | cut -d= -f2)
new_fp=$(openssl x509 -in new.pem -noout -fingerprint -sha256 | cut -d= -f2)
if [ "$old_fp" = "$new_fp" ]; then
echo "MATCH"
else
echo "CHANGED"
fi预期输出之一:
MATCH或:
CHANGED风险与边界
证书指纹只能确认“证书内容是否相同”,不能证明证书可信、未过期或域名匹配。若把指纹相同误当作完整安全校验,可能漏掉信任链、有效期和主机名问题;安全替代方案是同时执行证书链验证、有效期检查和主机名校验。
MD5、SHA-1 指纹仍可能用于兼容旧系统,但不应作为新的安全比对基准。默认使用 -sha256,并在变更单、资产台账或双人复核记录中保存完整指纹。
提取证书序列号和签名算法,便于吊销查询与签发记录核对。
查看证书序列号与签名算法
用于核对 CA 签发记录、CRL 或 OCSP 吊销信息,并确认当前证书采用的签名算法。序列号必须结合签发者识别,因为不同 CA 可能生成相同序列号。
基本语法
先输出序列号,再从证书文本中提取第一处签名算法:
openssl x509 -in cert.pem -noout -serial
openssl x509 -in cert.pem -noout -text | sed -n 's/^[[:space:]]*Signature Algorithm: /Signature Algorithm: /p' | head -n 1预期输出:
serial=<SERIAL_HEX>
Signature Algorithm: sha256WithRSAEncryption<SERIAL_HEX> 是证书序列号的十六进制表示;签名算法也可能显示为 ecdsa-with-SHA256、rsassaPss 等,实际结果取决于证书。
高频用法
核对吊销记录时同时输出签发者,避免只凭序列号匹配:
openssl x509 -in cert.pem -noout -issuer -serial预期输出:
issuer=<ISSUER_DISTINGUISHED_NAME>
serial=<SERIAL_HEX>查看 DER 格式证书时增加 -inform DER:
openssl x509 -in cert.der -inform DER -noout -serial
openssl x509 -in cert.der -inform DER -noout -text | sed -n 's/^[[:space:]]*Signature Algorithm: /Signature Algorithm: /p' | head -n 1预期输出:
serial=<SERIAL_HEX>
Signature Algorithm: <SIGNATURE_ALGORITHM>需要人工审计完整签名信息时查看全文:
openssl x509 -in cert.pem -noout -text预期结果:输出中包含 Serial Number、证书主体、签发者、有效期、公钥算法,以及两处 Signature Algorithm 字段。快速提取命令只显示第一处;全文审计时两处算法应保持一致。
输出读取
-serial 输出通常为连续十六进制字符串,不带 0x 前缀。部分管理平台会改成冒号分隔、十进制或去除前导零,因此跨系统核对时应先统一表示格式,并同时确认 issuer。
签名算法描述的是 CA 对证书签名时使用的算法,不等同于证书公钥算法。例如 RSA 公钥证书可以使用 sha256WithRSAEncryption 签名;判断公钥类型需另看 Public Key Algorithm。
风险与边界
只按序列号查询吊销状态时,若未限定签发者,可能命中错误 CA 的记录;安全替代方案是使用“签发者标识加序列号”联合查询。把十六进制序列号直接转为整数还可能丢失前导零,导致审计记录无法逐字匹配,建议保存 OpenSSL 原始输出。
若签名算法为 SHA-1、MD5 或其他已不符合组织策略的算法,不要仅凭命令结果直接替换证书。应先确认客户端兼容性和 CA 可用算法,再重新签发并完成灰度验证。
连接指定主机和端口,获取服务端返回的证书与证书链。
查看远程站点证书
用于确认远程 TLS 服务实际返回的叶子证书、上游中间证书和握手校验结果。以下命令不会修改服务器,只建立一次 TLS 连接并把服务端发送的证书链打印到终端。
基本语法
openssl s_client -connect example.com:443 \
-servername example.com \
-showcerts </dev/null预期输出(节选,证书内容和动态值会不同):
CONNECTED(<N>)
---
Certificate chain
0 s:<LEAF_SUBJECT>
i:<ISSUER_SUBJECT>
-----BEGIN CERTIFICATE-----
<BASE64_CERTIFICATE>
-----END CERTIFICATE-----
1 s:<INTERMEDIATE_SUBJECT>
i:<ROOT_OR_UPSTREAM_ISSUER>
-----BEGIN CERTIFICATE-----
<BASE64_CERTIFICATE>
-----END CERTIFICATE-----
---
Verify return code: <CODE> (<TEXT>)索引 0 是站点叶子证书,后续索引通常是服务器附带的中间证书;s 表示主题,i 表示签发者。-showcerts 只展示服务器发送的证书列表,不代表该列表已经构成并通过验证的可信链。:contentReference[oaicite:0]{index=0}
常用参数
-connect host:port:指定目标主机和 TLS 端口。-servername domain:发送 SNI。访问多域名共享 IP 的站点时必须填写证书对应域名。-showcerts:打印服务器随握手发送的全部证书。-verify_hostname domain:按域名检查叶子证书名称。-verify_return_error:遇到证书验证错误时让握手失败,而不是只打印错误后继续。-starttls smtp|imap|pop3|ftp|xmpp:先连接明文协议,再升级到 TLS。
高频用法
只查看叶子证书的关键字段,适合工单取证或快速比对:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
| openssl x509 -noout -subject -issuer -serial -dates -fingerprint -sha256预期输出:
subject=<LEAF_SUBJECT>
issuer=<ISSUER_SUBJECT>
serial=<SERIAL_HEX>
notBefore=<TIME>
notAfter=<TIME>
sha256 Fingerprint=<HEX_BYTES>读取时先核对 subject 是否属于目标域名,再看 issuer、有效期和 SHA-256 指纹。该管道只解析收到的第一张证书,也就是通常的叶子证书。
风险与边界
未指定 -servername 时,负载均衡器或共享虚拟主机可能返回默认证书,导致误判。安全做法是始终使用业务域名作为 SNI,即使 -connect 中填写的是 IP 地址。
把 2>/dev/null 用于结构化提取可以减少握手日志,但也会隐藏连接失败、协议不兼容和校验错误。排障时应先运行不重定向错误输出的完整命令,再决定是否静默处理。
Verify return code: 0 (ok) 只表示 OpenSSL 按当前信任库完成了链验证;仍应核对访问域名、SNI、目标端口和实际接入路径。若需要严格失败语义,增加 -verify_hostname 与 -verify_return_error。
排障清单
- 长时间无输出:确认 TCP 端口可达,并保留
</dev/null,避免命令等待交互输入。 - 返回错误证书:检查
-servername是否为业务域名,而不是节点 IP。 no peer certificate available:目标端口可能不是 TLS,或服务需要-starttls。- 链不完整:查看
Certificate chain是否缺少中间证书,并在客户端信任库或服务端链配置中继续验证。 - 握手失败:去掉
2>/dev/null,读取协议版本、密码套件、证书校验和网络错误。
无需下载证书文件即可检查 HTTPS 或 TLS 服务的证书有效期。
检查远程证书过期时间
用于在不下载证书文件的情况下读取远程 HTTPS 或 TLS 服务的生效时间和过期时间,并可按剩余天数返回适合监控脚本使用的退出码。
基本语法
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
| openssl x509 -noout -dates预期输出:
notBefore=<TIME_IN_GMT>
notAfter=<TIME_IN_GMT>notBefore 是证书开始生效时间,notAfter 是证书到期时间。只关心到期点时把 -dates 换成 -enddate;OpenSSL 的 -enddate 打印 notAfter,-checkend N 会在证书将在未来 N 秒内过期时返回非零状态。:contentReference[oaicite:1]{index=1}
到期阈值检查
下面脚本先获取并解析叶子证书,再检查它是否能继续有效超过 30 天。连接或解析失败返回 2,临近过期或已经过期返回 1,状态正常返回 0。
#!/usr/bin/env bash
set -uo pipefail
host="example.com"
port="443"
warn_days="30"
tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT
# 先单独保存叶子证书,避免把连接失败误报成即将过期。
if ! openssl s_client -connect "${host}:${port}" -servername "$host" </dev/null 2>/dev/null \
| openssl x509 -outform PEM -out "$tmp"; then
echo "ERROR: unable to retrieve or parse certificate" >&2
exit 2
fi
warn_seconds=$((warn_days * 86400))
if openssl x509 -in "$tmp" -noout -checkend "$warn_seconds" >/dev/null; then
echo "OK: certificate remains valid for more than ${warn_days} days"
else
echo "WARN: certificate expires within ${warn_days} days or is expired"
exit 1
fi正常分支预期输出:
OK: certificate remains valid for more than 30 days临近过期或已过期时预期输出:
WARN: certificate expires within 30 days or is expired监控系统应同时采集退出码和文本:0 表示超过阈值,1 表示需要续期处理,2 表示网络、TLS 握手或证书解析失败。
常用参数
-dates:同时输出notBefore和notAfter。-enddate:只输出过期时间。-checkend seconds:按秒检查剩余有效期,适合告警脚本。-servername domain:发送 SNI,避免读取到共享 IP 上的默认证书。-starttls protocol:检查 SMTP、IMAP、POP3 等先明文后升级 TLS 的服务。
风险与边界
该管道只检查服务器返回的第一张证书,通常是叶子证书;它不会检查每张中间证书的到期时间。需要审计整条链时,应先用 -showcerts 分离每个 PEM 证书后逐张执行 openssl x509 -noout -dates。
-checkend 只比较证书时间,不等同于完整 TLS 健康检查。它不会单独证明域名匹配、链可信、私钥匹配、吊销状态正常或服务一定可用,生产监控应把到期检查与握手验证分开。
判断依赖执行主机的系统时间。系统时钟明显漂移时,可能产生提前或延后的告警;安全替代方案是先确认 NTP 同步状态,再执行证书有效期检查。
排障清单
- 没有日期输出:去掉
2>/dev/null,确认连接错误、协议类型和端口。 - 读取到错误域名:检查
-servername,并确认 DNS、代理或负载均衡实际指向。 - 非 HTTPS 服务失败:为 SMTP、IMAP 等增加正确的
-starttls参数。 - 监控持续报连接失败:分别检查 DNS、TCP、TLS 握手和证书解析,不要直接按“即将过期”处理。
- 时间看似异常:确认输出通常使用 GMT,并核对执行主机当前时间。
检查证书是否覆盖目标主机名、通配符域名或指定 IP 地址。
验证证书域名
用于确认本地证书或线上站点返回的叶子证书是否覆盖目标 DNS 主机名、通配符域名或 IP 地址。验证成功只说明名称匹配,不代表证书链、有效期和吊销状态均正常。
命令定位
本地文件使用 openssl x509 -checkhost 或 -checkip。检查线上站点时,先用 openssl s_client 携带 SNI 获取实际叶子证书,再交给 openssl x509 判断名称。
高频用法
检查本地证书
CERT=server.crt
# DNS 主机名与 IP 地址必须使用对应的检查选项
openssl x509 -in "$CERT" -noout -checkhost api.example.com
openssl x509 -in "$CERT" -noout -checkhost www.example.net
openssl x509 -in "$CERT" -noout -checkip 192.0.2.10预期输出
Hostname api.example.com does match certificate
Hostname www.example.net does match certificate
IP 192.0.2.10 does match certificate命令退出码为 0 表示匹配;不匹配时退出码非零,并输出 does NOT match certificate。*.example.net 可匹配 www.example.net,但不能匹配裸域名 example.net 或多级名称 a.b.example.net。
检查线上站点返回的证书
HOST=api.example.com
PORT=443
# -servername 发送 SNI,避免虚拟主机返回默认证书
openssl s_client -connect "${HOST}:${PORT}" -servername "$HOST" </dev/null 2>/dev/null \
| openssl x509 -noout -checkhost "$HOST"预期输出
Hostname api.example.com does match certificate示例输出假设目标站点返回覆盖 api.example.com 的证书;实际主机名和端口按现场替换。通过负载均衡、CDN 或多证书虚拟主机访问时必须保留 -servername,否则可能拿到其他站点的默认证书。
查看证书中的 SAN
CERT=server.crt
# 直接读取 Subject Alternative Name,确认 DNS 与 IP 条目类型
openssl x509 -in "$CERT" -noout -ext subjectAltName预期输出
X509v3 Subject Alternative Name:
DNS:api.example.com, DNS:*.example.net, IP Address:192.0.2.10读取时区分 DNS: 与 IP Address:。证书即使包含 DNS:192.0.2.10,也不能通过 -checkip 192.0.2.10,因为 IP 地址必须编码为 IP 类型 SAN。
风险与边界
触发条件:用 grep 搜索 SAN 文本并自行判断。可能后果:错误处理通配符、国际化域名或 IP 类型,导致误判。安全替代方案:始终使用 -checkhost 或 -checkip。
名称匹配不会验证签发链,也不会证明证书当前有效。生产验收应继续执行 openssl verify,并按需要检查有效期、用途和吊销状态。
排障清单
- 返回
does NOT match certificate:检查实际访问名称是否存在于 SAN,通配符是否只覆盖一级子域。 - 线上检查结果与浏览器不同:确认端口、SNI 名称、代理入口和 DNS 解析目标一致。
Could not read certificate:确认输入为 PEM/DER 证书;DER 文件需增加-inform DER。- 当前版本不识别
-checkhost:查看openssl x509 -help,升级受支持版本,或使用openssl verify -verify_hostname。
速查:DNS 名称用 -checkhost,字面 IP 用 -checkip,线上取证书必须带 -servername。
使用根证书和中间证书验证服务器证书的信任链是否完整。
验证证书链
用于确认服务器叶子证书能否通过一个或多个中间 CA 回溯到指定根 CA,并同时检查签名、有效期、CA 约束和服务器用途。成功结果为 server.crt: OK;失败时根据 depth 和错误文本定位断点。
文件角色
server.crt 是待验证的叶子证书;intermediate-ca.pem 只用于构建链,应通过 -untrusted 提供;root-ca.pem 是明确信任的锚点,应通过 -CAfile 提供。

基本语法
# 根证书是信任锚;中间证书仅作为链构建候选
openssl verify \
-CAfile root-ca.pem \
-untrusted intermediate-ca.pem \
-purpose sslserver \
-show_chain \
server.crt预期输出
server.crt: OK
Chain:
depth=0: CN=api.example.com (untrusted)
depth=1: CN=Example Intermediate CA (untrusted)
depth=2: CN=Example Root CAdepth=0 是叶子证书,depth=1 起为中间 CA,最高深度通常是信任锚。(untrusted) 表示证书来自待构建链的候选集合,不等于证书不可信;最终是否可信取决于能否连接到 -CAfile 中的根证书。
高频用法
多个中间证书
# PEM 包可包含多个中间 CA;不要把它们加入根信任锚文件
cat intermediate-1.pem intermediate-2.pem > intermediates.pem
openssl verify -CAfile root-ca.pem -untrusted intermediates.pem \
-purpose sslserver server.crt预期输出
server.crt: OK同时验证服务器域名
# 在链验证通过的基础上,再要求证书覆盖目标主机名
openssl verify -CAfile root-ca.pem -untrusted intermediate-ca.pem \
-purpose sslserver -verify_hostname api.example.com server.crt预期输出
server.crt: OK复现缺失中间证书
# 故意不提供中间 CA,用于确认链断点是否位于叶子证书之后
openssl verify -CAfile root-ca.pem -purpose sslserver server.crt预期输出
CN=api.example.com
error 20 at 0 depth lookup: unable to get local issuer certificate
error server.crt: verification failed这里的 depth 0 表示验证器在叶子证书处找不到其签发者,通常是中间证书缺失、拿错或不匹配。若错误出现在更高 depth,继续检查对应中间 CA 的签发者和 CA 扩展。
风险与边界
触发条件:把中间 CA 或叶子证书放入 -CAfile。可能后果:验证可能提前在非预期证书处结束,掩盖真实客户端缺少中间链的问题。安全替代方案:-CAfile 仅放批准的根信任锚,中间证书统一放入 -untrusted。
触发条件:使用 -partial_chain、-no_check_time 或把验证时间改为异常值。可能后果:非根证书可能被当作终点,或过期、尚未生效的证书被放行。安全替代方案:生产验收保持默认严格行为;只有私有 PKI 策略或事故回放明确要求时才增加这些选项,并记录原因。
链验证成功不等于证书未被吊销,也不保证线上服务器实际发送了完整链。吊销状态需另查 CRL/OCSP;线上链还应使用 openssl s_client -showcerts 抓取后逐张核对。
排障清单
unable to get local issuer certificate:补齐正确中间 CA,核对叶子证书issuer与中间证书subject。invalid CA certificate:检查中间证书是否含CA:TRUE,并具备keyCertSign。certificate has expired或not yet valid:检查系统时间及链上每张证书的有效期。unsupported certificate purpose:确认叶子证书的扩展用途允许serverAuth。- 仍无法构链:增加
-show_chain,并分别查看每张证书的subject、issuer、SKI 与 AKI。
速查:根证书放 -CAfile,中间证书放 -untrusted,叶子证书放在命令末尾;看到 OK 后再验证域名和线上实际下发链。
解析 CSR 中的主题、公钥、签名和扩展请求信息。
查看证书请求
用于确认 CSR 的主题、申请公钥、签名算法和扩展请求是否符合签发预期。首选 openssl req 解析;-verify 只能校验 CSR 自签名是否完整,不能证明申请者身份或 CA 信任关系。
命令定位
openssl req 同时负责创建和解析 PKCS#10 CSR。检查 PEM 文件时直接指定 -in;DER 文件还要增加 -inform DER。保留 -noout,避免把原始 CSR 与解析文本混在同一输出中。
openssl req -in server.csr -noout -text -verify预期输出
Certificate request self-signature verify OK
Certificate Request:
Data:
Version: 1 (0x0)
Subject: CN=api.example.com, O=Example Corp
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (256 bit)
pub:
<HEX>
ASN1 OID: prime256v1
Attributes:
Requested Extensions:
X509v3 Subject Alternative Name:
DNS:api.example.com, DNS:www.example.com
Signature Algorithm: ecdsa-with-SHA256
Signature Value:
<HEX>主题、公钥类型、曲线、SAN 和签名算法取决于实际 CSR;<HEX> 表示长度不固定的十六进制数据。首行出现 self-signature verify OK,表示 CSR 内容与其中公钥匹配且未被破坏。
高频用法
只核对主题,适合工单审批或批量检查:
openssl req -in server.csr -noout -subject预期输出
subject=CN=api.example.com, O=Example Corp导出 CSR 中的公钥,并确认生成的是标准 SubjectPublicKeyInfo PEM:
openssl req -in server.csr -noout -pubkey > csr-public.pem
head -n 1 csr-public.pem预期输出
-----BEGIN PUBLIC KEY-----解析 DER 编码的 CSR:
openssl req -inform DER -in server.csr.der -noout -subject预期输出
subject=CN=api.example.com, O=Example Corp输出读取
Subject 是申请主题,但浏览器和多数 TLS 客户端主要依据 Requested Extensions 下的 Subject Alternative Name。Subject Public Key Info 用于确认 RSA 位数、EC 曲线或其他公钥算法;Signature Algorithm 用于发现过旧或策略不允许的摘要算法。
看到 Requested Extensions 不代表 CA 一定会原样签发。签发前应把 SAN、用途和密钥算法与申请单或自动化配置逐项比对,再检查最终证书是否保留了预期扩展。
风险与边界
当 CSR 被上传到外部网站、工单或聊天工具时,内部域名、组织名和邮箱等信息可能泄露。安全替代方案是在受控主机离线解析,只共享必要字段或经过脱敏的输出。
当 -verify 返回成功时,后果仅是确认 CSR 自身签名有效;若据此直接批准签发,仍可能把证书签给错误主体。安全替代方案是同时校验申请来源、SAN 白名单、密钥指纹和审批记录。
排障清单
Unable to load X509 request或Expecting: CERTIFICATE REQUEST:确认文件头尾为BEGIN/END CERTIFICATE REQUEST,并排除把证书或私钥当成 CSR。wrong tag、nested asn1 error:常见于 PEM/DER 格式指定错误;DER 文件使用-inform DER。Certificate request self-signature verify failure:CSR 可能损坏、被修改或生成过程异常,应重新生成,不要继续签发。- 没有
Requested Extensions:生成 CSR 时未请求 SAN 等扩展;应修正配置后重新生成,而不是假设 CA 会自动补齐。
兼容性
OpenSSL 1.1.1 与 3.x 均支持上述核心选项,但成功提示、字段缩进和算法名称可能略有不同。OpenSSL 3.x 还可能因 provider 或安全级别策略拒绝旧摘要算法;应升级申请端算法,不要通过降低全局安全策略绕过。
验证 RSA、EC 或通用私钥文件是否可读取并查看关键参数。
检查私钥信息
用于确认私钥文件能否解密读取、内部结构是否一致,并在不暴露私密参数的前提下查看算法、位数或曲线。通用检查优先使用 openssl pkey;只有需要算法专属诊断时才使用 openssl rsa 或 openssl ec。
首选检查流程
先执行只读一致性检查。未加密私钥直接返回结果;加密私钥会在终端安全提示输入口令,不要把口令写进命令行。
openssl pkey -in private.key -check -noout预期输出
Key is valid该结果表示私钥编码可读取且内部数学关系一致,不表示密钥未泄露、仍受授权或一定与目标证书匹配。命令失败时不会改写原文件。
安全查看关键参数
优先使用 -text_pub,它只展示可公开部分。RSA 通常显示位数、模数和指数;EC 通常显示公钥点、曲线 OID 与 NIST 曲线名。
openssl pkey -in private.key -text_pub -noout预期输出(RSA 示例)
Public-Key: (2048 bit)
Modulus:
<HEX>
Exponent: 65537 (0x10001)EC 私钥的对应输出通常包含 Public-Key: (256 bit)、ASN1 OID: prime256v1 和 NIST CURVE: P-256。<HEX> 是长度随密钥变化的公开参数,不应据此推断实际文件固定为 RSA。
RSA 与 EC 专项校验
算法已经确定时,可用专属子命令获得更明确的结果:
openssl rsa -in rsa.key -check -noout
openssl ec -in ec.key -check -noout预期输出
RSA key ok
read EC key
EC Key valid.若文件类型未知,仍应先用 openssl pkey。把 EC 私钥交给 openssl rsa,或把 PKCS#8 通用密钥误判为某一算法,会得到误导性的“无法读取”错误。
加密私钥
直接运行通用检查即可触发交互式口令输入:
openssl pkey -in encrypted.key -check -noout预期输出
Enter pass phrase for encrypted.key:
Key is valid提示文本会因版本和文件名不同而变化。自动化场景不要使用 -passin pass:明文口令,因为口令可能进入 shell 历史、进程参数、审计日志或流水线输出;优先使用受权限保护的口令文件、文件描述符或专用密钥管理系统。
风险与边界
使用 -text 而不是 -text_pub 时,会打印 RSA 私有指数、素数或 EC 私有标量。触发条件是终端被录屏、输出被重定向到日志或粘贴到工单;后果是私钥永久失密。安全替代方案是只查看公开参数,必要时在隔离终端检查并立即清理输出。
检查命令若被改成带 -out 的转换命令,可能重写编码或在缺少 -passout 时生成未加密副本。安全替代方案是把“检查”和“转换”分开,在副本上操作,并先设置 umask 077 与 chmod 600。
排障与兼容性
Could not read key、unable to load Private Key:确认文件确实是私钥,并检查 PEM 头尾、文件权限和路径。bad decrypt:口令错误或密文损坏;从可信备份恢复,不要反复改写原文件。unsupported:OpenSSL 3.x 可能缺少对应 provider,或密钥使用旧格式/算法;先确认算法与来源,再加载所需 provider 或迁移格式。- DER 私钥:增加
-inform DER;不要仅凭文件扩展名判断编码。 - 校验通过但服务仍报不匹配:分别从私钥、证书或 CSR 导出公钥后比较 SHA-256 摘要。
openssl pkey 是 OpenSSL 1.1.1 与 3.x 的通用入口,适合 RSA、EC 和多数现代密钥类型。不同版本的错误文案及 EC 专项输出可能不同;判断时以退出码和 Key is valid、RSA key ok、EC Key valid. 等核心结果为准。
确认服务器证书、CSR 和私钥是否属于同一组密钥材料。
匹配证书、CSR 和私钥
当证书部署后出现私钥不匹配、TLS 服务无法启动,或需要确认签发材料来源时,分别导出证书、CSR 和私钥中的公钥,统一转为 DER 后计算 SHA-256。三个摘要一致,说明它们使用同一组密钥材料。
核心方法
不要只比较 modulus:该方法主要适用于 RSA。比较标准化后的公钥摘要可覆盖 OpenSSL 当前支持的 RSA、EC 等密钥类型,也不会输出私钥内容。
高频用法
将文件名改为实际路径后执行。私钥如已加密,第三条命令会交互要求输入口令;自动化环境可使用受保护的 -passin file:<PATH> 或文件描述符传入。
set -euo pipefail
# 修改为实际证书、CSR 和私钥路径。
CERT=server.crt
CSR=server.csr
KEY=server.key
# 统一导出 DER 公钥并计算摘要,避免只适用于 RSA 的 modulus 比较法。
printf 'certificate: '
openssl x509 -in "$CERT" -noout -pubkey |
openssl pkey -pubin -outform DER |
openssl dgst -sha256
printf 'csr: '
openssl req -in "$CSR" -noout -pubkey |
openssl pkey -pubin -outform DER |
openssl dgst -sha256
printf 'private key: '
openssl pkey -in "$KEY" -pubout -outform DER |
openssl dgst -sha256预期输出
certificate: SHA2-256(stdin)= <DIGEST>
csr: SHA2-256(stdin)= <DIGEST>
private key: SHA2-256(stdin)= <DIGEST>实际十六进制摘要会不同,部分版本显示 SHA256 而不是 SHA2-256;只比较等号后的摘要。三行完全相同表示证书、CSR 和私钥匹配,任意一行不同都不能作为同一套材料部署。
风险与边界
摘要一致只证明公钥相同,不证明证书未过期、域名正确、链完整或受客户端信任。部署前仍需检查有效期、SAN、用途和完整证书链。
不要为排障输出私钥正文,也不要把口令写成 -passin pass:明文;明文可能进入 shell 历史或进程参数。安全替代方案是交互输入、权限为 600 的口令文件、文件描述符或密钥管理系统。
排障清单
Could not read certificate或Unable to load certificate:确认文件类型;DER 文件增加-inform DER。Could not read private key、bad decrypt:确认私钥格式和口令,避免反复覆盖原文件。- 摘要不一致:停止部署,寻找正确私钥或重新生成 CSR 并签发证书。
- 证书与私钥一致但服务仍失败:继续检查证书链顺序、文件权限、监听配置和服务日志。
速查结论:三个公钥摘要必须一致;一致不等于证书整体可用。
生成指定长度的 RSA 私钥,并按需设置加密口令。
生成 RSA 私钥
需要为 TLS 证书、CSR 或签名服务准备 RSA 密钥时,优先使用 openssl genpkey。先设置严格文件权限并阻止覆盖已有文件,生成后立即执行完整性检查,避免把空文件、截断文件或错误口令的密钥交给后续流程。
生成未加密私钥
以下示例生成 3072 位 PEM 私钥。未加密私钥适合由服务直接读取,但必须依赖主机权限、受控备份和密钥目录保护。
set -euo pipefail
umask 077
# 私钥路径存在时立即停止,避免破坏正在使用的密钥。
test ! -e server.key || {
echo 'server.key already exists; refusing to overwrite' >&2
exit 1
}
# -quiet 仅隐藏生成进度;真实错误仍写入 stderr 并返回非零状态。
openssl genpkey -quiet \
-algorithm RSA \
-pkeyopt rsa_keygen_bits:3072 \
-out server.key
openssl pkey -in server.key -check -noout预期输出
Key is valid命令成功后生成 server.key;umask 077 可避免新文件向组用户和其他用户开放。实际权限还应使用系统权限检查工具确认。
生成口令加密私钥
下例使用 Bash 文件描述符传入口令,避免口令直接出现在命令行参数和历史记录中。服务启动时必须能够安全取得同一口令,否则会阻塞等待输入或启动失败。
set -euo pipefail
umask 077
# 使用新文件名生成,校验完成后再切换服务配置。
test ! -e server-encrypted.key || {
echo 'server-encrypted.key already exists; refusing to overwrite' >&2
exit 1
}
# read -s 禁止终端回显,口令不会写入 shell 历史。
read -rsp 'Private key passphrase: ' KEY_PASS
printf '\n'
trap 'unset KEY_PASS' EXIT
# 口令通过 fd 3 传入;避免出现在命令行参数和进程列表中。
openssl genpkey -quiet \
-algorithm RSA \
-aes-256-cbc \
-pkeyopt rsa_keygen_bits:3072 \
-pass fd:3 \
-out server-encrypted.key 3<<<"$KEY_PASS"
openssl pkey \
-in server-encrypted.key \
-passin fd:3 \
-check -noout 3<<<"$KEY_PASS"
unset KEY_PASS
trap - EXIT预期输出
Private key passphrase:
Key is valid输入内容不会回显。该示例只输入一次口令,执行前应确认键盘布局和终端状态;生产自动化更适合由密钥管理系统向受控文件描述符提供口令。
常用参数
-pkeyopt rsa_keygen_bits:<BITS>:指定 RSA 位数,常见值为 2048、3072、4096;位数越高,生成和私钥运算成本越大。-aes-256-cbc:加密输出私钥;省略时生成未加密私钥。-out <PATH>:写入目标文件。目标已存在时可能被截断,因此应先检查并拒绝覆盖。-outform PEM|DER:选择文本封装或二进制格式;多数服务配置使用 PEM。
风险与边界
触发覆盖已有私钥时,旧证书会立即失去对应密钥,可能导致服务无法重启且无法恢复历史加密材料。安全替代方案是生成到新文件、校验后原子切换,并保留受控备份。
未加密私钥一旦被读取即可直接使用;加密私钥则把风险转移到口令保管和启动解锁。不要使用过宽权限、聊天工具传输或 -pass pass:明文,优先使用权限隔离、密钥管理系统或 HSM。
排障清单
server.key already exists:核对旧文件用途,改用新文件名,不要直接删除生产密钥。Error writing key:检查目录权限、磁盘空间、只读挂载和安全策略。bad decrypt:口令错误或文件损坏;先用备份验证,不要覆盖原文件。- 算法或加密方式不可用:检查 OpenSSL provider、系统加密策略和构建能力。
速查结论:生成前防覆盖,生成时限权限,生成后用 openssl pkey -check -noout 验证。
选择常用椭圆曲线并生成适用于 TLS 证书的 EC 私钥。
生成 EC 私钥
用于为 TLS 证书或 CSR 创建 EC 私钥。默认选 prime256v1(P-256);只有在确认 CA、负载均衡器、HSM 和客户端均支持时,才改用 secp384r1(P-384)。
基本语法
先用 umask 077 收紧新文件权限,再生成私钥并校验。该示例输出未加密的 PKCS#8 PEM,适合需要无人值守启动的服务。
umask 077
openssl genpkey \
-algorithm EC \
-pkeyopt ec_paramgen_curve:prime256v1 \
-out tls-ec.key
openssl pkey -in tls-ec.key -check -noout预期输出:
Key is validgenpkey 成功时通常保持静默;Key is valid 表示密钥结构可解析且内部一致。私钥文件名可替换,但不要写入共享目录或代码仓库。
常用参数
| 参数 | 作用 |
|---|---|
-algorithm EC |
生成 EC 私钥 |
-pkeyopt ec_paramgen_curve:prime256v1 |
使用 P-256 |
-pkeyopt ec_paramgen_curve:secp384r1 |
使用 P-384 |
-aes-256-cbc |
用口令加密私钥 |
-out <PATH> |
指定输出文件 |
需要人工解锁私钥时,可加入 -aes-256-cbc。服务无法交互输入口令时,不要直接启用加密,应改用严格文件权限、受控只读挂载或密钥管理服务。
高频用法
P-256 适合大多数公开 TLS 服务,兼容性和性能更稳。P-384 提供更高安全余量,但握手成本略高。导出公钥可用 openssl pkey -in tls-ec.key -pubout,公钥可分发,私钥必须保密。
风险与边界
未加密私钥被读取后,攻击者可冒充服务端。安全替代是限制目录和文件属主、仅向服务账号开放读取权限,并在疑似泄露后立即吊销证书和轮换密钥。
不要默认选择不常见曲线或显式曲线参数。触发兼容性问题时,CSR 可能被 CA 拒绝、服务无法加载密钥或 TLS 握手失败;优先回退到命名曲线 P-256 或 P-384。
排障与兼容性
unsupported algorithm:检查 Provider、FIPS 策略和曲线是否被禁用。Could not read key:检查路径、权限、PEM 完整性及是否需要口令。- 服务拒绝
BEGIN PRIVATE KEY:确认其是否支持 PKCS#8,再在副本上转换格式。 - OpenSSL 1.1.1 和 3.x 均可使用
genpkey;为兼容旧脚本,曲线名优先写prime256v1。
使用现有或新建私钥生成提交给证书颁发机构的 CSR。
生成证书请求
用于使用现有私钥或新建私钥生成 PKCS#10 CSR,并提交给 CA。生成前先确定主体信息和全部 DNS 名称;TLS 主机名校验主要依赖 SAN,仅填写 CN 容易得到不可用证书。
前置条件
准备私钥、主域名、备用域名和组织信息。私钥必须由申请方独占保存,CSR 可以交给 CA。示例中的国家、组织和域名均为演示值,执行前必须替换。
使用现有私钥
下面使用已有 EC 私钥生成 CSR,并写入两个 SAN;随后校验自签名并读取关键扩展。
openssl req -new \
-key tls-ec.key \
-out example.com.csr \
-subj "/C=CN/ST=Beijing/L=Beijing/O=Example/OU=Ops/CN=example.com" \
-addext "subjectAltName=DNS:example.com,DNS:www.example.com"
openssl req -in example.com.csr -noout -verify -subject
openssl req -in example.com.csr -noout -text \
| sed -n '/Requested Extensions:/,/Signature Algorithm:/p'预期关键输出:
Certificate request self-signature verify OK
subject=C=CN, ST=Beijing, L=Beijing, O=Example, OU=Ops, CN=example.com
Requested Extensions:
X509v3 Subject Alternative Name:
DNS:example.com, DNS:www.example.com
Signature Algorithm: ecdsa-with-SHA256self-signature verify OK 只表示 CSR 完整,不代表 CA 已批准。重点核对 subject、SAN 和公钥算法;不同 OpenSSL 版本可能仅在空格格式上有差异。
新建私钥并生成 CSR
没有现成私钥时,可一次创建 P-256 私钥和 CSR。-noenc 生成未加密私钥,适合无人值守服务;生成进度写入 keygen.log,失败时脚本会立即停止。
set -euo pipefail
umask 077
openssl req -new \
-newkey ec \
-pkeyopt ec_paramgen_curve:prime256v1 \
-noenc \
-keyout example.net.key \
-out example.net.csr \
-subj "/CN=example.net" \
-addext "subjectAltName=DNS:example.net" \
2>keygen.log
openssl req -in example.net.csr -noout -verify -subject
openssl pkey -in example.net.key -check -noout预期输出:
Certificate request self-signature verify OK
subject=CN=example.net
Key is valid风险与边界
遗漏 SAN 时,即使 CA 签发成功,客户端仍可能报主机名不匹配。安全替代是把全部域名写入 SAN,并在提交前用 openssl req -text -noout 复核。
不要把私钥口令写进命令行、脚本或 CI 日志。历史记录、进程列表或构建日志泄露后,私钥保护会失效;应使用交互输入、受限口令文件、文件描述符或密钥管理服务。
排障与兼容性
怀疑 CSR 与私钥不匹配时,比较两者公钥摘要;两行必须完全一致。
openssl pkey -in tls-ec.key -pubout -outform DER 2>/dev/null \
| openssl dgst -sha256 -r
openssl req -in example.com.csr -pubkey -noout \
| openssl pkey -pubin -outform DER 2>/dev/null \
| openssl dgst -sha256 -r预期输出:
<SHA256> *stdin
<SHA256> *stdin摘要不同表示选错私钥,应停止提交并重新生成 CSR。-addext 适用于 OpenSSL 1.1.1 和 3.x;更旧版本需通过配置文件的 req_extensions 写入 SAN。CA 可能重写扩展,签发后仍要检查最终证书。
在 CSR 或自签名证书中添加 DNS、IP 等主题备用名称。
配置证书 SAN
在生成 CSR 时用 subjectAltName 写入客户端实际访问的 DNS 名称或 IP 地址。现代 TLS 主机名校验主要读取 SAN;仅设置 CN 可能仍会因名称不匹配而失败。
基本语法
-addext "subjectAltName=..." 可直接添加 SAN。名称类型必须写明:域名使用 DNS:,IP 地址使用 IP:,多个值用逗号分隔。CN 可与主域名保持一致,但不能代替 SAN。
高频用法
下面生成 RSA 私钥和 CSR,同时加入两个 DNS 名称及一个 IPv4 地址;随后验证 CSR 自签名并查看扩展。
openssl req -new -newkey rsa:2048 -noenc -keyout api.key -out api.csr -subj "/CN=api.internal.example" -addext "subjectAltName=DNS:api.internal.example,DNS:api,IP:10.0.0.20" >/dev/null 2>&1
openssl req -in api.csr -noout -verify -subject -text预期输出的关键片段如下;缩进和字段顺序可能随版本略有差异。
Certificate request self-signature verify OK
subject=CN=api.internal.example
X509v3 Subject Alternative Name:
DNS:api.internal.example, DNS:api, IP Address:10.0.0.20读取时先确认 verify OK,再核对每个业务入口是否都出现在 Subject Alternative Name。CSR 正确不代表签发结果一定正确,CA 可能忽略或重写请求扩展,因此拿到证书后还要检查最终证书中的 SAN。
常用参数
-subj:非交互设置主题名;其中CN只是主题字段。-addext:添加一个扩展,可重复使用,但同一扩展 OID 不应重复定义。-noenc:生成不加密私钥,适合无人值守测试;生产环境应评估密钥保护方式。-verify -text -noout:校验 CSR 自签名并显示内容,不输出 PEM 正文。
风险与边界
当访问地址未写入 SAN、把 IP 错写成 DNS:,或证书签发端未复制请求扩展时,客户端会报主机名不匹配。安全做法是按真实访问入口列出最小名称集合,并在签发后检查最终证书,而不是只检查 CSR。
-noenc 会把私钥明文写入磁盘;一旦文件被读取,攻击者可冒充服务。自动化场景至少限制文件权限与目录访问,长期生产密钥优先使用受保护的密钥存储或加密私钥。
排障清单
- 浏览器报名称不匹配:核对实际 URL、SNI 与 SAN 是否一致。
- IP 访问失败:确认使用
IP:<地址>,不要写成DNS:<地址>。 unknown option -addext:当前 OpenSSL 过旧,改用配置文件的扩展节生成 CSR。- CSR 有 SAN、证书没有:检查 CA 的扩展复制策略,并重新签发。
速查:域名写 DNS:,地址写 IP:,最终以已签发证书中的 SAN 为准。
为本地开发、测试或内部服务快速生成自签名 TLS 证书。
生成自签名证书
用于本地开发、集成测试或受控内部环境,可一次生成私钥和自签名 TLS 证书。命令应同时设置 SAN、用途和有效期,生成后立即检查主题、签发者、日期及扩展。
基本语法
openssl req -x509 直接输出证书而不是 CSR;-newkey 创建新私钥,-days 设置有效天数,-addext 写入证书扩展。下面以仅用于 TLS 服务端的 RSA 证书为例。
高频用法
openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -noenc -keyout localhost.key -out localhost.crt -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" -addext "basicConstraints=critical,CA:FALSE" -addext "keyUsage=critical,digitalSignature,keyEncipherment" -addext "extendedKeyUsage=serverAuth" >/dev/null 2>&1
chmod 600 localhost.key
openssl x509 -in localhost.crt -noout -subject -issuer -dates -ext subjectAltName
openssl verify -CAfile localhost.crt localhost.crt预期输出如下;有效期时间为动态值。
subject=CN=localhost
issuer=CN=localhost
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
DNS:localhost, IP Address:127.0.0.1
localhost.crt: OKsubject 与 issuer 相同表示自签名;verify ... OK 只说明把该证书显式当作信任锚时验证成功,不代表操作系统、浏览器或其他客户端已经信任它。
常用参数
-x509:生成自签名证书,不输出 CSR。-days 365:设置有效期;测试证书宜按最短实际周期签发。-sha256:使用 SHA-256 参与签名。basicConstraints=CA:FALSE:明确这是终端服务证书,不作为 CA。extendedKeyUsage=serverAuth:限制为 TLS 服务端认证。-noenc:私钥不加密,便于服务自动启动,但必须加强文件权限。
风险与边界
自签名证书默认不受公共客户端信任。将它直接部署到公网会触发证书告警,用户若绕过告警还可能弱化中间人攻击防护。公网服务应使用受信任 CA;内部环境应通过受控信任库分发证书或内部 CA 根证书。
-noenc 生成明文私钥,泄露后可被用于冒充服务。Linux 上至少执行 chmod 600 并限制目录权限;Windows 应使用 ACL 限制读取。需要更强保护时移除 -noenc,或把密钥放入密钥管理系统、HSM 或受保护的服务账户目录。
排障清单
- 客户端仍报不受信任:把证书加入该客户端实际使用的信任库,或改由内部 CA 签发。
- 浏览器报名称错误:确认访问
localhost或127.0.0.1,并检查 SAN。 - 服务启动时报私钥权限或格式错误:确认进程账户可读,且配置分别指向
localhost.crt与localhost.key。 - 旧版本不识别
-noenc:改用兼容参数-nodes;OpenSSL 3.x 中优先使用-noenc。
速查:自签名证书适合测试和受控内部信任,不适合作为公网信任方案。
生成本地根 CA 私钥和根证书,用于内部测试证书签发。
创建本地根 CA
用于在隔离的开发或测试环境中生成一把受口令保护的根 CA 私钥,以及一张可直接作为信任锚使用的自签名根证书。示例限制根 CA 只能直接签发终端证书,避免误签中间 CA。
前置条件
确认已安装 OpenSSL,并在仅当前用户可访问的工作目录中执行。示例使用 RSA 4096 位密钥、SHA-256 和 10 年有效期;组织名与通用名称应替换为本环境的唯一标识。
生成私钥与根证书
以下命令先设置严格文件权限,再生成加密私钥和自签名证书。保护口令会交互输入,不要写入命令行、脚本或版本库。
set -euo pipefail
umask 077
mkdir -p local-ca/private local-ca/certs
# 防止重复执行时覆盖仍在使用的根密钥。
if [ -e local-ca/private/root-ca.key.pem ] || \
[ -e local-ca/certs/root-ca.cert.pem ]; then
echo "目标文件已存在,停止覆盖" >&2
exit 1
fi
openssl genpkey \
-algorithm RSA \
-aes-256-cbc \
-pkeyopt rsa_keygen_bits:4096 \
-out local-ca/private/root-ca.key.pem
chmod 600 local-ca/private/root-ca.key.pem
openssl req -x509 -new -sha256 \
-key local-ca/private/root-ca.key.pem \
-days 3650 \
-subj "/C=US/O=Example Dev/CN=Example Local Root CA" \
-addext "basicConstraints=critical,CA:TRUE,pathlen:0" \
-addext "keyUsage=critical,keyCertSign,cRLSign" \
-addext "subjectKeyIdentifier=hash" \
-out local-ca/certs/root-ca.cert.pem预期输出(密钥生成进度字符可能不同):
<KEY_GENERATION_PROGRESS>
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
Enter pass phrase for local-ca/private/root-ca.key.pem:命令完成后应得到 local-ca/private/root-ca.key.pem 和 local-ca/certs/root-ca.cert.pem。终端不打印证书正文属于正常现象。
验证结果
同时检查主体、签发者、有效期、序列号、CA 扩展和自签名链。根证书的 subject 与 issuer 应相同,CA:TRUE 和 Certificate Sign 必须存在。
openssl x509 \
-in local-ca/certs/root-ca.cert.pem \
-noout -subject -issuer -dates -serial \
-ext basicConstraints,keyUsage
openssl verify \
-CAfile local-ca/certs/root-ca.cert.pem \
local-ca/certs/root-ca.cert.pem预期输出:
subject=C=US, O=Example Dev, CN=Example Local Root CA
issuer=C=US, O=Example Dev, CN=Example Local Root CA
notBefore=<TIME>
notAfter=<TIME>
serial=<SERIAL>
X509v3 Basic Constraints: critical
CA:TRUE, pathlen:0
X509v3 Key Usage: critical
Certificate Sign, CRL Sign
local-ca/certs/root-ca.cert.pem: OK<TIME> 和 <SERIAL> 每次生成都会不同;读取重点是主体与签发者一致、扩展正确且验证结果为 OK。
风险与边界
根私钥一旦泄露,攻击者就能签发被已信任设备接受的任意证书。应将私钥加密、离线备份并限制访问;测试设备安装根证书后会扩大信任范围,测试结束应删除该信任锚。
示例中的 pathlen:0 禁止签发中间 CA,只适合根 CA 直接签发测试终端证书。需要生产式层级时,应让离线根 CA 仅签发中间 CA,再由中间 CA 日常签发,不要直接复用本示例。
排障清单
- 出现
unable to load key:确认私钥路径、PEM 格式和口令正确。 - 出现
Error checking x509 extension section:检查-addext拼写及 OpenSSL 版本。 - 自验证不是
OK:确认读取的是同一张根证书,且文件未被截断或替换。 - 重复执行提示文件已存在:先确认旧 CA 是否仍被信任;不要为省事直接覆盖,应该创建新目录并显式轮换。
兼容性
-addext 适用于 OpenSSL 1.1.1 及更新版本;更老版本需把扩展写入配置文件后用 -config 和 -extensions 加载。chmod 适用于类 Unix 环境,Windows 原生命令行应改用文件 ACL 限制根私钥访问。
使用自建 CA 对 CSR 签名并生成包含正确扩展的终端证书。
使用 CA 签发证书
使用上一条生成的本地根 CA 对服务器 CSR 签名,并由签发方明确写入 CA:FALSE、密钥用途、服务器用途和 SAN。最终得到可验证主机名、可构建到本地根 CA 的终端证书。
前置条件
需要存在 local-ca/private/root-ca.key.pem 和 local-ca/certs/root-ca.cert.pem。示例生成 api.internal.test 的 RSA 私钥与 CSR;DNS 名称和 IP 必须替换为客户端实际访问的地址。
生成 CSR 并签发
扩展文件由 CA 管理者控制,不直接复制申请者提交的任意扩展。这样可以避免 CSR 注入 CA:TRUE、错误用途或未授权 SAN。
set -euo pipefail
umask 077
mkdir -p issued
# 防止覆盖已部署的私钥或证书。
if [ -e issued/server.key.pem ] || [ -e issued/server.cert.pem ]; then
echo "目标文件已存在,停止覆盖" >&2
exit 1
fi
openssl genpkey \
-algorithm RSA \
-pkeyopt rsa_keygen_bits:2048 \
-out issued/server.key.pem
openssl req -new -sha256 \
-key issued/server.key.pem \
-subj "/C=US/O=Example Dev/CN=api.internal.test" \
-out issued/server.csr.pem
cat > issued/server-ext.cnf <<'EOF'
[server_cert]
basicConstraints = critical,CA:FALSE
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = api.internal.test
DNS.2 = api
IP.1 = 127.0.0.1
EOF
openssl x509 -req \
-in issued/server.csr.pem \
-CA local-ca/certs/root-ca.cert.pem \
-CAkey local-ca/private/root-ca.key.pem \
-CAcreateserial \
-days 365 \
-sha256 \
-extfile issued/server-ext.cnf \
-extensions server_cert \
-out issued/server.cert.pem预期输出(密钥生成进度字符可能不同):
<KEY_GENERATION_PROGRESS>
Enter pass phrase for local-ca/private/root-ca.key.pem:
Certificate request self-signature ok
subject=C=US, O=Example Dev, CN=api.internal.test签发成功后会生成 issued/server.cert.pem,并在 CA 证书旁创建或更新序列号文件。CSR 自签名通过只表示请求未损坏,不表示其中的身份已经获准。
验证证书与主机名
先验证证书链,再查看关键扩展并检查目标主机名。只看到链验证 OK 仍不够,客户端访问的 DNS 名称还必须命中 SAN。
openssl verify \
-CAfile local-ca/certs/root-ca.cert.pem \
issued/server.cert.pem
openssl x509 \
-in issued/server.cert.pem \
-noout -subject -issuer -dates \
-ext basicConstraints,keyUsage,extendedKeyUsage,subjectAltName
openssl x509 \
-in issued/server.cert.pem \
-noout -checkhost api.internal.test预期输出:
issued/server.cert.pem: OK
subject=C=US, O=Example Dev, CN=api.internal.test
issuer=C=US, O=Example Dev, CN=Example Local Root CA
notBefore=<TIME>
notAfter=<TIME>
X509v3 Basic Constraints: critical
CA:FALSE
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Server Authentication
X509v3 Subject Alternative Name:
DNS:api.internal.test, DNS:api, IP Address:127.0.0.1
Hostname api.internal.test does match certificate<TIME> 为实际签发时间;读取重点是签发者为本地根 CA、CA:FALSE、存在 serverAuth,且访问名称位于 SAN 中。
关键参数
-CA与-CAkey:指定签发证书和匹配的私钥;两者不匹配会导致签名失败。-CAcreateserial:首次签发时创建序列号文件,后续签发递增使用;共享目录中应避免并发写入。-extfile与-extensions:从受控配置节写入终端证书扩展。-days 365:设置终端证书有效期;内部证书也应尽量短期并配合自动轮换。
风险与边界
直接复制 CSR 扩展可能让申请者请求未授权域名,甚至得到 CA:TRUE 证书。安全替代方案是由签发方审核身份,并用受控扩展文件生成 SAN、用途和约束;签发前还应人工核对 CSR 主体与申请单。
openssl x509 -req 是轻量签发方式,不维护完整的签发数据库、撤销状态和审计记录。多人共享或生产环境应使用 openssl ca 的数据库流程或专用 CA 服务;序列号文件需串行更新,避免并发签发造成冲突。
示例服务器私钥未加密,便于服务无人值守启动,但泄露后可被冒用。应限制为服务账户可读,并优先使用密钥管理系统、硬件密钥或受控 Secret 挂载。
排障清单
certificate signature failure或密钥不匹配:比较 CA 证书公钥与 CA 私钥导出的公钥。- 链验证为
unable to get local issuer certificate:检查-CAfile是否指向实际签发者,且证书文件完整。 - 主机名检查失败:把客户端真实访问名称加入 SAN 后重新签发;只修改 CN 通常不能解决。
- 浏览器仍不信任:确认根证书已安装到正确的系统或浏览器信任库,并重启相关进程。
- ECDSA 终端密钥:通常删除
keyEncipherment,保留digitalSignature,再按实际 TLS 栈验证兼容性。