Настройка интеграции подписи для использования подписывания артефактов

В настоящее время подписывание артефактов поддерживает следующие интеграции подписывания:

• SignTool
• Действия GitHub
• Задачи Azure DevOps
• PowerShell для Authenticode
• Azure PowerShell (Политика CI для управления приложениями для бизнеса)
• Пакет SDK для подписывания артефактов

Мы постоянно работаем над поддержкой дополнительных интеграции подписей. Мы обновляем поддерживаемый список интеграции при наличии дополнительных интеграций.

В этой статье объясняется, как настроить каждую поддерживаемую интеграцию подписывания артефактов.

Настройка SignTool для подписания артефактов

В этом разделе объясняется, как настроить SignTool для работы с подписанием артефактов.

Предпосылки

Для выполнения задач из этой статьи необходимо следующее:

• Учетная запись для подписания артефактов, проверка личности и профиль сертификата.
• Индивидуальное или групповое назначение роли подписанта профиля сертификата артефакта.
• Обновление Windows 10 версии 1809/октябрь 2018 г. или более поздней версии, Windows 11 (все версии) или Windows Server 2016 или более поздней версии

Установщик клиентских инструментов для подписания артефактов

Клиентские средства подписывания артефактов для SignTool.exe — это библиотечный модуль, который требует следующие компоненты:

1. Пакет SDK для Windows SignTool.exe (минимальная версия: 10.0.2261.755)
2. Среда выполнения .NET 8
3. Распространяемый компонент Microsoft Visual C++
4. Клиент Dlib для подписывания артефактов

Чтобы упростить эту настройку, существует пакет установщика MSI, доступный для скачивания вместе с Setup.exe.

Установка из Диспетчера пакетов Windows

Установщик клиентских средств подписывания артефактов доступен в диспетчере пакетов Windows (WinGet).

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

Этот -e параметр предназначен для обеспечения установки официального пакета клиентских инструментов для подписывания артефактов. Эта команда устанавливает последнюю версию по умолчанию. Чтобы указать версию, добавьте -v <version> нужную версию в команду.

Установка из PowerShell

Чтобы установить клиентские средства подписывания артефактов с помощью PowerShell, запустите PowerShell от имени администратора и выполните следующую команду:

$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri "https://download.microsoft.com/download/70ad2c3b-761f-4aa9-a9de-e7405aa2b4c1/ArtifactSigningClientTools.msi" -OutFile .\ArtifactSigningClientTools.msi; Start-Process msiexec.exe -Wait -ArgumentList '/I ArtifactSigningClientTools.msi /quiet'; Remove-Item .\ArtifactSigningClientTools.msi

Сводка действий по настройке вручную

1. Скачайте и установите SignTool.
2. Скачайте и установите среду выполнения .NET 8.
3. Скачайте и установите пакет Artifact Signing dlib.
4. Создайте JSON-файл с учетной записью для подписи артефактов и профилем сертификата.
5. Чтобы подписать файл, вызовите SignTool.

Скачивание и установка SignTool

Для подписывания артефактов требуется использовать SignTool для подписывания файлов в Windows, в частности версию SignTool.exe, которая находится в пакете SDK для Windows 10.0.2261.755 или более поздней версии. Вы можете установить полный пакет SDK для Windows 10 с помощью установщика Visual Studio или скачать его отдельно.

Чтобы скачать и установить SignTool, выполните приведенные ниже действия.

1. Скачайте последнюю версию SignTool и Средств сборки Windows NuGet в Microsoft.Windows.SDK.BuildTools.

2. Установите SignTool из пакета SDK для Windows (минимальная версия: 10.0.2261.755, версия пакета SDK для Windows 20348 не поддерживается в нашем dlib).

Другим вариантом является использование последней версии nuget.exe, чтобы скачать и извлечь последний NuGet-пакет Инструментов сборки Windows SDK с помощью PowerShell.

1. Скачайте nuget.exe , выполнив следующую команду скачивания:

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

2. Скачайте и извлеките пакет NuGet Windows SDK Build Tools, выполнив вот такую команду установки:

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

Скачивание и установка среды выполнения .NET 8.0

Компоненты, которые SignTool использует для интерфейса с подписью артефактов, требуют установки среды выполнения .NET 8.0. Вам требуется только основная среда выполнения .NET 8.0. Убедитесь, что вы устанавливаете правильную среду выполнения платформы в зависимости от версии SignTool, которую вы планируете запустить. Кроме того, можно просто установить оба

Рассмотрим пример.

• Для x64 SignTool.exe: Загрузите среду выполнения .NET 8.0 — установщик Windows x64
• Для SignTool.exe x86: скачать среду выполнения .NET 8.0 — установщик для Windows x86

Скачивание и установка пакета dlib для подписывания артефактов

Чтобы скачать и установить пакет Artifact Signing dlib (файл .zip):

1. Скачайте пакет dlib для подписи артефактов.

2. Извлеките zip-файл dlib для подписания артефактов и установите его на узле подписывания в выбранной директории. Узел должен быть узлом, в котором вы используете SignTool для подписывания файлов.

Еще одним вариантом является загрузка пакета Artifact Signing dlib через NuGet, подобно пакету NuGet для средств сборки Windows SDK.

.\nuget.exe install Microsoft.ArtifactSigning.Client -x

Создание JSON-файла

Чтобы подписать с использованием подписи артефактов, необходимо указать сведения об учетной записи Подписи артефактов и профиле сертификата, созданном как часть предварительных требований. Эти сведения можно указать в JSON-файле, выполнив следующие действия.

1. Создайте файл JSON (например, metadata.json).

2. Добавьте определенные значения для учетной записи для подписи артефакта и профиля сертификатов в JSON-файл. Дополнительные сведения см. в файле metadata.sample.json, который входит в пакет dlib для подписания артефактов, или воспользуйтесь следующим примером:

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

¹ Необязательное "CorrelationId" поле — это непрозрачное строковое значение, которое можно предоставить для сопоставления запросов подписей с собственными рабочими процессами, такими как идентификаторы сборки или имена компьютеров.

Authentication

Эта задача выполняет проверку подлинности с помощью DefaultAzureCredential, который последовательно пробует различные методы проверки подлинности. Если один метод завершается ошибкой, он пытается выполнить следующую попытку, пока проверка подлинности не будет выполнена успешно.

Каждый метод проверки подлинности можно отключить по отдельности, чтобы избежать ненужных попыток.

Например, при проверке подлинности, используя EnvironmentCredential, отключите другие учетные данные, используя следующие параметры:

{
  "Endpoint": "<Artifact Signing account endpoint>",
  "CodeSigningAccountName": "<Signing account name>",
  "CertificateProfileName": "<Certificate profile name>",
  "CorrelationId": "<Optional CorrelationId value>",
  "ExcludeCredentials": [
     "ManagedIdentityCredential",
     "WorkloadIdentityCredential",
     "SharedTokenCacheCredential",
     "VisualStudioCredential",
     "VisualStudioCodeCredential",
     "AzureCliCredential",
     "AzurePowerShellCredential",
     "AzureDeveloperCliCredential",
     "InteractiveBrowserCredential"
 ]
}

Аналогичным образом, если, например, используется 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 Artifact Signing dlib bin folder>\x64\Azure.CodeSigning.Dlib.dll" /dmdf "<Path to metadata file>\metadata.json" <File to sign>
   

• В пакет SDK для Windows включены как x86, так и x64-разрядные версии SignTool. Обязательно ссылайтесь на соответствующую версию Azure.CodeSigning.Dlib.dll. Предыдущий пример предназначен для версии x64 SignTool.
• Убедитесь, что вы используете рекомендуемую версию Windows SDK в зависимостях, перечисленных в начале этой статьи, иначе файл dlib не будет работать.

Сертификаты подписывания артефактов имеют трехдневный срок действия, поэтому метка времени имеет решающее значение для продолжения успешной проверки подписи за этот трехдневный срок действия. Подписание артефактов рекомендует использовать Уполномоченного центра http://timestamp.acs.microsoft.com/ метки времени подписи Microsoft Public RSA.

Использование других интеграции подписей с подписью Артефакта

Вы также можете использовать следующие средства или платформы для настройки интеграции подписи с подписью Артефакта.

• GitHub Actions: Чтобы узнать, как использовать действие GitHub для подписывания артефактов, см. раздел "Подписывание артефактов — действия" в GitHub Marketplace. Выполните инструкции по настройке и использованию действия GitHub.

• Задача Azure DevOps: Чтобы использовать задачу Подписывание артефактов Azure DevOps, смотрите Подписывание артефактов в Visual Studio Marketplace. Выполните инструкции по настройке.

• PowerShell для подписывания кодов с использованием Authenticode: Используйте PowerShell для подписывания артефактов, см. в разделе "Подписывание артефактов" в PowerShell Gallery для установки модуля PowerShell.

• Azure PowerShell — политика CI "Управление приложениями для бизнеса": чтобы использовать подписывание артефактов для политики целостности кода (CI), следуйте инструкциям в статье "Подпись новой политики CI" и загрузите модуль PowerShell Az.ArtifactSigning.

• SDK для подписывания артефактов: Чтобы создать собственную интеграцию подписывания, можно использовать наш SDK для подписывания артефактов с открытым исходным кодом.

• Azure.Developer.ArtifactSigning.CryptoProvider: упрощает интеграцию службы с поставщиком шифрования .NET, который абстрагирует интеграцию конечной точки службы от потребителя.