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.

Set up a PGP or PKIX key pair that can be used to verify the identity of the
attestor. (Asymmetric key pairs generated by Cloud Key Management Service
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 your attestor in
the same Google Cloud Platform project where 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.

Create a Container Analysis note

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 a Container Analysis note:

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

NOTE_ID=NOTE_ID
DESCRIPTION=DESCRIPTION

where:

NOTE_ID is the internal name of the note in alphanumeric
characters with no spaces (for example, test-attestor-note)

DESCRIPTION is a human-readable display name for the note
(for example, Test Attestor Note)

In a text editor, create a JSON file in /tmp/note_payload.json that
describes the Container Analysis note:

Set permissions on the note

You must also set permissions on the Container Analysis note you created
so that it is accessible to the attestor project service account.
You do this by updating the IAM policy for the note to assign the
containeranalysis.notes.occurrences.viewer role to the account.

To set the permissions:

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

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)

Run gpg --gen-key from the command line:

gpg --batch --gen-key

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 in Binary Authorization with
the associated Container Analysis note. You must also add the cryptographic
public key.

To create the attestor:

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

ATTESTOR=ATTESTOR

where:

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

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.