Como criar keystores e truststore usando a interface do Edge

Esta é a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Este documento descreve como criar, modificar e excluir keystores e truststores para o Edge para a nuvem e para o Edge para as versões 4.18.01 e mais recentes da nuvem privada.

Sobre keystores/truststores e hosts virtuais para o Edge Cloud

O processo de criação de keystores/truststores para o Edge Cloud exige que você siga todos regras sobre o uso de hosts virtuais. Por exemplo, com hosts virtuais no Cloud:

• Os hosts virtuais precisam usar o TLS.
• Os hosts virtuais só podem usar a porta 443.
• É necessário usar um certificado TLS assinado. Não é permitido usar certificados não assinados com hosts virtuais na nuvem.
• O nome de domínio especificado pelo certificado TLS precisa corresponder ao alias do host virtual.

Saiba mais:

• Sobre TLS/SSL
• Como usar TLS com o Edge
• Perguntas frequentes sobre a configuração de hosts virtuais
• Sobre hosts virtuais

Implementar keystores e truststores em Borda

Para configurar funcionalidades que dependem da infraestrutura de chave pública, como o TLS, você precisa: criar keystores e truststores que contenham as chaves e os certificados digitais necessários.

No Edge, keystores e truststores são representados por uma entidade keystore que contêm um ou mais aliases. Ou seja, não há diferença de implementação entre um keystore e um truststore no Edge.

A diferença entre keystores e truststores é derivada dos tipos de entradas que elas contêm e de como são usadas no handshake do TLS:

• keystore: uma entidade de keystore que contém um ou mais aliases, em que cada alias contém um par de certificado/chave.
• truststore: uma entidade keystore que contém um ou mais aliases, em que cada alias contém apenas um certificado.

Ao configurar o TLS para um host virtual ou endpoint de destino, os keystores e truststores fornecem diferentes funções no processo de handshake do TLS. Ao configurar um host virtual ou um destino endpoint, especifique keystores e truststores separadamente no <SSLInfo> , como mostrado abaixo para um host virtual:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

Neste exemplo, você especifica o nome do keystore e o alias usados pelo host virtual para o keystore TLS. Você usa uma referência para especificar o nome do keystore e poder mudar o nome quando o certificado expirar. O alias contém um par certificado/chave usado para identificar o host virtual para um cliente TLS acessando o host virtual. Neste exemplo, não é necessário usar um truststore.

Se um repositório de confiança for necessário, por exemplo, para uma configuração de TLS bidirecional, use a tag <TrustStore> para especificar o repositório de confiança:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

Neste exemplo, a tag <TrustStore> faz referência apenas a um keystore e não especifica um alias específico. Cada alias no keystore contém um certificado, ou uma cadeia de certificados, que é usado como parte do processo de handshake do TLS.

Formatos de certificado compatíveis

* Recomendamos o uso de PEM, se possível.

Como usar keystores PKCS12 com o Edge para nuvem privada 4.53.00 ou posterior

Se você estiver usando o Edge para nuvem privada 4.53.00 ou mais recente, use apenas um keystore PKCS12 para fazer upload de chaves e certificados relacionados ao Apigee. Para receber ajuda com a conversão de chaves e certificados para o formato PKCS12/PFX, consulte Como converter certificados em um formato compatível.

Sobre a implementação de um alias

No Edge, um keystore contém um ou mais aliases, em que cada alias contém:

• Certificado TLS como um arquivo PEM ou PKCS12/PFX: um certificado assinado por uma autoridade certificadora (AC), um arquivo contendo uma cadeia de certificados em que o último certificado é assinado por uma AC ou um certificado autoassinado.
• Chave privada como um arquivo PEM ou PKCS12/PFX. O Edge oferece suporte a chaves de até 2.048 bits. Uma senha longa é opcional.

No Edge, uma truststore contém um ou mais aliases, em que cada alias contém:

• Certificado TLS como um arquivo PEM: um certificado assinado por uma autoridade de certificação uma cadeia de certificados em que o último certificado é assinado por uma AC ou um certificado certificado.

O Edge oferece uma interface e uma API que você usa para criar keystores, criar aliases, fazer upload de pares de certificado/chave e atualizar certificados. A interface e a API usadas para criar um repositório de confiança são as mesmas usadas para criar um keystore. A diferença é que, ao criar um repositório de certificados, você cria aliases que contêm apenas um certificado.

Sobre o formato dos arquivos de certificado e chave

Você pode representar certificados e chaves como arquivos PEM ou como arquivos PKCS12/PFX. Os arquivos PEM obedecem ao formato X.509. Se o certificado ou a chave privada não estiverem definidos por um arquivo PEM, você poderá convertê-los em um arquivo PEM usando utilitários, como openssl.

No entanto, muitos arquivos .crt e .key já estão no formato PEM. Se esses arquivos forem textos e estão entre:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

ou

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

Em seguida, os arquivos são compatíveis com o formato PEM e podem ser usados em um keystore ou truststore sem convertê-los em um arquivo PEM.

Sobre as cadeias de certificados

Se um certificado faz parte de uma cadeia, ele é processado de maneira diferente dependendo se é usado em um keystore ou em um truststore:

• Keystore: se um certificado fizer parte de uma cadeia, você precisará criar um único arquivo contendo todas as os certificados na cadeia. Os certificados precisam estar em ordem e o último deles precisa ser uma raiz. certificado ou intermediário assinado por um certificado raiz.
• Truststore: se um certificado faz parte de uma cadeia, você precisa criar um único arquivo contendo todos os certificados e fazer o upload desse arquivo para um alias ou fazer o upload de todos os certificados da cadeia separadamente para o truststore usando um alias diferente para cada certificado. Se você fizer o upload delas como um certificado único, os certificados devem estar em ordem e o último certificado deve ser um certificado raiz ou um intermediário assinado por um certificado raiz.
• Se você criar um único arquivo com vários certificados, insira uma linha vazia entre cada certificado.

Por exemplo, é possível combinar todos os certificados em um único arquivo PEM. Os certificados precisam estar em ordem, e o último precisa ser um certificado raiz ou intermediário assinado por um certificado raiz:

-----BEGIN CERTIFICATE----- 
(Your Primary TLS certificate) 
-----END CERTIFICATE----- 

-----BEGIN CERTIFICATE----- 
(Intermediate certificate) 
-----END CERTIFICATE-----
 
-----BEGIN CERTIFICATE----- 
(Root certificate or intermediate certificate signed by a root certificate) 
-----END CERTIFICATE-----

Se seus certificados forem representados como arquivos PKCS12/PFX, você poderá usar o openssl para criar um arquivo PKCS12/PFX da cadeia de certificados, conforme mostrado abaixo:

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

Ao trabalhar com cadeias de certificados em um truststore, você nem sempre precisa fazer upload de todos os certificados na cadeia. Por exemplo, você faz upload de um certificado do cliente, client_cert_1, e do certificado do emissor do certificado do cliente, ca_cert.

Durante a autenticação TLS bidirecional, a autenticação do cliente é bem-sucedida quando o servidor envia client_cert_1 ao cliente como parte do processo de handshake de TLS.

Como alternativa, você tem um segundo certificado, client_cert_2, assinado pelo mesmo certificado, ca_cert. No entanto, você não faz upload de client_cert_2 para o repositório de confiança. O repositório de confiança ainda contém apenas client_cert_1 e ca_cert.

Quando o servidor transmite client_cert_2 como parte do handshake de TLS, a solicitação é bem-sucedida. Isso ocorre porque o Edge permite que a verificação TLS seja bem-sucedida quando client_cert_2 não existe no truststore, mas foi assinado por um certificado que existe no truststore. Se você remover o certificado da AC, ca_cert, do repositório de confiança, a verificação do TLS vai falhar.

Considerações sobre os FIPS

Se você estiver usando o Edge para nuvem privada 4.53.00 ou posterior em um sistema operacional habilitado para FIPS, use apenas um keystore PKCS12 para fazer upload de chaves e certificados relacionados para a Apigee.

Conheça a página "Keystores TLS"

A página "Keystores TLS" é exibida:

Conforme destacado na figura anterior, na página "Armazenamentos de chaves TLS", é possível:

• Selecione um ambiente
• Criar um keystore e um alias
• Testar e excluir keystores
• Acessar e excluir aliases

Ver um alias

Para conferir um alias:

1. Acesse a página "Keystores TLS".
2. Selecione o ambiente (geralmente prod ou test).
3. Clique na linha associada ao alias que você quer consultar.

   Os detalhes do certificado e da chave do alias são exibidos.
   
   Você pode conferir todas as informações sobre o alias, incluindo a data de validade.

4. Use os botões na parte de cima da página para gerenciar o certificado:
   • Baixe o certificado como um arquivo PEM.
   • Gere uma CSR. Se você tiver um certificado expirado e quiser renová-lo, faça o download de um solicitação de assinatura de certificado (CSR, na sigla em inglês). Em seguida, você envia a CSR à sua AC para receber um novo certificado.
   • Atualizar um certificado. Cuidado: se você atualizar um certificado que esteja estiver sendo usado por um host virtual ou servidor de destino/endpoint de destino, você precisa entre em contato com o suporte do Apigee Edge para reiniciar os roteadores e processadores de mensagens. A maneira recomendada de atualizar certificado é:
     1. Crie um novo keystore ou truststore.
     2. Adicione o novo certificado ao novo keystore ou truststore.
     3. Atualize a referência no host virtual ou no endpoint de destino/servidor de destino para o keystore ou truststore. Consulte Atualize um certificado TLS para o Cloud para saber mais.
     4. Exclua o alias. Observação: se você excluir um alias e ele for por um host virtual ou endpoint de destino, o host virtual ou o o endpoint de destino vai falhar.

Criar um keystore/truststore e um alias

É possível criar um keystore para uso como um keystore TLS ou um truststore TLS. Um keystore é específico para um ambiente na sua organização, por exemplo, o ambiente de teste ou de produção. Portanto, se você quiser testar o keystore em um ambiente de teste antes de implantá-lo no ambiente de produção, é preciso criá-lo em ambos os ambientes.

Para criar um keystore em um ambiente, basta especificar o nome do keystore. Depois de criar um keystore nomeado em um ambiente, é possível criar aliases e fazer upload de um par de certificado/chave (keystore) ou apenas de um certificado (truststore) para o alias.

Para criar um keystore:

1. Acesse a página "Keystores TLS".
2. Selecione o ambiente (geralmente prod ou test).
3. Clique em + Keystore.
4. Especifique o nome do keystore. O nome só pode conter caracteres alfanuméricos.
5. Clique em Add Keystore. O novo keystore aparece na lista.
6. Use um dos procedimentos a seguir para adicionar um alias. Consulte também Formatos de arquivo de certificado compatíveis.
   • Como criar um alias a partir de um certificado (somente repositório de confiança)
   • Como criar um alias em um arquivo JAR (somente keystore)
   • Criar um alias de um certificado e uma chave (somente keystore)
   • Criar um alias de um arquivo PKCS12/PFX (somente keystore)
   • Criar um alias de um certificado autoassinado (somente keystore)

Como criar um alias a partir de um certificado (somente truststore)

Para criar um alias com base em um certificado:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para exibir o menu de ações e clique em +.
3. Especifique o Nome do alias.
4. Em "Detalhes do certificado", selecione Somente certificado no menu suspenso "Tipo".
5. Clique em Escolher arquivo ao lado de Arquivo de certificado e acesse a PEM que contém o certificado e clique em Abrir.
6. Por padrão, a API verifica se o certificado não expirou. Se preferir, selecione Permitir certificado expirado para ignorar a validação.
7. Selecione Salvar para fazer upload do certificado e criar o alias.

Como criar um alias em um arquivo JAR (somente keystore)

Para criar um alias a partir de um arquivo JAR:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para exibir o menu de ações e clique em +.
3. Especifique o Nome do alias.
4. Em "Detalhes do certificado", selecione Arquivo JAR no menu suspenso "Tipo".
5. Clique em Choose File ao lado de JAR File, navegue até o arquivo JAR que contém o certificado e a chave e clique em Open.
6. Se a chave tiver uma senha, especifique a Senha. se a chave não tiver senha, deixe esse campo em branco.
7. Por padrão, a API verifica se o certificado não expirou. É possível selecionar Permitir certificado expirado para pular a validação.
8. Selecione Salvar para fazer upload da chave e do certificado e criar o alias.

Criar um alias de um certificado e uma chave (somente keystore)

Para criar um alias com base em um certificado e uma chave:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para exibir o menu de ações e clique em +.
3. Especifique o Nome do alias.
4. Em "Detalhes do certificado", selecione Certificado e chave no menu suspenso "Tipo".
5. Clique em Escolher arquivo ao lado de Arquivo de certificado, navegue até o arquivo PEM que contém o certificado e clique em Abrir.
6. Se a chave tiver uma senha, especifique a Senha da chave. Se a chave não tiver senha, deixe esse campo em branco.
7. Clique em Choose File ao lado de Key File, acesse o arquivo PEM que contém a chave e clique em Open.
8. Por padrão, a API verifica se o certificado não expirou. É possível selecionar Permitir certificado expirado para pular a validação.
9. Selecione Salvar para fazer upload da chave e do certificado e criar o alias.

Criar um alias com base em um Arquivo PKCS12/PFX (somente keystore)

Para criar um alias a partir de um arquivo PKCS12 que contenha o certificado e a chave:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para exibir o menu de ações e clique em +.
3. Especifique o Nome do alias.
4. Em "Detalhes do certificado", selecione PKCS12/PFX no menu suspenso "Tipo".
5. Clique em Choose File ao lado de PKCS12/PFX, acesse a que contém a chave e o certificado e clique em Abrir.
6. Se a chave tiver uma senha, especifique a Senha do arquivo PKCS12/PFX. Se a chave não tiver uma senha, deixe esse campo em branco.
7. Por padrão, a API verifica se o certificado não expirou. Se preferir, selecione Permitir certificado expirado para ignorar a validação.
8. Selecione Salvar para fazer upload do arquivo e criar o alias.

Criar um alias com base em um certificado autoassinado (somente keystore)

Para criar um alias que use um certificado autoassinado, preencha um formulário com as informações informações necessárias para criar o certificado. Depois, o Edge cria o certificado e um par de chaves privadas e e faz upload delas para o alias.

Para criar um alias a partir de um certificado autoassinado:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para exibir o menu de ações e clique em +.
3. Especifique o Nome do alias.
4. Em "Detalhes do certificado", selecione Certificado assinado pelo próprio usuário no menu suspenso "Tipo".
5. Preencha o formulário usando a tabela abaixo.
6. Selecione Salvar para criar o par de chaves privadas e o certificado e fazer upload deles para o alias.

No certificado gerado, você vai encontrar os seguintes campos adicionais:

• Emissor
  A entidade que assinou e emitiu o certificado. Para um certificado autoassinado, CN que você especificou quando criou o certificado.
• Validade
  O período de validade do certificado representado como duas datas: a data em que o certificado início do período de validade e a data de término do período de validade do certificado. Ambos podem ser codificados como valores UTCTime ou GeneralizedTime.

A tabela a seguir descreve os campos do formulário:

Testar um keystore ou truststore

É possível testar o truststore e o keystore na interface do Edge para verificar se eles estão configurados corretamente. A interface de teste valida uma solicitação TLS do Edge para um serviço de back-end. O serviço de back-end pode ser configurado para oferecer suporte ao TLS unidirecional ou bidirecional.

Para testar o TLS unidirecional:

1. Acesse a página "Keystores TLS".
2. Selecione o ambiente (geralmente prod ou test).
3. Posicione o cursor sobre o keystore TLS que você quer testar para exibir o menu de ações e clique em Testar. A caixa de diálogo abaixo aparece mostrando o nome do repositório de confiança:
   
4. Insira o nome do host do serviço de back-end.
5. Digite o número da porta TLS (normalmente 443).
6. Especifique opcionalmente protocolos ou criptografias.
7. Selecione Testar.

Para testar o TLS bidirecional:

1. Para a loja de confiança desejada, selecione o botão Testar.
2. Na caixa de diálogo, selecione Two Way para o SSL Test Type. A seguinte caixa de diálogo será exibida:
   
3. Especifique o nome do keystore usado no TLS bidirecional.
4. Especifique o nome do alias no keystore que contém o certificado e a chave.
5. Insira o nome do host do serviço de back-end.
6. Digite o número da porta TLS (normalmente 443).
7. Especifique opcionalmente protocolos ou criptografias.
8. Selecione Testar.

Adicionar um certificado a um repositório de confiança para TLS bidirecional

Ao usar o TLS bidirecional para conexões de entrada, ou seja, uma solicitação de API para o Edge, o repositório de confiança contém um certificado ou uma cadeia de AC para cada cliente autorizado a fazer solicitações para o Edge.

Ao configurar inicialmente o truststore, é possível adicionar todos os certificados dos clientes conhecidos. No entanto, com o tempo, talvez você queira adicionar outros certificados ao truststore à medida que adicionar novos clientes.

Para adicionar novos certificados a um repositório de confiança usado para TLS bidirecional:

1. Verifique se você está usando uma referência ao truststore no host virtual.
2. Faça upload de um novo certificado para o truststore, conforme descrito acima em Como criar um alias a partir de um certificado (somente truststore).

3. Atualize a referência do repositório de confiança para definir o mesmo valor. Essa atualização faz com que o Edge recarregue o truststore e o novo certificado.

   Consulte Como modificar uma referência para mais informações.

Excluir um keystore/truststore ou alias

Tenha cuidado ao excluir um keystore/truststore ou um alias. Se você excluir um keystore, truststore ou alias que está sendo usado por um host virtual, endpoint de destino ou servidor de destino, todas as chamadas de API pelo host virtual ou pelo endpoint/servidor de destino vão falhar.

Normalmente, o processo usado para excluir um keystore/truststore ou alias é:

1. Crie um novo keystore/truststore ou alias conforme descrito acima.
2. Para conexões de entrada, ou seja, uma solicitação de API para o Edge, atualize a configuração de host virtual para fazer referência ao novo keystore e o alias de chave.
3. Para conexões de saída, ou seja, da Apigee para um servidor de back-end:
   1. Atualize a configuração do TargetEndpoint para todos os proxies de API que referenciaram o keystore e o alias de chave antigos para referenciar o novo keystore e o alias de chave. Se o TargetEndpoint faz referência a um TargetServer, atualize a definição de TargetServer para fazer referência ao novo keystore e alias da chave.
   2. Se o keystore e o truststore forem referenciados diretamente na definição de TargetEndpoint, será necessário reimplantar o proxy. Se o TargetEndpoint referenciar uma definição de TargetServer e a definição de TargetServer referenciar o keystore e o Truststore, não será necessário reimplantar o proxy.
4. Confirme se os proxies da API estão funcionando corretamente.
5. Exclua o keystore/truststore ou o alias.

Excluir um keystore

É possível excluir um keystore ou um truststore posicionando seu cursor sobre o keystore ou o trustore na lista para exibir as ações e clicando em . Se você excluir um keystore ou truststore que está sendo usado por um host virtual ou endpoint de destino/servidor de destino, todas as chamadas de API pelo host virtual ou endpoint de destino/servidor de destino vão falhar.

Atenção: não exclua um keystore até que você tenha convertido os hosts virtuais e os endpoints/servidores de destino para usar um novo keystore.

Excluir um alias

Para excluir um alias, posicione o cursor sobre ele na lista para mostrar o menu de ações e clique em . Se você excluir um alias que esteja sendo usado por um host virtual ou endpoint/servidor de destino, todas as chamadas de API por meio do host virtual ou do endpoint/destino de destino do Google Cloud vai falhar.

Atenção: não exclua um alias até que você tenha convertido seus hosts virtuais e endpoints/servidores de destino para usar um novo keystore e alias.