Configurar integrações de assinatura para usar a Assinatura Confiável

Atualmente, o Trusted Signing oferece suporte às seguintes integrações de assinatura:

• SignTool
• GitHub Actions
• Tarefas do Azure DevOps
• PowerShell para Authenticode
• Azure PowerShell (política de CI do Controle de Aplicativos para Empresas)
• SDK de Assinatura Confiável

Trabalhamos constantemente para dar suporte a mais integrações de assinatura. Atualizamos a lista de integração com suporte quando mais integrações estiverem disponíveis.

Este artigo explica como configurar cada integração de assinatura confiável com suporte.

Configurar o SignTool para usar a Assinatura Confiável

Essa seção explica como configurar o SignTool para usar com assinatura confiável.

Pré-requisitos

Para concluir as etapas deste artigo, você precisa de:

• Uma conta de Assinatura Confiável, validação de identidade e perfil de certificado.
• Uma atribuição individual ou em grupo da função de Signatário de Perfil de Certificado de Assinatura Confiável.
• Windows 10 versão 1809/atualização de outubro de 2018 ou mais recente, Windows 11 (todas as versões) ou Windows Server 2016 ou mais recente

Instalador de Ferramentas de Cliente de Assinatura Confiável

As Ferramentas de Cliente de Assinatura Confiável para SignTool.exe é um plug-in de biblioteca que requer os seguintes componentes:

1. SDK do Windows SignTool.exe (versão mínima: 10.0.2261.755)
2. Runtime do .NET 8
3. Microsoft Visual C++ redistribuível
4. Cliente de Assinatura Confiável Dlib

Para simplificar essa configuração, há um pacote do instalador MSI disponível para download junto com um Setup.exe.

Download de MSI de Ferramentas de Cliente de Assinatura Confiável

Download das Ferramentas de Cliente de Assinatura Confiável Setup.exe

Instalação do Gerenciador de Pacotes do Windows

O instalador de Ferramentas de Cliente de Assinatura Confiável está disponível no WinGet (Gerenciador de Pacotes do Windows).

Observação

O winget está disponível por padrão no Windows 11 e em versões modernas do Windows 10. No entanto, ele pode não estar instalado em versões mais antigas do Windows. Consulte a documentação do winget para obter instruções de instalação.

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

A opção -e é para garantir que o pacote oficial das Ferramentas de Cliente de Assinatura Confiável esteja instalado. Esse comando instala a versão mais recente por padrão. Para especificar uma versão, adicione um -v <version> com a versão desejada ao comando.

Instalação a partir do PowerShell

Para instalar as Ferramentas de Cliente de Assinatura Confiável usando o PowerShell, inicie o PowerShell como administrador e execute o seguinte comando:

$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

Resumo das etapas de instalação manual

1. Baixe e instale SignTool.
2. Baixe e instale o tempo de execução do .NET 8.
3. Baixe e instale o pacote dlib de Assinatura Confiável.
4. Crie um arquivo JSON para fornecer sua conta de Assinatura Confiável e um perfil de certificado.
5. Para assinar um arquivo, invoque SignTool.

Baixe e instale SignTool

A Assinatura Confiável requer o uso do SignTool para assinar arquivos no Windows, especificamente a versão do SignTool.exe que está no SDK do Windows 10 10.0.2261.755 ou posterior. Você pode instalar o SDK completo do Windows 10 por meio do Instalador do Visual Studio ou baixá-lo e instalá-lo separadamente.

Para baixar e instalar o SignTool:

1. Baixe a versão mais recente do NuGet das Ferramentas de Build do SignTool e do Windows em Microsoft.Windows.SDK.BuildTools.

2. A instalação da SignTool do SDK do Windows (versão mínima: 10.0.2261.755, a versão 20348 do SDK do Windows não é compatível com nossa dlib).

Outra opção é usar o arquivo de nuget.exe mais recente para baixar e extrair o pacote NuGet mais recente das Ferramentas de Build do SDK do Windows usando o PowerShell:

1. Baixe nuget.exe executando o seguinte comando de download:

   Invoke-WebRequest -Uri https://dist.nuget.org/win-x86-commandline/latest/nuget.exe -OutFile .\nuget.exe  
   

2. Baixe e extraia o pacote NuGet das Ferramentas de Build do SDK do Windows executando o seguinte comando de instalação:

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

Baixe e instale o tempo de execução do .NET 8.0

Os componentes usados pelo SignTool para interface com a Assinatura Confiável exigem a instalação do Runtime do .NET 8.0. Você precisa apenas do runtime principal do .NET 8.0. Instale o runtime de plataforma correto dependendo da versão do SignTool que você pretende executar. Ou você pode simplesmente instalar ambos

Por exemplo:

• Para x64 SignTool.exe: Baixar o runtime do .NET 8.0 – instalador do Windows x64
• Para x86 SignTool.exe: Baixar o runtime do .NET 8.0 – instalador do Windows x86

Baixar e instalar o pacote dlib de Assinatura Confiável

Para baixar e instalar o pacote dlib de Assinatura Confiável (um arquivo .zip):

1. Baixe o pacote dlib de Assinatura Confiável.

2. Extraia o conteúdo compactado do dlib de Assinatura Confiável e instale-o no nó de assinatura em sua escolha de diretório. O nó deve ser o nó em que você usa o SignTool para assinar arquivos.

Outra opção é baixar o pacote dlib de Assinatura Confiável por meio do NuGet semelhante ao pacote NuGet das Ferramentas de Build do SDK do Windows:

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

Criar um arquivo JSON

Para assinar usando a Assinatura Confiável, você precisa fornecer os detalhes da sua conta de Assinatura Confiável e do perfil de certificado que foram criados como parte dos pré-requisitos. Você fornece essas informações em um arquivo JSON concluindo essas etapas:

1. Crie um novo arquivo JSON (por exemplo, metadata.json).

2. Adicione os valores específicos para sua conta de Assinatura Confiável e o perfil de certificado ao arquivo JSON. Para obter mais informações, consulte o arquivo de metadata.sample.json incluído no pacote dlib de Assinatura Confiável ou use o seguinte exemplo:

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

   O valor do URI "Endpoint" deve ser um URI que se alinha à região em que você criou sua conta de Assinatura Confiável e o perfil de certificado ao configurar esses recursos. A tabela mostra regiões e suas URIs correspondentes.

   Region	Campos de classe de região	Valor do URI do ponto de extremidade
   Leste dos EUA	EastUS	https://eus.codesigning.azure.net
   Oeste dos EUA3 [1]	WestUS3	https://wus3.codesigning.azure.net
   Centro-Oeste dos EUA	WestCentralUS	https://wcus.codesigning.azure.net
   Oeste dos EUA 2	WestUS2	https://wus2.codesigning.azure.net
   Norte da Europa	NorthEurope	https://neu.codesigning.azure.net
   Europa Ocidental	WestEurope	https://weu.codesigning.azure.net

   ¹ O campo opcional "CorrelationId" é um valor de cadeia de caracteres opaco que você pode fornecer para correlacionar solicitações de sinal com seus próprios fluxos de trabalho, como identificadores de build ou nomes de máquina.

Autenticação

Essa Tarefa executa a autenticação usando DefaultAzureCredential, que tenta uma série de métodos de autenticação em ordem. Se um método falhar, ela tentará o próximo até que a autenticação seja bem-sucedida.

Cada método de autenticação pode ser desabilitado individualmente para evitar tentativas desnecessárias.

Por exemplo, ao autenticar com EnvironmentCredential especificamente, desabilite as outras credenciais com as seguintes entradas:

ExcludeEnvironmentCredential: falso ExcludeManagedIdentityCredential: verdadeiro ExcludeSharedTokenCacheCredential: verdadeiro ExcludeVisualStudioCredential: verdadeiro ExcludeVisualStudioCodeCredential: verdadeiro ExcludeAzureCliCredential: verdadeiro ExcludeAzurePowershellCredential: verdadeiro ExcludeInteractiveBrowserCredential: verdadeiro

Da mesma forma, se estiver usando, por exemplo, um AzureCliCredential, vamos ignorar a tentativa de autenticação com os vários métodos que vêm antes na ordem.

Usar SignTool para assinar um arquivo

Para invocar SignTool para assinar um arquivo:

1. Anote onde as Ferramentas de Build do SDK, o Azure.CodeSigning.Dlib extraído e o arquivo metadata.json estão localizados (de seções anteriores).

2. Substitua os espaços reservados no seguinte caminho pelos valores específicos que você anotou na etapa 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>
   

• O x86 e a versão x64 do SignTool estão incluídos no SDK do Windows. Lembre-se de referenciar a versão correspondente do Azure.CodeSigning.Dlib.dll. O exemplo anterior é para a versão x64 do SignTool.
• Certifique-se de usar a versão recomendada do SDK do Windows nas dependências listadas no início deste artigo ou se o arquivo dlib não funcionará.

Os certificados de Assinatura Confiável têm uma validade de três dias, portanto, o carimbo de data/hora é fundamental para a validação bem-sucedida contínua de uma assinatura além desse período de validade de três dias. A Trusted Signing recomenda o uso da Microsoft Public RSA Time Stamping Authority da Trusted Signing: http://timestamp.acs.microsoft.com/.

Use outras integrações de assinatura com Trusted Signing

Você também pode usar as seguintes ferramentas ou plataformas para configurar integrações de assinatura com a Assinatura Confiável.

• GitHub Actions: para saber como usar uma ação do GitHub para Assinatura Confiável, consulte Assinatura Confiável – Ações no GitHub Marketplace. Conclua as instruções para configurar e usar uma ação do GitHub.

• Tarefa do Azure DevOps: para usar a tarefa DevOps do Azure de Assinatura Confiável, consulte Assinatura Confiável no Visual Studio Marketplace. Conclua as instruções para a instalação.

• PowerShell para Authenticode: para usar o PowerShell para Assinatura Confiável, consulte Assinatura Confiável na Galeria do PowerShell para instalar o módulo do PowerShell.

• Azure PowerShell – Política de CI do Controle de Aplicativos para Empresas: para usar a Assinatura Confiável para assinatura de política de CI (integridade de código), siga as instruções em Assinar uma nova política de CI e consulte Módulo do PowerShell do Az.CodeSigning.

• SDK de Assinatura Confiável: para criar sua própria integração de assinatura, você pode usar nosso SDK de Assinatura Confiável de software livre.

• Azure.Developer.TrustedSigning.CryptoProvider: simplifica a integração do serviço com um provedor de criptografia .NET que abstrai a integração do ponto de extremidade de serviço do consumidor.