Obiettivi

Questa esercitazione ti guida nella creazione e nell'importazione in modo sicuro di chiavi di crittografia nel servizio Key Protect. È destinato agli utenti che non hanno la possibilità di Key Protect, ma chi potrebbe avere una certa familiarità con i sistemi di gestione delle chiavi. Il completamento della seguente procedura dovrebbe richiedere circa 20 minuti.

• Configurazione della CLI Key Protect

• Preparazione della tua istanza del servizio Key Protect per iniziare a importare chiavi

• Creazione e crittografia delle chiavi utilizzando il toolkit di crittografia OpenSSL

• Importazione di una chiave crittografata nel tuo Key Protect istanza

Questo tutorial non comporterà alcun addebito sul tuo IBM Cloud conto.

Prima di iniziare

Per iniziare, è necessario disporre della CLI di IBM Cloud in modo da poter interagire con i servizi che si configurano su IBM Cloud. Hai anche bisogno dei pacchetti openssl e jq installati localmente sul tuo computer.

1. Creare un progetto IBM Cloud.

2. Scaricare e installare CLI di baseIBM Cloud per il sistema operativo.

3. Configurare e configurare il Key Protect per avviare la gestione delle chiavi. Se hai già completato i primi due passi elencati in precedenza, inizia con il passo numero 3 al link prima di ritornare a questa esercitazione.

4. Scarica e installa la libreria di crittografia OpenSSL.

   È possibile utilizzare i comandi openssl per generare chiavi di crittografia sul proprio computer locale se si sta provando Key Protect per una prima volta. Questo tutorial richiede una versione di OpenSSL 1.0.2r o successiva.

   Se utilizzi un Mac, puoi scaricare OpenSSL tramite 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. In questo tutorial si utilizza jq per acquisire i dati specifici restituiti quando si chiama la funzione API Key Protect.

Passo 1. Crea un'istanza di Key Protect

Dopo aver creato un account su IBM Cloud, segui i passaggi riportati di seguito per configurare un Key Protect .

1. In una finestra di terminale, esegui il seguente comando per accedere a IBM Cloud con CLIIBM Cloud.

   ibmcloud login
   

   Se l'accesso non riesce, esegui il comando ibmcloud login --sso e prova di nuovo. Il parametro --sso è obbligatorio quando accedi con un ID federato. Se viene utilizzata questa opzione, vai al link elencato nell'output della CLI per generare una passcode monouso.

2. Selezionare l'account e il gruppo di risorse in cui si desidera creare un Istanza Key Protect.

   In questa esercitazione, interagisci con la regione Washington DC. Se hai eseguito l'accesso in una regione differente, assicurati di impostare Washington DC come tua regione di destinazione eseguendo questo comando.

   ibmcloud target -r us-east
   

3. Esegui il provisioning di un'istanza di Key Protect in tali account e gruppo di risorse.

   Per prima cosa, specificare il gruppo di risorse per l'istanza emettendo:

   ibmcloud target -g <your-resource-group>
   

   Ad esempio, ibmcloud target -g Default

   Quindi, è possibile creare l'istanza emettendo:

   ibmcloud resource service-instance-create "import-keys-demo" kms tiered-pricing us-east
   

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

4. Facoltativo: verificare che l'istanza di Key Protect sia stata creata correttamente visualizzando l'elenco delle istanze di Key Protect disponibili.

   ibmcloud resource service-instances
   

   Operazione riuscita. Ora hai a disposizione l'istanza di Key Protect, dove puoi archiviare e gestire le tue chiavi di crittografia. Continua al passo successivo.

Passo 2. Configura l'API Key Protect

Ora che è stato eseguito il provisioning di un'istanza di Key Protect, sei pronto per iniziare a utilizzare l'API.

Key Protect fornisce una GUI (graphical user interface) e un'API REST per creare, tracciare e gestire le chiavi di crittografia. L'intestazione L'API Key Protect richiede un IBM Cloud token IAM e ID istanza per l'autenticazione con il servizio.

In questa fase, si utilizza la CLI di IBM Cloud per raccogliere le credenziali di autenticazione necessarie per iniziare a interagire con API Key Protect. Per richiamare e preparare le tue credenziali per i passi successivi, imposti anche le credenziali come variabili di ambiente nel tuo terminale.

1. Nella finestra del terminale, impostare il Endpoint API Key Protect come variabile di ambiente.

   export KP_API_URL=https://<region>.kms.cloud.ibm.com
   

2. Genera un token di accesso IBM Cloud utilizzando il Plugin CLI Key Protect e impostalo come variabile di ambiente.

   La variabile di ambiente deve iniziare con il tipo di autorizzazione, Bearer. Il comando CLI, come mostrato nell'esempio, includerà automaticamente il tipo corretto.

   export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
   

   I token di accesso IBM Cloud sono validi per 1 ora ma puoi rigenerarli come necessario. Per generare un nuovo token di accesso, eseguire ibmcloud iam oauth-tokens . Per saperne di più sul recupero IBM Cloud token di accesso, vedere Recupero di un token di accesso.

3. Richiamare l'identificatore associato al Key Protect, quindi imposta il valore come variabile di ambiente.

   export INSTANCE_ID=`ibmcloud resource service-instance "import-keys-demo" --output json | jq -r '.[].guid'`
   

4. Facoltativo: verifica che le variabili di ambiente siano impostate correttamente riproducendole sul tuo schermo di terminale.

   $ echo $KP_API_URL
   https://us-east.kms.cloud.ibm.com
   $ echo $ACCESS_TOKEN
   Bearer eyJraWQiOiIyM...
   $ echo $INSTANCE_ID
   c1cf624b-6bed-4d4d-bd54-8e2534258a88
   

   Operazione riuscita. Disponi ora delle credenziali del servizio di cui hai bisogno per eseguire l'autenticazione presso l'API Key Protect. Continua al passo successivo.

Passo 3. Crea un token di importazione

Con le proprie credenziali del servizio, è possibile iniziare a interagire con Key Protect per creare e portare le tue chiavi di crittografia al servizio.

Nel passaggio successivo, dovrai creare un token di importazione per la tua istanza di Key Protect. Creando un token di importazione basato su una politica da te specificata, garantisci una maggiore sicurezza alla tua chiave di crittografia durante il trasferimento verso il servizio.

1. Utilizzando la tua sessione di terminale, passa a una nuova directory key-protect-test.

   mkdir key-protect-test && cd key-protect-test
   

   Utilizzi questa directory per memorizzare i file per i passi successivi.

2. Crea un token di importazione per il tuo Key Protect e salva quindi la risposta in un file JSON.

   $ curl -X POST \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -d '{
               "expiration": 1200,
               "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
   

   Nel corpo della richiesta, puoi specificare una politica sul token di importazione che ne limita l'utilizzo in base al tempo e al conteggio degli utilizzi. 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.

3. Visualizza i dettagli per il token di importazione.

   jq '.' createImportTokenResponse.json
   

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

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

Passo 4. Richiama il token di importazione

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

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

In questo passo, richiami la chiave di crittografia pubblica e il valore nonce associati al token di importazione. La chiave pubblica ti servirà per crittografare i dati in una fase successiva, mentre il nonce ti servirà per verificare la tua richiesta di importazione sicura al Servizio Key Protect.

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.

   $ curl -X GET \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" > 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": "2019-04-08T16:58:29Z",
       "expirationDate": "2019-04-08T17:18:29Z",
       "maxAllowedRetrievals": 1,
       "remainingRetrievals": 0,
       "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv...",
       "nonce": "8zJE9pKVdXVe/nLb"
   }
   

   Il valore payload rappresenta la chiave pubblica associata al token di importazione. Questo valore ha una codifica base64. Il valore nonce viene utilizzato per verificare l'originalità di una richiesta al servizio. Devi crittografare e fornire questo valore quando importi la tua chiave di crittografia in un passo successivo.

3. Decodifica e salva la chiave pubblica in un file denominato PublicKey.pem.

   jq -r '.payload' getImportTokenResponse.json | base64 --decode -o PublicKey.pem
   

   La chiave pubblica viene ora scaricata sul tuo computer in formato PEM. Continua al passo successivo.

Passo 5. Crea una chiave di codifica

Con Key Protect, puoi abilitare i vantaggi di sicurezza di BYOK (Bring Your Own Key) creando e caricando le tue chiavi per l'utilizzo su IBM Cloud.

Nel seguente passo, crei una chiave simmetrica AES a 256 bit sul tuo computer 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.

1. In una finestra di terminale, esegui questo comando openssl per creare una chiave di crittografia a 256 bit.

   openssl rand 32 > PlainTextKey.bin
   

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

Passo 6. Codifica nonce

Per verificare che i bit che riceviamo siano esattamente gli stessi che invii come parte di una richiesta, Key Protect richiede la verifica nonce quando si carica la chiave simmetrica nel 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 distribuito da Key Protect, ti aiuta a garantire che la 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. Codifica la chiave che hai generato nel passo precedente e imposta il valore codificato come una variabile di ambiente.

   KEY_MATERIAL=$(base64 PlainTextKey.bin)
   

2. Raccogli il valore nonce che hai richiamato nel passo 4.

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

3. Eseguire quanto segue per codificare il valore nonce con la chiave di crittografia generata nel passo 5. Quindi, salvare la risposta in un file denominato EncryptedValues.json.

   ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE --output json > EncryptedValues.json
   

4. Facoltativo: esaminare il contenuto del file JSON utilizzando jq come mostrato.

   jq '.' EncryptedValues.json
   

   L'output visualizza i valori che devi 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 che viene impacchettato (o crittografato) dalla chiave di crittografia che hai generato utilizzando OpenSSL. L'intestazione iv Il valore è il vettore di inizializzazione (IV) generato dall'algoritmo AES- GCM, ed è necessario in seguito affinché Key Protect può decodificare correttamente il nonce.

Passo 7. Codifica la chiave

Successivamente, utilizzare la chiave pubblica distribuita da Key Protect per crittografare la chiave simmetrica generata utilizzando OpenSSL.

1. Crittografa la chiave generata utilizzando la chiave pubblica richiamata nel passo 4.

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

   Se si verifica un errore di impostazioni del parametro quando si esegue openssl su Mac OSX, potrebbe essere necessario assicurarsi che OpenSSL sia configurato correttamente per il proprio ambiente sia configurato correttamente per il vostro 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 creare un collegamento simbolico al pacchetto. Aprire una nuova sessione terminale, quindi eseguire which openssl && openssl version per verificare che l'ultima versione di OpenSSL sia disponibile nel percorso /usr/local/. Se continui a riscontrare errori, assicurati di utilizzare solo i parametri elencati in questo esempio.

   Operazione riuscita. La tua chiave crittografata è stata salvata in un file denominato EncryptedKey.bin. Sei pronto per caricare la tua chiave crittografata su Key Protect. Continua al passo successivo.

Passo 8. Importa la chiave

Ora è possibile importare la chiave crittografata utilizzando il API Key Protect.

Per importare la chiave:

1. Raccogli i valori di chiave crittografata, nonce crittografato e IV (initialization vector).

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

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

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

2. Archivia la chiave crittografata nel tuo Key Protect ad esempio eseguendo il seguente comando curl.

   $ curl -X POST \
       "$KP_API_URL/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -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_256",
                       "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 indica la tua nuova chiave come chiave radice nel servizio, che potrai utilizzare per la crittografia dell'involucro.

   Key Protect riceve il pacchetto crittografato tramite il protocollo TLS 1.2 o 1.3. 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.

   Se la richiesta API non riesce con un errore di token di importazione scaduto, ritorna al passo 3 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.

3. Visualizza i dettagli per la chiave di crittografia.

   jq '.' createRootKeyResponse.json
   

   Il seguente frammento mostra un output di esempio.

   {
       "metadata": {
           "collectionType": "application/vnd.ibm.kms.key+json",
           "collectionTotal": 1
       },
       "resources": [
           {
               "id": "02fd6835-6001-4482-a892-13bd2085f75d",
               "type": "application/vnd.ibm.kms.key+json",
               "name": "encrypted-root-key",
               "state": 1,
               "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
               "extractable": false,
               "imported": true
           }
       ]
   }
   

   Il valore " id " è un identificatore univoco assegnato alla tua chiave e viene utilizzato per le successive chiamate alla API Key Protect. Il valore di " state " impostato su 1 indica che la chiave di crittografia si trova ora nello stato "Active ". 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.

4. Facoltativo: passare alla DashboardKey Protect per visualizzare e gestire la chiave di cifratura.

   

   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.

Passo 9. 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 dal tuo Istanza Key Protect.

   $ curl -X DELETE \
       "$KP_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 .
   

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

   rm *.json *.bin *.pem
   

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

   cd .. && rm -r key-protect-test
   

5. Facoltativo: rimuovi la tua istanza del servizio Key Protect.

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

   Se hai creato più chiavi di test nel tuo Key Protect istanza, assicurarsi di rimuovere tutte le chiavi di crittografia dall'istanza prima di eliminare o deprovisionare l'istanza.

Passi successivi

In questa esercitazione, è stato descritto come impostare API Key Protect, crea una chiave di crittografia e importa in modo sicuro una chiave crittografata nel tuo Istanza Key Protect.

• Ulteriori informazioni sull'utilizzo della tua chiave root per proteggere i dati inattivi.

• Distribuisci la tua chiave root nei servizi cloud supportati.

• Ulteriori informazioni su APIKey Protect.