Encapsuler et décapsuler à l'aide de KEM

Ce document décrit l'utilisation de mécanismes d'encapsulation de clé (KEM) avec des clés Cloud KMS pour établir des secrets partagés.

L'encapsulation utilise la clé publique de la paire de clés KEM, et la décapsulation utilise la clé privée de la paire de clés. Cloud KMS vous permet de récupérer la clé publique, que vous pouvez ensuite utiliser avec des bibliothèques standards pour encapsuler votre secret partagé. Pour décapsuler le secret partagé, utilisez les méthodes de décapsulation Cloud KMS. Vous ne pouvez pas utiliser le contenu de la clé privée en dehors de Cloud KMS.

Avant de commencer

  • Ce document fournit des exemples qui s'exécutent sur la ligne de commande. Pour simplifier l'utilisation des exemples, utilisez Cloud Shell. L'exemple de chiffrement utilise OpenSSL, pré-installé sur Cloud Shell. Sinon, installez OpenSSL sur votre ordinateur.
  • Créez une clé KEM avec l'objectif de clé KEY_ENCAPSULATION. Pour savoir quels algorithmes sont compatibles avec l'objectif de clé KEY_ENCAPSULATION, consultez la page Algorithmes d'encapsulation de clé.

Accorder des autorisations sur la clé

  • Attribuez le rôle roles/cloudkms.publicKeyViewer sur la clé à chaque utilisateur ou principal qui doit récupérer la clé publique pour encapsuler le secret.
  • Attribuez le rôle roles/cloudkms.decapsulator sur la clé à chaque utilisateur ou compte principal qui doit décapsuler des secrets avec cette clé.

Pour en savoir plus sur les autorisations et les rôles dans Cloud KMS, consultez Autorisations et rôles.

Encapsulation

Pour encapsuler à l'aide d'une clé KEM, récupérez la clé publique et utilisez-la pour encapsuler.

gcloud

Dans cet exemple, OpenSSL doit être installé sur votre système local.

Télécharger la clé publique

gcloud kms keys versions get-public-key KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --output-file PUBLIC_KEY_FILE \
    --public-key-format PUBLIC_KEY_FORMAT

Remplacez les éléments suivants :

  • KEY_VERSION : numéro de version de la clé que vous souhaitez utiliser pour l'encapsulation, par exemple 2.
  • KEY_NAME : nom de la clé que vous souhaitez utiliser pour l'encapsulation.
  • KEY_RING : nom du trousseau de clés qui inclut la clé
  • LOCATION : emplacement Cloud KMS du trousseau de clés.
  • PUBLIC_KEY_FILE : chemin d'accès local au fichier dans lequel la clé publique sera enregistrée.
  • PUBLIC_KEY_FORMAT : format cible de la clé publique (par exemple, nist-pqc). Le format par défaut est pem.

Encapsuler

Pour créer un secret partagé et un texte chiffré, vous pouvez utiliser la commande suivante :

openssl pkeyutl \
    -encap \
    -pubin \
    -inkey PEM_PUBLIC_KEY_FILE \
    -out CIPHERTEXT_FILE \
    -secret SHARED_SECRET_FILE

Remplacez les éléments suivants :

  • PEM_PUBLIC_KEY_FILE : chemin d'accès au fichier de clé publique téléchargé au format PEM.
  • CIPHERTEXT_FILE : chemin d'accès où vous souhaitez enregistrer le texte chiffré obtenu.
  • SHARED_SECRET_FILE : chemin d'accès où vous souhaitez enregistrer le secret partagé obtenu.
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE

Remplacez les éléments suivants :

  • PUBLIC_KEY_FILE : chemin d'accès au fichier de clé publique téléchargé au format brut.
  • PEM_PUBLIC_KEY_FILE : chemin d'accès et nom du fichier dans lequel enregistrer la clé publique au format PEM.

Décapsulation

Utilisez Cloud KMS pour décapsuler un texte chiffré.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer ou mettre à jour Google Cloud CLI.

gcloud kms decapsulate \
    --version KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --ciphertext-file CIPHERTEXT_FILE \
    --shared-secret-file SHARED_SECRET_FILE

Remplacez les éléments suivants :

  • KEY_VERSION : version de la clé à utiliser pour la décapsulation (par exemple, 3).
  • KEY_NAME : nom de la clé à utiliser pour la décapsulation.
  • KEY_RING : nom du trousseau de clés où se trouve la clé.
  • LOCATION : emplacement Cloud KMS du trousseau de clés.
  • CIPHERTEXT_FILE : chemin d'accès local au texte chiffré d'entrée.
  • SHARED_SECRET_FILE : chemin d'accès au fichier local pour enregistrer le secret partagé de sortie.

API

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

Exécutez la méthode CryptoKeyVersions.decapsulate.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION:decapsulate" \
  --request "POST" \
  --header "authorization: Bearer TOKEN" \
  --header "content-type: application/json" \
  --data '{"ciphertext": "CIPHERTEXT"}'

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant le trousseau de clés.
  • LOCATION : emplacement Cloud KMS du trousseau de clés.
  • KEY_RING : nom du trousseau de clés qui inclut la clé
  • KEY_NAME : nom de la clé à utiliser pour le chiffrement.
  • KEY_VERSION : ID de la version de clé à utiliser pour le chiffrement.
  • CIPHERTEXT : texte chiffré encodé en base64 que vous souhaitez décapsuler.