Crea certificaciones

En esta página, se describen los pasos para crear una certificación de Autorización Binaria.

Las certificaciones se usan para autorizar la implementación de imágenes de contenedor específicas en plataformas, como Google Kubernetes Engine (GKE) y Cloud Run. Para usar certificaciones, debes exigir certificaciones en la regla adecuada de tu política.

Con una sola certificación, se pueden autorizar imágenes idénticas que se almacenan en varias ubicaciones o registros diferentes, como Artifact Registry, Container Registry o un registro de contenedores externo.

En el momento de la implementación, la Autorización Binaria usa certificadores para verificar las certificaciones.

Para configurar la Autorización Binaria en Cloud Run, GKE, Google Distributed Cloud y Cloud Service Mesh, consulta Configura por plataforma y selecciona tu plataforma.

Usuarios de GKE: Para obtener un instructivo de extremo a extremo que describa la aplicación basada en certificaciones mediante la autorización binaria y Google Kubernetes Engine (GKE), consulta Comienza a usar la herramienta de línea de comandos o Comienza a usar la consola de Google Cloud.

Antes de comenzar

En Descripción general de las certificaciones, se proporcionan los pasos para completar antes de crear una certificación.

1. Habilitar autorización binaria

2. Crea certificadores mediante la consola de Google Cloud, Google Cloud CLI o la API de REST.

Configura el entorno

1. Especifica los ID de proyecto:

   ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
   ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
   

   Reemplaza lo siguiente:

   • ATTESTOR_PROJECT_ID: El nombre del proyecto en el que almacenas los certificadores
   • ATTESTATION_PROJECT_ID: El nombre del proyecto en el que almacenas las certificaciones

   Si deseas que tu certificación se cree en el mismo proyecto que tus certificadores, usa el mismo ID de proyecto para ambas variables. Consulta Configuración de varios proyectos para ver un instructivo de extremo a extremo en el que se muestra la separación de obligaciones con diferentes proyectos.

2. Especifica el nombre del certificador y la información de la imagen:

   ATTESTOR_NAME=ATTESTOR_NAME
   IMAGE_PATH=IMAGE_PATH
   IMAGE_DIGEST=IMAGE_DIGEST
   IMAGE_TO_ATTEST="${IMAGE_PATH}@${IMAGE_DIGEST}"
   

   Reemplaza lo siguiente:

   • ATTESTOR_NAME: El nombre del certificador, por ejemplo, build-secure o prod-qa.

   • IMAGE_PATH: Un URI que representa una ruta de acceso a una imagen. Si bien el URI debe incluir un dominio y un nombre de imagen, no es necesario que haga referencia a una imagen real. No se accede a las imágenes durante la creación de la certificación. Los siguientes son ejemplos de rutas de acceso de imágenes:

     • us-docker.pkg.dev/google-samples/containers/gke/hello-app
     • gcr.io/example-project/quickstart-image
     • example.com/hello-app.

   • IMAGE_DIGEST: Es el resumen del manifiesto de la imagen. Por ejemplo, sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567 es el resumen de la imagen asociado con la ruta de la imagen de ejemplo us-docker.pkg.dev/google-samples/containers/gke/hello-app. Si deseas aprender a obtener el resumen de una imagen en Artifact Registry, consulta Administra imágenes; para una imagen de Container Registry, consulta Enumera las versiones de una imagen.

Otorga funciones de Identity and Access Management

Para crear certificaciones, debes otorgar las siguientes funciones de Identity and Access Management (IAM) a la identidad que crea el certificador, de la siguiente manera:

• roles/containeranalysis.notes.attacher en el recurso de nota asociado con el certificador.
• roles/containeranalysis.occurrences.editor en el recurso del proyecto de certificación.

Debes crear una certificación basada en un certificador. El certificador está asociado con una nota de Artifact Analysis. Cuando se crea una certificación, se crea un caso de Artifact Analysis que se adjunta a la nota.

Obtén más información sobre cómo otorgar acceso.

Si deseas obtener información para crear una certificación en una canalización de Cloud Build, consulta Crea certificaciones con Kritis Signer.

Crea una certificación

Nota: Las imágenes de ejemplo de esta guía son solo de demostración. Te recomendamos que solo crees certificaciones para las imágenes que administras.

Crea una certificación con una clave almacenada de forma local

Para crear certificaciones firmadas con una clave local, haz lo siguiente:

1. Crea un archivo de carga útil de firma:

   gcloud

   Para crear el archivo de carga útil de firma, ingresa el siguiente comando:

   gcloud container binauthz create-signature-payload \
       --artifact-url="${IMAGE_TO_ATTEST}" > /tmp/generated_payload.json
   

   El archivo de carga útil con formato JSON es similar al siguiente resultado:

   {
     "critical": {
       "identity": {
         "docker-reference": "us-docker.pkg.dev/google-samples/containers/gke/hello-app"
       },
       "image": {
         "docker-manifest-digest": "sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567"
       },
       "type": "Google cloud binauthz container signature"
     }
   }
   

   API de REST

   Crea un archivo de carga útil llamado /tmp/generated_payload.json mediante las variables de entorno que configuraste antes en este documento:

   cat > /tmp/generated_payload.json << EOM
   {
     "critical": {
       "identity": {
         "docker-reference": "${IMAGE_PATH}"
       },
       "image": {
         "docker-manifest-digest": "${IMAGE_DIGEST}"
       },
       "type": "Google cloud binauthz container signature"
     }
   }
   EOM
   

2. Firma la carga útil con tu clave privada para generar un archivo de firma.

   En esta guía, se usa el algoritmo Elliptic Curve Digital Signing Algorithm (ECDSA) para firmar. También puedes usar el algoritmo RSA. Para obtener más información sobre los algoritmos de firma, consulta Algoritmos y propósitos de clave. Esta guía también usa el formato de firma de la Infraestructura de clave pública (X.509) (PKIX). También puedes usar PGP.

   PRIVATE_KEY_FILE=PRIVATE_KEY_FILE
   openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature
   

   Reemplaza PRIVATE_KEY_FILE por la ruta a la clave privada que generaste cuando creaste el certificador.

3. Obtén el ID de clave pública.

   Para recuperar el ID de la clave pública del certificador, ingresa el siguiente comando:

   PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \
     --format='value(userOwnedGrafeasNote.publicKeys[0].id)')
   

4. Cree la certificación:

   gcloud

   Para crear y validar la certificación, ingresa lo siguiente:

   gcloud container binauthz attestations create \
       --project="${ATTESTATION_PROJECT_ID}" \
       --artifact-url="${IMAGE_TO_ATTEST}" \
       --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
       --signature-file=/tmp/ec_signature \
       --public-key-id="${PUBLIC_KEY_ID}" \
       --validate
   

   La marca validate comprueba que el certificador que configuraste en la política pueda verificar la certificación.

   Nota: El ID de clave puede ser una string.

   API de REST

   Para crear la certificación, sigue estos pasos:

   1. Recupera el certificador asociado con la certificación y extrae el ID de clave pública almacenada:

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

      La autorización binaria muestra un objeto JSON similar al siguiente:

      {
        "name": "projects/example-project/attestors/test-attestor",
        "userOwnedGrafeasNote": {
          "noteReference": "projects/example-project/notes/test-attestor",
          "publicKeys": [
            {
              "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70",
              "pkixPublicKey": {
                "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n",
                "signatureAlgorithm": "ECDSA_P256_SHA256"
              }
            }
          ],
          "delegationServiceAccountEmail": "[e-mail]"
        },
        "updateTime": "2019-06-26T16:58:33.977438Z"
      }
      

      La clave pública se puede encontrar en el campo id.

   2. Crea un archivo JSON en /tmp/attestation.json que describa la certificación:

      cat > /tmp/attestation.json << EOM
      {
        "resourceUri": "${IMAGE_TO_ATTEST}",
        "note_name": "${NOTE_URI}",
        "attestation": {
           "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)",
           "signatures": [
              {
               "public_key_id": "${PUBLIC_KEY_ID}",
               "signature": "$(base64 --wrap=0 /tmp/ec_signature)"
              }
           ]
        }
       }
      EOM
      

   3. Cree la certificación:

      curl -X POST \
          -H "Content-Type: application/json" \
          -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \
          -H "Authorization: Bearer $(gcloud auth print-access-token)" \
          --data-binary @/tmp/attestation.json \
          "https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"
      

Crea una certificación con Cloud KMS

Para crear una certificación con Cloud Key Management Service, sigue estos pasos:

1. Crea variables de entorno:

   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
   

   Reemplaza lo siguiente:

   • KMS_KEY_PROJECT_ID: El ID del proyecto en el que se almacenan las claves de Cloud Key Management Service
   • KMS_KEY_LOCATION: La ubicación de la clave (global es el valor predeterminado).
   • 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.

2. Firma y crea la certificación:

   gcloud

   Ingrese el siguiente comando:

   gcloud beta container binauthz attestations sign-and-create \
       --project="${ATTESTATION_PROJECT_ID}" \
       --artifact-url="${IMAGE_TO_ATTEST}" \
       --attestor="${ATTESTOR_NAME}" \
       --attestor-project="${ATTESTOR_PROJECT_ID}" \
       --keyversion-project="${KMS_KEY_PROJECT_ID}" \
       --keyversion-location="${KMS_KEY_LOCATION}" \
       --keyversion-keyring="${KMS_KEYRING_NAME}" \
       --keyversion-key="${KMS_KEY_NAME}" \
       --keyversion="${KMS_KEY_VERSION}"
   

   API de REST

   1. Crea un archivo de carga útil llamado /tmp/generated_payload.json mediante las variables de entorno que configuraste antes:

      cat > /tmp/generated_payload.json << EOM
      {
        "critical": {
          "identity": {
            "docker-reference": "${IMAGE_PATH}"
          },
          "image": {
            "docker-manifest-digest": "${IMAGE_DIGEST}"
          },
          "type": "Google cloud binauthz container signature"
        }
      }
      EOM
      

   2. Firma el archivo de carga útil:

      curl \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer $(gcloud auth print-access-token)" \
        --header "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
        --data '{"digest":  {"DIGEST_ALGORITHM": "'$(openssl dgst -sha256 -binary /tmp/generated_payload.json | openssl base64)'" }}' \
      https://cloudkms.googleapis.com/v1/projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}/cryptoKeyVersions/${KMS_KEY_VERSION}:asymmetricSign?alt=json
      

      Reemplaza DIGEST_ALGORITHM por el algoritmo para resumir la entrada. En los ejemplos de esta guía, se usa un resumen sha256. Puedes usar sha256, sha384 o sha512.

      En este ejemplo, el resultado es similar al siguiente:

      {
        "signature": "<var>SIGNATURE</var>": "996305066",
        "name": "projects/<var>KMS_KEY_PROJECT_ID</var>/locations/<var>KMS_KEY_LOCATION</var>/keyRings/<var>KMS_KEYRING_NAME</var>/cryptoKeys/<var>KMS_KEY_NAME</var>/cryptoKeyVersions/<var>KMS_KEY_VERSION</var>"
      }
      

      En este resultado, SIGNATURE es la firma codificada en Base64 del archivo de carga útil.

   3. Almacena la firma en una variable de entorno:

      PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
      

   4. Recupera el certificador en cuyo nombre firmas la certificación y extrae el ID de la clave pública almacenada y el ID de la nota:

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

      La autorización binaria muestra un objeto JSON similar al siguiente:

      {
        "name": "projects/example-project/attestors/test-attestor",
        "userOwnedGrafeasNote": {
          "noteReference": "projects/example-project/notes/test-attestor",
          "publicKeys": [
            {
              "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70",
              "pkixPublicKey": {
                "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n",
                "signatureAlgorithm": "ECDSA_P256_SHA256"
              }
            }
          ],
          "delegationServiceAccountEmail": "[e-mail]"
        },
        "updateTime": "2019-06-26T16:58:33.977438Z"
      }
      

      Puedes encontrar el ID de la clave pública en el campo id y el ID de la nota en el campo noteReference.

   5. Almacena el ID de la clave pública en una variable de entorno:

      PUBLIC_KEY_ID="PUBLIC_KEY_ID"
      NOTE_URI="NOTE_URI"
      

      Reemplaza lo siguiente:

      • PUBLIC_KEY_ID: El ID de la clave pública del certificador.
      • NOTE_URI: El URI de la nota de Artifact Analysis asociada con el certificador.

   6. Crea un archivo JSON en /tmp/attestation.json que describa la certificación:

      cat > /tmp/attestation.json << EOM
      {
        "resourceUri": "${IMAGE_TO_ATTEST}",
        "note_name": "${NOTE_URI}",
        "attestation": {
           "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)",
           "signatures": [
               {
                   "public_key_id": "${PUBLIC_KEY_ID}",
                   "signature": "${PAYLOAD_SIGNATURE}"
               }
           ]
        }
      }
      EOM
      

   7. Cree la certificación:

      curl -X POST \
          -H "Content-Type: application/json" \
          -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \
          -H "Authorization: Bearer $(gcloud auth print-access-token)" \
          --data-binary @/tmp/attestation.json \
      "https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"
      

Creaste la certificación.

Nota: En el momento de la implementación, el ejecutor usa solo el resumen de la imagen para verificar la certificación. Como resultado, esta certificación se puede usar para implementar imágenes idénticas en varias ubicaciones, incluidas las que se almacenan de forma local, en Artifact Registry, Container Registry y en registros externos.

Verifica que se haya creado la certificación

Para verificar que se creó la certificación, puedes enumerar las certificaciones asociadas con la imagen.

gcloud

Para recuperar una lista de certificaciones, ingresa el siguiente comando:

gcloud container binauthz attestations list\
    --project="${ATTESTATION_PROJECT_ID}"\
    --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}"\
    --artifact-url="${IMAGE_TO_ATTEST}"

API de REST

Para solicitar una lista de certificaciones, ingresa el siguiente comando:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22

Si hay muchas certificaciones, la respuesta puede contener un valor nextPageToken. En este caso, puedes recuperar la página siguiente de resultados si repites la solicitud y agregas un parámetro de búsqueda pageToken, de la siguiente manera:

NEXT_PAGE_TOKEN=NEXT_PAGE_TOKEN
curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22&pageToken=${NEXT_PAGE_TOKEN}

Reemplaza NEXT_PAGE_TOKEN por el valor nextPageToken en la respuesta de la solicitud anterior.

Cuando el valor nextPageToken está vacío, significa que no hay más resultados.

Borra la certificación

Precaución: No debes borrar las certificaciones de las cargas de trabajo de producción. Borrar las certificaciones puede dar como resultado un comportamiento impredecible. Estas instrucciones son para borrar certificaciones de prueba, como las que se crearon antes en este documento.

Antes de borrar la certificación, debes hacer lo siguiente:

1. Comprende las consecuencias de borrarla. Borrar una certificación bloquea en última instancia las imágenes de contenedor asociadas con la certificación para que no se implementen.

2. Detén todos los contenedores en ejecución asociados con las certificaciones que deseas borrar.

3. Borra todas las copias de las certificaciones donde residen, por ejemplo, las certificaciones en los repositorios de Artifact Analysis y Artifact Registry.

4. Asegúrate de que las imágenes afectadas estén bloqueadas para la implementación. Para ello, intenta volver a implementarlas.

Nota: Para mayor seguridad, considera borrar el par de claves y el certificador asociado.

Para borrar una certificación, ejecuta los siguientes comandos:

1. Enumera las certificaciones:

   gcloud container binauthz attestations list \
     --attestor-project=${ATTESTOR_PROJECT_ID} \
     --attestor=${ATTESTOR_NAME}
   

   La certificación contiene un ID de caso. El resultado es similar al siguiente:

   projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID
   

2. Guarda el ID de caso.

   Guarda el ID de caso de la certificación que deseas borrar.

   OCCURRENCE_ID=OCCURRENCE_ID
   

3. Borra la certificación:

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X DELETE \
     https://containeranalysis.googleapis.com/v1beta1/projects/${ATTESTATION_PROJECT_ID}/occurrences/${OCCURRENCE_ID}
   

   Vuelve a enumerar las certificaciones para verificar que se hayan borrado.

¿Qué sigue?

• Obtén más información sobre la separación de obligaciones y funciones de Identity and Access Management.
• Implementa la separación de obligaciones en este instructivo de Configuración de varios proyectos (GKE).
• Implementa una imagen de contenedor (GKE) en un clúster en el que está habilitada la Autorización Binaria.
• Implementa una imagen de contenedor (Cloud Run) en un clúster en el que esté habilitada la Autorización Binaria.