Créer des certificateurs à l'aide de l'API REST

Cette page explique comment créer un certificateur personnalisé dans l'autorisation binaire à l'aide de l'API REST.

Vous pouvez également effectuer ces étapes à l'aide de Google Cloud CLI ou de Google Cloud Console. 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.

Présentation

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, vous devez effectuer les opérations suivantes :

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.) Vous pouvez également utiliser des paires de clés PGP au lieu de clés 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. Dans une configuration multiprojets, vous avez probablement un projet déployant hébergeant la configuration de votre stratégie et un projet certifiant distinct hébergeant vos certificateurs.

Avant de commencer

Définir le projet par défaut

Si ce n'est pas déjà fait, définissez le projet Google Cloud par défaut :

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Configurer l'environnement

Configurez des variables d'environnement pour stocker les noms et les numéros de vos projets :

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 votre projet certifiant est le même que votre projet déployant, utilisez le même ID de projet pour les deux variables.

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 une note Artifact Analysis :

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

À l'aide d'un éditeur de texte, créez un fichier JSON décrivant la note Artifact Analysis dans /tmp/note_payload.json :

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 Artifact 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 sur la note

Vous devez également définir des autorisations sur la note Artifact Analysis que vous avez créée afin qu'elle soit accessible au compte de service du projet certifiant. Pour ce faire, vous devez mettre à jour la stratégie IAM de la note afin d'attribuer au compte le rôle containeranalysis.notes.occurrences.viewer.

Pour définir les autorisations, procédez comme suit :

Générez un fichier JSON contenant les informations nécessaires pour définir la stratégie 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"
```
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 les données JSON lorsque vous définissez la stratégie.

Configurer des clés cryptographiques

L'autorisation binaire vous permet d'utiliser des clés PKIX afin de vérifier de manière sécurisée l'identité du signataire ayant créé une attestation. Ainsi, seules les parties validées peuvent autoriser une image de conteneur. Au lieu de clés PKIX, vous pouvez également utiliser des clés PGP.

Créer une paire de clés PKIX

L'autorisation binaire vous permet d'utiliser des paires de clés PKIX asymétriques pour vérifier une attestation. La paire de clés consiste en une clé privée, que le signataire utilise pour signer numériquement des attestations, et une clé publique que vous ajoutez au certificateur. Par la suite, l'outil d'application de l'autorisation binaire utilise la clé publique du certificateur pour vérifier que l'attestation a bien été créée par le signataire.

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 clés RSA ou PGP pour la signature. Consultez la page Objectifs et algorithmes des clés pour plus d'informations sur les algorithmes de signature.

Les paires de clés asymétriques générées et stockées dans Cloud KMS sont compatibles avec le format PKIX. Pour créer une clé Cloud KMS à utiliser avec l'autorisation binaire, consultez la page Créer des clés asymétriques. Veillez à choisir l'option Signature asymétrique comme objectif de clé lors de la création de celle-ci.

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}

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é :

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

Comme ce fichier contient à la fois une clé publique et une clé privée, vous devez extraire la clé publique vers un fichier distinct afin de pouvoir l'ajouter au certificateur :
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

Créer le certificateur

L'étape suivante consiste à créer le certificateur proprement dit dans l'autorisation binaire avec la note Artifact Analysis associée. Vous devez également ajouter la clé cryptographique publique.

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 le certificateur et associez-lui la clé de sécurité publique :

PKIX (Cloud KMS)

Configurez des variables d'environnement supplémentaires pour stocker des informations sur la paire de clés Cloud KMS pour l'appel à l'API d'autorisation binaire.

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

Téléchargez le fichier de clé publique depuis Cloud KMS et enregistrez-le sur votre système local dans un fichier nommé /tmp/kms_public_key.pem.

Générez un fichier JSON contenant les informations requises pour créer le certificateur :

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

Créez le certificateur :

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 (clé locale)

Générez un fichier JSON contenant les informations requises pour créer le certificateur :

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

Créez le certificateur :

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

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 afin de déterminer si le projet dispose des autorisations nécessaires pour accéder au certificateur référencé.

Générez un fichier JSON contenant les informations nécessaires pour définir la stratégie IAM sur votre certificateur :

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

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://binaryauthorization.googleapis.com/v1beta1/projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}:setIamPolicy"

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

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

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

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