Como ativar a criptografia de chaves secretas

Este documento explica como ativar a criptografia de chaves secretas de consumidor de apps para desenvolvedores (credenciais do cliente) armazenadas no banco de dados do Cassandra.

Visão geral

Tradicionalmente, o Apigee Edge para nuvem privada oferece criptografia opcional para dados do mapa de chave-valor (KVM) e tokens de acesso do OAuth 2.0.

A tabela a seguir descreve as opções de criptografia para dados em repouso no Apigee para nuvem privada:

Para ativar a criptografia de credenciais do cliente, é necessário realizar as seguintes tarefas em todos os nós do servidor de gerenciamento e do processador de mensagens:

• Crie um keystore para armazenar uma chave de criptografia de chaves (KEK). O Apigee usa essa chave criptografada para criptografar as chaves secretas necessárias para criptografar seus dados.
• Edite as propriedades de configuração em todos os nós do servidor de gerenciamento e do processador de mensagens.
• Crie um app para desenvolvedores para acionar a criação de chaves.
• Reinicie os nós.

Essas tarefas são explicadas neste documento.

O que você precisa saber sobre o recurso de criptografia de chaves

As etapas neste documento explicam como ativar o recurso KEK, que permite que o Apigee criptografe as chaves secretas usadas para criptografar as chaves secretas de consumidor de apps para desenvolvedores quando elas são armazenadas em repouso no banco de dados do Cassandra.

Por padrão, todos os valores atuais no banco de dados permanecem inalterados (em texto simples) e continuarão funcionando como antes.

Se você realizar qualquer operação de gravação em uma entidade não criptografada, ela será criptografada quando a operação for salva. Por exemplo, se você revogar um token não criptografado e depois aprová -lo, o token recém-aprovado será criptografado.

Como manter as chaves seguras

Armazene uma cópia do keystore em que a KEK está armazenada em um local seguro. Recomendamos usar seu próprio mecanismo seguro para salvar uma cópia do keystore. Conforme explicam as instruções neste documento, um keystore precisa ser colocado em cada nó do servidor de gerenciamento e do processador de mensagens em que o arquivo de configuração local possa fazer referência a ele. No entanto, também é importante armazenar uma cópia do keystore em outro lugar para proteção e como backup.

Como ativar a criptografia de chaves

Siga estas etapas para criptografar a chave secreta do consumidor:

Pré-requisitos

É necessário atender a estes requisitos antes de realizar as etapas neste documento:

• É necessário instalar ou fazer upgrade para o Apigee Edge para nuvem privada 4.50.00.10 ou mais recente.
• Você precisa ser um administrador do Apigee Edge para nuvem privada.

Etapa 1: gerar um keystore

Siga estas etapas para criar um keystore para armazenar a chave de criptografia de chaves (KEK):

1. Execute o comando a seguir para gerar um keystore para armazenar uma chave que será usada para criptografar a KEK. Insira o comando exatamente como mostrado. Você pode fornecer o nome do keystore que quiser:
   

   keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
   -keystore kekstore.p12 -storetype PKCS12

   Quando solicitado, insira uma senha. Você usará essa senha nas seções posteriores ao configurar o servidor de gerenciamento e o processador de mensagens.

   Esse comando gera um arquivo de keystore kekstore.p12 que contém uma chave com o alias KEYSTORE_NAME.

2. Opcional: verifique se o arquivo foi gerado corretamente com o comando a seguir. Se o arquivo estiver correto, o comando retornará uma chave com o alias KEYSTORE_NAME:

   keytool -list -keystore kekstore.p12

Etapa 2: configurar o servidor de gerenciamento

Em seguida, configure o servidor de gerenciamento. Se você tiver servidores de gerenciamento instalados em vários nós, repita essas etapas em cada nó.

1. Copie o arquivo de keystore gerado na etapa 1 para um diretório no nó do servidor de gerenciamento, como /opt/apigee/customer/application. Por exemplo:

   cp certs/kekstore.p12 /opt/apigee/customer/application

2. Verifique se o arquivo pode ser lido pelo usuário apigee:

   chown apigee:apigee /opt/apigee/customer/application/kekstore.p12

   chmod 400 /opt/apigee/customer/application/kekstore.p12

3. Adicione as seguintes propriedades a /opt/apigee/customer/application/management-server.properties. Se o arquivo não existir, crie-o. Consulte também Referência do arquivo de propriedades.
   

   conf_keymanagement_kmscred.encryption.enabled=true
   
   # Fallback is true to ensure your existing plaintext credentials continue to work
   conf_keymanagement_kmscred.encryption.allowFallback=true
   
   conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
   conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME
   
   # These could alternately be set as environment variables. These variables should be
   # accessible to Apigee user during bootup of the Java process. If environment
   # variables are specified, you can skip the password configs below.
   # KMSCRED_ENCRYPTION_KEYSTORE_PASS=
   # KMSCRED_ENCRYPTION_KEK_PASS=
   See also Using environment variables for configuration properties.
   
   conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
   conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

   A KEK_PASSWORD pode ser a mesma que a KEYSTORE_PASSWORD, dependendo da ferramenta usada para gerar o keystore.

4. Reinicie o servidor de gerenciamento usando os seguintes comandos:

   /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart

   /opt/apigee/apigee-service/bin/apigee-service edge-management-server wait_for_ready

   O comando wait_for_ready retorna a seguinte mensagem quando o servidor de gerenciamento está pronto:

   Checking if management-server is up: management-server is up.

5. Se você tiver servidores de gerenciamento instalados em vários nós, repita as etapas de 1 a 4 acima em cada nó do servidor de gerenciamento.

Etapa 3: criar um app para desenvolvedores

Agora que os servidores de gerenciamento estão atualizados, é necessário criar um app para desenvolvedores para acionar a geração da chave usada para criptografar os dados de credenciais do cliente:

1. Crie um app para desenvolvedores para acionar a criação de uma chave de criptografia de dados (KEK). Para conferir as etapas, consulte Como registrar um app.
2. Exclua o app para desenvolvedores, se quiser. Não é necessário mantê-lo depois que a chave de criptografia for gerada.

Etapa 4: configurar processadores de mensagens

Até que a criptografia seja ativada nos processadores de mensagens, as solicitações de ambiente de execução não poderão processar credenciais criptografadas.

1. Copie o arquivo de keystore gerado na etapa 1 para um diretório no nó do processador de mensagens, como /opt/apigee/customer/application. Por exemplo:

   cp certs/kekstore.p12 /opt/apigee/customer/application

2. Verifique se o arquivo pode ser lido pelo usuário apigee:

   chown apigee:apigee /opt/apigee/customer/application/kekstore.p12

3. Adicione as seguintes propriedades a /opt/apigee/customer/application/message-processor.properties. Se o arquivo não existir, crie-o. Consulte também Referência do arquivo de propriedades.

   conf_keymanagement_kmscred.encryption.enabled=true
   
   # Fallback is true to ensure your existing plaintext credentials continue to work
   conf_keymanagement_kmscred.encryption.allowFallback=true
   
   conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
   conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME
   
   # These could alternately be set as environment variables. These variables should be
   # accessible to Apigee user during bootup of the Java process. If environment
   # variables are specified, you can skip the password configs below.
   # KMSCRED_ENCRYPTION_KEYSTORE_PASS=
   # KMSCRED_ENCRYPTION_KEK_PASS=
   See also Using environment variables for configuration properties.
   
   
   conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
   conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

   A KEK_PASSWORD pode ser a mesma que a KEYSTORE_PASSWORD dependendo da ferramenta usada para gerar o keystore.

4. Reinicie o processador de mensagens usando os seguintes comandos:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor wait_for_ready

   O comando wait_for_ready retorna a seguinte mensagem quando o processador de mensagens está pronto para processar mensagens:

   Checking if message-processor is up: message-processor is up.

5. Se você tiver processadores de mensagens instalados em vários nós, repita as etapas de 1 a 4 em cada nó do processador de mensagens.

Resumo

Todos os apps para desenvolvedores que você criar a partir de agora terão a chave secreta de credencial criptografada em repouso no banco de dados do Cassandra.

Como usar variáveis de ambiente para propriedades de configuração

Como alternativa, é possível definir as seguintes propriedades de configuração do servidor de gerenciamento e do processador de mensagens usando variáveis de ambiente. Se definidas, as variáveis de ambiente substituem as propriedades definidas no arquivo de configuração do servidor de gerenciamento ou do processador de mensagens.

conf_keymanagement_kmscred.encryption.keystore.pass=
conf_keymanagement_kmscred.encryption.kek.pass=

As variáveis de ambiente correspondentes são:

export KMSCRED_ENCRYPTION_KEYSTORE_PASS=KEYSTORE_PASSWORD

export KMSCRED_ENCRYPTION_KEK_PASS=KEK_PASSWORD

Se você definir essas variáveis de ambiente, poderá omitir essas propriedades de configuração dos arquivos de configuração nos nós do servidor de gerenciamento e do processador de mensagens, porque elas serão ignoradas:

conf_keymanagement_kmscred.encryption.keystore.pass
conf_keymanagement_kmscred.encryption.kek.pass

Referência do arquivo de propriedades

Esta seção descreve as propriedades de configuração que você precisa definir em todos os nós do processador de mensagens e do servidor de gerenciamento, conforme explicado anteriormente neste documento.