Crear encargados de la atestación con la API REST

En esta página se explica cómo crear un verificador personalizado en la autorización binaria mediante la API REST.

También puedes seguir estos pasos con la CLI de Google Cloud o la consolaGoogle Cloud . Esta tarea forma parte de la configuración de la autorización binaria.

Usuarios de Cloud Build: pueden usar el built-by-cloud-build attestor para desplegar solo imágenes creadas por Cloud Build.

Información general

Un encargado de la atestación es un recurso que utiliza la autorización binaria para verificar una atestación. Google Cloud Para obtener más información sobre las certificaciones, consulta la descripción general de la autorización binaria.

Para crear un encargado de la atestación, debes hacer lo siguiente:

  • Crea una nota en Artifact Analysis para almacenar los metadatos de confianza que se usan en el proceso de certificación.
  • Configura un par de claves de infraestructura de clave pública (X.509) (PKIX) que se pueda usar para verificar la identidad del attestor. Los pares de claves asimétricas generados por Cloud Key Management Service (Cloud KMS) tienen un formato compatible con PKIX. También puedes usar pares de claves PGP en lugar de claves PKIX.
  • Crea el attestor en Binary Authorization y asocia la nota y la clave pública que has creado.

En una configuración de un solo proyecto, creas tu encargado de la atestación en el mismo proyecto Google Cloud en el que configuras tu política de autorización binaria. En una configuración de varios proyectos, lo más probable es que tengas un proyecto de implementación en el que se configure tu política y un proyecto de verificador independiente en el que se almacenen tus verificadores.

Antes de empezar

  1. Habilita la autorización binaria.

  2. Configura la autorización binaria para tu plataforma.

Definir el proyecto predeterminado

Si aún no lo has hecho, define el proyecto predeterminado: Google Cloud 

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Configurar el entorno

Configura las variables de entorno para almacenar los nombres y números de tus proyectos:

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

Si el proyecto de attestor y el de deployer son el mismo, usa el mismo ID de proyecto para ambas variables.

También debe obtener los nombres de las cuentas de servicio de los proyectos:

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

Crear una nota de Artifact Analysis

La autorización binaria utiliza Artifact Analysis para almacenar metadatos de confianza que se usan en el proceso de autorización. Por cada attestor que cree, debe crear una nota de Artifact Analysis. Cada atestación se almacena como una instancia de esta nota.

Para crear una nota de análisis de artefactos:

  1. Configura variables de entorno para almacenar el ID de la nota y una descripción legible por humanos:

    NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION

    Haz los cambios siguientes:

    • NOTE_ID es el nombre interno de la nota en caracteres alfanuméricos sin espacios (por ejemplo, test-attestor-note).
    • NOTE_URI es la ruta completa del recurso de la nota
    • DESCRIPTION es el nombre visible de la nota, que es legible por humanos (por ejemplo, Test Attestor Note).

  2. En un editor de texto, crea un archivo JSON en /tmp/note_payload.json que describa la nota de análisis de artefactos:

    cat > /tmp/note_payload.json << EOM
{
  "name": "${NOTE_URI}",
  "attestation": {
    "hint": {
      "human_readable_name": "${DESCRIPTION}"
    }
  }
}
EOM

  3. Para crear la nota, envía una solicitud HTTP a la API REST de Artifact Analysis:

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/note_payload.json  \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/?noteId=${NOTE_ID}"

Para verificar que la nota se ha creado correctamente, ejecuta el siguiente comando:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/"

Definir los permisos de la nota

También debes definir permisos en la nota de Artifact Analysis que has creado para que la cuenta de servicio del proyecto de attestor pueda acceder a ella. Para ello, actualiza la política de gestión de identidades y accesos de la nota para asignar el rol containeranalysis.notes.occurrences.viewer a la cuenta.

Para definir los permisos, sigue estos pasos:

  1. Genera un archivo JSON que contenga la información necesaria para definir la política de IAM en tu nota:

    cat > /tmp/iam_request.json << EOM
{
  'resource': '${NOTE_URI}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/containeranalysis.notes.occurrences.viewer',
        'members': [
          'serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

  2. Añade la cuenta de servicio y los roles de acceso solicitados a la política de gestión de identidades y accesos de la nota que has creado:

    curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}:setIamPolicy"

Configurar claves criptográficas

La autorización binaria te permite usar claves PKIX para verificar de forma segura la identidad del firmante que creó una atestación. De esta forma, solo las partes verificadas pueden autorizar una imagen de contenedor. Como alternativa a PKIX, también puedes usar claves PGP.

Crear un par de claves PKIX

La autorización binaria te permite usar pares de claves PKIX asimétricas para verificar una atestación. El par de claves consta de una clave privada, que el firmante usa para firmar digitalmente las certificaciones, y una clave pública, que añades al certificador. Más adelante, el verificador de la autorización binaria usa la clave pública del attestor para comprobar que la atestación la ha creado el firmante.

En esta guía, se usa el algoritmo de firma digital de curva elíptica (ECDSA) recomendado para generar un par de claves PKIX. También puedes usar claves RSA o PGP para firmar. Consulta Propósitos y algoritmos de claves para obtener más información sobre los algoritmos de firma.

Los pares de claves asimétricas generados y almacenados en Cloud KMS cumplen el formato PKIX. Para crear una clave de Cloud KMS que se pueda usar con Autorización binaria, consulta Crear claves asimétricas. Asegúrate de elegir Firma asimétrica como finalidad de la clave al crearla.

PKIX (Cloud KMS)

Para crear el par de claves en Cloud KMS, sigue estos pasos:

  1. Para configurar las variables de entorno necesarias para crear el par de claves, ejecuta los siguientes comandos:

    KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
KMS_KEY_LOCATION=KMS_KEY_LOCATION
KMS_KEYRING_NAME=KMS_KEYRING_NAME
KMS_KEY_NAME=KMS_KEY_NAME
KMS_KEY_VERSION=KMS_KEY_VERSION
KMS_KEY_PURPOSE=asymmetric-signing
KMS_KEY_ALGORITHM=KMS_KEY_ALGORITHM
KMS_PROTECTION_LEVEL=KMS_PROTECTION_LEVEL

    Haz los cambios siguientes:

    • KMS_KEY_PROJECT_ID: el ID del proyecto en el que se almacenan las claves.
    • KMS_KEY_LOCATION: la ubicación de la clave
    • KMS_KEYRING_NAME: el nombre del conjunto de claves
    • KMS_KEY_NAME: el nombre de la clave.
    • KMS_KEY_VERSION: la versión de la clave
    • KMS_KEY_ALGORITHM: el algoritmo; ec-sign-p256-sha256 es la opción recomendada
    • KMS_PROTECTION_LEVEL: el nivel de protección (por ejemplo, software)

  2. Para crear el conjunto de claves, ejecuta el siguiente comando:

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

  3. Para crear la clave, ejecuta el siguiente comando:

    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 (clave local)

Para generar un nuevo par de claves asimétricas PKIX local y almacenarlo en un archivo, haz lo siguiente:

  1. Genera la clave:

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

  2. Como este archivo contiene una clave pública y una privada, debes extraer la clave pública en un archivo independiente para poder añadirla al verificador:

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

Crear el encargado de la atestación

El siguiente paso es crear el encargado de la atestación en la autorización binaria con la nota de análisis de artefactos asociada. También debes añadir la clave pública criptográfica.

Para crear el encargado de la atestación, sigue estos pasos:

  1. Configura una variable de entorno para almacenar el nombre del attestor tal como se define en Autorización binaria:

    ATTESTOR_NAME=ATTESTOR_NAME

    donde ATTESTOR_NAME es el nombre del attestor que quieres crear (por ejemplo, build-secure o prod-qa).

  2. Crea el attestor y adjunta la clave de seguridad pública:

    PKIX (Cloud KMS)

    1. Configura variables de entorno adicionales para almacenar información sobre el par de claves de Cloud KMS para la llamada a la API Binary Authorization.

      KMS_CRYPTO_KEY_URI="projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}"
KMS_CRYPTO_KEY_VERSION_URI="${KMS_CRYPTO_KEY_URI}/cryptoKeyVersions/${KMS_KEY_VERSION}"
KMS_KEY_ID="//cloudkms.googleapis.com/v1/${KMS_CRYPTO_KEY_VERSION_URI}"

    2. Descarga el archivo de clave pública de Cloud KMS y guárdalo en un archivo llamado /tmp/kms_public_key.pem en tu sistema local.

    3. Genera un archivo JSON que contenga la información necesaria para crear el attestor:

      cat > /tmp/attestor.json << EOM
{
    "userOwnedDrydockNote": {
        "noteReference": "${NOTE_URI}",
        "publicKeys": {
            "id": "${KMS_KEY_ID}",
            "pkixPublicKey": {
                "signatureAlgorithm": "${KMS_KEY_ALGORITHM}",
                "publicKeyPem": $( \
                    python < /tmp/kms_public_key.pem \
                    -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
                )
            }
        }
    }
}
EOM

    4. Crea el encargado de la atestación:

      curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/attestor.json \
"https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"

    PKIX (clave local)

    1. Genera un archivo JSON que contenga la información necesaria para crear el attestor:

      cat > /tmp/attestor.json << EOM
{
   "userOwnedGrafeasNote": {
       "noteReference": "${NOTE_URI}",
       "publicKeys": {
           "pkixPublicKey": {
               "signatureAlgorithm": "ecdsa_p256_sha256",
               "publicKeyPem": $( \
                   python < ${PUBLIC_KEY_FILE} \
                   -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
               )
           }
       }
   }
}
EOM

    2. Crea el encargado de la atestación:

      curl -X POST  \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
   --data-binary @/tmp/attestor.json \
"https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"

  3. Añade una vinculación de roles de gestión de identidades y accesos para el proyecto de implementación al encargado de la atestación. La usa la autorización binaria cuando evalúa una política para determinar si el proyecto tiene permisos para acceder al attestor al que se hace referencia.

    Genera un archivo JSON que contenga la información necesaria para definir la política de gestión de identidades y accesos en tu attestor:

    cat > /tmp/iam_request.json << EOM
{
  'resource': 'projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/binaryauthorization.attestorsVerifier',
        'members': [
          'serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

    Añade la cuenta de servicio y los roles de acceso solicitados a la política de gestión de identidades y accesos de la nota que has creado:

    curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://binaryauthorization.googleapis.com/v1beta1/projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}:setIamPolicy"

Verificar que se ha creado el encargado de la atestación

Para verificar que se ha creado el attestor, ejecuta el siguiente comando:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors/"

Siguientes pasos