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

Atualmente, a Assinatura Confiável suporta as seguintes integrações de assinatura:

• SignTool
• GitHub Actions
• Tarefas do Azure DevOps
• PowerShell para Authenticode
• Azure PowerShell (política de CI do Controle de Aplicativo para Empresas)
• SDK de assinatura confiável

Trabalhamos constantemente para apoiar mais integrações de assinatura. Atualizamos a lista de integração suportada quando mais integrações estão disponíveis.

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

Configurar o SignTool para usar a Assinatura Confiável

Esta seção explica como configurar o SignTool para usar com a Assinatura Confiável.

Pré-requisitos

Para concluir as etapas neste artigo, você precisa:

• Uma conta de Assinatura Confiável, validação de identidade e perfil de certificado.
• Atribuição individual ou em grupo da função de Signatário de Perfil de Certificado de Assinatura Confiável.

Resumo das etapas

1. Baixe e instale o SignTool.
2. Baixe e instale o .NET 8 Runtime.
3. Transfira e instale o pacote dlib de Assinatura Fidedigna.
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 o SignTool

A Assinatura Confiável requer o uso de 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 Visual Studio Installer ou baixá-lo e instalá-lo separadamente.

Para baixar e instalar o SignTool:

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

2. Instale o SignTool a partir do SDK do Windows (versão mínima: 10.0.2261.755, a versão 20348 do SDK do Windows não é suportada com o nosso dlib).

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

1. Faça o download 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 do Windows SDK Build Tools executando o seguinte comando de instalação:

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

Baixe e instale o .NET 8.0 Runtime

Os componentes que o SignTool usa para interagir com a Assinatura Confiável exigem a instalação do .NET 8.0 Runtime Você precisa apenas do núcleo do .NET 8.0 Runtime. Certifique-se de instalar o tempo de execução correto da plataforma, dependendo da versão do SignTool que você pretende executar. Ou, você pode simplesmente instalar ambos

Por exemplo:

• Para x64 SignTool.exe: Baixar .NET 8.0 Runtime - Windows x64 installer
• Para x86 SignTool.exe: Baixar .NET 8.0 Runtime - Windows x86 installer

Baixe e instale 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 dlib de Assinatura Confiável e instale-o no nó de assinatura no diretório de sua escolha. O nó deve ser o nó onde você usa o SignTool para assinar arquivos.

Outra opção é baixar o pacote dlib de Assinatura Confiável via NuGet, semelhante ao pacote NuGet das Ferramentas de Compilação 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 estas 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 perfil de certificado ao arquivo JSON. Para obter mais informações, consulte o arquivo 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 "Endpoint" valor de URI deve ser um URI alinhado com a região onde você criou sua conta de Assinatura Confiável e perfil de certificado ao configurar esses recursos. A tabela mostra regiões e seus URIs correspondentes.

   País/Região	Campos de classe de região	Valor do URI do ponto de extremidade
   E.U.A. Leste	EastUS	https://eus.codesigning.azure.net
   Oeste US3 [1]	WestUS3	https://wus3.codesigning.azure.net
   E.U.A. Centro-Oeste	WestCentralUS	https://wcus.codesigning.azure.net
   E.U.A. Oeste 2	WestUS2	https://wus2.codesigning.azure.net
   Europa do Norte	Norte da Europa	https://neu.codesigning.azure.net
   Europa Ocidental	Europa Ocidental	https://weu.codesigning.azure.net

   1 O campo opcional "CorrelationId" é um valor de cadeia de caracteres opaco que você pode fornecer para correlacionar solicitações de assinatura com seus próprios fluxos de trabalho, como identificadores de compilação ou nomes de máquinas.

Autenticação

Esta 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, ele tentará o próximo até que a autenticação seja bem-sucedida.

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

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

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

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

Usar o SignTool para assinar um arquivo

Para invocar o SignTool para assinar um arquivo:

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

2. Substitua os espaços reservados no caminho a seguir 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>
   

• A versão x86 e x64 do SignTool estão incluídas no SDK do Windows. Certifique-se de fazer referência à 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 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 Assinatura Confiável recomenda o uso da Autoridade Pública de Carimbo de Data/Hora RSA da Assinatura Confiável: http://timestamp.acs.microsoft.com/.

Usar outras integrações de assinatura com a Assinatura Confiável

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

• Ações do GitHub: 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 de DevOps do Azure: para usar a tarefa Assinatura Confiável do Azure DevOps, consulte Assinatura Confiável no Visual Studio Marketplace. Conclua as instruções de configuraçã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 Aplicativo para Empresas: para usar a Assinatura Confiável para assinatura de política de integridade de código (CI), siga as instruções em Assinar uma nova política de CI e consulte Az.CodeSigning PowerShell Module.

• SDK de assinatura confiável: para criar sua própria integração de assinatura, você pode usar nosso SDK de assinatura confiável de código aberto. Observe que esta versão do SDK aparece como não listada. Ele ainda está sendo suportado e será suportado quando um SDK mais recente for lançado.