Ce document décrit l'utilisation de mécanismes d'encapsulation de clés (KEM) avec des clés Cloud KMS pour établir des codes 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 code secret partagé. Pour décapsuler le code secret partagé, utilisez les méthodes de décapsulation Cloud KMS. Vous ne pouvez pas utiliser le matériel de clé privée en dehors de Cloud KMS.
Avant de commencer
- Cette rubrique 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é de
KEY_ENCAPSULATION. Pour savoir quels algorithmes sont compatibles avec l'objectif de cléKEY_ENCAPSULATION, consultez la page Algorithmes d'encapsulation de clés.
Accorder des autorisations sur la clé
- Accordez le
roles/cloudkms.publicKeyViewerrôle sur la clé à chaque utilisateur ou principal qui doit récupérer la clé publique pour encapsuler le code secret. - Accordez le 'roles/cloudkms.decapsulator' rôle sur la clé à chaque utilisateur ou principal qui doit décapsuler des codes secrets avec cette clé.
Pour en savoir plus sur les autorisations et les rôles dans Cloud KMS, consultez la page 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 exemple2.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ésPUBLIC_KEY_FILE: chemin d'accès au fichier local dans lequel la clé publique sera enregistréePUBLIC_KEY_FORMAT: format cible de la clé publique, par exemplenist-pqc. Le format par défaut estpem.
Reformater la clé publique
La commande d'encapsulation nécessite que la clé publique soit au format PEM. Si vous avez téléchargé la clé publique dans un autre format, tel que nist-pqc, vous devez la convertir au format PEM. Si votre clé publique est déjà au format PEM,
passez à la section Encapsuler.
Utilisez la commande suivante pour convertir la clé publique d'une clé ML-KEM-768 :
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE
Utilisez la commande suivante pour convertir la clé publique d'une clé ML-KEM-1024 :
{ echo -n "MIIGMjALBglghkgBZQMEBAMDggYhAA==" | 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 brutPEM_PUBLIC_KEY_FILE: chemin d'accès et nom de fichier pour enregistrer la clé publique au format PEM
Encapsuler
Pour créer un code 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 PEMCIPHERTEXT_FILE: chemin d'accès où vous souhaitez enregistrer le texte chiffré résultantSHARED_SECRET_FILE: chemin d'accès où vous souhaitez enregistrer le code secret partagé résultant
Go
Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.
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 la dernière version de 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 exemple3KEY_NAME: nom de la clé à utiliser pour la décapsulationKEY_RING: nom du trousseau de clés dans lequel se trouve la cléLOCATION: emplacement Cloud KMS du trousseau de clésCIPHERTEXT_FILE: chemin d'accès au fichier local pour le texte chiffré d'entréeSHARED_SECRET_FILE: chemin d'accès au fichier local pour enregistrer le code secret partagé de sortie
Go
Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.
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.
Utilisez la
CryptoKeyVersions.decapsulate
méthode.
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ésLOCATION: emplacement Cloud KMS du trousseau de clésKEY_RING: nom du trousseau de clés qui inclut la cléKEY_NAME: nom de la clé à utiliser pour le chiffrementKEY_VERSION: ID de la version de clé à utiliser pour le chiffrementCIPHERTEXT: texte chiffré encodé en base64 que vous souhaitez décapsuler