你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

设置签名集成以使用受信任签名

Trusted Signing 目前支持以下签名集成:

  • SignTool
  • GitHub Actions
  • Azure DevOps 任务
  • 验证码 PowerShell
  • Azure PowerShell(适用于企业 CI 策略的应用控制)
  • 受信任签名 SDK

我们不断努力支持更多的签名集成。 当有更多集成可用时,我们将更新受支持的集成列表。

本文介绍了如何设置每个受支持的受信任签名签名集成。

设置 SignTool 以使用受信任签名

本部分介绍如何设置 SignTool 以与 Trusted Signing 配合使用。

先决条件

若要完成本文中的步骤,需要:

  • 受信任签名帐户、标识验证和证书配置文件。
  • “受信任签名证书配置文件签名者”角色的单个分配或组分配。
  • Windows 10 版本 1809/2018 年 10 月更新或更高版本、Windows 11(所有版本)或 Windows Server 2016 或更高版本

受信任签名客户端工具安装程序

SignTool.exe 的受信任签名客户端工具是一个库插件,需要使用以下组件:

  1. Windows SDK SignTool.exe(最低版本:10.0.2261.755)
  2. .NET 8 运行时
  3. Microsoft Visual C++ 可再发行组件
  4. 受信任签名客户端 Dlib

为了简化此安装,可以使用可与 Setup.exe 一起下载的 MSI 安装程序包。

从 Windows 包管理器安装

受信任签名客户端工具安装程序在 Windows 包管理器 (WinGet) 上可用。

注意

winget 在 Windows 11 和新式版本的 Windows 10 中默认提供。 但是,它可能不会在较旧版本的 Windows 中安装。 有关安装说明,请参阅 winget 文档

winget install -e --id Microsoft.Azure.TrustedSigningClientTools

-e 选项的作用是确保安装官方受信任签名客户端工具包。 此命令默认安装最新版本。 若要指定版本,请将带有所需版本的 -v <version> 添加到命令中。

从 PowerShell 安装

要使用 PowerShell 安装受信任签名客户端工具,请以管理员身份启动 PowerShell 并运行以下命令:

$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri "https://download.microsoft.com/download/6d9cb638-4d5f-438d-9f21-23f0f4405944/TrustedSigningClientTools.msi" -OutFile .\TrustedSigningClientTools.msi; Start-Process msiexec.exe -Wait -ArgumentList '/I TrustedSigningClientTools.msi /quiet'; Remove-Item .\TrustedSigningClientTools.msi

手动安装步骤的摘要

  1. 下载并安装 SignTool。
  2. 下载并安装 .NET 8 运行时。
  3. 下载并安装受信任签名 dlib 包
  4. 创建 JSON 文件以提供受信任签名帐户和证书配置文件
  5. 若要对文件进行签名,请调用 SignTool

下载并安装 SignTool

受信任签名需要使用 SignTool 在 Windows 上对文件进行签名,特别是 Windows 10 SDK 10.0.2261.755 或更高版本中的 SignTool.exe 版本。 你可以通过 Visual Studio 安装程序安装完整的 Windows 10 SDK,也可以下载并单独安装该工具

下载并安装 SignTool:

  1. Microsoft.Windows.SDK.BuildTools 下载最新版本的 SignTool 和 Windows 生成工具 NuGet。

  2. 安装 Windows SDK 中的 SignTool(最低版本:10.0.2261.755,20348 Windows SDK 版本不受 dlib 支持)。

另一个选项是通过 PowerShell 使用最新的 nuget.exe 文件下载并提取最新的 Windows SDK 生成工具 NuGet 包:

  1. 通过运行以下下载命令下载 nuget.exe:

    Invoke-WebRequest -Uri https://dist.nuget.org/win-x86-commandline/latest/nuget.exe -OutFile .\nuget.exe  
    
  2. 通过运行以下安装命令下载并提取 Windows SDK 生成工具 NuGet 包:

    .\nuget.exe install Microsoft.Windows.SDK.BuildTools -Version 10.0.22621.3233 -x
    

下载并安装 .NET 8.0 运行时

SignTool 用来与受信任签名进行交互的组件需要安装 .NET 8.0 运行时。你只需要核心 .NET 8.0 运行时。 请确保根据要运行的 SignTool 版本安装正确的平台运行时。 或者,可以两个都安装

例如:

下载并安装受信任签名 dlib 包

若要下载并安装受信任签名 dlib 包(.zip 文件),请执行以下步骤:

  1. 下载受信任签名 dlib 包

  2. 解压缩受信任签名 dlib 压缩内容,并将其安装到所选目录中的签名节点上。 节点必须是要使用 SignTool 对文件进行签名的节点。

另一个选项是通过 NuGet 下载受信任签名 dlib 包(类似于 Windows SDK 生成工具 NuGet 包):

.\nuget.exe install Microsoft.Trusted.Signing.Client -Version 1.0.53 -x

创建 JSON 文件

若要使用受信任签名进行签名,需要提供作为先决条件的一部分创建的受信任签名帐户和证书配置文件的详细信息。 你可以通过完成以下步骤,在 JSON 文件中提供这些信息:

  1. 创建新的 JSON 文件(例如 metadata.json)。

  2. 将受信任签名帐户和证书配置文件对应的特定值添加到 JSON 文件。 有关详细信息,请参阅受信任签名 dlib 包中包含的 metadata.sample.json 文件,或使用以下示例:

    {
      "Endpoint": "<Trusted Signing account endpoint>",
      "CodeSigningAccountName": "<Trusted Signing account name>",
      "CertificateProfileName": "<Certificate profile name>",
      "CorrelationId": "<Optional CorrelationId value>"
    }
    

    "Endpoint" URI 值所拥有的 URI 必须与在设置受信任签名帐户和证书配置文件时用于创建这些资源的区域一致。 该表显示了区域及其对应的 URI。

    区域 区域类字段 终结点 URI 值
    美国东部 EastUS https://eus.codesigning.azure.net
    West US3 [1] WestUS3 https://wus3.codesigning.azure.net
    美国中西部 WestCentralUS https://wcus.codesigning.azure.net
    美国西部 2 美国西部 2 https://wus2.codesigning.azure.net
    北欧 NorthEurope https://neu.codesigning.azure.net
    西欧 西欧 https://weu.codesigning.azure.net

    1 可选的 "CorrelationId" 字段是一个不透明的字符串值,可用于将签名请求与自己的工作流(例如生成标识符或计算机名称)相关联。

身份验证

此任务使用 DefaultAzureCredential 执行身份验证,这会按顺序尝试一系列身份验证方法。 如果一种方法失败,它会尝试下一种方法,直到身份验证成功。

可以单独禁用每种身份验证方法,以避免不必要的尝试。

例如,具体而言,在使用 EnvironmentCredential 进行身份验证时,请使用以下输入禁用其他凭据:

ExcludeEnvironmentCredential: false ExcludeManagedIdentityCredential: true ExcludeSharedTokenCacheCredential: true ExcludeVisualStudioCredential: true ExcludeVisualStudioCodeCredential: true ExcludeAzureCliCredential: true ExcludeAzurePowershellCredential: true ExcludeInteractiveBrowserCredential: true

类似地,如果使用 AzureCliCredential,则建议不要尝试使用该方法前面的几种方法进行身份验证。

使用 SignTool 对文件进行签名

若要调用 SignTool 以对文件进行签名,请执行以下操作:

  1. 记下 SDK 生成工具、解压缩的 Azure.CodeSigning.Dlib 和 metadata.json 文件的位置(来自前面的部分)。

  2. 将以下路径中的占位符替换为在步骤 1 中记录的特定值:

    & "<Path to SDK bin folder>\x64\signtool.exe" sign /v /debug /fd SHA256 /tr "http://timestamp.acs.microsoft.com" /td SHA256 /dlib "<Path to Trusted Signing dlib bin folder>\x64\Azure.CodeSigning.Dlib.dll" /dmdf "<Path to metadata file>\metadata.json" <File to sign>
    
  • x86 和 x64 版本的 SignTool 均包含在 Windows SDK 中。 请务必引用相应版本的 Azure.CodeSigning.Dlib.dll。 上面的示例适用于 SignTool 的 x64 版本。
  • 请确保在本文开头列出的依赖项中使用推荐的 Windows SDK 版本,否则 dlib 文件将无法正常运行。

受信任签名证书的有效期为 3 天,因此时间戳对于超过 3 天有效期后继续成功验证签名至关重要。 Trusted Signing 建议使用 Trusted Signing 的 Microsoft 公共 RSA 时间戳颁发机构:http://timestamp.acs.microsoft.com/

使用 Trusted Signing 的其他签名集成

还可以使用以下工具或平台设置与受信任签名的签名集成。

  • GitHub Actions:若要了解如何使用 GitHub 操作进行受信任签名,请参阅 GitHub Marketplace 中的受信任签名 - 操作。 按照设置和使用 GitHub 操作的说明完成操作。

  • Azure DevOps 任务:若要使用受信任签名 Azure DevOps 任务,请参阅 Visual Studio Marketplace 中的受信任签名。 按照说明完成设置。

  • 验证码 PowerShell:若要使用适用于受信任签名的 PowerShell,请参阅 PowerShell 库中的受信任签名以安装相应的 PowerShell 模块。

  • Azure PowerShell - 适用于企业 CI 策略的应用控制:若要使用受信任签名进行代码完整性 (CI) 策略签名,请按照对新 CI 策略进行签名中的说明进行操作,并访问 Az.CodeSigning PowerShell 模块

  • 受信任签名 SDK:若要创建你自己的签名集成,可以使用我们的开源受信任签名 SDK

  • Azure.Developer.TrustedSigning.CryptoProvider:简化了服务与可从使用者抽象服务终结点集成的 .NET 加密提供程序的集成。