Obiettivi

Questa esercitazione ti guida nella creazione e nell'importazione in modo sicuro di chiavi di crittografia nel servizio Hyper Protect Crypto Services. È destinato agli utenti che non hanno dimestichezza con la funzione di gestione delle chiavi di Hyper Protect Crypto Services, ma che potrebbero avere familiarità con i sistemi di gestione delle chiavi. Il completamento dei seguenti passi richiede circa 20 minuti.

• Configurazione dell'API del servizio di gestione delle chiavi
• Preparazione della tua istanza del servizio Hyper Protect Crypto Services per iniziare a importare chiavi
• Creazione e crittografia delle chiavi utilizzando il toolkit di crittografia OpenSSL
• Importazione di una chiave crittografata nella tua istanza del servizio Hyper Protect Crypto Services

Questa esercitazione non comporterà alcun addebito sul tuo account IBM Cloud.

Flusso di fasi

Il seguente diagramma di flusso fornisce una panoramica su come creare e importare le chiavi di codifica. È possibile fare clic su ogni passo del grafico per visualizzare i dettagli del passo.

Prima di iniziare

Per iniziare, hai bisogno della CLI IBM Cloud in modo da poter interagire con i servizi di cui esegui il provisioning su IBM Cloud. È inoltre necessario installare localmente i pacchetti di openssl e jq sulla stazione di lavoro.

1. Creare un account IBM Cloud.

2. Scarica e installa la CLI IBM Cloud per il tuo sistema operativo.

3. Scaricare e installare IBM Key Protect CLI plug-in v0.6.3 o successivi, e configurarlo da utilizzare in Hyper Protect Crypto Services. Assicurarsi di aggiornare la variabile KP_PRIVATE_ADDR all'URL endpoint di gestione delle chiavi di istanza corrente.

   Per verificare la tua versione IBM Key Protect CLI plug-in:

   ibmcloud plugin show key-protect
   

   Per aggiornare il tuo IBM Key Protect CLI plug-in all'ultima versione:

   ibmcloud plugin update key-protect -r 'IBM Cloud'
   

4. Scaricare e installare la libreria di crittografiaOpenSSL.

   Puoi utilizzare i comandi openssl per creare le chiavi di crittografia sulla tua stazione di lavoro locale se stai provando Hyper Protect Crypto Services per la prima volta. Questa esercitazione richiede OpenSSL versione 1.0.2r o superiore.

   Se stai utilizzando un Mac, puoi essere rapidamente operativo con OpenSSL utilizzando Homebrew. Esegui brew install openssl se stai installando il pacchetto per la prima volta oppure esegui brew upgrade openssl per eseguire l'upgrade del tuo pacchetto esistente alla versione più recente.

5. Scaricare e installare jq.

   jq ti aiuta a dividere in sezioni i dati JSON. Utilizzerai jq in questa esercitazione per acquisire e utilizzare i dati specifici restituiti quando richiami l'API del servizio di gestione delle chiavi Hyper Protect Crypto Services.

6. Creare un'istanza di servizio Hyper Protect Crypto Services.

7. Inizializza l'istanza di servizio Hyper Protect Crypto Services.

8. Impostare il servizio di gestione delle chiavi Hyper Protect Crypto Services.

Crea un token di importazione

Con le tue credenziali di servizio, puoi iniziare a interagire con l'API del servizio di gestione delle chiavi per creare e portare le chiavi di crittografia al servizio.

Nel seguente passo, creerai un token di importazione per la tua istanza di servizio Hyper Protect Crypto Services. Creando un token di importazione basato su una politica da te specificata, abiliti una maggiore sicurezza per la tua chiave di crittografia mentre è in transito al servizio.

1. Dalla riga di comando, cambiare in una nuova directory hs-crypto-test.

   mkdir hs-crypto-test && cd hs-crypto-test
   

   Userai questa directory per memorizzare i file che creerai nei passi successivi.

2. È possibile creare un token di importazione per la propria istanza di servizio Hyper Protect Crypto Services tramite l'utilizzo del key management service API o utilizzando la CLI e quindi salvare la risposta ad un file JSON.

   • Utilizza API

     curl -X POST $HPCS_API_URL/api/v2/import_token \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -H "Bluemix-Instance: $INSTANCE_ID" \
         -d '{
             "expiration": 1200,
             "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
     

     Nel corpo della richiesta, è possibile specificare una politica sul token di importazione che limiti l'utilizzo in base al tempo e al conteggio di utilizzo. In questo esempio, imposti il tempo di scadenza per il token di importazione su 1200 secondi (20 minuti) e consenti anche solo un singolo richiamo di tale token entro il tempo di scadenza.

   • Utilizza la CLI IBM Key Protect

     ibmcloud kp import-token create --instance-id $INSTANCE_ID --max-retrievals=1 --expiration=1200 -o json > createImportTokenResponse.json
     

3. Visualizza i dettagli per il token di importazione.

   jq '.' createImportTokenResponse.json
   

   L'output visualizza i metadati associati al token di importazione, come la data di creazione e i dettagli della politica. Il seguente frammento di codice mostra un output di esempio.

   {
     "creationDate": "2020-06-08T16:58:29Z",
     "expirationDate": "2020-06-08T17:18:29Z",
     "maxAllowedRetrievals": 1,
     "remainingRetrievals": 1
   }
   

Recupera il token di importazione

Nel passo precedente, hai creato un token di importazione e hai visualizzato i metadati associati al token.

In questo passo, richiamerai la chiave pubblica e il valore nonce associati al token di importazione. Avrai bisogno della chiave pubblica per crittografare i dati in un passo successivo e del nonce per verificare la tua richiesta di importazione protetta al servizio Hyper Protect Crypto Services.

Per richiamare il contenuto del token di importazione:

1. Richiama il token di importazione che hai generato nel passo precedente e salva quindi la risposta in un file JSON.

   • Utilizza API

     curl -X GET $HPCS_API_URL/api/v2/import_token \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Bluemix-Instance: $INSTANCE_ID" > getImportTokenResponse.json
     

   • Utilizza la CLI IBM Key Protect

     ibmcloud kp import-token show -o json > getImportTokenResponse.json
     

2. Facoltativo; ispeziona il contenuto del token di importazione.

   jq '.' getImportTokenResponse.json
   

   L'output visualizza informazioni dettagliate sul token di importazione. Il seguente frammento di codice mostra un output di esempio con i valori troncati.

   {
     "creationDate": "2020-06-08T16:58:29Z",
     "expirationDate": "2020-06-08T17:18:29Z",
     "maxAllowedRetrievals": 1,
     "remainingRetrievals": 0,
     "payload": "MIICIjANBgkqhkiG...",
     "nonce": "8zJE9pKVdXVe/nLb"
   }
   

   Il valore payload rappresenta la chiave pubblica associata al token di importazione. Questo valore ha una codifica base64. Per una sicurezza aggiuntiva, Hyper Protect Crypto Services fornisce un valore nonce utilizzato per verificare l'originalità di una richiesta al servizio. Sarà necessario crittografare e fornire questo valore quando si importa la chiave di codifica.

3. Decodificare e salvare la chiave pubblica in un file chiamato PublicKey.pem ed estrarre i valori in variabili da utilizzare in seguito.

   jq -r '.payload' getImportTokenResponse.json | openssl enc -base64 -A -d -out PublicKey.pem
   

   HPCS_PUBKEY="$(jq -r '.payload' getImportTokenResponse.json)"
   NONCE="$(jq -r '.nonce' getImportTokenResponse.json)"
   

   La chiave pubblica viene ora scaricata sulla workstation in formato PEM. Continua al passo successivo.

Creare una chiave di codifica

Con Hyper Protect Crypto Services, puoi attivare i vantaggi di sicurezza di Keep Your Own Key (KYOK) creando e caricando le tue proprie chiavi di crittografia da utilizzare su IBM Cloud.

Nel passo seguente, si creerà una chiave simmetrica AES a 256 bit sulla stazione di lavoro locale.

Questa esercitazione utilizza il toolkit di crittografia OpenSSL per generare una chiave pseudo-casuale, ma potresti voler esplorare le diverse opzioni per generare chiavi più complesse in base alle tue esigenze di sicurezza. Ad esempio, potresti voler utilizzare il sistema di gestione delle chiavi interno della tua organizzazione, supportato da un HSM (hardware security module) in loco, per creare ed esportare le chiavi.

Se si desidera creare una chiave simmetrica AES a 256 - bit, dalla riga di comando, eseguire il seguente comando openssl :

openssl rand 32 > PlainTextKey.bin

È possibile saltare questo passo se si utilizza la propria chiave in questo tutorial.

Operazione riuscita. La tua chiave di crittografia viene ora salvata in un file denominato PlainTextKey.bin. Continua al passo successivo.

Imposta la chiave di crittografia come variabile di ambiente

Se si crea la chiave seguendo passo 3, per codificare il tasto e impostare il valore codificato come variabile di ambiente, eseguire il seguente comando. È possibile saltare questo passo se si utilizza la propria chiave in questo tutorial:

KEY_MATERIAL=$(openssl enc -base64 -A -in PlainTextKey.bin)

Crittografare il nonce con la chiave di codifica

Per la sicurezza extra, Hyper Protect Crypto Services richiede verifica nonce quando si importa una chiave di codifica al servizio.

Nella crittografia, un nonce funge da token di sessione che verifica l'originalità di una richiesta per proteggere da attacchi malintenzionati e da chiamate non autorizzate. Utilizzando lo stesso nonce che era stato distribuito da Hyper Protect Crypto Services, aiuti a garantire che la tua richiesta di caricare una chiave sia valida. Il valore nonce deve essere crittografato utilizzando la stessa chiave che vuoi importare nel servizio.

Per crittografare il valore nonce:

1. Se si desidera utilizzare l'API per eseguire i passi successivi, effettuare quanto segue:

   Non devi eseguire questo passo se stai per utilizzare la CLI IBM Key Protect.

   1. Scarica la kms-encrypt-nonce binaria di esempio compatibile con il tuo sistema operativo. Estrarre il file, quindi spostare il file binario nella directory hs-crypto-test.

      Il binario contiene uno script che è possibile utilizzare per eseguire la crittografia AES - CBC sul valore nonce utilizzando la chiave generata nel passo 2. Per ulteriori informazioni sullo script, controlla il file di origine su GitHub.

   2. Se si sta utilizzando Linux, contrassegnare il file come eseguibile eseguendo il seguente comando chmod. È possibile saltare questo passo se si utilizza Windows.

      chmod +x ./kms-encrypt-nonce
      

   3. Eseguire lo script per crittografare il valore nonce con la chiave generata in passo 2.

2. Salva il nonce criptato in un file chiamato EncryptedValues.json.

   • Utilizza API

     ./kms-encrypt-nonce -key $KEY_MATERIAL -nonce $NONCE -alg "CBC" > EncryptedValues.json
     

   • Utilizza la CLI IBM Key Protect

     ibmcloud kp import-token nonce-encrypt --key "$KEY_MATERIAL" --nonce "$NONCE" --cbc -o json > EncryptedValues.json
     

3. Facoltativo: Ispeziona il contenuto del file JSON.

   jq '.' EncryptedValues.json
   

   L'output visualizza i valori che sarà necessario fornire per il passo successivo. Il seguente frammento di codice mostra un output di esempio con i valori troncati.

   {
     "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
     "iv": "puQrzDX7gU1TcTTx"
   }
   

   Il valore encryptedNonce rappresenta il nonce originale racchiuso (o codificato) dalla chiave generata utilizzando OpenSSL. Il valore iv è il vettore di inizializzazione (IV) creato dall'algoritmo AES - CBC ed è richiesto successivamente in modo che Hyper Protect Crypto Servicespossa decodificare correttamente il nonce.

Crittografa la chiave di codifica creata

Successivamente, utilizza la chiave pubblica che è stata distribuita da Hyper Protect Crypto Services nel passo 2 per crittografare la chiave di crittografia che hai creato utilizzando OpenSSL.

• Crittografare la chiave di codifica creata con l'API, e assegnare la chiave alla variabile di ambiente:

  openssl pkeyutl \
    -encrypt \
    -pubin \
    -keyform PEM \
    -inkey PublicKey.pem \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha1 \
    -in PlainTextKey.bin \
    -out EncryptedKey.bin
  

  ENCRYPTED_KEY=$(openssl enc -base64 -A -in EncryptedKey.bin)
  

  Se riscontri un errore nelle impostazioni di parametro quando esegui il comando openssl su Mac OSX, è possibile che tu debba assicurarti che OpenSSL sia configurato correttamente per il tuo ambiente. Se hai installato OpenSSL utilizzando Homebrew, esegui brew update e quindi brew install openssl per ottenere la versione più recente. Quindi, eseguire export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.bash_profile per collegare il package. Dalla riga di comando, esegui which openssl && openssl version per verificare che l'ultima versione di OpenSSL sia disponibile nell'ubicazione /usr/local/. Se continui a riscontrare errori, assicurati di utilizzare solo i parametri elencati in questo esempio.

• Crittografare la chiave di codifica creata con il IBM Key Protect CLI:

  ibmcloud kp import-token key-encrypt -k "$KEY_MATERIAL" -p "$HPCS_PUBKEY" --hash SHA1 -o json > EncryptedKey.json
  ENCRYPTED_KEY=$(jq -r '.encryptedKey' EncryptedKey.json)
  

  Operazione riuscita. Ora sei pronto a caricare la tua chiave crittografata in Hyper Protect Crypto Services. Continua al passo successivo.

Importa il tasto crittografato

Puoi ora importare la chiave crittografata utilizzando l'API del servizio di gestione delle chiavi.

Per importare la chiave codificata:

1. Raccogliere il nonce codificato e i valori del vettore di inizializzazione (IV).

   ENCRYPTED_NONCE=$(jq -r '.encryptedNonce' EncryptedValues.json)
   

   IV=$(jq -r '.iv' EncryptedValues.json)
   

2. Memorizzare la chiave crittografata nella propria istanza di servizio Hyper Protect Crypto Services.

   • Utilizza API

     curl -X POST  $HPCS_API_URL/api/v2/keys \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -H "Bluemix-Instance: $INSTANCE_ID" \
         -d '{
           "metadata": {
             "collectionType": "application/vnd.ibm.kms.key+json",
             "collectionTotal": 1
           },
           "resources": [
           {
             "name": "encrypted-root-key",
             "type": "application/vnd.ibm.kms.key+json",
             "payload": "'"$ENCRYPTED_KEY"'",
             "extractable": false,
             "encryptionAlgorithm": "RSAES_OAEP_SHA_1",
             "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
             "iv": "'"$IV"'"
           }
         ]
       }' > createRootKeyResponse.json
     

     Nel corpo della richiesta, fornisci la chiave di crittografia che hai preparato nel passo precedente. Puoi fornire i valori di IV e nonce crittografato necessari per verificare la richiesta. Infine, il valore extractable impostato su false designa la tua nuova chiave come una chiave root nel servizio che puoi utilizzare per la crittografia envelope.

     Se la richiesta API non riesce con un errore di importazione token scaduto, tornare al passo 1 per creare un nuovo token di importazione. Ricordati che i token di importazione e le loro chiavi pubbliche associate scadono in base alla politica da te specificata al momento della creazione.

   • Utilizza la CLI IBM Key Protect

     ibmcloud kp key create new-imported-key --key-material "$ENCRYPTED_KEY" --encrypted-nonce "$ENCRYPTED_NONCE" --iv "$IV" --sha1 -o json > createRootKeyResponse.json
     

     Dietro le quinte, Hyper Protect Crypto Services riceve il tuo pacchetto crittografato su una connessione TLS 1.2. All'interno di un HSM (Hardware Security Module), il sistema utilizza la chiave privata per decrittografare la chiave simmetrica. Infine, il sistema utilizza la chiave simmetrica e l'IV per decrittografare il nonce e verificare la richiesta. La tua chiave è ora conservata in un modulo di sicurezza hardware convalidato di tipo FIPS 140 - 2 Level 4.

3. Visualizzare i dettagli per la chiave.

   jq '.' createRootKeyResponse.json
   

   Il seguente frammento mostra un output di esempio.

   {
     "metadata": {
       "collectionType": "application/vnd.ibm.kms.key+json",
       "collectionTotal": 1
     },
     "resources": [
       {
         "id": "644cba65-e240-471f-8b84-14115447d2ae",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "encrypted-root-key",
         "state": 1,
         "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:346d9f67-4bb2-481e-a3e1-3c2c646aa886:key:644cba65-e240-471f-8b84-14115447d2ae",
         "extractable": false,
         "imported": true
       }
     ]
   }
   

   • Il valore id è un identificativo univoco assegnato alla tua chiave e viene utilizzato per chiamate successive all'API del servizio di gestione delle chiavi.

   • Il valore state impostato su 1 indica che la tua chiave si trova ora nello Stato chiave attivo.

   • Il valore crn fornisce il percorso con ambito completo alla chiave che specifica dove si trova la risorsa all'interno di IBM Cloud.

   • Infine, i valori extractable e imported descrivono questa risorsa come una chiave root che hai importato nel servizio. Quando imposti l'attributo extractable su true, il servizio designa la chiave come chiave standard che puoi archiviare nelle tue applicazioni o nei tuoi servizi. In caso contrario, quando si imposta l'attributo extractable a false, il servizio designa la chiave come chiave principale.

4. Facoltativo: vai al dashboard Hyper Protect Crypto Services per visualizzare e gestire la tua chiave.

   Puoi sfogliare le caratteristiche generali delle tue chiavi dalla pagina dei dettagli dell'applicazione. Scegli da un elenco di opzioni per la gestione della tua chiave, come ad esempio la rotazione della chiave o l'eliminazione della chiave.

Ripulisci

1. Raccogli l'identificativo per la chiave di crittografia che hai importato nel passo precedente.

   ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
   

2. Rimuovi la chiave di crittografia dalla tua istanza del servizio Hyper Protect Crypto Services.

   • Utilizza API

     curl -X DELETE $HPCS_API_URL/api/v2/keys/$ROOT_KEY_ID \
       -H "Accept: application/vnd.ibm.collection+json" \
       -H "Authorization: $ACCESS_TOKEN" \
       -H "Bluemix-Instance: $INSTANCE_ID" | jq .
     

   • Utilizza la CLI IBM Key Protect

     ibmcloud kp key delete {ROOT_KEY_ID}
     

3. Rimuovere tutti i file locali associati a questa esercitazione.

   rm kms-encrypt-nonce *.json *.bin *.pem
   

4. Elimina la directory di test che hai creato per questa esercitazione.

   cd .. && rm -r hs-crypto-test
   

5. Facoltativo: rimuovi la tua istanza del servizio Hyper Protect Crypto Services.

   ibmcloud resource service-instance-delete import-keys-demo
   

   Se hai creato ulteriori chiavi di test nella tua istanza del servizio, assicurati di rimuovere tutte le chiavi di crittografia dalla tua istanza del servizio prima di annullare il provisioning dell'istanza.

Passi successivi

In questa esercitazione, hai imparato come configurare l'API del servizio di gestione delle chiavi Hyper Protect Crypto Services, creare una chiave di codifica e importare in modo sicuro una chiave crittografata nella tua istanza del servizio Hyper Protect Crypto Services.

• Ulteriori informazioni sull'utilizzo della tua chiave root per proteggere i dati inattivi.
• Distribuisci la tua chiave root nei servizi cloud supportati.
• Ulteriori informazioni sull'API del servizio di gestione delle chiavi.