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.

As a Cloud Build user, 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. Create a JSON file that describes the note:

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

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}"
   

   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"
   

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 lets you use PKIX keys or post-quantum cryptography (PQC) keys to verify attestations. You only need to set up one type of key using one of the following methods:

• Create post-quantum cryptography (PQC) keys: Create PQC keys managed by Cloud Key Management Service to help address threats from future quantum computers.
• Generate a key pair: Create standard PKIX key pairs using Cloud KMS or local tools.

Create post-quantum cryptography (PQC) keys

To provide long-term security and address threats from future quantum computers, Binary Authorization supports keys that use post-quantum cryptography (PQC) algorithms. These algorithms are standardized to be resistant to attacks from both classical and quantum computers.

• Supported algorithms: Binary Authorization supports PQC signature algorithms, such as ML-DSA-65 (Dilithium3), for creating and verifying attestations.
• Key management: We recommend that you manage your PQC keys using Cloud Key Management Service. Cloud KMS provides secure storage and management for these cryptographic keys.

Generate a PQC key pair

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
     

2. 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; ml-dsa-65
   • KMS_PROTECTION_LEVEL: the protection level—for example, software

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

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

4. 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}
   

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.