Esta página se ha traducido con Cloud Translation API.

Crear atestaciones

En esta página se describen los pasos para crear una atestación de autorización binaria.

Las certificaciones se usan para autorizar el despliegue de imágenes de contenedor específicas en plataformas como Google Kubernetes Engine (GKE) y Cloud Run. Para usar las atestaciones, debes requerirlas en la regla correspondiente de tu política.

Una sola certificación puede 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 del despliegue, la autorización binaria usa atestadores para verificar las atestaciones.

Para configurar la autorización binaria en Cloud Run, GKE, Google Distributed Cloud y Cloud Service Mesh, consulta Configuración por plataforma y selecciona tu plataforma.

Usuarios de GKE: para consultar un tutorial completo que describa la aplicación basada en atestación con la autorización binaria y Google Kubernetes Engine (GKE), consulta Empezar a usar la herramienta de línea de comandos o Empezar a usar la consola Google Cloud .

Antes de empezar

En Descripción general de las certificaciones se indican los pasos que debes seguir antes de crear una certificación.

Habilitar la autorización binaria
Crea verificadores mediante la Google Cloud consola, la CLI de Google Cloud o la API REST.

Configurar el entorno

Especifica los IDs de tus proyectos:
```
ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
```
Haz los cambios siguientes:
- ATTESTOR_PROJECT_ID: el nombre del proyecto en el que almacenas tus attestors
- ATTESTATION_PROJECT_ID: el nombre del proyecto en el que almacenas tus certificaciones
Si quieres que la certificación se cree en el mismo proyecto que tus certificadores, usa el mismo ID de proyecto para ambas variables. Para ver un tutorial completo que muestre la separación de funciones con diferentes proyectos, consulta Configuración de varios proyectos.
Especifica el nombre del attestor 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}"
```
Haz los cambios siguientes:
- ATTESTOR_NAME: el nombre del encargado de la atestación, por ejemplo, build-secure o prod-qa.
- IMAGE_PATH: un URI que representa una ruta de imagen. Aunque la 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 atestación. Estos son algunos ejemplos de rutas 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: el resumen del manifiesto de la imagen. Por ejemplo, sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567 es el digest de la imagen asociado a la ruta de la imagen de ejemplo us-docker.pkg.dev/google-samples/containers/gke/hello-app. Para saber cómo obtener el digest de una imagen en Artifact Registry, consulta Gestionar imágenes. Para obtener el de una imagen en Container Registry, consulta Listar las versiones de una imagen.

Asignar roles de Gestión de Identidades y Accesos

Para crear certificaciones, debes asignar los siguientes roles de Gestión de Identidades y Accesos (IAM) a la identidad que crea el certificador, tal como se indica a continuación:

roles/containeranalysis.notes.attacher en el recurso de nota asociado al encargado de la atestación.
roles/containeranalysis.occurrences.editor en el proyecto de certificación resource.

Creas una certificación basada en un certificador. El attestor está asociado a una nota de Artifact Analysis. Al crear una certificación, se crea una instancia de Artifact Analysis y se adjunta a la nota.

Más información sobre cómo conceder acceso

Para saber cómo crear una atestación en una canalización de Cloud Build, consulta Crear atestaciones con Cloud Build.

Crear una atestación

Crear una certificación con una clave almacenada localmente

Para crear certificaciones firmadas con una clave local, sigue estos pasos:

Crea un archivo de carga útil de firma:

gcloud

Para crear el archivo de carga útil de la firma, introduce 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 tiene un aspecto similar al siguiente:

{
  "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 REST

Crea un archivo de carga útil llamado /tmp/generated_payload.json con las variables de entorno que has definido anteriormente 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

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

En esta guía se usa el algoritmo recomendado Elliptic Curve Digital Signature Algorithm (ECDSA) para la firma. También puedes usar el algoritmo RSA. Para obtener más información sobre los algoritmos de firma, consulta Propósitos y algoritmos de claves. Esta guía también usa el formato de firma de 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
```
Sustituye PRIVATE_KEY_FILE por la ruta a la clave privada que generaste al crear el attestor.

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

Para obtener el ID de clave pública del encargado de la atestación, introduce el siguiente comando:

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

Crea la atestación:

gcloud

Para crear y validar la certificación, introduce 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 la certificación se puede verificar mediante el certificador que has configurado en tu política.

Nota: El ID de clave puede ser cualquier cadena.

API REST

Para crear la atestación, sigue estos pasos:

Obtén el attestor asociado a la atestación y extrae el ID de la 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/"

Autorización Binaria devuelve 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": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2019-06-26T16:58:33.977438Z"
}

La clave pública se encuentra en el campo id.

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

Crea la atestació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/"

Crear una atestación con Cloud KMS

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

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
```
Haz los cambios siguientes:
- KMS_KEY_PROJECT_ID: el ID del proyecto en el que se almacenan tus claves de Cloud Key Management Service
- KMS_KEY_LOCATION: la ubicación de la clave (global es el valor predeterminado)
- 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

Firma y crea la atestación:

gcloud

Introduce 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 REST

Crea un archivo de carga útil llamado /tmp/generated_payload.json con las variables de entorno que has definido anteriormente:

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

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

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

En este ejemplo, la salida es similar a la 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.

Almacena la firma en una variable de entorno:
```
PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
```

Recupera el encargado de la atestación en cuyo nombre vas a firmar la atestación y extrae el ID de clave pública y el ID de nota almacenados:

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

Autorización Binaria devuelve 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": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2019-06-26T16:58:33.977438Z"
}

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

Almacena el ID de la clave pública en una variable de entorno:
```
PUBLIC_KEY_ID="PUBLIC_KEY_ID"
NOTE_URI="NOTE_URI"
```
Haz los cambios siguientes:
- PUBLIC_KEY_ID: el ID de clave pública del encargado de la atestación.
- NOTE_URI: el URI de la nota de análisis de artefactos asociada al attestor.

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

Crea la atestació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/"

Has creado la certificación.

Verifica que se ha creado la certificación

Para verificar que se ha creado la atestación, puedes enumerar las atestaciones asociadas a la imagen.

gcloud

Para obtener una lista de certificaciones, introduce 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 REST

Para solicitar una lista de certificaciones, introduce 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, puede obtener la siguiente página de resultados repitiendo la solicitud y añadiendo un parámetro de consulta pageToken, como se indica a continuación:

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}

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

Si nextPageToken está vacío, significa que no hay más resultados.

Eliminar la atestación

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

Entiende las consecuencias de eliminarlo. Si eliminas una atestación, se acabarán bloqueando las imágenes de contenedor asociadas a la atestación, por lo que no se podrán desplegar.
Detén todos los contenedores en ejecución asociados a las certificaciones que quieras eliminar.
Elimina todas las copias de las certificaciones donde se encuentren, por ejemplo, las certificaciones de los repositorios de Artifact Registry y Artifact Analysis.
Comprueba que las imágenes afectadas no se puedan desplegar intentando volver a desplegarlas.

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

Mostrar las certificaciones:

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

La atestación contiene un ID de ocurrencia. La salida tiene un aspecto similar al siguiente:

projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID

Guarda el ID de la ocurrencia.

Guarda el ID de ocurrencia de la certificación que quieras eliminar.
```
OCCURRENCE_ID=OCCURRENCE_ID
```

Elimina la atestación:

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

Verifica que las certificaciones se han eliminado volviendo a enumerarlas.

Siguientes pasos

Consulta más información sobre la separación de funciones y los roles de gestión de identidades y accesos.
Implementa la separación de tareas en este tutorial sobre la configuración de varios proyectos (GKE).
Despliega una imagen de contenedor (GKE) en un clúster en el que esté habilitada la autorización binaria.
Despliega una imagen de contenedor (Cloud Run) en un clúster en el que esté habilitada la autorización binaria.

Crear atestaciones Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Antes de empezar

Configurar el entorno

Asignar roles de Gestión de Identidades y Accesos

Crear una atestación

Crear una certificación con una clave almacenada localmente

gcloud

API REST

gcloud

API REST

Crear una atestación con Cloud KMS

gcloud

API REST

Verifica que se ha creado la certificación

gcloud

API REST

Eliminar la atestación

Siguientes pasos

Crear atestaciones