Como criar keystores e truststore usando a interface do Edge

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Neste documento, descrevemos como criar, modificar e excluir keystores e truststores para o Edge para o Cloud e para o Edge para o Cloud privado versões 4.18.01 e mais recentes.

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 todas as regras sobre o uso de hosts virtuais. Por exemplo, com hosts virtuais na nuvem:

• Os hosts virtuais precisam usar TLS.
• Os hosts virtuais só podem usar a porta 443.
• Você precisa 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 de host do host virtual.

Saiba mais:

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

Implementar keystores e truststores no Edge

Para configurar funcionalidades que dependem da infraestrutura de chaves públicas, como o TLS, é necessário criar keystores e truststores que contenham as chaves e os certificados digitais necessários.

No Edge, os 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 deriva dos tipos de entradas que elas contêm e de como são usadas no handshake de TLS:

• keystore: uma entidade 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 os truststores têm funções diferentes no processo de handshake do TLS. Ao configurar um host virtual ou um endpoint de destino, especifique keystores e truststores separadamente na tag <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 usado pelo host virtual para o keystore TLS. Você usa uma referência para especificar o nome do keystore e poder mudá-lo depois, quando o certificado expirar. O alias contém um par certificado/chave usado para identificar o host virtual para um cliente TLS que acessa o host virtual. Neste exemplo, não é necessário um truststore.

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

<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, não especifica um alias específico. Cada alias no keystore contém um certificado ou uma cadeia de certificados que é usada como parte do processo de handshake TLS.

Formatos de certificado compatíveis

* Recomendamos usar PEM, se possível.

Como usar keystores PKCS12 com o Edge para nuvem privada 4.53.00 ou versões mais recentes

Se você estiver usando o Edge para nuvem privada 4.53.00 ou versões mais recentes, use apenas um keystore PKCS12 para fazer upload de chaves e certificados relacionados para a Apigee. Para ajuda com a conversão das chaves e certificados atuais para o formato PKCS12/PFX, consulte Converter certificados para o 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 de certificação (CA), um arquivo que contém uma cadeia de certificados em que o último certificado é assinado por uma CA ou um certificado autoassinado.
• Chave privada como um arquivo PEM ou PKCS12/PFX. O Edge é compatível com tamanhos de chave de até 2.048 bits. Uma senha longa é opcional.

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

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

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

Sobre o formato dos arquivos de certificado e chave

É possível representar certificados e chaves como arquivos PEM ou PKCS12/PFX. Os arquivos PEM estão em conformidade com o formato X.509. Se o certificado ou a chave privada não estiverem definidos por um arquivo PEM, use utilitários como openssl para fazer a conversão.

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

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

ou

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

Assim, os arquivos são compatíveis com o formato PEM e podem ser usados em um keystore ou truststore sem conversão para um arquivo PEM.

Sobre cadeias de certificados

Se um certificado fizer parte de uma cadeia, o tratamento será diferente dependendo se ele é usado em um keystore ou em um truststore:

• Keystore: se um certificado fizer parte de uma cadeia, crie um único arquivo com todos os certificados da cadeia. Os certificados precisam estar em ordem, e o último precisa ser um certificado raiz ou um certificado intermediário assinado por um certificado raiz.
• Truststore: se um certificado fizer parte de uma cadeia, você precisará 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 upload deles como um único certificado, eles precisarão estar em ordem, e o último certificado precisa ser um certificado raiz ou um certificado intermediário assinado por um certificado raiz.
• Se você criar um único arquivo com vários certificados, insira uma linha em branco entre cada um deles.

Por exemplo, você pode combinar todos os certificados em um único arquivo PEM. Os certificados precisam estar em ordem, e o último precisa ser um certificado raiz ou um certificado 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 os certificados forem representados como arquivos PKCS12/PFX, use o comando openssl para criar um arquivo PKCS12/PFX de uma 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 keystore de confiança, nem sempre é necessário 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, não faça upload de client_cert_2 para o truststore. O keystore 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 acontece porque o Edge permite que a verificação de 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 de CA, ca_cert, do truststore, a verificação de TLS vai falhar.

Considerações sobre o FIPS

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

Acessar a página "Keystores TLS"

A página "Keystores TLS" é exibida:

Conforme destacado na figura anterior, a página "Keystores TLS" permite:

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

Ver um alias

Para ver 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 visualizar.

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

4. Gerencie o certificado usando os botões na parte de cima da página para:
   • Baixe o certificado como um arquivo PEM.
   • Gere uma CSR. Se você tiver um certificado expirado e quiser renová-lo, baixe uma solicitação de assinatura de certificado (CSR). Em seguida, envie a CSR à CA para receber um novo certificado.
   • Atualizar um certificado. Atenção: se você atualizar um certificado que está sendo usado por um host virtual ou servidor/endpoint de destino, entre em contato com o suporte do Apigee Edge para reiniciar os roteadores e processadores de mensagens. A maneira recomendada de atualizar um 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 servidor de destino/endpoint de destino para o keystore ou truststore. Consulte Atualizar um certificado TLS para a nuvem para mais informações.
     4. Exclua o alias. Observação: se você excluir um alias que está sendo usado por um host virtual ou endpoint de destino, o host virtual ou endpoint de destino vai falhar.

Criar um keystore/truststore e um alias

É possível criar um keystore para uso como um keystore 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, crie-o nos dois ambientes.

Para criar um keystore em um ambiente, basta especificar o nome dele. Depois de criar um keystore nomeado em um ambiente, você pode criar aliases e fazer upload de um par certificado/chave (keystore) ou de um certificado apenas (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 aceitos.
   • Criar um alias de um certificado (somente truststore)
   • Como criar um alias de um arquivo JAR (somente keystore)
   • Crie um alias de um certificado e uma chave (somente keystore)
   • Criar um alias de um arquivo PKCS12/PFX (somente keystore)
   • Como criar um alias de um certificado autoassinado (somente keystore)

Como criar um alias de um certificado (somente truststore)

Para criar um alias de um certificado:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para mostrar o menu de ações e clique em +.
3. Especifique o Nome do alias.
4. Em "Detalhes do certificado", selecione Apenas certificado 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. Por padrão, a API verifica se o certificado não expirou. Se quiser, 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 de um arquivo JAR (somente keystore)

Para criar um alias de um arquivo JAR:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para mostrar 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 Escolher arquivo ao lado de Arquivo JAR, navegue até o arquivo JAR que contém o certificado e a chave e clique em Abrir.
6. Se a chave tiver uma senha, especifique a Senha. 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 quiser, selecione Permitir certificado expirado para ignorar a validação.
8. Selecione Salvar para fazer upload da chave e do certificado e criar o alias.

Como criar um alias de um certificado e uma chave (somente keystore)

Para criar um alias de um certificado e uma chave:

1. Acesse a página "Keystores TLS".
2. Posicione o cursor sobre o keystore para mostrar 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 não tiver, deixe esse campo em branco.
7. Clique em Escolher arquivo ao lado de Arquivo de chave, navegue até o arquivo PEM que contém a chave e clique em Abrir.
8. Por padrão, a API verifica se o certificado não expirou. Se quiser, selecione Permitir certificado expirado para ignorar a validação.
9. Selecione Salvar para fazer upload da chave e do certificado e criar o alias.

Criar um alias de um arquivo PKCS12/PFX (somente keystore)

Para criar um alias 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 mostrar 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 Escolher arquivo ao lado de PKCS12/PFX, navegue até o arquivo 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 quiser, selecione Permitir certificado expirado para ignorar a validação.
8. Selecione Salvar para fazer upload do arquivo e criar o alias.

Como criar um alias de um certificado autoassinado (somente keystore)

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

Para criar um alias de um certificado autoassinado:

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

No certificado gerado, você vai encontrar estes campos adicionais:

• Emissor
  A entidade que assinou e emitiu o certificado. Para um certificado autoassinado, esse é o CN especificado ao criar o certificado.
• Validade
  O período de validade do certificado representado como duas datas: a data em que o período de validade do certificado começa e a data em que ele termina. Ambos podem ser codificados como valores UTCTime ou GeneralizedTime.

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

Testar um keystore ou truststore

Você pode 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 seguinte caixa de diálogo aparece mostrando o nome do truststore:
   
4. Insira o nome do host do serviço de back-end.
5. Digite o número da porta TLS (normalmente 443).
6. Se quiser, especifique protocolos ou algoritmos de criptografia.
7. Selecione Testar.

Para testar o TLS bidirecional:

1. Para o keystore de confiança desejado, selecione o botão Testar.
2. Na caixa de diálogo, selecione Bidirecional para o Tipo de teste SSL. A seguinte caixa de diálogo vai aparecer:
   
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. Se quiser, especifique protocolos ou algoritmos de criptografia.
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 truststore contém um certificado ou uma cadeia de CA para cada cliente autorizado a fazer solicitações para o Edge.

Ao configurar o truststore inicialmente, você pode adicionar todos os certificados dos clientes conhecidos. No entanto, com o tempo, talvez seja necessário adicionar mais certificados ao keystore de confiança à medida que você adiciona 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 Criar um alias de um certificado (somente truststore).

3. Atualize a referência do truststore 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 alias. Se você excluir um keystore, um truststore ou um alias que está sendo usado por um host virtual, um endpoint de destino ou um servidor de destino, todas as chamadas de API pelo host virtual ou 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 no Edge, atualize a configuração do host virtual para referenciar o novo keystore e o alias da 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 faziam referência ao keystore e ao alias de chave antigos para fazer referência ao novo keystore e alias de chave. Se o TargetEndpoint referenciar um TargetServer, atualize a definição do TargetServer para referenciar o novo keystore e o alias da chave.
   2. Se o keystore e o truststore forem referenciados diretamente da definição de TargetEndpoint, reimplante o proxy. Se o TargetEndpoint referenciar uma definição TargetServer, e essa definição referenciar o keystore e o truststore, não será necessário reimplantar o proxy.
4. Confirme se os proxies de API estão funcionando corretamente.
5. Exclua o keystore/truststore ou o alias.

Excluir um keystore

Para excluir um keystore ou truststore, posicione o cursor sobre ele na lista para exibir o menu de ações e clique em . Se você excluir um keystore ou truststore que está sendo usado por um host virtual ou endpoint/servidor de destino, todas as chamadas de API pelo host virtual ou endpoint/servidor de destino vão falhar.

Atenção: não exclua um keystore até converter seus hosts virtuais e endpoints/servidores de destino para usar um novo keystore.

Excluir um alias

Para excluir um alias, posicione o cursor sobre ele na lista para exibir o menu de ações e clique em . Se você excluir um alias que está sendo usado por um host virtual ou endpoint/servidor de destino, todas as chamadas de API pelo host virtual ou endpoint/servidor de destino vão falhar.

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