Configurare le integrazioni di firma per l'uso di Firma attendibile

Firma attendibile supporta attualmente le integrazioni di firma seguenti:

• SignTool
• Azioni di GitHub
• Attività di Azure DevOps
• PowerShell per Authenticode
• Azure PowerShell (criteri di integrità del codice di Controllo delle applicazioni)
• Trusted Signing SDK

Microsoft lavora costantemente per supportare più integrazioni di firma. L'elenco di integrazioni supportate viene aggiornato quando sono disponibili altre integrazioni.

Questo articolo illustra come configurare ogni integrazione di firma compatibile con Firma attendibile.

Configurare SignTool per l'uso di Firma attendibile

Questa sezione illustra come configurare SignTool per l'uso con Firma attendibile.

Prerequisiti

Per completare i passaggi di questo articolo sono necessari:

• Un account di Firma attendibile, la convalida dell'identità e un profilo di certificato.
• Assegnazione individuale o di gruppo del ruolo Firmatario del profilo del certificato di Firma attendibile.
• Windows 10 versione 1809/ottobre 2018 Update o versione successiva, Windows 11 (tutte le versioni) o Windows Server 2016 o versioni successive

Programma di installazione degli strumenti client per la firma attendibile

Trusted Signing Client Tools for SignTool.exe è un plug-in di libreria che richiede i componenti seguenti:

1. Windows SDK SignTool.exe (versione minima: 10.0.2261.755)
2. Runtime di .NET 8
3. Microsoft Visual C++ Redistributable
4. Dlib client di firma attendibile

Per semplificare questa configurazione, è disponibile un pacchetto del programma di installazione MSI per il download insieme a un Setup.exe.

Installazione dal Gestione pacchetti Windows

Il programma di installazione degli strumenti client di firma attendibile è disponibile nel Gestione pacchetti Windows (WinGet).

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

L'opzione -e consiste nel verificare che sia installato il pacchetto ufficiale Degli strumenti client per la firma attendibile. Questo comando installa la versione più recente per impostazione predefinita. Per specificare una versione, aggiungere un oggetto -v <version> con la versione desiderata al comando .

Installazione da PowerShell

Per installare gli strumenti client di firma attendibili con PowerShell, avviare PowerShell come amministratore ed eseguire il comando seguente:

$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

Riepilogo dei passaggi di installazione manuale

1. Scaricare e installare SignTool.
2. Scaricare e installare il runtime di .NET 8.
3. Scaricare e installare il pacchetto dlib di Firma attendibile.
4. Creare un file JSON per fornire l'account di Firma attendibile e un profilo di certificato.
5. Richiamare SignTool per firmare un file.

Scaricare e installare SignTool

Firma attendibile richiede l'uso di SignTool per firmare i file in Windows, in particolare la versione di SignTool.exe disponibile in Windows 10 SDK 10.0.2261.755 o versione successiva. È possibile installare l'SDK completo di Windows 10 tramite il programma di installazione di Visual Studio o scaricarlo e installarlo separatamente.

Per scaricare e installare SignTool:

1. Scaricare l'ultima versione di SignTool e degli strumenti di compilazione di Windows NuGet all'indirizzo Microsoft.Windows.SDK.BuildTools.

2. Installare SignTool da Windows SDK (versione minima: 10.0.2261.755, la versione di Windows SDK 20348 non è supportata con il nostro dlib).

Un'altra opzione consiste nell'usare il file nuget.exe più recente per scaricare ed estrarre l'ultimo pacchetto NuGet degli strumenti di compilazione di Windows SDK usando PowerShell:

1. Scaricare nuget.exe eseguendo il comando di download seguente:

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

2. Scaricare ed estrarre il pacchetto NuGet degli strumenti di compilazione di Windows SDK eseguendo il comando di installazione seguente:

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

Scaricare e installare il runtime di .NET 8.0

I componenti usati da SignTool per interfacciarsi con Firma attendibile richiedono l'installazione del runtime di .NET 8.0. È necessario solo il runtime principale di .NET 8.0. Assicurarsi di installare il runtime per la piattaforma corretta a seconda della versione di SignTool che si intende eseguire. In alternativa, è possibile installare entrambi

Ad esempio:

• Per SignTool.exe x64: Scaricare il programma di installazione di .NET 8.0 Runtime per Windows x64
• Per SignTool.exe x86: Scaricare il programma di installazione di .NET 8.0 Runtime per Windows x86

Scaricare e installare il pacchetto dlib di Firma attendibile

Per scaricare e installare il pacchetto dlib di Firma attendibile (un pacchetto ZIP):

1. Scaricare il pacchetto dlib di Firma attendibile.

2. Estrarre il contenuto compresso del pacchetto dlib di Firma attendibile e installarlo nel nodo di firma nella directory scelta. Il nodo deve essere quello in cui si usa SignTool per firmare i file.

Un'altra possibilità è scaricare il pacchetto dlib di Firma attendibile tramite NuGet, in modo simile al pacchetto NuGet degli strumenti di compilazione di Windows SDK:

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

Creare un file JSON

Per firmare usando Firma attendibile, è necessario specificare i dettagli dell'account di Firma attendibile e del profilo di certificato creati come parte dei prerequisiti. Per fornire queste informazioni in un file JSON, seguire questa procedura:

1. Creare un nuovo file JSON, ad esempio metadata.json.

2. Aggiungere i valori specifici per l'account di Firma attendibile e il profilo di certificato al file JSON. Per altre informazioni, vedere il file metadata.sample.json incluso nel pacchetto dlib di Firma attendibile o usare l'esempio seguente:

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

   Il valore dell'URI "Endpoint" deve essere allineato all'area in cui sono stati creati l'account di Firma attendibile e il profilo di certificato al momento della configurazione di queste risorse. La tabella mostra le aree e gli URI corrispondenti.

   Paese	Campi della classe dell'area	Valore URI dell'endpoint
   Stati Uniti orientali	EastUS	https://eus.codesigning.azure.net
   Stati Uniti occidentali3 [1]	WestUS3	https://wus3.codesigning.azure.net
   Stati Uniti centro-occidentali	WestCentralUS	https://wcus.codesigning.azure.net
   West US 2	Stati Uniti occidentali 2	https://wus2.codesigning.azure.net
   Europa settentrionale	NorthEurope	https://neu.codesigning.azure.net
   Europa occidentale	Europa occidentale	https://weu.codesigning.azure.net

   ¹ Il campo facoltativo "CorrelationId" è un valore stringa opaco che è possibile fornire per correlare le richieste di firma con i propri flussi di lavoro, ad esempio identificatori di build o nomi di computer.

Autenticazione

Questa attività esegue l'autenticazione usando DefaultAzureCredential, che tenta una serie di metodi di autenticazione in ordine. Se un metodo ha esito negativo, tenta di eseguire l'autenticazione successiva fino a quando l'autenticazione non riesce.

Ogni metodo di autenticazione può essere disabilitato singolarmente per evitare tentativi non necessari.

Ad esempio, quando si esegue l'autenticazione con EnvironmentCredential specificamente, disabilitare le altre credenziali con gli input seguenti:

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

Analogamente, se si usa ad esempio un AzureCliCredential , si vuole ignorare il tentativo di autenticazione con i vari metodi che lo precedono nell'ordine.

Usare SignTool per firmare un file

Per richiamare SignTool per firmare un file:

1. Prendere nota della posizione in cui si trovano gli strumenti di compilazione dell'SDK, il pacchettoAzure.CodeSigning.Dlib estratto e il file metadata.json (dalle sezioni precedenti).

2. Sostituire i segnaposto nel percorso seguente con i valori specifici annotati nel passaggio 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>
   

• Windows SDK include sia la versione x86 che la versione x64 di SignTool. Assicurarsi di fare riferimento alla versione corrispondente di Azure.CodeSigning.Dlib.dll. L'esempio precedente è per la versione x64 di SignTool.
• Assicurarsi di usare la versione consigliata di Windows SDK nelle dipendenze elencate all'inizio di questo articolo oppure il file dlib non funzionerà.

I certificati di Firma attendibile hanno una validità di tre giorni, quindi il timestamp è fondamentale per la convalida continuativa di una firma oltre il periodo di validità di tre giorni. Firma attendibile consiglia l'uso dell'autorità di riconoscimento timestamp RSA pubblica di Microsoft per Firma attendibile: http://timestamp.acs.microsoft.com/.

Usare altre integrazioni di firma con Firma attendibile

È anche possibile usare gli strumenti o le piattaforme seguenti per configurare integrazioni di firma con Firma attendibile.

• GitHub Actions: per informazioni su come usare un'azione GitHub per Firma attendibile, vedere Firma attendibile - Azioni in GitHub Marketplace. Completare le istruzioni per configurare e usare un'azione GitHub.

• Attività di Azure DevOps: per usare l'attività Firma attendibile di Azure DevOps, vedere Firma attendibile in Visual Studio Marketplace. Completare le istruzioni per la configurazione.

• PowerShell per Authenticode: per usare PowerShell per Firma attendibile, vedere Firma attendibile in PowerShell Gallery per installare il modulo di PowerShell.

• Azure PowerShell - Criteri di integrità del codice di Controllo delle applicazioni: per usare Firma attendibile per firmare criteri di integrità del codice (CI), seguire le istruzioni riportate in Firmare un nuovo criterio di integri del codice e vedere Modulo PowerShell Az.CodeSigning.

• Trusted Signing SDK: per creare un'integrazione di firma personalizzata, è possibile usare il nostro Trusted Signing SDK open source.

• Azure.Developer.TrustedSigning.CryptoProvider: semplifica l'integrazione del servizio con un provider di crittografia .NET che astrae l'integrazione dell'endpoint di servizio dal consumer.