KeyLocker是一款功能强大的代码签名工具，它允许您将代码签名证书存储在云端，并安全地远程签名其哈希值。然而，初始设置存在一些陷阱，本文将帮助您解决这些陷阱。 

 审查变量 

KeyLocker 在您的系统上运行的关键一步是正确设置变量。这些变量不仅决定了签名工具的路径，还主要承载身份验证信息。您可以为单个会话设置它们，也可以永久设置它们。 您可以通过多种方式在系统中设置变量。除了单独的文件和变量之外，您还可以将它们存储在 Windows 凭据管理器中。如果您想使用 GUI 进行签名，则可以在“单击签名”实用程序中设置它们，该实用程序位于您的 KeyLocker 帐户中（但是，这些变量在系统级别不起作用）。 您可以使用命令行轻松地在 Windows 中设置变量。运行 cmd 并输入：

setx VARIABLE=value

注意 - setx 适用于用户变量，不适用于系统变量。 

为了KeyLocker正常运行，需要设置客户端身份验证 + 签名工具和 DigiCert 库的位置变量。

身份验证设置

• SM_CLIENT_CERT_FILE -从 DigiCert ONE 指南中下载的扩展名为 p12 的身份验证证书的位置路径

• SM_HOST - DigiCert ONE 主机地址，即 https://clientauth.one.digicert.com 

这两个变量并非机密变量，因为证书受密码保护。您可以安全地在系统中设置它们。接下来的两个变量是机密变量，如果多个用户可以访问系统，我建议不要在系统中设置它们。最好将它们存储在 Windows 密码管理器中。有关在 Windows 中设置变量的更多信息，请参阅文章“ Windows 凭据设置”。 

• SM_API_KEY -您在 DigiCert ONE 界面中生成的API 密钥

• SM_CLIENT_CERT_PASSWORD - P12 中的身份验证证书的密码，该密码已在 DC1 指南中显示给您一次
  

设置签名工具的路径
使用以下命令向 PATH 变量添加值： 

setx PATH "path;%PATH%"

此命令会将新值添加到 PATH 变量的现有用户值中，并永久保存。为了确保 KeyLocker 正常运行，您至少需要设置以下两项：

• Windows SDK 和 signtool的路径

• DigiCert Keylocker 工具路径

找到 Windows SDK 的有效路径（该路径使用您已安装的版本号）。您还需要 DigiCert Keylocker Tools，该工具已从 DigiCert ONE 下载并安装；您可以在 C:\Program Files\DigiCert\DigiCert Keylocker Tools 中找到它。 

我们将通过 CMD 同时添加这两个变量，否则一个变量将覆盖另一个变量：

setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"

您也可以通过 Windows GUI 设置系统变量；通过 CMD 速度更快，但多次输入会导致值相互覆盖。您也可以使用 PowerShell。 

 如何在 Windows 中手动编辑PATH 变量 

如果您想确保值被保留，您可以手动编辑 PATH： 

1. 打开控制面板→系统→高级系统设置。 

2. 单击环境变量。 

3. 查找PATH（在系统变量或用户变量中）。 

4. 单击“编辑”，添加单独的路径，然后保存。 

 如何使用PowerShell添加PATH变量

如果您想使用PowerShell将路径永久添加到PATH变量，请按照以下步骤操作： 

1. 以管理员身份打开PowerShell（右键单击开始→WindowsPowerShell（管理员））。 

2. 首先，找出“PATH”变量的当前值：

[System.Environment]::GetEnvironmentVariable("Path", "User")

然后向现有值添加新路径： 

$path = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")

如果需要添加另一条路径，请重复该过程：

$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")

执行命令后，重新启动命令行或计算机以使更改生效。 

注意：如果要更改系统“PATH”变量（适用于所有用户），请在命令中将“User”替换为“Machine”。 

 注意：通过CMD设置变量后，必须重新启动命令行，否则更改不会生效！ 

在CMD中检查变量值：

echo %VARIABLE%

例如“echo%PATH%”。然后CMD将显示其值。 

 检查配置是否正确 

KeyLocker工具包含smctl实用程序，它不仅可用于签名，还可用于基本诊断。以下命令检查工作站上的所有设置是否正确，以及smctl是否能够连接到DigiCert云：

smctl healthcheck

输出将确认您是否已连接到KeyLocker（身份验证已成功），以及smctl是否检测到签名工具（例如signtool）的存在。例如： 

smctl healthcheck
--------- Account Settings ---------
Teams: Disabled
Threat detection: Enabled
        Static Binary Analysis: Enabled
        Software Composition Analysis: Disabled

--------- User credentials ---------
Status: Connected

Username: XXXX-keylocker
Accounts: XXXX-1699076
Authentication: 2FA
Environment: Prod
Credentials:
        Host: https://clientauth.one.digicert.com
        API key: 010897bf735bbc57d48270cd3d_50dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxe4 (Pulled from environment variable)
        Client certificate file path: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
        Client certificate password: ytf_xxxxxx0F (Pulled from environment variable)
API keys:
        Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
       
Client certificates:
        Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
      
Privileges:
        Can sign: Yes
        Can approve offline release: No
        Can revoke certificate: Yes
        Can scan: No

Permissions:
Account Manager:
        MANAGE_AM_PERMISSION
        MANAGE_AM_ROLE
        MANAGE_AM_ACCOUNT_USER
        VIEW_AM_ROLE
        VIEW_AM_ACCOUNT
        VIEW_AM_USER
        VIEW_AM_ORGANIZATION
        VIEW_AM_AUDIT_LOG

Keypairs:
        SIGN_SM_HASH
        VIEW_SM_KEYPAIR
        MANAGE_SM_KEYPAIR

Certificates:
        VIEW_SM_CERTIFICATE
        REVOKE_SM_CERTIFICATE

Other permissions:
        VIEW_SM_LICENSE
        MANAGE_SM_CC_API_KEY

--------- Signing tools ---------
Signtool 32 bit:
        Mapped: No
Signtool:
        Mapped: Yes
        Path: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe
Mage:
        Mapped: No
Nuget:
        Mapped: No
Jarsigner:
        Mapped: No
Apksigner:
        Mapped: No

如果存在身份验证问题，请检查您是否已在DigiCertONE界面中设置了KeyLocker指南中获取的正确值。如有疑问，您可以重置指南并创建新的凭据。

您还可能会遇到smctl无法检测到signtool或其他签名工具的情况。这意味着您需要将它们的位置添加到用户或系统的PATH变量中。请参阅上文关于变量的部分。 

 MMC和证书存在检查 

如果您使用的是Windows系统，请检查证书管理器，使用命令certmgr.msc启动它。如果与KeyLocker的同步成功完成，您将在证书存储区中看到一个带有私钥标志的证书。但这并不意味着该证书和私钥确实存在——带有私钥的证书仍然存储在云端。 

 如果证书不存在，请运行同步。

smctl windows certsync

同步成功后，您将看到确认信息： 

 同步别名证书：

key_1236506290，ID：ac793b6d-cac4-4be4-b145-003d4d1d63db 和 SHA1 指纹：54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72c

签名问题 

如果您在签名方面遇到问题，请尝试从最简单到最复杂的方法。最简单的方法是使用DigiCert实用程序smctl进行签名，该实用程序也可以作为signtool或jarsigner等签名工具的扩展程序。这是冲突最少的方法，并且不需要任何参数。为了进行故障排除，请勿使用时间戳或任何其他选项。 

 使用smctl简单签名：

smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exe

您可以使用“keypair-alias”或“fingerprint”参数引用证书，您可以找到有关证书的此信息，例如，使用命令smctlwindowscertsync。 

 签名后，可以验证签名：

smctl sign verify --input

有关签名帮助，请参阅文章使用SMCTL签署二进制文件。

 使用smctl成功签名后，您可以使用其他工具（例如signtool）进行签名。它应该也能正常工作。请保留证书的自动选择，并逐步添加更多参数。 

 一旦它按照您的期望成功运行，您可以尝试签名，例如使用VisualStudio或其他开发环境。 

 在哪里可以找到日志 如果以上所有方法均失败，并且签名仍然无法生效，我建议您检查smctl和其他DigiCert工具的日志。如果您在与我们的支持团队解决问题时使用日志，无疑可以加快问题的解决速度。 您可以在smctl.log文件中找到smctl实用程序日志，该文件位于给定用户配置文件中的/.signingmanager/logs文件夹中。尝试在CMD中输入

echo %USERPROFILE%/.signingmanager/logs

您将看到完整的文件夹位置。 

 其他资源和信息 

KeyLocker文档中的常见错误-故障排除指南。 

DigiCert网站上的KeyLocker文档