Creating attestors using the Console

This page explains how to create an attestor in Binary Authorization using the Google Cloud Platform Console. As an alternative, you can also perform these steps using gcloud and curl commands at the command line. This task is part of setting up Binary Authorization.

Overview

An attestor is a party that is responsible for attesting that a required process has completed before a container image can be deployed. This party can be a human user or, more often, a machine process like a build and test system, or your continuous integration (CI) and deployment (CD) pipelines.

Creating an attestor requires you to:

  • Generate a PGP key pair that can be used to verify the identity of the attestor
  • 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 PGP key pairs or PKIX keys to securely verify the identity of attestors. This ensures that only verified parties can authorize a container image.

Create a PGP key pair

A PGP key pair consists of a private key, which you use to digitally sign attestations, and a public key, which you add to the attestor as stored by the Binary Authorization service.

To generate the key pair:

  1. Set up environment variables to store the name of the attestor and an e-mail address associated with the key pair:

    ATTESTOR_NAME=ATTESTOR_NAME
    ATTESTOR_EMAIL=ATTESTOR_EMAIL
    

    where:

    • ATTESTOR_NAME is the name of the attestor (for example, test-attestor)
    • ATTESTOR_EMAIL is the e-mail address associated with the attestor (for example, attestor@example.com)
  2. Run gpg --gen-key from the command line:

    gpg --batch --gen-key <(
      cat <<- EOF
        Key-Type: RSA
        Key-Length: 2048
        Name-Real: "${ATTESTOR_NAME}"
        Name-Email: "${ATTESTOR_EMAIL}"
        %commit
    EOF
    )
    
  3. Export the public key:

    gpg --armor --export "${ATTESTOR_EMAIL}" > /tmp/generated-key.pgp
    

The exported public key is located in /tmp/generated-key.pgp. The private key is stored on the local system where you ran the gpg --gen-key command.

Create a PKIX key pair

Binary Authorization allows you to use asymmetric PKIX key pairs instead of PGP keys to verify the identity of an attestor. As with PGP keys, 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.

The asymmetric key pairs generated and stored in Cloud Key Management Service are compliant with the PKIX format. To create a Cloud Key Management Service 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.

Create the attestor

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

Binary Authorization uses Container Analysis to store trusted metadata used in the authorization process. For each attestor you create, you must create one Container 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 the Binary Authorization page

  2. In the Attestors tab, click Create.

    Screenshot of policy tab showing default rule

  3. Click Create New Attestor.

    Screenshot of Create Attestors page

  4. Enter a name for the attestor (for example, build-secure or prod-qa) in the Attestor Name field.

  5. Select Automatically Generate a Container Analysis Note to create a new note.

    If you want to use an existing note that you previously created, de-select this option and enter the fully-qualified name in the Container Analysis Note ID field. The name has the format projects/PROJECT_ID/notes/NOTE_ID.

  6. Add the public key to the attestor:

    PGP

    1. Click Add an OpenPGP Public Key.

      Screenshot of PGP public keys text box

    2. Open /tmp/generated-key.pgp in a text editor. This is the public key file that you created in the previous step. Copy the contents of the file to the Paste Key text box and click Done.

    3. Click Create.

    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
    4. Click Submit.

  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 Platform Console.

  2. Open the Attestors tab.

Screenshot of Attestors tab showing created attestors

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 Platform 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 Platform Console.

To add the IAM role binding:

<pre class="devsite-click-to-copy">
gcloud --project <var>ATTESTOR_PROJECT_ID</var> \
    beta container binauthz attestors add-iam-policy-binding \
    "projects/<var>ATTESTOR_PROJECT_ID</var>/attestors/<var>ATTESTOR</var>" \
    --member=<var>ADMIN_EMAIL_ACCOUNT</var> \
    --role=roles/binaryauthorization.attestorsViewer
</pre>

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

<pre class="devsite-click-to-copy">
gcloud --project <var>ATTESTOR_PROJECT_ID</var> \
    beta container binauthz attestors remove-iam-policy-binding \
    "projects/<var>ATTESTOR_PROJECT_ID</var>/attestors/<var>ATTESTOR</var>" \
    --member=<var>ADMIN_EMAIL_ACCOUNT</var> \
    --role=roles/binaryauthorization.attestorsViewer
</pre>

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Binary Authorization Documentation