Подпишите образы контейнеров с использованием Notation и Azure Key Vault, используя самоподписанный сертификат.

2025-05-04

Подписывание образов контейнеров — это процесс, обеспечивающий их подлинность и целостность. Это достигается путем добавления цифровой подписи в образ контейнера, который можно проверить во время развертывания. Сигнатура помогает убедиться, что изображение находится у доверенного издателя и не было изменено. Нотация — это средство безопасности цепочки поставок с открытым исходным кодом, разработанное сообществом нотаричного проекта и поддерживаемое корпорацией Майкрософт, которое поддерживает подписание и проверку образов контейнеров и других артефактов. Azure Key Vault (AKV) используется для хранения сертификатов с ключами подписывания, которые могут использоваться с помощью Notation и плагина Notation AKV (azure-kv) для подписания и проверки контейнерных образов и других объектов. Реестр контейнеров Azure (ACR) позволяет присоединять подписи к образам контейнеров и другим артефактам, а также просматривать эти подписи.

В этом руководстве рассматриваются следующие темы:

Установите Notation CLI и плагин AKV
Создание самозаверяющего сертификата в AKV
Создание и отправка образа контейнера с помощью задач ACR
Подписывание образа контейнера с помощью Notation CLI и подключаемого модуля AKV
Проверка образа контейнера на соответствие подписи с помощью Notation CLI
Установка меток времени

Предпосылки

Создание или использование Реестр контейнеров Azure для хранения образов и подписей контейнеров
Создание или использование Azure Key Vault для управления сертификатами
Установка и настройка последних команд Azure CLI или выполнение команд в Azure Cloud Shell

Установка CLI-интерфейса Notation и плагина AKV

Установите нотацию версии 1.3.0 в среде Linux amd64. Следуйте инструкциям по установке нотации, чтобы скачать пакет для других сред.

# Download, extract and install
curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v1.3.0/notation_1.3.0_linux_amd64.tar.gz
tar xvzf notation.tar.gz

# Copy the Notation binary to the desired bin directory in your $PATH, for example
cp ./notation /usr/local/bin

Установите плагин Нотации Azure Key Vault azure-kv версии 1.2.1 в среде Linux amd64.

Замечание

URL-адрес и контрольная сумма SHA256 для плагина Notation Azure Key Vault можно найти на странице выпуска плагина.
```
notation plugin install --url https://github.com/Azure/notation-azure-kv/releases/download/v1.2.1/notation-azure-kv_1.2.1_linux_amd64.tar.gz --sha256sum 67c5ccaaf28dd44d2b6572684d84e344a02c2258af1d65ead3910b3156d3eaf5
```
Перечислите доступные подключаемые модули и убедитесь, что подключаемый модуль azure-kv с версией 1.2.1 включен в список.
```
notation plugin ls
```

Настройка переменных среды

Замечание

Чтобы упростить выполнение команд в руководстве, укажите значения ресурсов Azure для сопоставления существующих ресурсов ACR и AKV.

Настройте имена ресурсов AKV.

AKV_SUB_ID=myAkvSubscriptionId
AKV_RG=myAkvResourceGroup
# Name of the existing AKV used to store the signing keys
AKV_NAME=myakv
# Name of the certificate created in AKV
CERT_NAME=wabbit-networks-io
CERT_SUBJECT="CN=wabbit-networks.io,O=Notation,L=Seattle,ST=WA,C=US"
CERT_PATH=./${CERT_NAME}.pem

Настройте имена ресурсов ACR и изображений.

ACR_SUB_ID=myAcrSubscriptionId
ACR_RG=myAcrResourceGroup
# Name of the existing registry example: myregistry.azurecr.io
ACR_NAME=myregistry
# Existing full domain of the ACR
REGISTRY=$ACR_NAME.azurecr.io
# Container name inside ACR where image will be stored
REPO=net-monitor
TAG=v1
IMAGE=$REGISTRY/${REPO}:$TAG
# Source code directory containing Dockerfile to build
IMAGE_SOURCE=https://github.com/wabbit-networks/net-monitor.git#main

az login

Чтобы узнать больше об Azure CLI и о том, как войти в систему, см. статью Вход с помощью Azure CLI.

Безопасный доступ к ACR и AKV

При работе с ACR и AKV необходимо предоставить соответствующие разрешения для обеспечения безопасного и управляемого доступа. Вы можете авторизовать доступ для различных сущностей, таких как пользователи, служебные субъекты или управляемые удостоверения, в зависимости от ваших конкретных сценариев. В этом руководстве доступ авторизован для пользователя Azure, выполнившего вход.

Авторизация доступа к ACR

Для реестров, включенных для управления доступом на основе атрибутов Microsoft Entra (ABAC), роли Container Registry Repository Reader и Container Registry Repository Writer необходимы для создания и подписывания образов контейнеров в ACR.

Для реестров, не включенных в ABAC, роли AcrPull и AcrPush необходимы.

Дополнительные сведения о разрешениях репозитория на основе Microsoft Entra ABAC см. в разделе "Разрешения репозитория на основе Microsoft Entra".

Задайте подписку, содержащую ресурс ACR
```
az account set --subscription $ACR_SUB_ID
```

Назначьте роли. Правильная роль, используемая в назначении ролей, зависит от того, включен ли реестр ABAC или нет.

USER_ID=$(az ad signed-in-user show --query id -o tsv)
ROLE1="Container Registry Repository Reader" # For ABAC-enabled registries. Otherwise, use "AcrPull" for non-ABAC-enabled registries.
ROLE2="Container Registry Repository Writer" # For ABAC-enabled registries. Otherwise, use "AcrPush" for non-ABAC-enabled registries.
az role assignment create --role "$ROLE1" --role "$ROLE2" --assignee $USER_ID --scope "/subscriptions/$ACR_SUB_ID/resourceGroups/$ACR_RG/providers/Microsoft.ContainerRegistry/registries/$ACR_NAME"

Авторизация доступа к AKV

В этом разделе мы рассмотрим два варианта авторизации доступа к AKV.

Использование Azure RBAC (рекомендуется)

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

Key Vault Certificates Officer для создания и чтения сертификатов
Key Vault Certificates Userдля чтения существующих сертификатов
Key Vault Crypto User для операций подписывания

Дополнительные сведения о доступе Key Vault с помощью Azure RBAC см. в статье "Использование Azure RBAC" для управления доступом.

Задайте подписку, содержащую ресурс AKV
```
az account set --subscription $AKV_SUB_ID
```

Назначьте роли

USER_ID=$(az ad signed-in-user show --query id -o tsv)
az role assignment create --role "Key Vault Certificates Officer" --role "Key Vault Crypto User" --assignee $USER_ID --scope "/subscriptions/$AKV_SUB_ID/resourceGroups/$AKV_RG/providers/Microsoft.KeyVault/vaults/$AKV_NAME"

Назначьте политику доступа в AKV (устаревшая версия)

Для удостоверения требуются следующие разрешения:

Create разрешения для создания сертификата
Get разрешения на чтение существующих сертификатов
Sign разрешения для операций подписывания

Дополнительные сведения о назначении политики доступа субъекту см. статью «Назначение политики доступа».

Задайте подписку, содержащую ресурс AKV:
```
az account set --subscription $AKV_SUB_ID
```

Задайте политику доступа в AKV:

USER_ID=$(az ad signed-in-user show --query id -o tsv)
az keyvault set-policy -n $AKV_NAME --certificate-permissions create get --key-permissions sign --object-id $USER_ID

Это важно

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

Создание самозаверяющего сертификата в AKV (Azure CLI)

Ниже показано, как создать самозаверяющий сертификат для тестирования.

Создайте файл политики сертификата.

После выполнения файла политики сертификата, как показано ниже, он создает допустимый сертификат, совместимый с требованием сертификата нотаричного проекта в AKV. Значение ekus предназначено для подписи кода, но оно не обязательно для обозначения подписи артефактов. Субъект используется позже в качестве удостоверения личности доверия, которому пользователь доверяет при проверке.
```
cat <<EOF > ./my_policy.json
{
    "issuerParameters": {
    "certificateTransparency": null,
    "name": "Self"
    },
    "keyProperties": {
      "exportable": false,
      "keySize": 2048,
      "keyType": "RSA",
      "reuseKey": true
    },
    "secretProperties": {
      "contentType": "application/x-pem-file"
    },
    "x509CertificateProperties": {
    "ekus": [
        "1.3.6.1.5.5.7.3.3"
    ],
    "keyUsage": [
        "digitalSignature"
    ],
    "subject": "$CERT_SUBJECT",
    "validityInMonths": 12
    }
}
EOF
```

Создайте сертификат.

az keyvault certificate create -n $CERT_NAME --vault-name $AKV_NAME -p @my_policy.json

Подписывание образа контейнера с помощью Notation CLI и подключаемого модуля AKV

Проверка подлинности в ACR с помощью вашего личного удостоверения Azure.
```
az acr login --name $ACR_NAME
```

Это важно

Если у вас установлен Docker на системе и вы использовали az acr login или docker login для аутентификации в вашем ACR, ваши учетные данные уже сохранены и доступны для записей. В этом случае вам не нужно снова запускать notation login, чтобы пройти проверку подлинности в вашем ACR. Дополнительные сведения о параметрах проверки подлинности для нотации см. в статье Аутентификация с помощью реестров, совместимых с OCI.

Создание и отправка нового образа с помощью задач ACR. Всегда используйте значение дайджеста для идентификации изображения для подписывания, так как теги являются изменяемыми и могут быть перезаписаны.
```
DIGEST=$(az acr build -r $ACR_NAME -t $REGISTRY/${REPO}:$TAG $IMAGE_SOURCE --no-logs --query "outputImages[0].digest" -o tsv)
IMAGE=$REGISTRY/${REPO}@$DIGEST
```
В этом руководстве, если образ уже создан и хранится в реестре, тег служит идентификатором этого образа для удобства.
```
IMAGE=$REGISTRY/${REPO}:$TAG
```
Получите идентификатор ключа подписывания. Сертификат в AKV может иметь несколько версий, следующая команда получает идентификатор ключа последней версии.
```
KEY_ID=$(az keyvault certificate show -n $CERT_NAME --vault-name $AKV_NAME --query 'kid' -o tsv)
```

Подписывание образа контейнера с помощью формата подписи COSE с помощью идентификатора ключа подписи. Чтобы подписать с помощью самоподписанного сертификата, необходимо задать значение конфигурации подключаемого модуля self_signed=true.

notation sign --signature-format cose --id $KEY_ID --plugin azure-kv --plugin-config self_signed=true $IMAGE

Для проверки подлинности с помощью AKV по умолчанию следующие типы учетных данных, если они включены, будут проверены в порядке:

Если вы хотите указать тип учетных данных, используйте дополнительную конфигурацию подключаемого модуля credential_type. Например, вы можете явно установить credential_type на azurecli, чтобы использовать учетные данные Azure CLI, как показано ниже:

notation sign --signature-format cose --id $KEY_ID --plugin azure-kv --plugin-config self_signed=true --plugin-config credential_type=azurecli $IMAGE

В таблице ниже приведены значения для различных типов учетных данных credential_type.

Тип учетных данных	Значение для `credential_type`
Учетные данные для среды	`environment`
Идентификационные данные рабочей нагрузки	`workloadid`
Учетные данные для управляемого удостоверения	`managedid`
Учетные данные для входа с помощью Azure CLI	`azurecli`

Просмотрите график подписанных изображений и связанных подписей.
```
notation ls $IMAGE
```

Верификация образа контейнера с помощью CLI Notation

Чтобы проверить образ контейнера, добавьте корневой сертификат, который подписывает конечный сертификат, в хранилище доверия и создайте политики доверия для верификации. Для сертификата, самозаверяющего себя и используемого в этом руководстве, корневой сертификат — это сам сертификат, самозаверяющий себя.

Скачайте общедоступный сертификат.

az keyvault certificate download --name $CERT_NAME --vault-name $AKV_NAME --file $CERT_PATH

Добавьте скачанный общедоступный сертификат в именованное хранилище доверия для проверки подписи.
```
STORE_TYPE="ca"
STORE_NAME="wabbit-networks.io"
notation cert add --type $STORE_TYPE --store $STORE_NAME $CERT_PATH
```
Список сертификатов для подтверждения.
```
notation cert ls
```
Настройте политику доверия перед проверкой.

Политики доверия позволяют пользователям указывать настроенные политики проверки. В следующем примере настраивается политика доверия с именем wabbit-networks-images, которая применяется ко всем артефактам $REGISTRY/$REPO и использует именованное хранилище $STORE_NAME доверия типа $STORE_TYPE. Кроме того, предполагается, что пользователь доверяет определенному удостоверению, идентифицированному по субъекту X.509 $CERT_SUBJECT. Для получения дополнительной информации см. спецификацию хранилища доверия и политики доверия.
```
cat <<EOF > ./trustpolicy.json
{
    "version": "1.0",
    "trustPolicies": [
        {
            "name": "wabbit-networks-images",
            "registryScopes": [ "$REGISTRY/$REPO" ],
            "signatureVerification": {
                "level" : "strict" 
            },
            "trustStores": [ "$STORE_TYPE:$STORE_NAME" ],
            "trustedIdentities": [
                "x509.subject: $CERT_SUBJECT"
            ]
        }
    ]
}
EOF
```
Используется notation policy для импорта конфигурации политики доверия из файла JSON, созданного ранее.
```
notation policy import ./trustpolicy.json
notation policy show
```
Используется notation verify для проверки того, что образ контейнера не был изменен с момента сборки.
```
notation verify $IMAGE
```
После успешной проверки изображения с помощью политики доверия возвращается дайджест sha256 проверенного образа в успешном выходном сообщении.

Установка меток времени

С момента выпуска версии Notation 1.2.0, поддерживается временная метка в соответствии с RFC 3161. Это улучшение расширяет доверие подписей, созданных в течение срока действия сертификата, доверяя центру метки времени (TSA), обеспечивая успешную проверку подписи даже после истечения срока действия сертификатов. В качестве подписанта образов убедитесь, что вы подписываете образы контейнеров с использованием меток времени, созданных доверенным центром сертификации времени (TSA). Чтобы проверить метки времени, убедитесь, что вы доверяете подписывщику изображений и связанному TSA, и установить доверие с помощью хранилищ доверия и политик доверия. Метка времени снижает затраты, устраняя необходимость периодически повторного подписывания образов из-за истечения срока действия сертификата, что особенно важно при использовании краткосрочных сертификатов. Подробные инструкции по подписи и проверке с помощью метки времени см. в руководстве по метке времени нотарии проекта.

Дальнейшие шаги

Нотация предоставляет решения CI/CD в Azure Pipelines и GitHub Actions:

Чтобы подписать и проверить образы контейнеров в пайплайнах ADO, см. раздел Подписывание и проверка образа контейнера с использованием Notation в Azure Pipeline
Чтобы подписать образы контейнеров с помощью GitHub Actions, см. статью "Подпись образа контейнера с использованием нотации GitHub Actions"
Сведения о проверке образов контейнеров с помощью GitHub Actions см. в статье "Проверка образа контейнера с нотацией с помощью GitHub Actions"

Чтобы обеспечить развертывание только доверенных образов контейнеров в службе Azure Kubernetes (AKS):

Используйте целостность образов политики Azure (предварительное), следуя руководству используйте целостность образов для проверки подписанных изображений перед их развертыванием в кластерах службы Azure Kubernetes (AKS) (предварительное)
Используйте Политику Azure , выполнив инструкции по защите рабочих нагрузок AKS: проверка подписей образов контейнера с помощью политики Azure