Como ativar a criptografia de chaves secretas

Neste documento, explicamos como ativar a criptografia de chaves secretas do consumidor de apps de desenvolvedor (credenciais do cliente) armazenadas no banco de dados do Cassandra.

Visão geral

Tradicionalmente, a Apigee Edge para nuvem privada fornece criptografia opcional para dados de mapa de chave-valor (KVM) e tokens de acesso OAuth.

A tabela a seguir descreve as opções de criptografia para dados em repouso na Apigee para Private Cloud:

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

• Crie um keystore para armazenar uma chave de criptografia de chaves (KEK). A 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 de desenvolvedor 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 chave

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

Por padrão, os valores atuais no banco de dados vão permanecer inalterados (em texto simples) e vão continuar 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 proteger as chaves

Armazene uma cópia do keystore em que a KEK está armazenada em um local seguro. Recomendamos que você use seu próprio mecanismo seguro para salvar uma cópia do keystore. Como explicam as instruções neste documento, um keystore precisa ser colocado em cada nó do processador de mensagens e do servidor de gerenciamento em que o arquivo de configuração local pode referenciá-lo. Mas também é importante armazenar uma cópia do keystore em outro lugar para proteção e como backup.

Ativar a criptografia de chaves

Siga estas etapas para criptografar a chave secreta do consumidor:

Pré-requisitos

Você precisa atender a estes requisitos antes de realizar as etapas deste 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 da Apigee Edge para nuvem privada.

Etapa 1: gerar um keystore

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

1. Execute o comando a seguir para gerar um keystore que armazene uma chave que será usada para criptografar a KEK. Digite o comando exatamente como mostrado. Você pode dar o nome que quiser ao keystore:
   

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

   Quando solicitado, digite uma senha. Você usará essa senha em 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 vai 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. 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 a 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

   O KEK_PASSWORD pode ser igual ao 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 de desenvolvedor

Agora que os servidores de gerenciamento foram atualizados, você precisa criar um app de desenvolvedor para acionar a geração da chave usada para criptografar os dados das credenciais do cliente:

1. Crie um app de desenvolvedor para acionar a criação de uma chave de criptografia de dados (DEK). Para ver as etapas, consulte Como registrar um app.
2. Exclua o app do desenvolvedor, 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. 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 a 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

   O KEK_PASSWORD pode ser igual ao 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 de desenvolvedor que você criar a partir de agora terão o secret de credencial criptografado 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 processador de mensagens e do servidor de gerenciamento usando variáveis de ambiente. Se definidas, as variáveis de ambiente substituem as propriedades definidas no processador de mensagens ou no arquivo de configuração do servidor de gerenciamento.

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 as propriedades de configuração dos arquivos de configuração nos nós do processador de mensagens e do servidor de gerenciamento, já que elas serão ignoradas:

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

Referência do arquivo de propriedades

Nesta seção, descrevemos 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.