Create attestors using the Google Cloud console

This page explains how to create an 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.

Before you begin

Before you create attestors, do the following:

  1. Binary Authorization must be enabled. See Enabling Binary Authorization for more information.

  2. The policy must be configured to allow only images that are verified by attestors. See Configuring a policy using the Console to learn more.

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.

Creating an attestor requires you to:

  • Set up a 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 public key 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 allows you to use PKIX keys to securely verify the identity of attestors. This ensures that only verified parties can authorize a container image.

In this guide, the recommended Elliptic Curve Digital Signing 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 allows you to use asymmetric PKIX key pairs to verify the identity of an attestor. The key pair consists of a private key, which the attestor uses to digitally sign attestations, and a public key, which you add to the attestor as stored by the Binary Authorization service.

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.

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)

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