Questo documento descrive l'utilizzo dei meccanismi di incapsulamento delle chiavi (KEM) con le chiavi Cloud KMS per stabilire secret condivisi.
L'incapsulamento utilizza la chiave pubblica della coppia di chiavi KEM, mentre il decapsulamento utilizza la chiave privata della coppia di chiavi. Cloud KMS ti consente di recuperare la chiave pubblica, che puoi quindi utilizzare con le librerie standard per incapsulare il secret condiviso. Per decapsulare il secret condiviso, utilizza i metodi di decapsulamento di Cloud KMS. Non puoi utilizzare il materiale della chiave privata al di fuori di Cloud KMS.
Prima di iniziare
- Questo documento fornisce esempi che vengono eseguiti dalla riga di comando. Per semplificare l'utilizzo degli esempi, utilizza Cloud Shell. L'esempio di crittografia utilizza OpenSSL, che è preinstallato su Cloud Shell. In caso contrario, installa OpenSSL sul tuo computer.
- Crea una chiave KEM con lo scopo della chiave di
KEY_ENCAPSULATION. Per vedere quali algoritmi sono supportati per lo scopo della chiaveKEY_ENCAPSULATION, consulta Algoritmi di incapsulamento delle chiavi.
Concedi le autorizzazioni per la chiave
- Concedi il ruolo
roles/cloudkms.publicKeyViewersulla chiave a ogni utente o entità che deve recuperare la chiave pubblica per incapsulare il secret. - Concedi il ruolo 'roles/cloudkms.decapsulator' sulla chiave a ogni utente o entità che deve decapsulare i secret con questa chiave.
Per ulteriori informazioni su autorizzazioni e ruoli in Cloud KMS, consulta Autorizzazioni e ruoli.
Incapsulamento
Per eseguire l'incapsulamento utilizzando una chiave KEM, recupera la chiave pubblica e utilizzala per l'incapsulamento.
gcloud
Questo esempio richiede l'installazione di OpenSSL sul sistema locale.
Scarica la chiave pubblica
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
Sostituisci quanto segue:
KEY_VERSION: il numero di versione della chiave che vuoi utilizzare per l'incapsulamento, ad esempio2.KEY_NAME: il nome della chiave che vuoi utilizzare per l'incapsulamento.KEY_RING: il nome delle chiavi automatizzate che contiene la chiave.LOCATION: la posizione di Cloud KMS delle chiavi automatizzate.PUBLIC_KEY_FILE: il percorso del file locale in cui verrà salvata la chiave pubblica.PUBLIC_KEY_FORMAT: il formato di destinazione per la chiave pubblica, ad esempionist-pqc. Il formato predefinito èpem.
Riformatta la chiave pubblica
Il comando di incapsulamento richiede che la chiave pubblica sia in formato PEM. Se hai scaricato la chiave pubblica in un altro formato, ad esempio nist-pqc, devi convertirla in formato PEM. Se la chiave pubblica è già in formato PEM,
continua da Incapsula.
Utilizza il seguente comando per convertire la chiave pubblica per una chiave ML-KEM-768:
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE
Utilizza il seguente comando per convertire la chiave pubblica per una chiave ML-KEM-1024:
{ echo -n "MIIGMjALBglghkgBZQMEBAMDggYhAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE
Sostituisci quanto segue:
PUBLIC_KEY_FILE: il percorso del file della chiave pubblica scaricata in formato non elaborato.PEM_PUBLIC_KEY_FILE: il percorso e il nome del file in cui salvare la chiave pubblica in formato PEM.
Incapsula
Per creare un secret condiviso e un testo crittografato, puoi utilizzare il seguente comando:
openssl pkeyutl \
-encap \
-pubin \
-inkey PEM_PUBLIC_KEY_FILE \
-out CIPHERTEXT_FILE \
-secret SHARED_SECRET_FILE
Sostituisci quanto segue:
PEM_PUBLIC_KEY_FILE: il percorso del file della chiave pubblica scaricata in formato PEM.CIPHERTEXT_FILE: il percorso in cui vuoi salvare il testo crittografato risultante.SHARED_SECRET_FILE: il percorso in cui vuoi salvare il secret condiviso risultante.
Go
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Cloud KMS.
Decapsulamento
Utilizza Cloud KMS per decapsulare un testo crittografato.
gcloud
Per utilizzare Cloud KMS dalla riga di comando, devi prima installare o eseguire l'upgrade all'ultima versione di 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
Sostituisci quanto segue:
KEY_VERSION: la versione della chiave da utilizzare per il decapsulamento, ad esempio3.KEY_NAME: il nome della chiave da utilizzare per il decapsulamento.KEY_RING: il nome delle chiavi automatizzate in cui si trova la chiave.LOCATION: la posizione di Cloud KMS per le chiavi automatizzate.CIPHERTEXT_FILE: il percorso del file locale per il testo crittografato di input.SHARED_SECRET_FILE: il percorso del file locale per salvare il secret condiviso di output.
Go
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Cloud KMS.
API
Questi esempi utilizzano curl come client HTTP per mostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accesso all'API Cloud KMS.
Utilizza il
CryptoKeyVersions.decapsulate
metodo.
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"}'
Sostituisci quanto segue:
PROJECT_ID: l'ID del progetto che contiene le chiavi automatizzate.LOCATION: la posizione di Cloud KMS delle chiavi automatizzate.KEY_RING: il nome delle chiavi automatizzate che contiene la chiave.KEY_NAME: il nome della chiave da utilizzare per la crittografia.KEY_VERSION: l'ID della versione della chiave da utilizzare per la crittografia.CIPHERTEXT: il testo crittografato codificato in Base64 che vuoi decapsulare.