Creating attestations

This page explains how to create an attestation in Binary Authorization from the command line.

The instructions on this page outline the steps that an attestor needs to perform in order to authorize a container image for deployment. In a real-world scenario, you incorporate these steps into a script or automation that can be triggered by machine process or a human user, rather than enter them manually at the command line.

Overview

An attestation is a statement by an attestor that a required process in your pipeline has been completed and that a container image is authorized for deployment. The attestation itself is a digitally-signed record that contains the full path to a version of the image as stored in your container image registry, as well as the identity of the attestor.

You can create an attestation using either a PGP or PKIX signature.

Set the default project

If you have not already set your default Google Cloud Platform project:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

where PROJECT_ID is the name of your project.

Set up the environment

Set up environment variables to store the name of the attestor who is making the attestation and the registry path to the image you want to deploy:

ATTESTOR=ATTESTOR_NAME
IMAGE_PATH=IMAGE_PATH
IMAGE_DIGEST=IMAGE_DIGEST
IMAGE_TO_ATTEST=${IMAGE_PATH}@${IMAGE_DIGEST}

where:

  • ATTESTOR_NAME is the name of the attestor (for example, build-secure or prod-qa)
  • IMAGE_PATH is the path in Container Registry to the image you want to deploy (for example, gcr.io/example-project/quickstart-image)
  • IMAGE_DIGEST is the SHA-256 digest of the image manifest. For information on getting the image digest, see Listing the versions of an image in Container Registry

Each container image stored in Container Registry or another registry has a unique path to its location, as well as a SHA-256 digest that uniquely identifies its version. Attestations reference the full image path and digest, which allows you to authorize specific versions of an image.

The following is an example of a full registry path:

gcr.io/example-project/quickstart-image@sha256:bedb3feb23e81d162e33976fd7b245adff00379f4755c0213e84405e5b1e0988

Create an attestation with a PGP signature

For attestations signed with a PGP public key, you do the following:

  • Create an attestation payload to send to Binary Authorization that references the registry path
  • Sign the payload and generate a PGP signature file
  • Get the public key fingerprint
  • Create the attestation with the signature file and public key fingerprint

Create an attestation payload

The attestation payload is a JSON-formatted file that references the location of the container image.

To create the payload file:

gcloud beta container binauthz create-signature-payload \
    --artifact-url="${IMAGE_TO_ATTEST}" > /tmp/generated_payload.json

The payload file looks similar to the following:

{
  "critical": {
    "identity": {
      "docker-reference": "gcr.io/example-project/quickstart-image
    },
    "image": {
      "docker-manifest-digest": "sha256:bedb3feb23e81d162e33976fd7b245
adff00379f4755c0213e84405e5b1e0988"
    },
    "type": "Google cloud binauthz container signature"
  }
}

Sign the payload and generate a signature file

After you have created the payload file, you must sign it using the public cryptographic key you generated when you created the attestor using the CLI or console.

To sign the payload file:

  1. Set up an environment variable to store the e-mail of the attestor as defined when you generated the PGP key pair:

    ATTESTOR_EMAIL=ATTESTOR_EMAIL
    
  2. Sign the generated payload:

    gpg \
        --local-user "${ATTESTOR_EMAIL}" \
        --armor \
        --output /tmp/generated_signature.pgp \
        --sign /tmp/generated_payload.json
    

The output file is a digitally-signed version of the payload file you created above.

Get the public key fingerprint

You must send a public key fingerprint to Binary Authorization along with the signature file when you create an attestation.

To get the public key fingerprint:

  1. Get the key details:

    gpg --list-keys ${ATTESTOR_EMAIL}
    

    This command prints a message similar to the following:

    pub   rsa2048 2018-07-05 [SCEA]
          PUBLIC_KEY_FINGERPRINT
    uid           [ultimate] "Test Attestor" <"attestor@example.com">
    

    where PUBLIC_KEY_FINGERPRINT is the version 4, full 160-bit fingerprint, expressed as a 40 character hexadecimal string, such as ABAB2098B3F5F05FF0D12ABE45895BDDDCD17B90. See the OpenPGP RFC for more information on PGP fingerprints.

  2. Set up an environment variable to store the fingerprint:

    PUBLIC_KEY_FINGERPRINT=PUBLIC_KEY_FINGERPRINT
    

Create the attestation

To create the attestation:

gcloud beta container binauthz attestations create \
    --artifact-url="${IMAGE_TO_ATTEST}" \
    --attestor="projects/${PROJECT_ID}/attestors/${ATTESTOR}" \
    --signature-file=/tmp/generated_signature.pgp \
    --pgp-key-fingerprint="${PUBLIC_KEY_FINGERPRINT}"

Create an attestation with a PKIX signature

To create an attestation with PKIX signature:

  1. Set up environment variables to store information about the projects where your attestations, attestors and Cloud Key Management Service keys are stored, as well as information about your PKIX key pair:

    ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
    ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
    KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
    KMS_KEY_LOCATION=KMS_KEY_LOCATION
    KMS_KEYRING_NAME=KMS_KEYRING_NAME
    KMS_KEY_NAME=KMS_KEY_NAME
    KMS_KEY_VERSION=KMS_KEY_VERSION
    

    where:

    • ATTESTATION_PROJECT_ID is the ID of the project where your attestations are stored
    • ATTESTOR_PROJECT_ID is the ID of the project where your attestors are stored
    • KMS_KEY_PROJECT_ID is the ID of the project where your Cloud Key Management Service keys are stored
    • KMS_KEY_LOCATION is the location of the key (global is the default)
    • KMS_KEYRING_NAME is the name of the key ring
    • KMS_KEY_NAME is the name of the key
    • KMS_KEY_VERSION is the key version
  2. Create and upload the signed attestation:

    gcloud --project="${ATTESTATION_PROJECT_ID}"
        alpha container binauthz attestations sign-and-create \
        --artifact-url="${IMAGE_TO_ATTEST}" \
        --attestor="${ATTESTOR}" \
        --attestor-project="${ATTESTOR_PROJECT_ID}" \
        --keyversion-project="${KMS_KEY_PROJECT_ID}" \
        --keyversion-location="${KMS_KEY_LOCATION}" \
        --keyversion-keyring="${KMS_KEYRING_NAME}" \
        --keyversion-key="${KMS_KEY_NAME}" \
        --keyversion="${KMS_KEY_VERSION}"
    

Verify that the attestation was created

gcloud beta container binauthz attestations list \
    --attestor="projects/${PROJECT_ID}/attestors/${ATTESTOR}"

What's next

هل كانت هذه الصفحة مفيدة؟ يرجى تقييم أدائنا:

إرسال تعليقات حول...

Binary Authorization Documentation