Créer des certificateurs à l'aide de gcloud CLI

Cette page explique comment créer un certificateur dans l'autorisation binaire à l'aide de Google Cloud CLI. Vous pouvez également effectuer ces étapes à l'aide de Google Cloud Console ou de l'API REST. Cette tâche fait partie de la configuration de l'autorisation binaire.

Utilisateurs de Cloud Build: vous pouvez utiliser le certificateur built-by-cloud-build pour déployer uniquement des images créées par Cloud Build.

Un certificateur est une ressource Google Cloud utilisée par l'autorisation binaire pour valider une attestation. Pour en savoir plus sur les attestations, consultez la page Présentation de l'autorisation binaire.

Pour créer un certificateur, procédez comme suit :

Créer une note dans Artifact Analysis pour stocker les métadonnées de confiance utilisées dans le processus d'autorisation.
Configurer une paire de clés PKIX pouvant être utilisées pour vérifier l'identité du certificateur. (Les paires de clés asymétriques générées par Cloud Key Management Service (Cloud KMS) sont dans un format compatible avec PKIX.)
Créer le certificateur proprement dit dans l'autorisation binaire, puis lui associer la note et la clé publique que vous avez créées.

Dans une configuration à un seul projet, vous créez votre certificateur dans le projet Google Cloud au sein duquel vous configurez votre stratégie d'autorisation binaire. Pour accéder à un tutoriel de projet unique de bout en bout incluant ces étapes, consultez les pages suivantes : Premiers pas avec Google Cloud CLI ou Premiers pas avec la console Google Cloud.

Dans une configuration multiprojets, nous vous recommandons de disposer de projets distincts: un projet de déploiement, dans lequel votre stratégie est configurée, un projet certifiant, dans lequel sont stockés vos certificateurs et un projet d'attestation pour les attestations. Pour accéder à un tutoriel multiprojet de bout en bout incluant ces étapes, consultez la page Configuration multiprojets.

Avant de commencer

Avant de créer des certificateurs, procédez comme suit :

Configurer l'environnement du projet

Dans cette section, vous allez configurer des variables d'environnement.

Configurez des variables d'environnement pour stocker les noms et les numéros de vos projets. Si votre projet certifiant est le même que votre projet déployant, utilisez le même ID de projet pour les deux variables.

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

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

Vous devez également obtenir les noms des comptes de service associés à ces projets :

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"

Créer une note Artifact Analysis

L'autorisation binaire utilise Artifact Analysis pour stocker les métadonnées de confiance utilisées dans le processus d'autorisation. Pour chaque certificateur que vous créez, vous devez créer une note Artifact Analysis. Chaque attestation est stockée en tant qu'occurrence de cette note.

Pour créer la note, procédez comme suit:

Configurez des variables d'environnement pour stocker l'ID de note et une description lisible :
```
NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION
```
Remplacez les éléments suivants :
- NOTE_ID est le nom interne de la note, composé de caractères alphanumériques sans espace (par exemple, test-attestor-note) ;
- NOTE_URI est le chemin d'accès complet à la ressource de note ;
- DESCRIPTION est le nom lisible à afficher pour la note (par exemple, Test Attestor Note).

Dans un éditeur de texte, créez un fichier JSON décrivant la note:

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

Créez la note en envoyant une requête HTTP à l'API REST Container 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}"

Pour vérifier que la note a bien été créée, exécutez la commande suivante :

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

Définir des autorisations IAM sur la note

Vous devez attribuer un rôle IAM (Identity and Access Management) au compte de service du projet certifiant pour la ressource de note Artifact Analysis. Pour ce faire, ajoutez le compte de service du projet certifiant au rôle containeranalysis.notes.occurrences.viewer dans la stratégie IAM de la note.

Pour ajouter le rôle, procédez comme suit:

Générez un fichier JSON contenant les informations nécessaires pour définir le rôle IAM sur votre note :

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

Ajoutez le compte de service et les rôles d'accès requis à la stratégie IAM pour la note que vous avez créée :
```
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"
```
Remarque : Lorsque vous ajoutez un rôle à la stratégie à l'aide de la méthode ci-dessus, celui-ci remplace tous les rôles existants sur la note. Si vous souhaitez conserver les rôles existants, veillez à les inclure dans le fichier de données JSON précédent.

Utilisation multiprojet

Si vous stockez le certificateur dans un projet et que vous le déployez dans un projet distinct, vous devez attribuer le rôle roles/binaryauthorization.attestorsVerifier au compte de service associé au projet déployant sur le certificateur.

Configurer des clés cryptographiques

L'autorisation binaire vous permet d'utiliser des clés PKIX afin de valider les attestations.

Générer une paire de clés

Dans ce guide, l'algorithme de signature numérique à courbe elliptique (ECDSA) recommandé est utilisé pour générer une paire de clés PKIX. Vous pouvez également utiliser des paires de clés RSA ou PGP. Consultez la page Objectifs et algorithmes des clés pour plus d'informations sur les algorithmes de signature.

Une paire de clés PKIX comprend une clé privée que les signataires utilisent pour signer les attestations, et une clé publique que vous ajoutez au certificateur. Au moment du déploiement, l'autorisation binaire utilise cette clé publique pour valider l'attestation.

PKIX (Cloud KMS)

Pour créer la paire de clés dans Cloud KMS, procédez comme suit :

Pour configurer les variables d'environnement nécessaires à la création de la paire de clés, exécutez les commandes suivantes :
```
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
```
Remplacez les éléments suivants :
- KMS_KEY_PROJECT_ID : ID du projet dans lequel les clés sont stockées
- KMS_KEY_LOCATION : emplacement de la clé
- KMS_KEYRING_NAME : nom du trousseau de clés
- KMS_KEY_NAME : nom de la clé
- KMS_KEY_VERSION : version de la clé
- KMS_KEY_ALGORITHM : algorithme. La valeur ec-sign-p256-sha256 est recommandée.
- KMS_PROTECTION_LEVEL : niveau de protection (par exemple, software).

Pour créer le trousseau, exécutez la commande suivante :

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

Pour créer la clé, exécutez la commande suivante :
```
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}
```
Remplacez les éléments suivants :
- KMS_KEY_NAME : nom de la clé
- KMS_KEY_LOCATION : emplacement de la clé
- KMS_KEYRING_NAME : nom du trousseau de clés
- KMS_KEY_PURPOSE: objectif de la clé, défini sur ASYMMETRIC_SIGN
- KMS_KEY_ALGORITHM : algorithme. La valeur ec-sign-p256-sha256 est recommandée.
- KMS_PROTECTION_LEVEL : niveau de protection (par exemple, software).

PKIX (clé locale)

Pour générer une paire de clés PKIX asymétrique locale et la stocker dans un fichier, procédez comme suit :

Générez la clé privée :

PRIVATE_KEY_FILE correspond au nom du fichier contenant la clé privée utilisée pour signer la charge utile de l'attestation.
```
PRIVATE_KEY_FILE="/tmp/ec_private.pem"
openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}
```
Extrayez la clé publique de la clé privée et stockez-la dans un fichier :

PUBLIC_KEY_FILE est le nom du fichier contenant la clé publique, stockée dans le certificateur.
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

Créer le certificateur

Pour créer le certificateur, procédez comme suit :

Configurez une variable d'environnement pour stocker le nom du certificateur, tel que défini dans l'autorisation binaire :
```
ATTESTOR_NAME=ATTESTOR_NAME
```
Où ATTESTOR_NAME est le nom du certificateur que vous souhaitez créer (par exemple, build-secure ou prod-qa).

Créez la ressource de certificateur dans l'autorisation binaire :

gcloud --project="${ATTESTOR_PROJECT_ID}" \
    container binauthz attestors create "${ATTESTOR_NAME}" \
    --attestation-authority-note="${NOTE_ID}" \
    --attestation-authority-note-project="${ATTESTOR_PROJECT_ID}"

Ajoutez une liaison de rôle IAM avec le certificateur pour le projet déployant. Celle-ci est utilisée par l'autorisation binaire lorsqu'elle évalue une stratégie pour déterminer si le projet est autorisé à accéder aux attestations associées.
```
gcloud container binauthz attestors add-iam-policy-binding \
    "projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
    --member="serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}" \
    --role=roles/binaryauthorization.attestorsVerifier
```
Pour ajouter la clé publique au certificateur, procédez comme suit:
PKIX (Cloud KMS)
Pour ajouter la clé publique d'une paire de clés Cloud KMS au certificateur, exécutez la commande suivante:
```
gcloud --project="${ATTESTOR_PROJECT_ID}" \
    container binauthz attestors public-keys add \
    --attestor="${ATTESTOR_NAME}" \
    --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}"
```
PKIX (clé locale)
Pour ajouter une clé publique PKIX stockée localement à un certificateur, exécutez la commande suivante:
```
gcloud --project="${ATTESTOR_PROJECT_ID}" \
    container binauthz attestors public-keys add \
    --attestor="${ATTESTOR_NAME}" \
    --pkix-public-key-file=${PUBLIC_KEY_FILE} \
    --pkix-public-key-algorithm=ecdsa-p256-sha256
```
Si vous ajoutez une clé publique à un certificateur sans spécifier d'ID de clé (qui peut être n'importe quelle chaîne), celui-ci est automatiquement attribué au format RFC 6920 : ni:///sha-256;..., où ... est un hachage encodé de la clé publique. Cette valeur est renvoyée dans le champ id du résultat de la commande. L'ID renvoyé peut être enregistré dans PUBLIC_KEY_ID et utilisé pour créer une attestation.

Enregistrez l'ID de clé publique.

Pour créer une attestation, vous avez besoin de l'ID de clé publique.

Pour enregistrer l'ID de la clé publique, vous pouvez copier le résultat de la commande binauthz attestors public-keys add ci-dessus.

Vous pouvez également afficher l'ID de clé publique de votre certificateur à tout moment à l'aide de la commande suivante :

gcloud container binauthz attestors describe ${ATTESTOR}

Pour enregistrer votre ID de clé publique dans une variable d'environnement, saisissez la commande suivante:

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

Vérifier que le certificateur a bien été créé

Pour vérifier que le certificateur a été créé, exécutez la commande suivante :

gcloud container binauthz attestors list \
    --project="${ATTESTOR_PROJECT_ID}"

Étapes suivantes

Découvrez comment créer des attestations pour votre certificateur.
Mettez à jour votre stratégie d'autorisation binaire pour exiger des attestations en utilisant la console Google Cloud, Google Cloud CLI et l'API REST.