Sobre as chaves de criptografia da Apigee

Você está vendo a documentação da Apigee X.
Veja a documentação da Apigee Edge.

Nesta seção, descrevemos os tipos de chaves de criptografia e como criá-las no ambiente de execução da Apigee.

Durante o processo de configuração da Apigee, você gera as seguintes chaves de criptografia do Google Cloud KMS:

Tipo de chave Criado quando Descrição
Chave de criptografia do aplicativo Etapa 4: criar uma organização

Criptografa dados de aplicativos como KVMs, cache e chaves secretas de cliente, que são armazenadas no banco de dados.

Há uma chave de criptografia de aplicativo por organização. Todas as instâncias/regiões em uma organização compartilham a mesma chave de criptografia do aplicativo.

A chave de criptografia do aplicativo é compatível com todos os locais do Cloud KMS compatíveis com o Cloud HSM e o Cloud EKM. O Google recomenda o uso de um local multirregional (como us ou eu) ou um local birregional (eur5, name4) ao criar essa chave.

A escolha do local do keyring depende do tipo de instalação usado: o assistente de provisionamento da Apigee não permite escolher um local para ele, ele escolhe o local para você. Se você usar a linha de comando, poderá escolher o local do keyring.

Chave de criptografia de disco Etapa 6: criar uma instância de ambiente de execução

Criptografa dados da instância do ambiente de execução antes de serem gravados no disco.

Os tipos de dados criptografados incluem KVMs, KMS, Tokens OAuth e códigos de autorização, cache de ambiente, buckets e cotas de cota; e chaves secretas dos clientes. Os dados do KMS incluem empresas, aplicativos para desenvolvedores, desenvolvedores, produtos de API, tokens e chaves de API.

Essa chave está localizada na mesma região da instância do ambiente de execução. Ao criar uma nova chave, corresponda o local da chave à localização da instância do ambiente de execução.

Cada combinação de instância/região tem a própria chave de criptografia de disco.

Pontos principais

Considere as seguintes informações ao criar as chaves de criptografia do disco e do aplicativo:

  • O local da chave de criptografia do aplicativo de ambiente de execução da Apigee é compatível com todos os locais do Cloud KMS compatíveis com o Cloud HSM e o Cloud EKM.
  • O local da chave de criptografia de disco precisa corresponder ao local do ambiente de execução da instância em que a chave é usada.
  • Depois de definido, não é possível alterar o local de uma das chaves.
  • Todas as chaves precisam estar em um keyring. Se você tiver várias instâncias, cada uma com sua própria chave de criptografia de disco, elas poderão estar no mesmo keyring.
  • As chaves de diferentes tipos precisam estar em keyrings separados. As chaves de criptografia de disco não podem estar no mesmo keyring que a chave de criptografia do aplicativo.
  • As chaves precisam ter um purpose. Se usar a linha de comando para gerar suas novas chaves, defina purpose como encryption. Se usa o Console do Cloud, escolha criptografia/descriptografia simétrica para fazer isso.
  • As chaves são definidas por um caminho de chave que usa o seguinte padrão:
    projects/PROJECT_ID/locations/KEY_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME

Como listar chaves existentes

Se você já tiver criado novas chaves de criptografia do Google Cloud KMS para a Apigee, poderá usá-las, em vez de criar novas chaves durante a configuração.

Para listar todas as chaves KMS em um keyring:

  1. Execute o comando gcloud kms keys list, como mostra o exemplo a seguir:

    gcloud kms keys list --keyring KEYRING_NAME --location KEYRING_LOCATION

Também é possível ver suas chaves no Console do Cloud.

Como gerar novas chaves na linha de comando

É possível criar um keyring e uma chave no Console do Cloud ou na linha de comando.

Cada tipo de chave precisa ter o próprio keyring. Por exemplo, as chaves de criptografia de disco podem ser armazenadas em um keyring, mas a chave de criptografia do aplicativo precisa ser armazenada em um keyring separado.

Chaves de disco

Para gerar um novo keyring e chave de criptografia de disco:

  1. Crie um novo keyring usando o comando gcloud:
    gcloud kms keyrings create my-disk-key-ring \
      --location $RUNTIME_LOCATION \
      --project $PROJECT_ID

    Isso cria um novo keyring chamado my-disk-key-ring. O keyring de disco precisa ser definido como o mesmo local da instância. Cada instância e keyring têm o próprio local.

  2. Crie uma nova chave de disco usando o comando kms keys create; Por exemplo:
    gcloud kms keys create my-disk-key --keyring my-disk-key-ring \
      --location $RUNTIME_LOCATION --purpose "encryption" --project $PROJECT_ID

    Esse comando cria uma nova chave chamada my-disk-key e a adiciona ao my-disk-key-ring key ring.

    A chave pode ser referenciada pelo caminho de chave. É possível ver o caminho da chave com o comando a seguir:

    gcloud kms keys list \
      --location=$RUNTIME_LOCATION \
      --keyring=$DISK_KEY_RING_NAME \
      --project=$PROJECT_ID

    O caminho de chave é semelhante ao seguinte:

    projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/my-disk-key-ring/cryptoKeys/my-disk-key
  3. Conceda acesso para que o agente de serviço da Apigee use a nova chave executando o comando gcloud kms keys add-iam-policy-binding; por exemplo:
    gcloud kms keys add-iam-policy-binding my-disk-key \
      --location $RUNTIME_LOCATION \
      --keyring my-disk-key-ring \
      --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
      --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
      --project $PROJECT_ID

    Esse comando vincula a chave ao agente de serviços da Apigee.

Chaves do aplicativo

Para gerar um novo keyring e chave de criptografia de aplicativos:

  1. Defina uma variável de ambiente para o local do keyring e da chave de criptografia do banco de dados do ambiente de execução. Isso ajuda a garantir a consistência quando na criação e facilita o acompanhamento na documentação.

    O valor é o local físico em que o keyring e a chave de criptografia do banco de dados são armazenados.

    • Configurações de região única, em que você tem apenas uma instância em uma região: escolha entre os locais regionais do KMS.

      Exemplo:

      APPKEY_LOCATION="us-west1"

      O valor pode ser o mesmo que $RUNTIME_LOCATION (também uma região), mas não precisa ser. No entanto, isso poderá resultar em uma melhoria no desempenho.

    • Configurações multirregionais: escolha entre os locais multirregionais compatíveis (como us ou eu) ou locais birregionais.

      Exemplo:

      APPKEY_LOCATION="us"

      O Google recomenda que, se você tiver uma configuração multirregional nos EUA, use us como seu local, se possível. Do contrário, use nam4.

  2. Crie um novo keyring usando o comando gcloud; Por exemplo:
    gcloud kms keyrings create my-app-key-ring --location $APPKEY_LOCATION --project $PROJECT_ID

    Isso cria um novo keyring chamado my-app-key-ring. O local da chave de criptografia do banco de dados da Apigee é compatível com todos os locais do Cloud KMS compatíveis com o Cloud HSM e o Cloud EKM.

    O nome do keyring precisa ser exclusivo para sua organização. Se você criar uma segunda ou uma região subsequente, o nome não poderá ser igual ao de outros keyrings.

  3. Crie uma chave usando o comando gcloud kms keys create; Por exemplo:
    gcloud kms keys create my-app-key --keyring my-app-key-ring \
      --location $APPKEY_LOCATION --purpose "encryption" --project $PROJECT_ID

    Esse comando cria uma nova chave chamada my-app-key e a adiciona ao keyring.

    A chave pode ser referenciada pelo código da chave. Para receber o código da chave, use o seguinte comando:

    gcloud kms keys list \
      --location=$APPKEY_LOCATION \
      --keyring=$APPKEY_KEY_RING_NAME \
      --project=$PROJECT_ID

    O ID da chave tem a seguinte sintaxe (semelhante a um caminho de arquivo):

    projects/PROJECT_ID/locations/APPKEY_LOCATION/keyRings/APPKEY_RING_NAME/cryptoKeys/APPKEY_NAME

    Neste exemplo, o caminho do ID da chave é:

    projects/my-cloud-project/locations/us-west1/keyRings/my-app-key-ring/cryptoKeys/my-app-key
  4. Conceda acesso para que o agente de serviço da Apigee use a nova chave executando o comando gcloud kms keys add-iam-policy-binding usando a seguinte sintaxe:

    gcloud kms keys add-iam-policy-binding APP_KEY_NAME \
      --location APP_KEY_LOCATION \
      --keyring APP_KEY_RING_NAME \
      --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
      --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
      --project PROJECT_ID

    Exemplo:

    gcloud kms keys add-iam-policy-binding my-app-key \
      --location $APPKEY_LOCATION \
      --keyring my-app-key-ring \
      --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
      --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
      --project $PROJECT_ID

    Esse comando vincula a chave ao agente de serviços da Apigee.

    Após a conclusão dessa solicitação, gcloud responde com algo semelhante ao seguinte:

    Updated IAM policy for key [runtime].
    bindings:
    - members:
      - serviceAccount:service-1234567890@gcp-sa-apigee.iam.gserviceaccount.com
      role: roles/cloudkms.cryptoKeyEncrypterDecrypter
    etag: BwWqgEuCuwk=
    version: 1

    Se você receber um erro como este:

    INVALID_ARGUMENT: Role roles/cloudkms.cryptokms.cryptoKeyEncrypterDecrypter is not supported for this resource.

    Verifique se você usou o número do projeto e não o nome do projeto no endereço de e-mail da conta de serviço.

Como gerar novas chaves usando o Console do Cloud

É possível gerar novas chaves usando o Console do Cloud e usando o utilitário "Criar chave", conforme descrito em Como criar e gerenciar chaves de conta de serviço.

Ao usar o Console para criar uma nova chave:

  • Para a chave de criptografia do aplicativo, defina o local como qualquer local do Cloud KMS compatível com o Cloud HSM e o Cloud EKM. A IU não permite que você escolha qualquer outro local para a chave. Por isso, ela corresponderá ao que você escolheu no keyring.
  • Depois de criar a chave, consiga o caminho da chave no painel Chaves de criptografia selecionando o menu de três pontos ao lado da chave e, em seguida, selecionando Copiar nome do recurso.

Como verificar chaves

Para ver o caminho da sua chave, use o seguinte comando:

gcloud kms keys describe runtime --location $RUNTIME_LOCATION \
    --keyring KEYRING_NAME --format="value(name)"

gcloud retorna o caminho de chave no seguinte formato:

projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME

Exemplo:

projects/my-cloud-project/locations/us-west1/keyRings/my-disk-key-ring/cryptoKeys/my-disk-key

Também é possível verificar o caminho da chave no Console do Cloud. Para mais informações, consulte Chave.