Create attestors using the Google Cloud console

This page explains how to create a custom attestor in Binary Authorization by using the Google Cloud console. As an alternative, you can also perform these steps by using the Google Cloud CLI, 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.

Before you begin

Before you create attestors, do the following:

1. Enable Binary Authorization.

2. Set up Binary Authorization for your platform.

Overview

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

To create an attestor, you do the following:

• Set up a key pair that can be used to first sign an image, creating an attestation, and later verify the image, when it's being deployed. PKIX key pairs are key pairs that are generated by Cloud Key Management Service (Cloud KMS) in PKIX-compatible format.
• Create the attestor itself in Binary Authorization and associate the public key that you created

In a single-project setup, you create your attestor in the same project as you configure your Binary Authorization policy. In a multi-project setup, you most likely have a deployer project where your policy is configured and a separate attestor project where your attestors are stored.

Set up cryptographic keys

Binary Authorization lets you use PKIX keys to securely sign an image and then later verify it. This ensures that only verified parties can authorize a container image. To use attestation, you set up asymmetric keys, such as Public-Key Infrastructure (X.509) (PKIX) keys, to securely verify the identity of attestors. When an image is deployed Binary Authorization checks the image's attestation, that was signed with the private key, using the public key in the attestor.

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

Create a PKIX key pair

Binary Authorization lets you use asymmetric PKIX key pairs to sign and verify an image.

A PKIX key pair consists of a private key, which the signer uses to digitally sign attestations, and a public key, which you add to the attestor. At deploy time, Binary Authorization uses this public key to verify the attestation signed by the private key.

The asymmetric key pairs generated and stored in Cloud KMS are compliant with the PKIX format. To create a Cloud KMS key for use with Binary Authorization, see Creating Asymmetric Keys. Make sure that you choose Asymmetric Sign as the key purpose when you create the key.

Note: Skip this step if you have already created keys.

PKIX (Cloud KMS)

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

1. Set up environment variables needed to create the key pair.

   KMS_KEY_PROJECT_ID=${PROJECT_ID}
   KMS_KEYRING_NAME=my-binauthz-keyring
   KMS_KEY_NAME=my-binauthz-kms-key-name
   KMS_KEY_LOCATION=global
   KMS_KEY_PURPOSE=asymmetric-signing
   KMS_KEY_ALGORITHM=ec-sign-p256-sha256
   KMS_PROTECTION_LEVEL=software
   KMS_KEY_VERSION=1
   

2. Create the keyring.

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

3. Create the key:

   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}
   

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 key:

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

2. Since this file contains a public and private key together, you need to extract the public key into a separate file so you can add it to the attestor:

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

Create the attestor

The next step is to create the attestor itself and to associate a Artifact Analysis note and public key.

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 attestor:

1. Go to the Binary Authorization page for the attestor project.

   Go to Binary Authorization

2. In the Attestors tab, click Create.

3. Click Create New Attestor.

4. In Attestor Name, enter a name for the attestor (for example, build-secure or prod-qa).

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

   PKIX (local key)

   1. Click Add a PKIX Key.
   2. Click Import from file.
   3. Navigate to and select the PKIX key file you saved earlier. Note: You can also paste a public key in PEM format.
   4. Select the Signature algorithm. The example key in this guide is generated with the Elliptic Curve P256 - SHA Digest algorithm.

   PKIX (Cloud KMS)

   1. Click Add a PKIX Key.
   2. Click Import from Cloud KMS.

   3. Enter the resource ID for the key version in the window that opens. The format for the resource ID is:

      projects/KMS_KEY_PROJECT_ID/locations/KMS_KEY_LOCATION/keyRings/KMS_KEYRING_NAME/cryptoKeys/KMS_KEY_NAME/cryptoKeyVersions/KMS_KEY_VERSION
      

      where:

      • KMS_KEY_PROJECT_ID is the ID of the project where the 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

      If you created a Cloud KMS key pair using the sample environment variables in this page, you can view the resource ID with the following command:

      echo projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}/cryptoKeyVersions/${KMS_KEY_VERSION}
      

      You must have the `cloudkms.publicKeyViewer` role on the key resource to add the key.

   4. Click Submit.

6. If you want to use an existing note that you previously created, expand the Advanced Settings section.

   1. Deselect Automatically generate an Artifact Analysis note.

   2. Enter the fully-qualified name in the Artifact Analysis Note ID field. The name has the format projects/PROJECT_ID/notes/NOTE_ID.

7. Click Create.

Verify that the attestor was created

To verify that the attestor was created:

1. Return to the Binary Authorization page in the Google Cloud console.

2. Open the Attestors tab.

Multi-project setup

If you are using a multi-project setup, where you have a separate deployer and attestor projects, there are additional permissions that need to be set on the attestor resource in order for the deployer project to use attestations created by it during deployment.

Add an IAM role binding for the deployer project

You must add an IAM role binding for the deployer project service account to the attestor. This is used by Binary Authorization when it evaluates a policy to determine whether the account has permissions to access the attestor.

You must add the IAM role binding from the command line, as this step is not supported in the Google Cloud console.

To add the IAM role binding:

1. Set up environment variables to store your project names and numbers.

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

2. Set up environment variables to store the service account names for the projects:

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

3. Add the IAM role binding:

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

Add an IAM role binding for the user setting up Binary Authorization

You must add an IAM role binding for the user who adds an attestor to the Binary Authorization policy in the deployer project, as the user must have the permission to view the attestor to add. If desired, this permission can safely be revoked after the attestor has been added.

You must also add the IAM role binding from the command line, as this step is not supported in the Google Cloud console.

To add the IAM role binding:

gcloud --project ATTESTOR_PROJECT_ID \
    beta container binauthz attestors add-iam-policy-binding \
    "projects/ATTESTOR_PROJECT_ID/attestors/ATTESTOR" \
    --member=ADMIN_EMAIL_ACCOUNT \
    --role=roles/binaryauthorization.attestorsViewer

To remove the IAM role binding after the attestor has been added:

gcloud --project ATTESTOR_PROJECT_ID \
    beta container binauthz attestors remove-iam-policy-binding \
    "projects/ATTESTOR_PROJECT_ID/attestors/ATTESTOR" \
    --member=ADMIN_EMAIL_ACCOUNT \
    --role=roles/binaryauthorization.attestorsViewer

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.