Azure Container Registry におけるコンテンツの信頼Content trust in Azure Container Registry

Azure Container Registry では、Docker のコンテンツの信頼モデルを実装し、署名済みのイメージのプッシュとプルを有効にします。Azure Container Registry implements Docker's content trust model, enabling pushing and pulling of signed images. この記事では、コンテナー レジストリ内でコンテンツの信頼を有効にする方法について説明します。This article gets you started enabling content trust in your container registries.

注意

コンテンツの信頼は、Azure Container Registry の Premium SKU の機能です。Content trust is a feature of the Premium SKU of Azure Container Registry.

コンテンツの信頼の動作概念How content trust works

セキュリティを考慮して設計されたあらゆる分散システムにとって大切なことは、システムに入力されるデータの "ソース" と "整合性" の両方を確認することです。Important to any distributed system designed with security in mind is verifying both the source and the integrity of data entering the system. データのコンシューマーは、データの公開元 (ソース) を確認できること、またデータが公開後に改変されていないこと (整合性) を確認できることが必要です。Consumers of the data need to be able to verify both the publisher (source) of the data, as well as ensure it's not been modified after it was published (integrity).

レジストリにプッシュするイメージには、イメージの発行者がコンテンツの信頼を通じて署名することができます。As an image publisher, content trust allows you to sign the images you push to your registry. イメージのコンシューマー (レジストリからイメージをプルする人またはシステム) は、署名済みのイメージのみをプルするように各自のクライアントを構成することができます。Consumers of your images (people or systems pulling images from your registry) can configure their clients to pull only signed images. 署名済みのイメージをそのコンシューマーがプルすると、Docker クライアントによってイメージの整合性が確認されます。When an image consumer pulls a signed image, their Docker client verifies the integrity of the image. このモデルでは、レジストリに存在する署名済みのイメージが確かに本人によって発行され、また発行された後に改変されていないという確信をコンシューマーは得ることができます。In this model, consumers are assured that the signed images in your registry were indeed published by you, and that they've not been modified since being published.

信頼済みのイメージTrusted images

コンテンツの信頼は、リポジトリ内のタグと連動します。Content trust works with the tags in a repository. イメージ リポジトリは、署名済みのタグを持ったイメージと署名されていないタグを持ったイメージの両方を格納できます。Image repositories can contain images with both signed and unsigned tags. たとえば、署名の対象を myimage:stablemyimage:latest のイメージに限定し、myimage:dev には署名しないといったことが考えられます。For example, you might sign only the myimage:stable and myimage:latest images, but not myimage:dev.

署名キーSigning keys

コンテンツの信頼は、一連の暗号署名キーを使って管理されます。Content trust is managed through the use of a set of cryptographic signing keys. これらのキーは、レジストリ内の特定のリポジトリ関連付けられます。These keys are associated with a specific repository in a registry. Docker クライアントとご利用のレジストリがリポジトリ内のタグに対する信頼を管理する際に使用する署名キーには、いくつかの種類があります。There are several types of signing keys that Docker clients and your registry use in managing trust for the tags in a repository. コンテンツの信頼を有効にしてコンテナー発行/消費パイプラインに統合するときは、それらのキーを慎重に管理する必要があります。When you enable content trust and integrate it into your container publishing and consumption pipeline, you must manage these keys carefully. 詳細については、この記事の後半にある「キー管理」および Docker ドキュメントの「Manage keys for content trust (コンテンツの信頼に使用するキーの管理)」を参照してください。For more information, see Key management later in this article and Manage keys for content trust in the Docker documentation.

ヒント

これは Docker のコンテンツ信頼モデルをごく簡単に説明したものです。This was a very high-level overview of Docker's content trust model. コンテンツの信頼についての詳細な解説については、「Content trust in Docker (Docker におけるコンテンツの信頼)」を参照してください。For an in-depth discussion of content trust, see Content trust in Docker.

レジストリのコンテンツの信頼を有効にするEnable registry content trust

まず、コンテンツの信頼をレジストリ レベルで有効にしましょう。Your first step is to enable content trust at the registry level. コンテンツの信頼を有効にした後、クライアント (ユーザーまたはサービス) は、署名済みのイメージをレジストリにプッシュすることができます。Once you enable content trust, clients (users or services) can push signed images to your registry. レジストリに対してコンテンツの信頼を有効にしたからといって、コンテンツの信頼を有効にしているコンシューマーにレジストリの使用が限定されることはありません。Enabling content trust on your registry does not restrict registry usage only to consumers with content trust enabled. コンテンツの信頼を有効にしていないコンシューマーも引き続き、通常どおりにレジストリを使うことができます。Consumers without content trust enabled can continue to use your registry as normal. 一方、クライアントでコンテンツの信頼を有効にしているコンシューマーは、レジストリ内の署名済みのイメージのみを表示することができます。Consumers who have enabled content trust in their clients, however, will be able to see only signed images in your registry.

レジストリに対してコンテンツの信頼を有効にするには、まず Azure portal で目的のレジストリに移動します。To enable content trust for your registry, first navigate to the registry in the Azure portal. [ポリシー] で、 [コンテンツの信頼] > [有効] > [保存] の順に選択します。Under Policies, select Content Trust > Enabled > Save.

Azure portal でレジストリに対するコンテンツの信頼を有効にする

クライアントのコンテンツの信頼を有効にするEnable client content trust

信頼済みのイメージを取り扱うためには、イメージの発行者とコンシューマーの双方が、その Docker クライアントに対してコンテンツの信頼を有効にする必要があります。To work with trusted images, both image publishers and consumers need to enable content trust for their Docker clients. パブリッシャーは、コンテンツの信頼が有効になっているレジストリに関して、そこにプッシュするイメージに署名することができます。As a publisher, you can sign the images you push to a content trust-enabled registry. コンシューマーは、コンテンツの信頼を有効にすることで、レジストリの表示を署名済みのイメージのみに限定することができます。As a consumer, enabling content trust limits your view of a registry to signed images only. Docker クライアントでは、コンテンツの信頼が既定では無効になっていますが、シェル セッションごと、またはコマンドごとにコンテンツの信頼を有効にすることができます。Content trust is disabled by default in Docker clients, but you can enable it per shell session or per command.

シェル セッションに関してコンテンツの信頼を有効にするには、DOCKER_CONTENT_TRUST 環境変数を 1 に設定します。To enable content trust for a shell session, set the DOCKER_CONTENT_TRUST environment variable to 1. たとえば、Bash シェルで次のように入力します。For example, in the Bash shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

一方、個々のコマンドに関してコンテンツの信頼を有効または無効にしたい場合、いくつかの Docker コマンドでは、--disable-content-trust 引数がサポートされています。If instead you'd like to enable or disable content trust for a single command, several Docker commands support the --disable-content-trust argument. 個々のコマンドでコンテンツの信頼を有効にするには、次のようにします。To enable content trust for a single command:

# Enable content trust for single command
docker build --disable-content-trust=false -t myacr.azurecr.io/myimage:v1 .

シェル セッションに関してコンテンツの信頼を有効にした場合で、かつ特定のコマンドについてはコンテンツの信頼を無効にしたい場合は、次のようにします。If you've enabled content trust for your shell session and want to disable it for a single command:

# Disable content trust for single command
docker build --disable-content-trust -t myacr.azurecr.io/myimage:v1 .

イメージに署名するためのアクセス許可を与えるGrant image signing permissions

信頼済みのイメージをレジストリにプッシュできるのは、アクセス許可が与えられたユーザーまたはシステムだけです。Only the users or systems you've granted permission can push trusted images to your registry. 信頼済みのイメージをプッシュするアクセス許可をユーザー (またはサービス プリンシパルを使用するシステム) に与えるには、その Azure Active Directory ID に AcrImageSigner ロールを与えます。To grant trusted image push permission to a user (or a system using a service principal), grant their Azure Active Directory identities the AcrImageSigner role. レジストリにイメージをプッシュするために必要な AcrPush (または同等の) ロールとは別に、これを追加することになります。This is in addition to the AcrPush (or equivalent) role required for pushing images to the registry. 詳細については、「Azure Container Registry のロールとアクセス許可」を参照してください。For details, see Azure Container Registry roles and permissions.

以降、Azure portal と Azure CLI から AcrImageSigner ロールを付与する方法について詳しく説明します。Details for granting the AcrImageSigner role in the Azure portal and the Azure CLI follow.

Azure ポータルAzure portal

Azure portal でレジストリに移動し、 [アクセス制御 (IAM)] > [ロール割り当ての追加] を選択します。Navigate to your registry in the Azure portal, then select Access control (IAM) > Add role assignment. [ロール割り当ての追加][ロール] で [AcrImageSigner] を選択し、ユーザーまたはサービス プリンシパルを選択して (複数可)、 [保存] を選択します。Under Add role assignment, select AcrImageSigner under Role, then Select one or more users or service principals, then Save.

この例では、AcrImageSigner ロールが 2 つのエンティティに割り当てられています。"service-principal" という名前のサービス プリンシパルと "Azure User" という名前のユーザーです。In this example, two entities have been assigned the AcrImageSigner role: a service principal named "service-principal," and a user named "Azure User."

Azure portal でレジストリに対するコンテンツの信頼を有効にする

Azure CLIAzure CLI

署名のためのアクセス許可を Azure CLI を使ってユーザーに与えるには、特定のレジストリを有効範囲として AcrImageSigner ロールをユーザーに割り当てます。To grant signing permissions to a user with the Azure CLI, assign the AcrImageSigner role to the user, scoped to your registry. コマンドの形式は次のとおりです。The format of the command is:

az role assignment create --scope <registry ID> --role AcrImageSigner --assignee <user name>

たとえば、このロールを自分自身に与えるには、認証済みの Azure CLI セッションで次のコマンドを実行します。For example, to grant yourself the role, you can run the following commands in an authenticated Azure CLI session. REGISTRY の値は、実際の Azure Container Registry の名前に合わせて変更してください。Modify the REGISTRY value to reflect the name of your Azure container registry.

# Grant signing permissions to authenticated Azure CLI user
REGISTRY=myregistry
USER=$(az account show --query user.name --output tsv)
REGISTRY_ID=$(az acr show --name $REGISTRY --query id --output tsv)

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee $USER

信頼済みのイメージをレジストリにプッシュするための権限をサービス プリンシパルに与えることもできます。You can also grant a service principal the rights to push trusted images to your registry. サービス プリンシパルは、信頼済みのイメージをレジストリにプッシュする必要のある無人のシステム (ビルド システムなど) で使用できます。Using a service principal is useful for build systems and other unattended systems that need to push trusted images to your registry. その形式は、ユーザーにアクセス許可を与えるときと同様ですが、--assignee の値に指定するのはサービス プリンシパル ID となります。The format is similar to granting a user permission, but specify a service principal ID for the --assignee value.

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee <service principal ID>

<service principal ID> には、サービス プリンシパルの appIdobjectId、またはその servicePrincipalNames を指定できます。The <service principal ID> can be the service principal's appId, objectId, or one of its servicePrincipalNames. サービス プリンシパルと Azure Container Registry の取り扱いについて詳しくは、「サービス プリンシパルによる Azure Container Registry 認証」をご覧ください。For more information about working with service principals and Azure Container Registry, see Azure Container Registry authentication with service principals.

ロールが変更されたら、新しいロールを有効にするために、az acr login を実行して Azure CLI のローカル ID トークンを更新します。After any role changes, run az acr login to refresh the local identity token for the Azure CLI so that the new roles can take effect.

信頼済みのイメージをプッシュするPush a trusted image

信頼済みのイメージのタグをコンテナー レジストリにプッシュするには、コンテンツの信頼を有効にし、docker push でイメージをプッシュします。To push a trusted image tag to your container registry, enable content trust and push the image with docker push. 署名済みのタグを初めてプッシュするとき、ルート署名キーとリポジトリ署名キーの両方のパスフレーズを作成するように求められます。The first time you push a signed tag, you're asked to create a passphrase for both a root signing key and a repository signing key. ルート キーとリポジトリ キーは、どちらもマシンのローカルで生成されて格納されます。Both the root and repository keys are generated and stored locally on your machine.

$ docker push myregistry.azurecr.io/myimage:v1
The push refers to repository [myregistry.azurecr.io/myimage]
ee83fc5847cb: Pushed
v1: digest: sha256:aca41a608e5eb015f1ec6755f490f3be26b48010b178e78c00eac21ffbe246f1 size: 524
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 4c6c56a:
Repeat passphrase for new root key with ID 4c6c56a:
Enter passphrase for new repository key with ID bcd6d98:
Repeat passphrase for new repository key with ID bcd6d98:
Finished initializing "myregistry.azurecr.io/myimage"
Successfully signed myregistry.azurecr.io/myimage:v1

コンテンツの信頼を有効にした状態で初めて docker push を実行した後、それ以降のプッシュには、同じルート キーが Docker クライアントで使用されます。After your first docker push with content trust enabled, the Docker client uses the same root key for subsequent pushes. それ以降は、同じリポジトリに対してプッシュするたびに、リポジトリ キーのみが求められます。On each subsequent push to the same repository, you're asked only for the repository key. 信頼済みイメージのプッシュ先となるリポジトリが変わると、その都度、新しいリポジトリ キーのパスフレーズを入力するよう求められます。Each time you push a trusted image to a new repository, you're asked to supply a passphrase for a new repository key.

信頼済みのイメージをプルするPull a trusted image

信頼済みのイメージをプルするには、コンテンツの信頼を有効にして、通常どおりに docker pull コマンドを実行します。To pull a trusted image, enable content trust and run the docker pull command as normal. 通常のユーザーが信頼済みのイメージをプルするには、AcrPull ロールがあれば十分です。To pull trusted images, the AcrPull role is enough for normal users. AcrImageSigner ロールなどの追加のロールは不要です。No additional roles like an AcrImageSigner role are required. コンテンツの信頼を有効にしているコンシューマーは、署名済みタグの付いたイメージだけをプルすることができます。Consumers with content trust enabled can pull only images with signed tags. 以下に示したのは、署名済みのタグをプルする例です。Here's an example of pulling a signed tag:

$ docker pull myregistry.azurecr.io/myimage:signed
Pull (1 of 1): myregistry.azurecr.io/myimage:signed@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b: Pulling from myimage
8e3ba11ec2a2: Pull complete
Digest: sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Status: Downloaded newer image for myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Tagging myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b as myregistry.azurecr.io/myimage:signed

コンテンツの信頼を有効にしているクライアントが、署名されていないタグをプルしようとしても、その操作は失敗します。If a client with content trust enabled tries to pull an unsigned tag, the operation fails:

$ docker pull myregistry.azurecr.io/myimage:unsigned
No valid trust data for unsigned

バックグラウンド処理Behind the scenes

docker pull を実行すると、Docker クライアントは、プル対象のタグについて、Notary CLI で使われているものと同じライブラリを使って、タグから SHA-256 ダイジェストへのマッピングを要求します。When you run docker pull, the Docker client uses the same library as in the Notary CLI to request the tag-to-SHA-256 digest mapping for the tag you're pulling. クライアントは信頼データの署名を確認した後、"ダイジェストでプル" するよう Docker Engine に命令を出します。After validating the signatures on the trust data, the client instructs Docker Engine to do a "pull by digest." このエンジンが、プルの実行中、SHA-256 チェックサムをコンテンツのアドレスとして使い、Azure Container Registry にイメージのマニフェストを要求して検証します。During the pull, the Engine uses the SHA-256 checksum as a content address to request and validate the image manifest from the Azure container registry.

キー管理Key management

信頼済みのイメージを初めてプッシュするときの docker push 出力に記載されているように、ルート キーはきわめて機微な情報です。As stated in the docker push output when you push your first trusted image, the root key is the most sensitive. ルート キーは必ずバックアップして、安全な場所に保管してください。Be sure to back up your root key and store it in a secure location. ルート キーは必ずバックアップを作成して、安全な場所に保管してください。By default, the Docker client stores signing keys in the following directory:

~/.docker/trust/private

ルート キーとリポジトリ キーをバックアップする際は、それらを圧縮してアーカイブし、安全にオフラインで (USB 記憶装置などに) 保管してください。Back up your root and repository keys by compressing them in an archive and storing it securely offline (such as on a USB storage device). たとえば Bash の場合は次のようになります。For example, in Bash:

umask 077; tar -zcvf docker_private_keys_backup.tar.gz ~/.docker/trust/private; umask 022

信頼済みのイメージをプッシュするとき、ローカルで生成されるルート キーとリポジトリ キーの他に、いくつかのキーが Azure Container Registry により生成されて格納されます。Along with the locally generated root and repository keys, several others are generated and stored by Azure Container Registry when you push a trusted image. Docker の実装によるコンテンツの信頼で用いられる各種キーに関して、管理上の詳しいガイダンスを含む詳細については、Docker のドキュメントの「Manage keys for content trust (コンテンツの信頼に使用するキーの管理)」を参照してください。For a detailed discussion of the various keys in Docker's content trust implementation, including additional management guidance, see Manage keys for content trust in the Docker documentation.

ルート キーの紛失Lost root key

ルート キーが利用できなくなった場合、そのキーでタグが署名されているリポジトリ内の署名済みのタグにはアクセスできなくなります。If you lose access to your root key, you lose access to the signed tags in any repository whose tags were signed with that key. 紛失したルート キーで署名されたイメージ タグへのアクセスを Azure Container Registry で復元することはできません。Azure Container Registry cannot restore access to image tags signed with a lost root key. レジストリのすべての信頼データ (署名) を削除するには、まずそのレジストリに対するコンテンツの信頼を無効にしてから再度有効にしてください。To remove all trust data (signatures) for your registry, first disable, then re-enable content trust for the registry.

警告

レジストリのコンテンツの信頼を無効にしてから再度有効にすると、そのレジストリの各リポジトリに存在するすべての署名済みタグの信頼データがすべて削除されますDisabling and re-enabling content trust in your registry deletes all trust data for all signed tags in every repository in your registry. この操作を元に戻すことはできません。つまり削除された信頼データを Azure Container Registry で復旧することはできません。This action is irreversible--Azure Container Registry cannot recover deleted trust data. コンテンツの信頼を無効にしても、イメージそのものは削除されません。Disabling content trust does not delete the images themselves.

レジストリに対してコンテンツの信頼を無効にするには、Azure portal で目的のレジストリに移動します。To disable content trust for your registry, navigate to the registry in the Azure portal. [ポリシー] で、 [コンテンツの信頼] > [無効] > [保存] の順に選択します。Under Policies, select Content Trust > Disabled > Save. レジストリ内の署名がすべて失われるという警告が表示されます。You're warned of the loss of all signatures in the registry. そのレジストリ内のすべての署名を完全に削除する場合は、 [OK] を選択してください。Select OK to permanently delete all signatures in your registry.

Azure portal でレジストリに対するコンテンツの信頼を無効にする

次の手順Next steps

コンテンツの信頼の詳細については、Docker のコンテンツの信頼に関するページを参照してください。See Content trust in Docker for additional information about content trust. この記事では要点を絞って説明しましたが、コンテンツの信頼は広範囲に及ぶテーマです。Docker のドキュメントで、さらに踏み込んだ情報を得ることができるでしょう。While several key points were touched on in this article, content trust is an extensive topic and is covered more in-depth in the Docker documentation.