Como criar keystores e truststore usando a interface do Edge

Você está visualizando 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 a Edge Cloud

O processo de criação de keystores/truststores para a 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 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:

Implementar keystores e truststores no Edge

Para configurar funcionalidades que dependem da infraestrutura de chave pública, 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 é 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 de 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 endpoint de destino, especifique keystores e truststores separadamente na tag <SSLInfo>, conforme 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 do 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 de certificado/chave usado para identificar o host virtual para um cliente TLS que o acessa. 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 é usada como parte do processo de handshake do TLS.

Formatos de certificado aceitos

Formato Upload de API e interface com suporte Suporte a Northbound 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.

Como usar chaveiros PKCS12 com o Edge para nuvem privada 4.53.00 ou mais recente

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 Converter certificados para o formato aceito.

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 certificadora (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, 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 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 obedecem ao formato X.509. Se o certificado ou a chave privada não for definido por um arquivo PEM, você poderá convertê-lo 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 de texto e estiverem em:

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

ou

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

Em seguida, os arquivos ficam compatíveis com o formato PEM e podem ser usados em um keystore ou truststore sem serem convertidos 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 faz parte de uma cadeia, é necessário criar um único arquivo contendo todos os certificados da cadeia. Os certificados precisam estar em ordem, e o último precisa ser um certificado raiz 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 deles como um único certificado, eles precisarão estar em ordem e o último certificado precisa ser raiz ou 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, 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 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 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 uma loja de certificados, nem sempre é necessário fazer upload de todos os certificados da 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 de TLS seja bem-sucedida quando client_cert_2 não existe no repositório de confiança, mas foi assinado por um certificado que existe no repositório. 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 o FIPS

Se você estiver usando a Edge para nuvem privada 4.53.00 ou mais recente 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"

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

Edge

Para acessar a página "Armazenamentos de chaves TLS" usando a interface do Edge:

  1. Faça login em https://apigee.com/edge como administrador da organização.
  2. Selecione a organização.
  3. Selecione Administrador > Ambiente > Keystores de TLS.

Edge clássico (nuvem privada)

Para acessar a página "Armazenamentos de chaves TLS" usando a interface clássica do Edge:

  1. Faça login em http://ms-ip:9000 como administrador da organização, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione a organização.
  3. Selecione Administrador > Configuração do ambiente > Keystores TLS.

A página "Keystores TLS" é exibida:

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

Conferir 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:
    • Faça o download do certificado como um arquivo PEM.
    • Gere uma CSR. Se você tiver um certificado expirado e quiser renová-lo, faça o download de uma solicitação de assinatura de certificado (CSR). Em seguida, você envia a CSR à sua AC para receber um novo certificado.
    • Atualizar um certificado. Cuidado: se você atualizar um certificado que está sendo usado por um host virtual ou um servidor/endpoint de destino, entre em contato com o suporte da Apigee Edge para reiniciar os roteadores e os 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 no endpoint de destino/servidor de destino para o keystore ou truststore. Para saber mais, consulte Atualizar um certificado TLS para a nuvem.
      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 ou o endpoint de destino vai falhar.

Criar um keystore/truststore e um alias

É possível criar um keystore para uso como keystore ou 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, é 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 truststore)

Para criar um alias a partir de 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 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 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 "Certificate details", selecione JAR File no menu suspenso "Type".
  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 senha, deixe o 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 da chave e do certificado e criar o alias.

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

Para criar um alias a partir de 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 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 preferir, 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 usando um arquivo PKCS12 que contém 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 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 para o 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 o upload do arquivo e criar o alias.

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 o upload deles para o alias.

Para criar um alias usando 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 pública/privada e fazer o upload dele 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, esse é o CN especificado ao criar o certificado.
  • Validade
    O período de validade do certificado representado por duas datas: a data em que o período de validade do certificado começa e a data em que o período de validade do certificado termina. 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 é 2048 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 de validade do certificado, em dias. Aceita valores positivos diferentes de zero. 365 Não
Nome comum O nome comum (CN) da organização identifica os nomes de domínio totalmente qualificados associados ao certificado. Geralmente, é 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 CN pode ser um ou mais nomes de host pertencentes ao mesmo domínio (por exemplo, example.com, www.example.com), um nome curinga (por exemplo, *.example.com) ou uma lista de domínios. Não inclua nenhum protocolo (http:// ou https://), número de porta ou caminho de recurso.

O certificado só é válido se o nome de 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 comprimento máximo é de 64 caracteres. N/A Não
Nome da organização Nome da organização. O comprimento 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 ou província. O tamanho máximo é de 128 caracteres. N/A Não
País Código do país com duas letras. Por exemplo, IN para a Índia e US para os 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 da Internet, um nome de DNS, um endereço IP e um identificador uniforme de recursos (URI).

Máximo de 255 caracteres para cada valor. Você pode separar os nomes por vírgula ou pressionando a tecla Enter depois de cada nome.

 N/A Não

Testar um keystore ou truststore

É possível testar o repositório de chaves e de confiança 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 caixa de diálogo a seguir é 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 o repositório de certificados pela primeira vez, é possível adicionar todos os certificados dos clientes conhecidos. No entanto, com o tempo, talvez você queira adicionar outros certificados ao repositório de certificados à medida que novos clientes forem adicionados.

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 repositório de confiança 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 recarrege o truststore e o novo certificado.

    Consulte Como modificar uma referência para saber mais.

Excluir um keystore/truststore ou alias

Tenha cuidado ao excluir um keystore/truststore ou 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 endpoint de destino/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 repositório de chaves 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 referencia 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 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

Para excluir um keystore ou truststore, posicione o cursor sobre ele na lista para mostrar 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 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 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 está sendo usado por um host virtual ou endpoint/servidor de destino, todas as chamadas de API pelo host virtual ou pelo endpoint/servidor de destino vão falhar.

Atenção: não exclua um alias até que os hosts virtuais e os endpoints/serviços de destino sejam convertidos para usar um novo keystore e alias.