Crea certificadores mediante la API de REST

En esta página, se explica cómo crear un certificador en la autorización binaria mediante la API de REST. Como alternativa, también puedes realizar estos pasos mediante Google Cloud Console o comandos de gcloud en la línea de comandos. Esta tarea forma parte de la configuración de la autorización binaria.

Descripción general

Un certificador es un recurso de GCP 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 Container 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.

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 Container Analysis

La autorización binaria usa Container 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 Container Analysis. Cada certificación se almacena como un caso de esta nota.

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

  1. 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
    

    En el ejemplo anterior, se ilustra 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).
  2. En un editor de texto, crea un archivo JSON en /tmp/note_payload.json que describa la nota de Container Analysis:

    cat > /tmp/note_payload.json << EOM
    {
      "name": "${NOTE_URI}",
      "attestation": {
        "hint": {
          "human_readable_name": "${DESCRIPTION}"
        }
      }
    }
    EOM
    
  3. Envía una solicitud HTTP a la API de REST de Container 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 creó de forma correcta, 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 Container 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 la función containeranalysis.notes.occurrences.viewer a la cuenta.

Para establecer los permisos, sigue estos pasos:

  1. 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
    
  2. 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"
    

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.

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

  1. Genera la clave:

    PRIVATE_KEY_FILE="/tmp/ec_private.pem"
    openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}
    
  2. 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 Container Analysis asociada. También debes agregar la clave criptográfica pública.

Para crear el certificador, sigue estos pasos:

  1. 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).

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

    PKIX (clave local)

    1. 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
      
    2. 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 (Cloud KMS)

    1. Configura las variables de entorno para almacenar información sobre el par de claves que administra Cloud KMS.

      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_TYPE=KMS_KEY_TYPE
      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}"
      

      En el ejemplo anterior, se ilustra lo siguiente:

      • KMS_KEY_PROJECT_ID es el ID del proyecto en el que se almacenan las claves.
      • KMS_KEY_LOCATION es la ubicación de la clave (por ejemplo, global).
      • KMS_KEYRING_NAME es el nombre del llavero de claves.
      • KMS_KEY_NAME es el nombre de la clave.
      • KMS_KEY_VERSION es la versión de la clave.
      • KMS_KEY_TYPE es el tipo de encriptación de la clave (por ejemplo, ECDSA_P256_SHA256).
    2. 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.

    3. 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_TYPE}",
                      "publicKeyPem": $( \
                          python < /tmp/kms_public_key.pem \
                          -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
                      )
                  }
              }
          }
      }
      EOM
      
    4. 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}"
      
  3. 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/v1/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/"

Próximos pasos