Como ativar a criptografia de chaves secretas

Este documento explica como ativar a criptografia de segredos de consumo do app de desenvolvedor (credenciais de cliente) armazenados no banco de dados do Cassandra.

Visão geral

Tradicionalmente, o Apigee Edge para Private Cloud oferecia criptografia opcional para dados de mapa de chave-valor (KVM, na sigla em inglês) e tokens de acesso OAuth.

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

Para ativar a criptografia das credenciais do cliente, você precisa realizar 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, na sigla em inglês). O Apigee usa essa chave 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 chaves

As etapas neste documento explicam como ativar o recurso KEK, que permite que a Apigee criptografe as chaves secretas usadas para criptografar os segredos de consumo do app do desenvolvedor quando eles são armazenados 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 continuam 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 usar seu próprio mecanismo seguro para salvar uma cópia do keystore. Conforme explicado nas instruções neste documento, é preciso colocar um keystore em cada nó do processador de mensagens e do servidor de gerenciamento 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 local para fins de segurança e como backup.

Como ativar a criptografia de chave

Siga estas etapas para a criptografia de chave secreta do consumidor:

Pré-requisitos

Você precisa atender a estes requisitos antes de executar as etapas deste documento:

• É necessário instalar ou fazer upgrade para o Apigee Edge para nuvem privada 4.50.00.10 ou posterior.
• 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 abaixo para gerar um keystore para armazenar uma chave que será usada para criptografar a KEK. Digite o comando exatamente como mostrado. (Você pode fornecer qualquer nome de keystore):
   

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

   Quando solicitado, insira uma senha. Você vai 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 retornará uma chave com o alias KEYSTORE_NAME:

   keytool -list -keystore kekstore.p12

Como trabalhar com keystores BCFKS para sistemas operacionais habilitados para FIPS

Se você estiver usando o Edge para nuvem privada em um sistema operacional habilitado para FIPS, gere um keystore do tipo BCFKS. Esse keystore pode ser gerado em uma máquina que não é FIPS e transferido para uma máquina compatível com FIPS. Para gerar o keystore, use o seguinte comando:

keytool -genseckey -alias <KEYSTORE_NAME> -keyalg AES -keysize 256 \
-storetype BCFKS -keystore keystore.bcfks \
-providerpath /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-keypass keystorepass -storepass keystorepass

Talvez seja necessário executar outras configurações do Java na máquina em que você está gerando o keystore. Talvez seja necessário editar o arquivo de segurança Java da máquina (normalmente localizado em /usr/lib/jvm/jre/lib/security/java.security). Nesse arquivo, encontre e edite as seguintes propriedades:

# Don't rely on /dev/random for generating random numbers
securerandom.source=file:/dev/urandom
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS

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 um deles.

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 propriedades abaixo a /opt/apigee/customer/application/management-server.properties. Se o arquivo não existir, crie-o. Consulte também Referência do arquivo de propriedade.
   

   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 o mesmo que o 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ó de servidor de gerenciamento.

Etapa 3: criar um app para desenvolvedores

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

1. Crie um app de desenvolvedor 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 do desenvolvedor, se quiser. Não é necessário mantê-la 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 execução não poderão processar credenciais criptografadas.

1. Copie o arquivo de keystore gerado na Etapa 1 em 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 propriedades abaixo a /opt/apigee/customer/application/message-processor.properties. Crie o arquivo se ele não existir. Consulte também a Referência do arquivo de propriedade.

   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

   Observe que 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ó de processador de mensagens.

Resumo

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

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

Você também pode definir as propriedades de configuração do processador de mensagens e do servidor de gerenciamento usando variáveis de ambiente. Se definido, as variáveis de ambiente substituem as propriedades definidas no arquivo de configuração do processador de mensagens ou 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 essas propriedades de configuração dos arquivos de configuração nos nós do processador de mensagens e do servidor de gerenciamento, porque elas serão ignoradas:

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

Referência do arquivo de propriedade

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