Use the simple signing attestation check

This page shows you how to use the Binary Authorization continuous validation (CV) simple signing attestation check. The check verifies the attestations of container images associated with Pods running in a Google Kubernetes Engine (GKE) cluster where CV is enabled.

Costs

This guide uses the following Google Cloud services:

  • Binary Authorization, but CV is available free of charge during the Preview stage
  • GKE
  • Cloud Key Management Service

To generate a cost estimate based on your projected usage, use the pricing calculator.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Binary Authorization, Cloud Key Management Service, Google Kubernetes Engine APIs:

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles. 

    gcloud services enable binaryauthorization.googleapis.com cloudkms.googleapis.com container.googleapis.com

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  10. To initialize the gcloud CLI, run the following command: 

    gcloud init

  11. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the Binary Authorization, Cloud Key Management Service, Google Kubernetes Engine APIs:

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles. 

    gcloud services enable binaryauthorization.googleapis.com cloudkms.googleapis.com container.googleapis.com
    14.
  14. Ensure that the gcloud CLI is updated to the latest version.
  15. Install the kubectl command-line tool.
  16. If your Binary Authorization policies and GKE clusters are in different projects, make sure that Binary Authorization is enabled in both projects.

Required roles

This section shows you how to set roles for this check.

Overview

If you run all of the products that are mentioned in this guide in the same project, you don't need to set any permissions. Binary Authorization configures the roles correctly when you enable it. If you run the products in different projects, you must set roles as described in this section.

To ensure that the Binary Authorization Service Agent in each project has the necessary permissions to evaluate the CV simple signing attestation check, ask your administrator to grant the following IAM roles to the Binary Authorization Service Agent in each project:

  • If your cluster project is different from the policy project: Binary Authorization Policy Evaluator (roles/binaryauthorization.policyEvaluator) on the cluster project Binary Authorization Service Agent, for it to access the policy project
  • If your attestation project is different from your policy project: Container Analysis Occurrences Viewer (roles/containeranalysis.occurrences.viewer) on the policy project Binary Authorization Service Agent, for it to access the attestation project

For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give the Binary Authorization Service Agent in each project the required permissions through custom roles or other predefined roles.

Grant roles using the gcloud CLI

To ensure that the Binary Authorization Service Agent in each project has the necessary permissions to evaluate the CV simple signing attestation check, grant the Binary Authorization Service Agent in each project the following IAM roles:

  1. Grant permission for the cluster project's Binary Authorization Service Agent to access the policy in the policy project.

    1. Get the cluster project's Binary Authorization service agent:

      PROJECT_NUMBER=$(gcloud projects list --filter="projectId:CLUSTER_PROJECT_ID" \
  --format="value(PROJECT_NUMBER)")
CLUSTER_SERVICE_ACCOUNT="service-$PROJECT_NUMBER@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

      Replace CLUSTER_PROJECT_ID with the project ID of the cluster.

    2. Allow CV to evaluate the policy on the cluster:

      gcloud projects add-iam-policy-binding POLICY_PROJECT_ID \
    --member="serviceAccount:$CLUSTER_SERVICE_ACCOUNT" \
    --role='roles/binaryauthorization.policyEvaluator'

      Replace POLICY_PROJECT_ID with the ID of the project that contains your policy.

  2. Allow the policy project Binary Authorization Service Agent to access the attestations in your attestation project:

    1. Obtain the policy project's Binary Authorization service agent:

      PROJECT_NUMBER=$(gcloud projects list \
  --filter="projectId:POLICY_PROJECT_ID" \
  --format="value(PROJECT_NUMBER)")
SERVICE_ACCOUNT="service-$PROJECT_NUMBER@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

      Replace POLICY_PROJECT_ID with the ID of the project that contains your policy.

    2. Grant the role:

      gcloud projects add-iam-policy-binding ATTESTATION_PROJECT_ID \
    --member="serviceAccount:$SERVICE_ACCOUNT" \
    --role='roles/containeranalysis.occurrences.viewer'

      Replace ATTESTATION_PROJECT_ID with the ID of the project that contains your attestations.

Create a key pair

In this section, you create an Elliptic Curve Digital Signature Algorithm (ECDSA) asymmetric key pair.

You use the private key to sign the image, which creates the attestation. You include the public key in a platform policy. When CV checks the attestation, it uses the public key to verify the attestation.

You can use either Cloud Key Management Service or local keys, but we recommend that you use Cloud KMS keys for production.

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. To do so, we recommend that you fill in the placeholders in the following command, and then run the command.

    KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
KMS_KEYRING_NAME=KMS_KEYRING_NAME
KMS_KEY_NAME=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
KEY_FILE=KEY_FILE

    Replace the following:

    • KMS_KEY_PROJECT_ID: your project ID
    • KMS_KEYRING_NAME: a name for your Cloud KMS key ring
    • KMS_KEY_NAME: a name for your Cloud KMS key
    • KEY_FILE: a local path to save your Cloud KMS key

  2. Create the key ring:

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

  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} \
    --project=${KMS_KEY_PROJECT_ID}

  4. Export the public key material to a file:

    gcloud kms keys versions get-public-key ${KMS_KEY_VERSION} \
    --key=${KMS_KEY_NAME} \
    --keyring=${KMS_KEYRING_NAME} \
    --location=${KMS_KEY_LOCATION} \
    --output-file=${KEY_FILE} \
    --project=${KMS_KEY_PROJECT_ID}

Local key

To create the key pair locally, do the following:

  1. Create the private key:

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

  2. Get the public key from the private key:

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

Create a platform policy

To create a CV platform policy with a simple signing attestation check, do the following:

  1. Create the simple signing attestation check platform policy YAML file:

    PKIX Cloud KMS 

    cat > /tmp/my-policy.yaml << EOF
gkePolicy:
  checkSets:
  - checks:
    - simpleSigningAttestationCheck:
        containerAnalysisAttestationProjects:
        - projects/ATTESTATION_PROJECT_ID
        attestationAuthenticators:
          pkixPublicKeySet:
            pkixPublicKeys:
              publicKeyPem: |