Create attestors using the gcloud CLI

This page explains how to create an attestor in Binary Authorization using the Google Cloud CLI. As an alternative, you can perform these steps by using the Google Cloud console or the REST API. This task is part of setting up Binary Authorization.

Cloud Build users: you can instead use the built-by-cloud-build attestor to deploy only images built by Cloud Build.

An attestor is a Google Cloud resource that Binary Authorization uses to verify an attestation. To learn more about attestations, see Binary Authorization overview.

To create an attestor you do the following:

• Create a note in Artifact Analysis to store trusted metadata used in the attestation process.
• Set up a Public-Key Infrastructure (X.509) (PKIX) key pair that can be used to verify the identity of the attestor. (Asymmetric key pairs generated by Cloud Key Management Service (Cloud KMS) are in PKIX-compatible format.)
• Create the attestor itself in Binary Authorization, and associate the note and public key you created.

In a single-project setup, you create the attestor in the same Google Cloud project where you configure your Binary Authorization policy. For an end-to-end, single-project tutorial that includes these steps, see Get started using the Google Cloud CLI or Get started using the Google Cloud console.

In a multi-project setup, we recommend that you have separate projects: a deployer project, where your policy is configured; an attestor project, where your attestors are stored; and an attestation project for attestations. For an end-to-end, multi-project tutorial that includes these steps, see multi-project setup.

Before you begin

Before you create attestors, do the following:

1. Enable Binary Authorization.

2. Set up Binary Authorization for your platform.

Set up the project environment

In this section, you set up environment variables.

Set up environment variables to store your project names and numbers. If your attestor and deployer projects are the same project, use the same project ID for both variables.

DEPLOYER_PROJECT_ID=DEPLOYER_PROJECT_ID=
DEPLOYER_PROJECT_NUMBER="$(
    gcloud projects describe "${DEPLOYER_PROJECT_ID}" \
      --format="value(projectNumber)"
)"

ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
ATTESTOR_PROJECT_NUMBER="$(
    gcloud projects describe "${ATTESTOR_PROJECT_ID}" \
    --format="value(projectNumber)"
)"

You must also get the service account names for the projects:

DEPLOYER_SERVICE_ACCOUNT="service-${DEPLOYER_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
ATTESTOR_SERVICE_ACCOUNT="service-${ATTESTOR_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

Create a Artifact Analysis note

Binary Authorization uses Artifact Analysis to store trusted metadata used in the authorization process. For each attestor you create, you must create one Artifact Analysis note. Each attestation is stored as an occurrence of this note.

To create the note, follow these steps:

1. Set up environment variables to store the note ID and a human-readable description:

   NOTE_ID=NOTE_ID
   NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
   DESCRIPTION=DESCRIPTION
   

   Replace the following:

   • NOTE_ID: the internal name of the note in alphanumeric characters with no spaces—for example, test-attestor-note
   • NOTE_URI: the fully-qualified path to the note resource
   • DESCRIPTION: a human-readable display name for the note—for example, Test Attestor Note

2. In a text editor, create a JSON file that describes the note:

   cat > /tmp/note_payload.json << EOM
   {
     "name": "${NOTE_URI}",
     "attestation": {
       "hint": {
         "human_readable_name": "${DESCRIPTION}"
       }
     }
   }
   EOM
   

3. Create the note by sending an HTTP request to the Artifact Analysis REST API:

   curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
       -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
       --data-binary @/tmp/note_payload.json  \
       "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/?noteId=${NOTE_ID}"
   

   Caution: Binary Authorization doesn't support Artifact Analysis regional storage or regional endpoints. We recommend that you use the Artifact Analysis global API endpoint (https://containeranalysis.googleapis.com/).

   To verify that the note was created successfully, run the following command:

   curl \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
       -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
       "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/"
   

Set IAM permissions on the note

You must grant an Identity and Access Management (IAM) role to the attestor project service account on the Artifact Analysis note resource. You do this by adding the attestor project service account to the containeranalysis.notes.occurrences.viewer role in the note's IAM policy.

To add the role, do the following:

1. Generate a JSON file that contains the information needed to set the IAM role on your note:

   cat > /tmp/iam_request.json << EOM
   {
     "resource": "${NOTE_URI}",
     "policy": {
       "bindings": [
         {
           "role": "roles/containeranalysis.notes.occurrences.viewer",
           "members": [
             "serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}"
           ]
         }
       ]
     }
   }
   EOM
   

2. Add the service account and requested access roles to the IAM policy for the note you created:

   curl -X POST  \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
       --data-binary @/tmp/iam_request.json \
       "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}:setIamPolicy"
   

   Note: When you add a role to the policy using the above method, it replaces any existing roles on the note. If you want to preserve existing roles, make sure that you include them in the preceding JSON data file.

Multi-project use

If you store the attestor in one project and you deploy in a separate project, you must grant the roles/binaryauthorization.attestorsVerifier role to the service account associated with the deployer project on the attestor.

Set up cryptographic keys

Binary Authorization allows you to use PKIX keys to verify attestations.

Generate a key pair

In this guide, you use the recommended Elliptic Curve Digital Signature Algorithm (ECDSA) to generate a PKIX key pair. You can also use RSA or PGP key pairs. See Key purposes and algorithms for more information on signing algorithms.

A PKIX key pair comprises a private key that signers use to sign attestations, and a public key that you add to the attestor. At deployment time, Binary Authorization uses this public key to verify the attestation.

PKIX (Cloud KMS)

To create the key pair in Cloud KMS, do the following:

1. To set up environment variables needed to create the key pair, run the following commands:

   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
   KMS_KEY_PURPOSE=asymmetric-signing
   KMS_KEY_ALGORITHM=KMS_KEY_ALGORITHM
   KMS_PROTECTION_LEVEL=KMS_PROTECTION_LEVEL
   

   Replace the following:

   • KMS_KEY_PROJECT_ID: the ID of the project where the keys are stored
   • KMS_KEY_LOCATION: the location of the key
   • KMS_KEYRING_NAME: the name of the key ring
   • KMS_KEY_NAME: the name of the key
   • KMS_KEY_VERSION: the key version
   • KMS_KEY_ALGORITHM: the algorithm; ec-sign-p256-sha256 is recommended
   • KMS_PROTECTION_LEVEL: the protection level—for example, software

2. To create the key ring, run the following command:

   gcloud kms keyrings create ${KMS_KEYRING_NAME} \
       --location ${KMS_KEY_LOCATION}
   

3. To create the key, run the following command:

   gcloud kms keys create ${KMS_KEY_NAME} \
       --location ${KMS_KEY_LOCATION} \
       --keyring ${KMS_KEYRING_NAME}  \
       --purpose ${KMS_KEY_PURPOSE} \
       --default-algorithm ${KMS_KEY_ALGORITHM} \
       --protection-level ${KMS_PROTECTION_LEVEL}
   

   Replace the following:

   • KMS_KEY_NAME: the name of the key
   • KMS_KEY_LOCATION: the location of the key
   • KMS_KEYRING_NAME: the name of the key ring
   • KMS_KEY_PURPOSE: the purpose of the key, set to ASYMMETRIC_SIGN
   • KMS_KEY_ALGORITHM: the algorithm, ec-sign-p256-sha256 is recommended
   • KMS_PROTECTION_LEVEL: the protection level—for example, software

PKIX (local key)

Warning: We strongly recommend against using locally generated key pairs in production environments as they present a security risk. We recommend that you instead use Cloud Key Management Service. This example is provided for illustrative purposes only.

To generate a new local asymmetric PKIX key pair and store it in a file, do the following:

1. Generate the private key:

   PRIVATE_KEY_FILE is the name of the file containing the private key used for signing the attestation payload.

   PRIVATE_KEY_FILE="/tmp/ec_private.pem"
   openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}
   

2. Extract the public key from the private key and store it in a file:

   PUBLIC_KEY_FILE is the name of the file containing the public key that is stored in the attestor.

   PUBLIC_KEY_FILE="/tmp/ec_public.pem"
   openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
   

Create the attestor

To create the attestor, follow these steps:

1. Set up an environment variable to store the name of the attestor as defined in Binary Authorization:

   ATTESTOR_NAME=ATTESTOR_NAME
   

   where ATTESTOR_NAME is the name of the attestor you want to create (for example, build-secure or prod-qa).

2. Create the attestor resource in Binary Authorization:

   gcloud --project="${ATTESTOR_PROJECT_ID}" \
       container binauthz attestors create "${ATTESTOR_NAME}" \
       --attestation-authority-note="${NOTE_ID}" \
       --attestation-authority-note-project="${ATTESTOR_PROJECT_ID}"
   

3. Add an IAM role binding for the deployer project to the attestor. This is used by Binary Authorization when it evaluates a policy to determine whether the project has permissions to access any associated attestations.

   gcloud container binauthz attestors add-iam-policy-binding \
       "projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
       --member="serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}" \
       --role=roles/binaryauthorization.attestorsVerifier
   

4. To add the public key to the attestor, do the following:

   PKIX (Cloud KMS)

   To add the public key from a Cloud KMS key pair to the attestor, run the following command:

   gcloud --project="${ATTESTOR_PROJECT_ID}" \
       container binauthz attestors public-keys add \
       --attestor="${ATTESTOR_NAME}" \
       --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}"
   

   PKIX (local key)

   To add a locally stored PKIX public key to an attestor, run the following command:

   gcloud --project="${ATTESTOR_PROJECT_ID}" \
       container binauthz attestors public-keys add \
       --attestor="${ATTESTOR_NAME}" \
       --pkix-public-key-file=${PUBLIC_KEY_FILE} \
       --pkix-public-key-algorithm=ecdsa-p256-sha256
   

   If you add a public key to an attestor and don't specify a key ID (which can be any string), it is automatically be given one in the RFC 6920 format: ni:///sha-256;..., where ... is an encoded hash of the public key. This value is returned in the id field of the command output. The returned ID can be saved in PUBLIC_KEY_ID and used to create an attestation.

Save the public key ID

To create an attestation, you need the public key ID.

To save the public key ID, you can copy it from the output of the binauthz attestors public-keys add command, above.

Alternatively, you can view your attestor's public key ID at any time using the following command:

gcloud container binauthz attestors describe ${ATTESTOR}.

To save your public key ID in an environment variable, enter the following command:

PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \
--format='value(userOwnedGrafeasNote.publicKeys[0].id)')

Verify that the attestor was created

To verify that the attestor was created, run the following command:

gcloud container binauthz attestors list \
    --project="${ATTESTOR_PROJECT_ID}"

What's next

• Learn how to create attestations for your attestor.
• Update your Binary Authorization policy to require attestations using the Google Cloud console, the Google Cloud CLI, and the REST API.