如何使用本指南：
错误按签名方法或工具分组。“接口”列会显示客户看到消息的位置——命令行 (CLI) 窗口、应用程序/图形用户界面 (GUI) 弹出窗口、日志文件、CI/CD 管道控制台或常规 Windows 系统消息——以便您快速确认所查看的条目是否正确。“错误/症状”列中的引号文本是 SSL.com 文档中提供的原文消息。对于需要更改 SSL.com 后端的问题，“解决方案”列会直接说明——在这种情况下，客户下一步需要联系 SSL.com 支持团队，他们会根据需要将问题升级到工程团队。
基于令牌的代码签名 — 通用 /SignTool
适用于任何使用 Microsoft SignTool 的硬件令牌工作流程（YubiKey 或 SafeNet）。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
“‘Signtool’未被识别为内部或外部命令、可运行程序或批处理文件” |
CLI |
命令输入时只使用了单词“signtool”，而不是 signtool.exe 的完整路径。 |
将命令中的“signtool”替换为 signtool.exe 的完整路径（例如 C:\Program Files (x86)\Windows Kits\10\bin\ \x64\signtool.exe）。 |
|
|
“时间戳证书不符合最小公钥长度要求” |
CLI |
SSL.com 的默认时间戳服务器颁发基于 ECDSA 的时间戳，而签名软件/供应商不接受 ECDSA 时间戳密钥。 |
请您的软件供应商允许使用 ECDSA 时间戳密钥，或者使用传统的 RSA 时间戳端点。 http://ts.ssl.com/legacy. |
|
|
“Windows 无法验证此驱动程序软件的发布者” |
Windows系统 |
该软件或驱动程序分发时未应用有效的代码签名证书，因此 Windows 无法确认发布者的身份。 |
在分发软件之前，请使用有效的 OV 或 EV 代码签名证书对软件进行签名。 |
|
|
安装OV/EV证书后出现配置问题 |
Windows系统 |
OV 和 EV 代码签名证书是手动安装到计算机的证书存储区中的，而不是从硬件令牌/HSM 中使用。 |
不要手动安装 OV/EV 代码签名证书；直接从 YubiKey FIPS 令牌、SafeNet 令牌或通过 eSigner 云签名使用它们。 |
YubiKey FIPS令牌错误
适用于在 YubiKey FIPS 140-2 硬件令牌上颁发的代码签名证书。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
不知道/找不到 YubiKey PIN 码或 PUK 码 |
无 |
PIN/PUK 从未从账户门户网站检索到，或者令牌已重新发放。 |
登录 SSL.com 客户门户，打开证书订单，然后使用“物理令牌/YubiKey FIPS 140-2”下的“激活”链接检索 PIN 码和 PUK 码。 |
|
|
计算机未检测到 YubiKey / SignTool 未找到证书 |
Windows系统 |
Yubico Authenticator 或所需的微型驱动程序未安装，因此操作系统无法识别令牌上的证书。 |
安装 Yubico Authenticator 和 YubiKey 迷你驱动程序；在签名之前，确认令牌的序列号出现在 Yubico Authenticator 中。 |
Thales SafeNet（金雅拓）令牌错误
适用于在 Thales SafeNet/Gemalto USB 令牌上颁发的代码签名证书，与 SafeNet 身份验证客户端 (SAC) 一起使用。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
“密码错误” |
应用程序/图形用户界面 |
使用 SignTool 登录时输入了错误的令牌密码/PIN 码。 |
重新输入正确的令牌密码；如果忘记了，请从您的 SSL.com 帐户订单详情中找回或使用您的 PUK 重置密码。 |
|
|
“由于登录失败次数过多，令牌已被锁定” |
应用程序/图形用户界面 |
密码/PIN码错误尝试次数已超过最大允许次数。 |
打开 SafeNet 身份验证客户端，使用高级视图，选择设置令牌密码，输入您的 PUK 作为管理员密码，然后设置并确认新的令牌密码。 |
|
|
“‘Signtool’未被识别为内部或外部命令、可运行程序或批处理文件” |
CLI |
与通用令牌部分相同的 SignTool 路径问题——输入的命令缺少完整的可执行文件路径。 |
将命令中的“signtool”替换为 signtool.exe 的完整路径。 |
|
|
SafeNet 身份验证客户端安装后无法检测到令牌 |
Windows系统 |
SAC 已安装，但计算机未重新启动，因此驱动程序/服务更改尚未生效。 |
安装 SafeNet 身份验证客户端后重启计算机；然后应该可以识别令牌。 |
电子签名工具 CodeSignTool（CLI）
适用于 SSL.com 的 CodeSignTool Java CLI 实用程序。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
找不到电子签名者凭证 ID |
应用程序/图形用户界面 |
账户门户中未找到凭证 ID（CodeSignTool 和 CSC API 需要此 ID）。 |
在 SSL.com 帐户中，打开证书订单，滚动到签名凭证部分，查看电子签名者凭证 ID、证书序列号和电子签名者标签。 |
|
|
“错误：无效的一次性密码”（手动签名） |
应用程序/图形用户界面 |
扫描到身份验证器应用程序中的二维码与使用的用户名/密码/凭证 ID 不匹配，或者一次性密码已过期。 |
请确认您扫描的是正确的账号二维码（不是队友共享的二维码），重新生成新的验证码，并立即重新输入，因为验证码过期很快。 |
|
|
“错误：无效的 OTP”（自动/TOTP 签名） |
CLI |
TOTP 密钥属于与指定的用户名、密码和凭证 ID 不同的帐户/证书；密钥本身无效；或者系统时间不同步。 |
验证 TOTP 密钥与正在使用的帐户和凭据 ID 是否匹配，确认密钥已正确复制，并将系统时钟与可靠的时间服务器同步（TOTP 依赖于与签名服务器的紧密时间对齐）。 |
|
|
“‘C:\Users\Admin\Dropbox\My’ 不是内部或外部命令、可运行程序或批处理文件。” / “系统找不到指定的路径。” |
CLI |
由于传递给 CodeSignTool 的文件路径包含空格且未加引号，因此 shell 将其解析为多个单独的参数。 |
将输入文件路径和输出目录路径用引号括起来，并将参数直接键入或复制粘贴到命令行中，而不是通过其他文本编辑器。 |
|
|
“此时出现\Documents\sample 是意料之外的。” |
CLI |
未加引号的路径解析失败问题依然存在——shell 在空格处断开路径，并将剩余部分视为一个多余的标记。 |
将完整的文件路径用引号括起来，以便 shell 将其视为单个参数。 |
|
|
“警告：不支持 sun.reflect.Reflection.getCallerClass。这会影响性能。” |
CLI |
由运行 CodeSignTool 所用的 JVM 版本触发的良性 Java 运行时警告。 |
这是一个性能警告，并非签名失败——可以忽略；请验证实际输出，确认是否显示“代码签名成功”。 |
|
|
当密码包含特殊字符时，签名命令会静默失败或拒绝凭据。 |
CLI |
-password 参数包含特殊字符（例如 !、@、^），但没有用引号括起来，因此 shell 错误地解析了该值。 |
当密码包含特殊字符时，请用引号将其括起来，例如 -password=”P!@^^ssword12″。 |
|
|
缺少 credential_id 参数（多证书帐户） |
CLI |
该帐户拥有多个 eSigner 代码签名证书，因此 CodeSignTool 无法默认使用单个凭据。 |
显式传递 -credential_id=在命令中；使用 get_credential_ids 列出帐户上的所有凭据 ID。 |
|
|
{“error_description”:”code: QuotaExceededError – message: Quota exceeded”,”error”:”server_error”} |
CLI / CI-CD |
与签名凭证关联的恶意软件扫描插件已达到内部使用限制，即使帐户仪表板显示仍有签名次数。 |
这并非您这边可以自行解决的问题。请联系 SSL.com 支持团队，以便他们调整您账户的恶意软件扫描限制；修复完成后请等待 1-2 小时再重试。 |
SSL.com 支持（内部/账户特定） |
|
“com.ssl.code.signing.tool.exception.CscApiException: server_error 500 at com.ssl.code.signing.tool.csc.CscApi.sendOtp(…)” |
日志文件 |
登录成功，但发送短信一次性密码的请求失败，原因是 SSL.com 端的签名凭证存在配置问题。 |
请联系 SSL.com 支持部门重置凭证的 OTP 配置。 |
SSL.com 支持（内部/账户特定） |
|
即使签名实际上失败了，CodeSignTool 仍报告成功（退出代码 0）。 |
CI/CD 流水线 |
旧版本的 CodeSignTool 存在一个错误，导致它无论实际结果如何都会报告成功，使得管道故障难以检测。 |
更新到最新版本的 CodeSignTool，该版本可以正确报告故障。 |
|
|
连续签署多个文件时达到身份验证速率限制。 |
CI/CD 流水线 |
现在，每个文件都需要重新登录/身份验证，而不是重复使用一个会话令牌进行多次签名。 |
在签名会话期间重复使用同一个身份验证令牌，而不是在每次传输文件前都进行身份验证。如果大流量/企业客户仍然达到限额，应联系 SSL.com 支持团队，讨论其帐户的限额问题。 |
|
|
“错误：无效的一次性密码”（手动签名） |
应用程序/图形用户界面 |
扫描到身份验证器应用程序中的二维码与使用的用户名/密码/凭证 ID 不匹配，或者一次性密码已过期。 |
请确认您扫描的是正确的账号二维码（不是队友共享的二维码），重新生成新的验证码，并立即重新输入，因为验证码过期很快。 |
|
|
使用 Visual Studio 构建的 MSI 安装程序签名无效 |
应用程序/图形用户界面 |
eSigner 与 Visual Studio 打包工具生成的 MSI 安装程序之间存在已知的兼容性问题。 |
使用 WiX 工具集而不是 Visual Studio 来构建 MSI 安装程序，这是一种变通方法。 |
eSignerCKA（云密钥适配器）
适用于 eSigner CKA，它将 eSigner 证书加载到 Windows 证书存储中，以便与 SignTool.exe 或 Certutil.exe 一起使用，包括 CI/CD 管道。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
“时间戳证书不符合最小公钥长度要求” |
CLI |
使用 eSigner CKA 和 SignTool 时遇到的 ECDSA 时间戳兼容性问题与基于令牌的签名相同。 |
请联系您的软件供应商以允许使用 ECDSA 时间戳密钥，或使用旧版端点。 http://ts.ssl.com/legacy 用于 RSA 时间戳。 |
|
|
“此文件格式无法签名，因为它无法识别。”（对 .app 文件进行签名） |
CLI |
在 Dynamics 365 Business Central 应用程序本身安装之前，尝试使用 eSigner CKA 对 Microsoft Dynamics 365 Business Central .app 文件进行签名，因此 SignTool 无法解析文件格式。 |
首先安装 Microsoft Dynamics 365 Business Central（服务器安装选项），然后使用 SignTool 通过 eSigner CKA 对生成的 .app 文件进行签名。 |
|
|
VBA宏签名静默失败/签名被拒绝 |
应用程序/图形用户界面 |
VBA 向 eSigner 发送代码的 SHA1 哈希值，但 eSigner 要求 SHA256 或更高版本。 |
在 HKCU\SOFTWARE\Microsoft\VBA\Security 下添加 DWORD 注册表值 V1HashEnhanced，并根据 Microsoft 的指导将其设置为 2 (SHA256)、3 (SHA384) 或 4 (SHA512)，然后重新签名。 |
|
|
证书无法显示/无法通过 SignTool 使用。 |
应用程序/图形用户界面 |
eSigner CKA 未安装，或者签名模式（手动/自动）和证书类型（生产/测试）未配置。 |
安装 eSigner CKA，并在尝试签名之前显式配置签名模式和证书类型；先确认在 eSigner 上注册。 |
|
|
“签名凭据未配置。请确保在签名前已颁发证书。” + “无法检索证书 ID。错误：对象引用未设置为对象的实例。” / (CLI) “未处理的异常：System.NullReferenceException：对象引用未设置为对象的实例。位于 eSignerCKATool.eSignerCKATool.Config(CommandLineInfo commandLineInfo)” |
应用程序/图形用户界面 + 命令行界面 |
可能是账户中残留的/无效的签名凭证（例如旧的、未使用的凭证），而此版本的 eSigner CKA 无法正确跳过这些凭证；也可能是账户中显示为“已颁发”但尚未完成与云签名后端链接的证书。 |
首先，尝试删除本地配置文件夹 %APPDATA%\eSignerCKA 和 %LOCALAPPDATA%\eSignerCKA，然后重新运行配置命令，确保使用 -mode product 参数和您的帐户用户名（而非您的电子邮件地址）。如果问题仍然存在，请联系 SSL.com 支持团队——移除无效凭据或完成证书设置需要后端操作。在此期间，您可以使用 CodeSignTool 作为替代方案。 |
SSL.com支持 |
|
eSigner CKA 登录后立即崩溃（Windows 事件查看器）：“.NET 运行时事件 1026 — DisplayData 期间 eSignerCSP.UI.Utils.CspWrapper.C_UnloadAllCertificate 中出现 System.AccessViolationException”；重启/重新安装后问题仍然存在 |
日志文件/应用程序崩溃 |
旧版本 eSigner CKA 的一个已知缺陷会导致其在启动时崩溃，即使证书存储为空；这有时与残留凭证问题有关。 |
这需要更新 eSigner CKA 版本。请联系 SSL.com 支持团队，以便将此问题升级至工程部门。在此期间，请使用 CodeSignTool 进行签名。 |
SSL.com 支持（内部/账户特定） |
|
“[错误] 找不到文件‘C:\Program Files (x86)\SSL Corp eSigner CKA\eSignerKSP64.dll’。” / “[错误] 找不到文件‘C:\Program Files (x86)\SSL Corp eSigner CKA\eSignerKSP32.dll’。” |
日志文件 |
某些 eSigner CKA 安装程序版本在内部组件重命名后缺少这些支持文件——这不是您的计算机上的任何问题导致的。 |
请完整重新安装 eSigner CKA：删除 Program Files 和 AppData 文件夹，重启计算机，然后重新安装。即使出现此消息，签名功能可能仍然有效。如果之后文件仍然缺失，请联系 SSL.com 支持团队获取修复后的安装程序。 |
SSL.com支持 |
|
仅在自动/自动签名模式下显示“无效 OTP”（手动模式下有效） |
应用程序/图形用户界面 |
通常情况下，问题出在错误的 TOTP 密钥、与当前使用的凭据 ID 不匹配的 TOTP 密钥，或者计算机时钟不同步。有时，也可能是由于之前安装遗留的配置文件与当前配置文件冲突造成的。 |
请确认您使用的是正确的 TOTP 密钥，并且您的系统时钟准确无误。如果问题仍然存在，请删除 %APPDATA%\eSignerCKA 和 %LOCALAPPDATA%\eSignerCKA 文件夹，然后重新安装 eSigner CKA。 |
SSL.com支持 |
|
“SignerSign() 失败。(-2146893821/0x80090003 NTE_BAD_KEY)” / “signtool.exe：SignTool 错误：发生意外的内部错误。” — 在进行大量批量签名时（通常在签名约 100 个文件后） |
CLI / CI-CD |
在进行大量批量签名时，帐户上的恶意软件扫描功能达到内部使用限制，导致签名会话中断。 |
请联系 SSL.com 支持团队，调整账户高登录量情况下的恶意软件扫描限制。作为一种临时解决方案，您可以分批登录，并在每批登录之间刷新凭据（使用 `config -r` 命令）。 |
SSL.com 支持（内部/账户特定） |
|
每次电子签名操作（签名、PIN码重置、二维码重置）时，“密钥状态”均已禁用。 |
应用程序/图形用户界面/命令行界面 |
SSL.com 后端已禁用签名凭证。 |
请联系 SSL.com 支持——只有 SSL.com 才能重新启用已禁用的签名凭证；客户方面无法解决此问题。 |
SSL.com 支持（内部/账户特定） |
电子签名恶意软件扫描（签名前）
适用于 SSL.com 的可选预签名恶意软件扫描功能，该功能在 eSigner 工具包（Express、CodeSignTool、API、CKA）中均可用。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
“错误：需要签名的哈希值是恶意软件对象哈希值” |
CLI |
恶意软件扫描检测到提交的文件存在匹配项，并按预期自动停止了签名过程。 |
这是检测到恶意软件时的预期行为——在重新提交之前检查并修复标记的文件；除非扫描功能原本就没打算开启，否则这不是配置错误。 |
|
|
恶意软件扫描不适用于签名请求 |
应用程序/图形用户界面 |
帐户的“签名凭据”部分中，“启用恶意软件拦截器”单选按钮未与“启用签名凭据”单选按钮一起激活。 |
在 SSL.com 证书订购页面的“签名凭据”下，确保在签名之前同时选中“启用签名凭据”和“启用恶意软件阻止程序”。 |
CI/CD 流水线集成（GitHub Actions、GitLab CI、Jenkins、Travis、Azure DevOps）
适用于嵌入 CI/CD 管道脚本中的自动化 eSigner CodeSignTool 或 eSigner CKA 签名步骤。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
签名步骤在流程中途失败，原因不明。 |
CI/CD 流水线 |
在签名步骤附近，管道脚本（YAML/Groovy 等）中引入了拼写错误或错误的换行符。 |
仔细检查管道脚本，查看是否有拼写错误和多余的换行符；在进一步排查问题之前，请将其与 SSL.com 发布的示例管道（例如 github.com/SSLcom/codesigner-github-sample）进行比较。 |
|
|
配置参数拼写错误，例如使用了 -topt 而不是 -totp。 |
CI/CD 流水线 |
管道配置文件中存在拼写错误的参数名称。 |
在管道脚本中，将参数名称更正为 -totp（而不是 -topt）。 |
|
|
在流水线运行器中使用 x64 构建时出现 SignTool 错误 |
CI/CD 流水线 |
当与 eSigner CKA 一起使用时，管道运行器的环境与 signtool.exe 的 x64 版本不兼容。 |
切换管道步骤，改为调用 x86 版本的 signtool.exe。 |
|
|
“提供的授权无效、已过期、已被撤销、与授权请求中使用的重定向 URI 不匹配，或者已颁发给其他客户端。” / “错误：invalid_grant” |
CI/CD 流水线 |
可能的原因有以下几种：账户密码已重置，但流水线仍保存着旧密码；流水线使用的是电子邮件地址而不是账户用户名；密码中的特殊字符（例如 $、!、反引号）在脚本中未正确引用；相同的凭据在本地有效，但在 CI/CD 提供商的服务器上无效；或者该账户未启用基于密码的 API 登录。 |
请使用账户用户名（而非电子邮件地址）进行身份验证。如果密码最近重置过，请更新流水线中保存的凭据。在流水线脚本中，请将凭据变量用引号括起来，尤其是在密码包含特殊字符的情况下。首先使用 CodeSignTool 的 get_credential_ids 命令在本地测试凭据。如果仍然失败（特别是如果仅在 CI/CD 提供商处出现此问题，而本地测试没有问题），请联系 SSL.com 支持，因为这可能需要在后端启用 API 登录或刷新账户授权。 |
SSL.com支持 |
|
“无法检索凭据 ID。错误：解析值时遇到意外字符：<。路径”，第 0 行，第 0 个字符。” |
CI/CD 流水线 |
SSL.com 服务器出现短暂故障，导致返回的是一个网页而不是预期的数据。这种情况通常是暂时的。 |
请稍等片刻，然后重新运行命令。如果问题反复出现，请联系 SSL.com 技术支持。 |
SSL.com支持 |
证书生命周期及常见错误
无论采用何种签名方法，都可能出现与证书有效性、信任链和密钥处理相关的错误。
|
错误/症状 |
接口 |
可能的原因 |
分辨率 |
来源 |
|
证书已过期或签名后不再受信任 |
无 |
代码签名证书已过期，而之前签名的代码没有时间戳，因此其签名有效性现在与证书的过期时间挂钩。 |
获取新证书并重新签署受影响的代码；始终在签名时添加时间戳，以便有效期超过证书到期日。 |
|
|
证书的有效期出乎意料地短 |
无 |
CA/浏览器论坛的要求现在将新颁发的公开信任代码签名证书的有效期限制为 458 天，自 2026 年 2 月 27 日起生效。 |
这是行业普遍要求，并非错误——在同一购买期限内，证书可能需要更频繁地重新颁发，而无需额外费用。 |
快速参考：我应该从哪本指南开始？
- 使用物理 YubiKey 或 SafeNet 令牌进行签名：首先 使用您的代码签名证书
- 使用 eSigner CodeSignTool 进行签名：从以下开始 eSigner CodeSignTool命令指南
- 使用电子签名云密钥适配器 (CKA) 进行签名：首先 如何使用 eSigner CKA（云密钥适配器）通过 SignTool.exe 或 Certutil.exe 自动执行 EV 代码签名
- 使用 eSigner CKA 在 CI/CD 中实现自动签名：从以下方面开始 如何将电子签名器 CKA 与 CI/CD 工具集成
- 使用 eSigner CodeSignTool 在 CI/CD 中自动签名
