Como criar keystores e truststore usando a interface do Edge

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Este documento descreve como criar, modificar e excluir keystores e truststores para o Edge para o Cloud e o Edge para as versões de nuvem privada 4.18.01 e posteriores.

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 TLS.
• Os hosts virtuais só podem usar a porta 443.
• É necessário usar um certificado TLS assinado. Certificados não assinados não podem ser usados com hosts virtuais no Cloud.
• 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 TLS com o Edge
• Perguntas frequentes sobre como configurar 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 na implementação entre um keystore e um truststore no Edge.

A diferença entre keystores e truststore é derivada dos tipos de entradas que eles contêm e como são usados no handshake de TLS:

• keystore: uma entidade keystore que contém uma 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, keystores e truststores oferecem diferentes no processo de handshake de TLS. Ao configurar um host virtual ou um 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. Use uma referência para especificar o nome do keystore e mudá-lo 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 há truststore obrigatórios.

Se um truststore for necessário, por exemplo, para uma configuração TLS bidirecional, use o 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 especificar um alias específico. Cada alias no keystore contém um certificado, ou cadeia de certificados, que é usado como parte do processo de handshake do TLS.

Formatos de certificado compatíveis

Formato	Suporte para upload de interface e API	Compatível com sentido norte	Validado
PEM	Sim	Sim	Sim
* PKCS12	Sim	Sim	Sim Observação: a Apigee converte internamente PKCS12 em PEM.
* DER	Não	Não	Sim
* PKCS7	Não	Não	Não

* Recomendamos o uso de PEM se possí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 um certificado de certificado (CA), um arquivo que contém uma cadeia de certificados em que o último é assinado por uma AC ou um certificado autoassinado.
• Chave privada como um arquivo PEM ou PKCS12/PFX. O Edge oferece suporte a tamanhos de chave de até 2.048 bits. Um a senha longa é opcional.

No Edge, um 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 fornece uma interface e uma API que você usa para criar keystores, criar aliases, fazer upload de certificado/chave e atualizar certificados. A interface e a API usadas para criar um truststore são as mesmas que você usar para criar um keystore. A diferença é que, ao criar um truststore, você cria aliases que contêm apenas um certificado.

Sobre o formato do certificado e da chave arquivos

Você pode representar certificados e chaves como arquivos PEM ou como arquivos 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, 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 fizer parte de uma cadeia, ele será tratado de maneira diferente dependendo se ele for usado ou não em uma 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 fizer parte de uma cadeia, você precisará criar um único arquivo. que contêm todos os certificados e fazer upload desse arquivo para um alias ou fazer upload de todos os certificados na 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 que contenha 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 no e o último certificado precisa ser um certificado raiz ou intermediário assinado por uma raiz certificado:

-----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 o upload de um certificado do cliente, client_cert_1, e ao 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 truststore. O truststore ainda contém apenas client_cert_1 e ca_cert.

Quando o servidor passa client_cert_2 como parte do handshake de TLS, a solicitação funciona. 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 remova o certificado de CA (ca_cert) do truststore e, em seguida, a verificação TLS falhar.

Acesse a página "Keystores TLS"

Acesse a página "Keystores do TLS", conforme descrito abaixo.

A página "Keystores TLS" é exibida:

Como 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 de alias são exibidos.
   
   É possível ver todas as informações sobre o alias, inclusive a data de validade.

4. Gerencie o certificado usando os botões na parte superior da página para:
   • 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 à CA para receber uma nova 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 servidor de destino/endpoint de destino ao servidor o keystore ou o 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 endpoint de destino vai falhar.

Criar um keystore/truststore e um alias

É possível criar um keystore para usar como um keystore TLS ou um truststore de TLS. Um keystore é específico para um ambiente na sua organização, como de teste ou 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, você poderá criar aliases e fazer upload de um par de certificado/chave (keystore) ou faça upload de um só 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 com base em um certificado (somente truststore)
   • Como criar um alias a partir de um JAR arquivo (somente keystore)
   • Criar um alias com base em um certificado (somente keystore)
   • Criar um alias com um arquivo PKCS12/PFX (somente keystore)
   • Criar um alias de um certificado autoassinado (somente keystore)

Como criar um alias com base em um certificado (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. É possível selecionar Permitir certificado expirado para pular a validação.
7. Selecione Salvar para fazer upload do certificado e criar o alias.

Como criar um alias a partir de 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 com base em um certificado e key (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 Choose File ao lado de Certificate File, acesse o arquivo PEM que contém o certificado e clique em Open.
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 para o arquivo PKCS12/PFX. se a chave não tiver senha, deixe este 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 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 autoassinado 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ê verá 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:

Campo do formulário	Descrição	Padrão	Obrigatório
Nome do alias	Nome do alias. O tamanho máximo é de 128 caracteres.	N/A	Sim
Tamanho da chave	Tamanho da chave, em bits. O valor padrão e máximo é de 2.048 bits.	2048	Não
Algoritmo de assinatura	Algoritmo de assinatura para gerar chave privada. Os valores válidos são "SHA512withRSA", "SHA384withRSA" e "SHA256withRSA" (padrão).	SHA256withRSA	Não
Validade do certificado em dias	Duração da validade do certificado, em dias. Aceita valor positivo diferente de zero.	365	Não
Nome comum	Nome comum (CN, na sigla em inglês) da organização identifica os nomes de domínio totalmente qualificados associadas ao certificado. Normalmente, ele é composto por um host e um nome de domínio. Por exemplo, api.enterprise.apigee.com, www.apigee.com etc. O comprimento máximo é de 64 caracteres. Dependendo do tipo de certificado, o O CN pode ser um ou mais nomes de host pertencentes ao mesmo domínio (por exemplo, example.com, www.exemplo.com), um nome curinga (por exemplo, *.exemplo.com) ou uma lista de domínios. Não incluir qualquer protocolo (http:// ou https://), número de porta ou caminho de recurso. O certificado será válido somente se o nome do host da solicitação corresponder a pelo menos um dos nomes comuns do certificado.	N/A	Sim
E-mail	Endereço de e-mail. O tamanho máximo é de 255 caracteres.	N/A	Não
Nome da unidade organizacional	Nome da equipe da organização. O tamanho máximo é de 64 caracteres.	N/A	Não
Nome da organização	Nome da organização O tamanho máximo é de 64 caracteres.	N/A	Não
Localidade	Nome da cidade. O tamanho máximo é de 128 caracteres.	N/A	Não
Estado/Província	Nome do estado/província. O tamanho máximo é de 128 caracteres.	N/A	Não
País	O código do país com duas letras. Por exemplo, IN para a Índia, EUA para Estados Unidos da América.	N/A	Não
Nomes alternativos	Lista de nomes de host alternativos. Permite que outras identidades sejam vinculadas ao assunto do certificado. As opções definidas incluem um endereço de e-mail eletrônico na Internet, um endereço um endereço IP e um URI (identificador uniforme de recursos). Máximo de 255 caracteres para cada valor. Você pode separar os nomes por vírgula ou pressionando a tecla Enter após cada nome.	N/A	Não

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 podem ser configurados para oferecer suporte a 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. Caixa de diálogo a seguir aparece uma caixa 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 (geralmente 443).
6. Também é possível especificar protocolos ou criptografias.
7. Selecione Testar.

Para testar o TLS bidirecional:

1. Para o truststore desejado, selecione o botão Testar.
2. Na caixa de diálogo, selecione Mão dupla para o Tipo de teste SSL. 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 (geralmente 443).
7. Também é possível especificar protocolos ou criptografias.
8. Selecione Testar.

Adicionar um certificado a um truststore para TLS bidirecional

Ao usar 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 com permissão para fazer solicitações ao 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 truststore 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 com base em um certificado (somente truststore).

3. Atualize a referência do truststore para defini-la com 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, o truststore ou alias usado por um host virtual, endpoint ou servidor de destino, todos As chamadas de API por meio do host virtual ou do endpoint/servidor de destino 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. Em conexões de saída, que significam 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 antigo keystore e o alias da chave para fazer referência ao novo keystore e o alias da 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 do TargetEndpoint reimplante o proxy. Se o TargetEndpoint fizer referência a um a definição de TargetServer e a definição de TargetServer referenciam o keystore e truststore, nenhuma reimplantação do proxy será necessária.
4. Confirme se os proxies da API estão funcionando corretamente.
5. Exclua o keystore/truststore ou o alias.

Excluir um keystore

Você pode 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 usados por um host virtual ou endpoint/servidor de destino, todas as chamadas de API por meio do host virtual ou o endpoint/servidor de destino vai falhar.

Cuidado: não exclua um keystore até ter convertido seu hosts virtuais e endpoints/servidores de destino para usar um novo keystore.

Excluir um alias

É possível excluir um alias posicionando seu cursor sobre o alias na lista para exibir as ações e clicando 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.

Cuidado: não exclua um alias antes de converter seus arquivos hosts e endpoints de destino/servidores de destino para usar um novo repositório de chaves e alias.