Criando e importando chaves de criptografia

Aprenda como criar, criptografar e trazer suas chaves de criptografia para a nuvem usando o Hyper Protect Crypto Services.

Objetivos

Este tutorial fornece orientação durante a criação e a importação segura de chaves de criptografia para o serviço Hyper Protect Crypto Services. Ele destina-se a usuários que são novos para a função de gerenciamento de chave dos Hyper Protect Crypto Services, mas que possam ter alguma familiaridade com os sistemas de gerenciamento de chave. As etapas a seguir precisam levar cerca de 20 minutos para serem concluídas.

  • Configurando a API de serviço de gerenciamento de chaves
  • Preparando a sua instância de serviço do Hyper Protect Crypto Services para começar a importar chaves
  • Criando e criptografando chaves usando o kit de ferramentas de criptografia OpenSSL
  • Importando uma chave criptografada para a sua instância de serviço do Hyper Protect Crypto Services

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

Fluxo de tarefas

O fluxograma a seguir fornece uma visão geral sobre como criar e importar chaves de criptografia. É possível clicar em cada etapa no gráfico para visualizar os detalhes da etapa.

Clique em cada etapa para obter mais detalhes sobre o fluxo
Fluxo de tarefas de criação e importação de uma chave de criptografia
1. Criar um token de importação 2. Recuperar o token de importação 3. Criar uma chave de criptografia 4. Configurar a chave de criptografia como uma variável de ambiente 5. Criptografar o nonce com a chave de criptografia 6. Criptografar a chave de criptografia criada 7. Importar a chave criptografada 8. Limpar

Antes de Iniciar

Para começar, será necessária a CLI do IBM Cloud para que seja possível interagir com os serviços provisionados no IBM Cloud. Os pacotes openssl e jq também precisam estar instalados em sua estação de trabalho.

  1. Crie uma conta do IBM Cloud.

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

  3. Faça download e instale o plug-in da CLI do IBM Key Protect v0.6.3 ou posterior e configure-o para usar em Hyper Protect Crypto Services. Certifique-se de atualizar a variável KP_PRIVATE_ADDR para a URL do terminal de gerenciamento de chave de instância atual.

    Para verificar sua versão de plug-in da CLI do IBM Key Protect:

    ibmcloud plugin show key-protect

    Para atualizar seu plug-in da CLI do IBM Key Protect para a versão mais recente:

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

  4. Faça o download e instale a OpenSSL biblioteca de criptografia

    É possível usar os comandos openssl para criar chaves de criptografia em sua estação de trabalho local se você estiver experimentando Hyper Protect Crypto Services pela primeira vez. Este tutorial requer a versão 1.0.2r do OpenSSL ou acima.

    Se você estiver usando um Mac, será possível ativar e executar rapidamente com o OpenSSL usando 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. Faça download e instale o jq.

    O jq ajuda a fatiar dados JSON. Você usará jq neste tutorial para pegar e usar dados específicos que são retornados quando você chama a API de serviço de gerenciamento de chaves Hyper Protect Crypto Services

  6. Crie uma instância de serviço dos Hyper Protect Crypto Services.

  7. Inicialize a instância de serviço dos Hyper Protect Crypto Services.

  8. Configure a API do serviço de gerenciamento de chave do Hyper Protect Crypto Services.

Criar um token de importação

Com suas credenciais de serviço, é possível começar a interagir com a API do serviço de gerenciamento de chaves 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 de serviço Hyper Protect Crypto Services. Ao criar um token de importação com base em uma política especificada, você permite segurança adicional para a sua chave de criptografia enquanto ela está em andamento para o serviço.

  1. Na linha de comandos, mude para um novo diretório hs-crypto-test.

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

    Você usará esse diretório para armazenar os arquivos que criará em etapas posteriores.

  2. É possível criar um token de importação para a sua instância de serviço Hyper Protect Crypto Services usando a API de serviço de gerenciamento chave ou usando a CLI e, em seguida, salve a resposta em um arquivo JSON.

    • Usar a 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

      No corpo da solicitação, é possível especificar uma política no token de importação que limita o uso com base no tempo e 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.

    • Use o IBM Key Protect CLI

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

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

    jq '.' createImportTokenResponse.json

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

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

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.

Nesta etapa, você recuperará a chave pública e o valor nonce associados ao token de importação. A chave pública será necessária para criptografar dados em uma etapa posterior e o nonce para verificar a sua solicitação de importação segura para o serviço Hyper Protect Crypto Services.

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.

    • Usar a 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

    • Use o IBM Key Protect CLI

      ibmcloud kp import-token show -o json > 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": "2020-06-08T16:58:29Z",
  "expirationDate": "2020-06-08T17:18:29Z",
  "maxAllowedRetrievals": 1,
  "remainingRetrievals": 0,
  "payload": "MIICIjANBgkqhkiG...",
  "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. Para segurança adicional, os Hyper Protect Crypto Services fornecem um valor nonce que é usado para verificar a originalidade de uma solicitação para o serviço. Será necessário criptografar e fornecer esse valor ao importar sua chave de criptografia.

  3. Decodifique e salve a chave pública em um arquivo chamado PublicKey.pem e extraia valores em variáveis para serem usadas posteriormente.

    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)"

    A chave pública agora é transferida por download para a sua estação de trabalho no formato PEM. Continue com a próxima etapa.

Criar uma chave de criptografia

Com Hyper Protect Crypto Services, é possível ativar os benefícios de segurança do Keep Your Own Key (KYOK) criando e carregando suas próprias chaves de criptografia para uso em IBM Cloud.

Na etapa a seguir, você criará uma chave simétrica AES de 256 bits em sua estação de trabalho 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.

Se você deseja criar uma chave simétrica AES de 256 bits, na linha de comandos, execute o seguinte comando openssl:

openssl rand 32 > PlainTextKey.bin

Será possível ignorar essa etapa se você usar a sua própria chave neste tutorial.

Sucesso! A sua chave de criptografia agora é salva em um arquivo chamado PlainTextKey.bin. Continue com a próxima etapa.

Configurar a chave de criptografia como uma variável de ambiente

Se você criar a chave seguindo a etapa 3, para codificar a chave e definir o valor codificado como uma variável de ambiente, execute o seguinte comando. É possível pular esta etapa se usar sua própria chave neste tutorial:

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

Criptografar o nonce com a chave de criptografia

Para segurança extra, Hyper Protect Crypto Services requer verificação nonce ao importar uma chave de criptografia 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 usar o mesmo nonce distribuído pelo Hyper Protect Crypto Services, você ajuda a assegurar que a sua solicitação para fazer upload de uma chave é válida. O valor nonce deve ser criptografado usando a mesma chave que você deseja importar para o serviço.

Para criptografar o valor nonce:

  1. Para usar a API na execução das etapas subsequentes, faça o seguinte:

    Não será necessário executar esta etapa se você for usar a CLI do IBM Key Protect.

    1. Faça download do kms-encrypt-nonce binary de amostra que é compatível com seu sistema operacional. Extraia o arquivo e, em seguida, mova o binário para o diretório hs-crypto-test.

      O binário contém um script que você pode usar para executar a criptografia AES-CBC no valor nonce usando a chave gerada em etapa 2. Para saber mais sobre o script, efetue o registro de saída do arquivo de origem no GitHub.

    2. Se estiver usando Linux, marque o arquivo como executável executando o comando chmod a seguir. Será possível ignorar essa etapa se você estiver usando o Windows.

      chmod +x ./kms-encrypt-nonce

    3. Execute o script para criptografar o valor nonce com a chave que você gerou em etapa 2.

  2. Salve o nonce criptografado em um arquivo chamado EncryptedValues.json.

    • Usar a API

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

    • Use o IBM Key Protect CLI

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

  3. Opcional: inspecione o conteúdo do arquivo JSON.

    jq '.' EncryptedValues.json

    A saída exibe os valores que precisam ser fornecidas na 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 é encapsulado (ou criptografado) pela chave que você gerou usando OpenSSL. O valor iv é o vetor de inicialização (IV) criado pelo algoritmo AES-CBC e será necessário posteriormente para que os Hyper Protect Crypto Servicespossam decriptografar o nonce com sucesso.

Criptografar a chave de criptografia criada

Em seguida, use a chave pública que foi distribuída por Hyper Protect Crypto Services na etapa 2 para criptografar a chave de criptografia que você criou usando OpenSSL.

  • Criptografe a chave de criptografia criada com a API e atribua a chave à variável de 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 você encontrar um erro de configurações de parâmetros ao executar o comando openssl no Mac OSX, poderá ser necessário assegurar que o OpenSSL esteja configurado corretamente 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 o link simbólico do pacote. Na linha de comandos, execute which openssl && openssl version para verificar se a versão mais recente do OpenSSL está disponível no local /usr/local/. Se você continuar a encontrar erros, certifique-se de usar apenas os parâmetros listados nesse exemplo.

  • Criptografe a chave de criptografia criada com a CLI IBM Key Protect:

    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)

    Sucesso! Você está pronto para fazer upload de sua chave criptografada no Hyper Protect Crypto Services. Continue com a próxima etapa.

Importar a chave criptografada

Agora é possível importar a chave criptografada usando a API do serviço de gerenciamento de chaves.

Para importar a chave criptografada:

  1. Reúna o nonce criptografado e os valores de vetor de inicialização (IV).

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

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

  2. Armazene a chave criptografada em sua instância de serviço dos Hyper Protect Crypto Services.

    • Usar a 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

      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 a sua nova chave como uma chave raiz no serviço que pode ser usado para criptografia de envelope.

      Se a solicitação de API falhar com um erro de token de importação expirado, retorne à etapa 1 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.

    • Use o IBM Key Protect CLI

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

      Nos bastidores, o Hyper Protect Crypto Services recebe o seu pacote criptografado por meio de uma conexão TLS 1.2. 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. Sua chave é agora armazenada em um módulo de segurança de hardware, resistente à violação, validado pelo FIPS 140-2 Nível 4.

  3. Visualizar detalhes para a chave.

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

    • O valor id é um identificador exclusivo atribuído à sua chave e usado para chamadas subsequentes à API do serviço de gerenciamento de chaves.

    • O valor state configurado como 1 indica que sua chave está agora no Estado da 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. Ao configurar o atributo extractable como true, o serviço designa a chave como uma chave padrão que pode ser armazenada em seus apps ou serviços. Caso contrário, ao configurar o atributo extractable como false, o serviço designa a chave como uma chave raiz.

  4. Opcional: navegue para o painel Hyper Protect Crypto Services para visualizar e gerenciar sua chave.

    É 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.

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. Remova a chave de criptografia de sua instância de serviço do Hyper Protect Crypto Services.

    • Usar a 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 .

    • Use o IBM Key Protect CLI

      ibmcloud kp key delete {ROOT_KEY_ID}

  3. Remova todos os arquivos locais associados a este tutorial.

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

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

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

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

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

    Se você tiver criado mais chaves de teste em sua instância de serviço, certifique-se de remover todas as chaves de criptografia da sua instância de serviço antes de desprover a instância.

Próximas etapas

Neste tutorial, você aprendeu a configurar a API de serviço de gerenciamento de chaves Hyper Protect Crypto Services, criar uma chave de criptografia e importar com segurança uma chave criptografada para sua instância de serviço Hyper Protect Crypto Services.