Como ativar a criptografia de chaves secretas

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

Informações gerais

Tradicionalmente, o Apigee Edge para nuvem privada fornece 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 na Apigee para nuvem privada:

Entidade Criptografia ativada por padrão Criptografia opcional disponível Documentação relacionada
KVMs Não Sim Consulte Sobre KVMs criptografadas.
Tokens de acesso do OAuth Não Sim Consulte Tokens de hash para segurança extra.
Segredos do consumidor do app do desenvolvedor Não Sim Para ativar, execute as etapas de configuração neste documento.

Para ativar a criptografia de credenciais de cliente, você precisa executar as seguintes tarefas em todos os nós de processador de mensagens e servidor de gerenciamento:

  • Crie um keystore para armazenar uma chave de criptografia de chaves (KEK, na sigla em inglês). A Apigee usa essa chave criptografada para criptografar as chaves secretas necessárias para criptografar seus dados.
  • Permite editar 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 secrets do consumidor do app do desenvolvedor quando elas estiverem armazenadas em repouso no banco de dados do Cassandra.

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

Se você executar 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 em segurança

Guarde uma cópia do keystore em que a KEK está armazenada em um local seguro. Recomendamos usar seu próprio mecanismo de segurança para salvar uma cópia do keystore. Conforme explicado nas instruções deste documento, é necessário colocar um keystore em cada nó do processador de mensagens e do servidor de gerenciamento onde o arquivo de configuração local possa referenciá-lo. Mas também é importante armazenar uma cópia do keystore em outro lugar para segurança e como backup.

Como ativar a criptografia de chaves

Siga estas etapas para criptografar a chave secreta do cliente:

Pré-requisitos

Você precisa atender a estes requisitos antes de realizar as etapas neste documento:

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

Etapa 1: gerar um keystore

Siga estas etapas para criar um keystore e armazenar a chave de criptografia de chaves (KEK, na sigla em inglês):

  1. Execute o comando a seguir para gerar um keystore e armazenar uma chave que será usada para criptografar a KEK. Digite o comando exatamente como mostrado. Você pode fornecer o nome de keystore que quiser:
    keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
-keystore kekstore.p12 -storetype PKCS12

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

    Esse comando gera um arquivo keystore kekstore.p12 contendo uma chave com o alias KEYSTORE_NAME.

  2. (Opcional) Verifique se o arquivo foi gerado corretamente usando 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 propriedades abaixo ao /opt/apigee/customer/application/management-server.properties. Se o arquivo não existir, crie-o. Consulte também Referência de arquivos 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 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ó.

Etapa 3: criar um app de desenvolvedor

Agora que os servidores de gerenciamento estão atualizados, crie 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 (KEK, na sigla em inglês). Para conferir 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 tempo de execução não poderão processar nenhuma credencial criptografada.

  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. 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 propriedades abaixo ao /opt/apigee/customer/application/message-processor.properties. Se o arquivo não existir, crie-o. Consulte também Referência de arquivos 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 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

Qualquer app de desenvolvedor que você criar a partir de agora terá 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, você pode definir as propriedades de configuração do processador de mensagens e do servidor de gerenciamento a seguir usando variáveis de ambiente. Se definidas, as variáveis de ambiente vão modificar 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 no processador de mensagens e nos nós 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 propriedade

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

Propriedade Padrão Descrição
conf_keymanagement_kmscred.encryption.enabled false Precisa ser true para ativar a criptografia de chaves.
conf_keymanagement_kmscred.encryption.allowFallback false Defina allowReplace como true para garantir que as credenciais de texto simples atuais continuem funcionando
conf_keymanagement_kmscred.encryption.keystore.path N/A Informe o caminho para o keystore da KEK no nó do processador de mensagens ou do servidor de gerenciamento. Consulte a Etapa 2: configurar o servidor de gerenciamento e a Etapa 3: configurar os processadores de mensagens.
conf_keymanagement_kmscred.encryption.kek.alias N/A Alias em que a KEK é armazenada no keystore.
conf_keymanagement_kmscred.encryption.keystore.pass N/A Opcional se você usa variáveis de ambiente para definir essas propriedades. Consulte também Como usar variáveis de ambiente para propriedades de configuração.
conf_keymanagement_kmscred.encryption.kek.pass N/A Opcional se você usa variáveis de ambiente para definir essas propriedades. Consulte também Como usar variáveis de ambiente para propriedades de configuração.