Objetivos

Este tutorial fornece orientação durante a criação e a importação segura de chaves de criptografia para o serviço Key Protect. Ele é voltado para usuários que são novos no Key Protect, mas que podem ter alguma familiaridade com os sistemas de gerenciamento de chaves. As etapas a seguir devem levar aproximadamente 20 minutos para serem concluídas.

• Configurando a CLI do Key Protect

• Preparando a sua instância de serviço do Key Protect para começar a importar chaves

• Criando e criptografando chaves usando o kit de ferramentas de criptografia OpenSSL

• Como importar uma chave criptografada para a instância do instância do Key Protect

Este tutorial não será cobrado em sua conta do IBM Cloud conta.

Antes de Iniciar

Para começar, é necessário ter a CLI do IBM Cloud, por meio da qual é possível interagir com os serviços fornecidos no IBM Cloud. Os pacotes openssl e jq também precisarão estar instalados localmente em seu computador.

1. Crie uma Conta IBM Cloud.

2. Faça o download e instale a IBM Cloud base CLI para o seu sistema operacional.

3. Configure e setup o Key Protect Plugin CLI para iniciar o gerenciamento de chaves. Se você já tiver concluído as duas primeiras etapas listadas anteriormente, comece com o passo número 3 no link antes de retornar a este tutorial.

4. Baixe e instale a biblioteca de criptografia OpenSSL.

   É possível usar comandos do openssl para gerar chaves de criptografia em seu computador local, caso esta seja sua primeira experiência com o Key Protect. Este tutorial requer o OpenSSL versão 1.0.2r ou mais recente.

   Se você estiver usando um Mac, pode baixar o OpenSSL usando o Homebrew. Execute brew install openssl se você estiver instalando o pacote pela primeira vez ou execute brew upgrade openssl para fazer upgrade de seu pacote existente para a versão mais recente.

5. Baixe e instale o jq.

   O jq ajuda a fatiar dados JSON. Neste tutorial, o jq é usado para a captura de dados específicos, retornados ao chamar a API do Key Protect.

Etapa 1. Crie uma instância do Key Protect

Depois de configurar uma conta do IBM Cloud, conclua as etapas a seguir para fornecer uma instância do Key Protect Instância.

1. Em uma janela de terminal, execute o comando a seguir para efetuar login no IBM Cloud com a IBM Cloud CLI.

   ibmcloud login
   

   Se o login falhar, execute o comando ibmcloud login --sso para tentar novamente. O parâmetro --sso é necessário quando você efetua login com um ID federado. Se essa opção for usada, acesse o link listado na saída da CLI para gerar uma senha descartável.

2. Selecione a conta e o grupo de recursos nos quais deseja criar uma instância do instância do Key Protect.

   Neste tutorial, você interage com a região Washington DC. Se você estiver conectado a uma região diferente, certifique-se de configurar Washington DC como a sua região de destino executando o comando a seguir.

   ibmcloud target -r us-east
   

3. Provisione uma instância do Key Protect dentro dessa conta e grupo de recursos.

   Primeiro, especifique o grupo de recursos para a instância emitindo:

   ibmcloud target -g <your-resource-group>
   

   Por exemplo,ibmcloud target -g Default

   Em seguida, é possível criar a instância emitindo:

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

   Este tutorial não incorrerá em cobranças em sua conta do IBM Cloud.

4. Opcional: verifique se a instância do Key Protect foi criada com êxito listando suas instâncias disponíveis do Key Protect.

   ibmcloud resource service-instances
   

   Sucesso! Você acabou de configurar a instância do Key Protect na qual pode armazenar e gerenciar suas chaves de criptografia. Continue com a próxima etapa.

Etapa 2. Configure a API do Key Protect

Agora que forneceu uma instância do Key Protect, você está pronto para começar a usar a API.

O Key Protect fornece uma interface gráfica com o usuário e uma API de REST para criar, controlar e gerenciar chaves de criptografia. Os comandos API do Key Protect requer um token do IAM e um ID de instância do IBM Cloud válidos para a autenticação no serviço.

Nesta etapa, as credenciais da CLI do IBM Cloud são usadas para reunir as credenciais de autenticação necessárias para iniciar a interação com as APIs do Key Protect. Para recuperar e preparar as suas credenciais para as etapas posteriores, você também configurará as credenciais como variáveis de ambiente em seu terminal.

1. Na janela de terminal, configure o terminal da API do Key Protect como uma variável de ambiente.

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

2. Gere um token de acesso do IBM Cloud utilizando o plug-in da CLI do Key Protect e configure-o como uma variável de ambiente.

   A variável de ambiente deve começar com o tipo de autorização, Bearer. O comando da CLI, conforme mostrado no exemplo, incluirá automaticamente o tipo correto.

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

   Os tokens de acesso do IBM Cloud são válidos por 1 hora, mas é possível regenerá-los conforme a necessidade. Para gerar um novo token de acesso, execute o ibmcloud iam oauth-tokens a seguir. Para saber mais sobre como recuperar tokens de acesso do IBM Cloud, consulte Recuperando um token de acesso.

3. Recupere o identificador que está associado à sua instância do Key Protect e, em seguida, configure o valor como uma variável de ambiente.

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

4. Opcional: verifique se as variáveis de ambiente estão configuradas corretamente, imprimindo-as na tela do terminal.

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

   Sucesso! Agora você está configurado com as credenciais de serviço necessárias para se autenticar na API do Key Protect. Continue com a próxima etapa.

Etapa 3. Criar um token de importação

Usando suas credenciais de serviço, é possível iniciar a interação com as APIs do Key Protect para criar e trazer suas chaves de criptografia para o serviço.

Na etapa a seguir, você criará um token de importação para a sua instância do Key Protect. Ao criar um token de importação com base em uma política especificada por você, você habilita segurança adicional para sua chave de criptografia enquanto ela está sendo transmitida para o serviço.

1. Usando a sua sessão de terminal, mude para um novo diretório key-protect-test.

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

   Você usa esse diretório para armazenar arquivos para etapas posteriores.

2. Crie um token de importação para a instância do Key Protect e, em seguida, salve a resposta em um arquivo 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
   

   No corpo da solicitação, é possível especificar uma política no token de importação que limita seu uso com base no tempo e na contagem de uso. Neste exemplo, você configura o prazo de expiração do token de importação para 1200 segundos (20 minutos) e também permite apenas uma recuperação desse token dentro do prazo de expiração.

3. Visualize detalhes para o token de importação.

   jq '.' createImportTokenResponse.json
   

   A saída exibe os metadados que estão associados ao seu token de importação, como a sua data de criação e detalhes de política. O fragmento a seguir mostra a saída de exemplo.

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

Etapa 4. Recuperar o token de importação

Na etapa anterior, você criou um token de importação e visualizou os metadados que estão associados ao token.

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

Nesta etapa, você recuperará a chave de criptografia pública e o valor nonce que estão associados ao token de importação. Posteriormente, você precisará da chave pública para criptografar os dados e do nonce para verificar sua solicitação de importação segura para o serviço do Key Protect.

Para recuperar o conteúdo do token de importação:

1. Recupere o token de importação gerado na etapa anterior e, em seguida, salve a resposta em um arquivo 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. Opcional: inspecione o conteúdo do token de importação.

   jq '.' getImportTokenResponse.json
   

   A saída exibe informações detalhadas sobre o token de importação. O fragmento a seguir mostra a saída de exemplo com valores truncados.

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

   O valor payload representa a chave pública que está associada ao token de importação. Esse valor tem a codificação Base64. O valor nonce é usado para verificar a originalidade de uma solicitação para o serviço. É necessário criptografar e fornecer esse valor ao importar a sua chave de criptografia em uma etapa posterior.

3. Decodifique e salve a chave pública em um arquivo chamado PublicKey.pem.

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

   A chave pública agora é transferida por download para o seu computador no formato PEM. Continue com a próxima etapa.

Etapa 5. Criar uma chave de criptografia

Com o Key Protect, é possível ativar os benefícios de segurança do Bring Your Own Key (BYOK), criando e fazendo upload de suas próprias chaves para uso no IBM Cloud.

Na etapa a seguir, você criará uma chave simétrica AES de 256 bits em seu computador local.

Este tutorial usa o kit de ferramentas de criptografia OpenSSL para gerar uma chave pseudoaleatória, mas talvez você queira explorar opções diferentes para gerar chaves mais fortes com base em suas necessidades de segurança. Por exemplo, talvez você queira usar o sistema de gerenciamento de chaves internas de sua organização, suportado por um módulo de segurança de hardware (HSM) local, para criar e exportar chaves.

1. Em uma janela do terminal, execute o comando openssl a seguir para criar uma chave de criptografia de 256 bits.

   openssl rand 32 > PlainTextKey.bin
   

   Sucesso! Sua chave de criptografia agora está salva em um arquivo chamado PlainTextKey.bin. Continue com a próxima etapa.

Etapa 6. Criptografar o nonce

Para verificar se os bits recebidos são exatamente iguais aos bits que foram enviados como parte de uma solicitação, o Key Protect exige a verificação de nonce ao fazer upload da chave simétrica para o serviço.

Em criptografia, um nonce serve como um token de sessão que verifica a originalidade de uma solicitação para proteger contra ataques maliciosos e chamadas não autorizadas. Ao utilizar o mesmo nonce distribuído pelo Key Protect, você ajuda a garantir a validade de sua solicitação para o upload de uma chave. O valor nonce deve ser criptografado usando a mesma chave que você deseja importar para o serviço.

Para criptografar o valor nonce:

1. Codifique a chave gerada na etapa anterior e configure o valor codificado como uma variável de ambiente.

   KEY_MATERIAL=$(base64 PlainTextKey.bin)
   

2. Reúna o valor nonce recuperado na etapa 4.

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

3. Execute o seguinte para criptografar o valor do nonce usando a chave de criptografia gerada na etapa 5. Em seguida, salve a resposta em um arquivo chamado EncryptedValues.json.

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

4. Opcional: inspecione o conteúdo do arquivo JSON utilizando o jq, conforme mostrado.

   jq '.' EncryptedValues.json
   

   A saída exibe os valores que você precisará fornecer para a próxima etapa. O fragmento a seguir mostra a saída de exemplo com valores truncados.

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

   O valor encryptedNonce representa o nonce original que foi agrupado (ou criptografado) pela chave de criptografia gerada usando OpenSSL. Os comandos iv O valor é o vetor de inicialização (IV) criado pelo algoritmo AES- GCM, e ele será necessário posteriormente para que o Key Protect seja bem-sucedido ao decriptografar o nonce.

Etapa 7. Criptografar a chave

Em seguida, use a chave pública que foi distribuída pelo Key Protect para criptografar a chave simétrica que foi gerada utilizando o OpenSSL.

1. Criptografe a chave gerada usando a chave pública recuperada na etapa 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
   

   Em caso de erros de configuração de parâmetro durante a execução do openssl No Mac OS X, talvez seja necessário verificar se o OpenSSL está devidamente configurado para o seu ambiente. Se você instalou o OpenSSL usando o Homebrew, execute brew update e, em seguida brew install openssl para obter a versão mais recente. Em seguida, execute export PATH="/usr/local/opt/openssl/bin:$PATH" >> ~/.bash_profile para criar um link simbólico para o pacote. Abra uma nova sessão de terminal, e em seguida, execute which openssl && openssl version para verificar se a versão mais recente doOpenSSL está disponível no endereço /usr/local/ Se você continuar a encontrar erros, certifique-se de usar apenas os parâmetros listados nesse exemplo.

   Sucesso! Sua chave criptografada agora está salva em um arquivo chamado EncryptedKey.bin. Você está pronto para fazer upload da chave criptografada para o Key Protect. Continue com a próxima etapa.

Etapa 8. Importar a chave

Agora, é possível importar a chave criptografada utilizando a API do Key Protect.

Para importar a chave:

1. Reúna os valores da chave criptografada, do nonce criptografado e do vetor de inicialização (IV).

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

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

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

2. Para armazenar a chave criptografada em sua instância do instância do Key Protect, execute o comando curl a seguir.

   $ 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
   

   No corpo da solicitação, você fornece a chave de criptografia preparada na etapa anterior. Você também fornece os valores nonce e IV criptografados necessários para verificar a solicitação. Por fim, o valor extractable configurado como false designa sua nova chave como chave raiz no serviço, que você pode usar para a criptografia de envelopes.

   O Key Protect utiliza o protocolo TLS 1.2 ou 1.3 para receber o pacote criptografado. Dentro de um módulo de segurança de hardware, o sistema usa a chave privada para decriptografar a chave simétrica. Por fim, o sistema usa a chave simétrica e o IV para decriptografar o nonce e verificar a solicitação.

   Se a solicitação de API falhar com um erro de token de importação expirado, retorne à etapa 3 para criar um novo token de importação. Lembre-se de que os tokens de importação e as suas chaves públicas associadas expiram com base na política especificada no horário de criação.

3. Visualize detalhes da chave de criptografia.

   jq '.' createRootKeyResponse.json
   

   O fragmento a seguir mostra uma saída de exemplo.

   {
       "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
           }
       ]
   }
   

   O valor de id é um identificador exclusivo designado para a chave e será usado nas chamadas subsequentes da API do Key Protect. O valor de “ state ” definido como 1 indica que sua chave de criptografia está agora no estado “Chave ativa ”. O valor crn fornece o caminho com escopo definido completo para a chave que especifica o local no qual o recurso reside dentro do IBM Cloud. Por fim, os valores extractable e imported descrevem esse recurso como uma chave raiz que foi importada para o serviço.

4. Opcional: navegue para o painel do Key Protect para visualizar e gerenciar sua chave de criptografia.

   

   É possível procurar as características gerais de suas chaves na página de detalhes do aplicativo. Escolha em uma lista de opções para gerenciar a sua chave, como girando a chave ou excluindo a chave.

Etapa 9. Limpar

1. Reúna o identificador da chave de criptografia que você importou na etapa anterior.

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

2. Remover a chave de criptografia da instância do 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. Remova todos os arquivos locais associados a este tutorial.

   rm *.json *.bin *.pem
   

4. Exclua o diretório de teste criado para este tutorial.

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

5. Opcional: remova a sua instância de serviço do Key Protect.

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

   Caso tenha criado mais chaves de teste na instância do Key Protect, certifique-se de remover todas as chaves de criptografia da instância antes de excluir ou remover a provisão da instância.

Próximas etapas

Neste tutorial, você aprendeu a configurar a API do Key Protect, criar uma chave de criptografia e a importar com segurança uma chave de criptografia para a instância do Key Protect.

• Saiba mais sobre como usar a sua chave raiz para proteger dados em repouso.

• Implemente a sua chave raiz em serviços de nuvem suportados.

• Saiba mais sobre a Key Protect API.