Crea certificadores mediante la API de REST

En esta página, se explica cómo crear un certificador personalizado en la Autorización Binaria mediante la API de REST.

Como alternativa, también puedes realizar estos pasos mediante Google Cloud CLI o la consola de Google Cloud. Esta tarea forma parte de la configuración de Autorización Binaria.

Usuarios de Cloud Build: En su lugar, puedes usar el certificador built-by-cloud-build para implementar solo imágenes compiladas por Cloud Build.

Descripción general

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

Para crear un certificador, 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 PKIX que se pueda usar para verificar la identidad del certificador [los pares de claves asimétricas que genera Cloud Key Management Service (Cloud KMS) tienen un formato compatible con PKIX]. También puedes usar pares de claves de PGP en lugar de claves de PKIX.
Crea el certificador en la autorización binaria y asocia la nota y la clave pública que creaste.

En una configuración de un solo proyecto, debes crear el certificador en el mismo proyecto de Google Cloud en el que configuras la política de autorización binaria. En una configuración de varios proyectos, lo más probable es que tengas un proyecto de implementador en el que se configure la política y un proyecto de certificador independiente en el que se almacenen los certificadores.

Antes de comenzar

Configura el proyecto predeterminado

Configura el proyecto predeterminado de Google Cloud si aún no lo hiciste:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Configura 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 los proyectos de implementador y de certificador se encuentran el mismo proyecto, usa el mismo ID del proyecto para ambas variables.

También debes obtener los nombres de las cuentas de servicio para 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"

Crea una nota de Artifact Analysis

Autorización Binaria usa Artifact Analysis para almacenar los metadatos de confianza que se usan en el proceso de autorización. En cada certificador que creas, se debe crear una nota de Artifact Analysis. Cada certificación se almacena como un caso de esta nota.

Para crear una nota de Artifact Analysis, sigue estos pasos:

Configura variables de entorno para almacenar el ID de nota y una descripción legible:
```
NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION
```
Reemplaza lo siguiente:
- 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 completamente calificada al recurso de nota.
- DESCRIPTION es el nombre visible y legible de la nota (por ejemplo, Test Attestor Note).

En un editor de texto, crea un archivo JSON en /tmp/note_payload.json que describa la nota de Artifact Analysis:

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

Envía una solicitud HTTP a la API de REST de Artifact Analysis para crear la nota:

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 haya 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/"

Establece permisos en la nota

También debes establecer los permisos en la nota de Artifact Analysis que creaste a fin de que sea accesible para la cuenta de servicio del proyecto del certificador. Para ello, actualiza la política de IAM de la nota a fin de asignar el rol containeranalysis.notes.occurrences.viewer a la cuenta.

Para establecer los permisos, sigue estos pasos:

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

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

Agrega la cuenta de servicio y las funciones de acceso solicitadas a la política de IAM para la nota que creaste:
```
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"
```
Cuando agregas un rol a la política mediante el método anterior, se reemplaza cualquier rol existente en la nota. Si deseas conservar las funciones existentes, asegúrate de incluirlas en los datos JSON cuando configures la política.

Configura claves criptográficas

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

Crea un par de claves de PKIX

La autorización binaria te permite usar pares de claves de PKIX asimétricos para verificar una certificación. El par de claves consta de una clave privada, que el firmante usa para firmar de forma digital las certificaciones, y una clave pública, que agregas al certificador. Luego, el ejecutor de la autorización binaria usa la clave pública del certificador para verificar que el firmante haya creado la certificación.

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

Los pares de claves asimétricas que se generaron y almacenaron en Cloud KMS son compatibles con el formato PKIX. Para crear una clave de Cloud KMS que se pueda usar con la autorización binaria, consulta Crea claves asimétricas. Asegúrate de elegir la firma asimétrica como propósito de la clave cuando crees la clave.

PKIX (Cloud KMS)

Para crear el par de claves en Cloud KMS, haz lo siguiente:

A fin de 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
```
Reemplaza lo siguiente:
- KMS_KEY_PROJECT_ID: el ID del proyecto en el que se almacenan las claves.
- KMS_KEY_LOCATION: es la ubicación de la clave.
- KMS_KEYRING_NAME: es el nombre del llavero de claves.
- KMS_KEY_NAME: el nombre de la clave.
- KMS_KEY_VERSION: es la versión de la clave.
- KMS_KEY_ALGORITHM: el algoritmo; se recomienda ec-sign-p256-sha256
- KMS_PROTECTION_LEVEL: el nivel de protección, por ejemplo, software

Para crear el llavero de claves, ejecuta el siguiente comando:

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

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)

Sigue estos pasos a fin de generar un par nuevo y local de claves de PKIX asimétricas y almacenarlo en un archivo:

Genera la clave:

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

Dado que este archivo contiene una clave pública y una privada, debes extraer la clave pública en un archivo distinto para poder agregarla al certificador:
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

Crea el certificador

El siguiente paso es crear el certificador en la autorización binaria con la nota de Artifact Analysis asociada. También debes agregar la clave criptográfica pública.

Para crear el certificador, sigue estos pasos:

Configura una variable de entorno para almacenar el nombre del certificador, como se define en la autorización binaria:
```
ATTESTOR_NAME=ATTESTOR_NAME
```
En el ejemplo anterior, ATTESTOR_NAME es el nombre del certificador que deseas crear (por ejemplo, build-secure o prod-qa).

Crea el certificador y adjunta la llave de seguridad pública:

PKIX (Cloud KMS)

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

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

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

Genera un archivo JSON que contenga la información necesaria para crear el certificador:

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

Crea el certificador:

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)

Genera un archivo JSON que contenga la información necesaria para crear el certificador:

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

Crea el certificador:

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

Agrega una vinculación de función de IAM para el proyecto del implementador al certificador. La autorización binaria usa esta vinculación cuando evalúa una política a fin de determinar si el proyecto tiene permisos para acceder al certificador al que se hace referencia.

Genera un archivo JSON que contenga la información necesaria para establecer la política de IAM en el certificador:

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

Agrega la cuenta de servicio y las funciones de acceso solicitadas a la política de IAM para la nota que creaste:

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"

Verifica que se haya creado el certificador

Para verificar que se haya creado el certificador, 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/"

¿Qué sigue?

Obtén más información sobre cómo crear certificaciones para tu certificador.
Actualiza tu política de Autorización Binaria para requerir certificaciones mediante la consola de Google Cloud, Google Cloud CLI y la API de REST.