Como criar keystores e truststore usando a interface do Edge

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Neste documento, descrevemos como criar, modificar e excluir keystores e truststores do Edge para o Cloud e do Edge para a nuvem privada versão 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 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.
  • É 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 do host virtual.

Saiba mais:

Como implementar keystores e truststores no Edge

Para configurar a funcionalidade que depende da infraestrutura de chave pública, como o TLS, é preciso 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 truststore é derivada dos tipos de entradas que eles contêm e de como eles são usados no handshake de TLS:

  • keystore: uma entidade keystore que contém um ou mais aliases, em que cada alias contém um par de certificados/chaves.
  • 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 um endpoint de destino, keystores e truststores fornecem papéis 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>, 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, especifique 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. Assim, será possível alterá-lo mais tarde, quando o certificado expirar. O alias contém um par de certificados/chaves usado para identificar o host virtual para um cliente TLS que acessa o host virtual. Neste exemplo, não é necessário ter 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>

Nesse exemplo, a tag <TrustStore> faz referência apenas a um keystore, ela 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

Formato Compatível com upload de API e interface Suporte para o 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 usar o PEM, se possível.

Sobre a implementação de um alias

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

  • O certificado TLS como um arquivo PEM ou PKCS12/PFX: um certificado assinado por uma autoridade de certificação (CA, na sigla em inglês), 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 é 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 um contém:

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

O Edge fornece uma IU e uma API que você usa para criar keystores, criar aliases, fazer upload de pares de certificados/chaves e atualizar certificados. A IU e a API usadas para criar um truststore são as mesmas que você usa para criar um keystore. A diferença é que, ao criar um truststore, 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 for definido por um arquivo PEM, você pode 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 eles forem arquivos de texto e estiverem 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 você pode usá-los 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, você vai processá-lo de maneira diferente, dependendo se o certificado é usado em um keystore ou em um truststore:

  • Keystore: se um certificado fizer parte de uma cadeia, você precisará criar um único arquivo contendo todos os certificados na cadeia. Os certificados precisam estar em ordem, e o último certificado precisa ser um certificado raiz ou um certificado intermediário assinado por um certificado raiz.
  • Truststore: se um certificado fizer parte de uma cadeia, será necessário criar um único arquivo contendo todos os certificados e fazer upload desse arquivo para um alias ou fazer 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 precisará ser raiz ou intermediário assinado por um certificado raiz.
  • Se você criar um único arquivo que contenha vários certificados, insira uma linha vazia 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 certificado 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 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 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 para o cliente como parte do processo de handshake do 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 é 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 existente no truststore. Se você remover o certificado de AC (ca_cert) do truststore, a verificação de TLS falhará.

Conhecer a página "Keystores TLS"

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

Borda

Para acessar a página "TLS Keystores" 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 TLS.

Borda clássica (nuvem privada)

Para acessar a página "TLS Keystores" 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" vai aparecer:

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

Ver um alias

Para ver um alias:

  1. Acesse a página TLS Keystores.
  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 exibidos.

    Você pode ver 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:
    • 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, na sigla em inglês). Em seguida, envie a CSR para a AC para obter um novo certificado.
    • Atualizar um certificado. Cuidado: se você atualizar um certificado que está sendo usado por um host virtual ou por um endpoint de servidor/destino de destino, entre em contato com o suporte do Apigee Edge para reiniciar os roteadores e processadores de mensagens. Esta é 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/servidor de destino/para o keystore ou o truststore. Consulte Atualizar um certificado TLS para o Cloud para saber mais.
      4. Exclua o alias. Observação: se você excluir um alias e ele estiver sendo usado por um host virtual ou endpoint de destino, o host virtual ou o endpoint de destino 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 de um ambiente na sua organização, como 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, só é preciso especificar o nome do keystore. Depois de criar um keystore nomeado em um ambiente, crie aliases e faça upload de um par de certificados/chaves (keystore) ou faça upload de um somente certificado (truststore) para o alias.

Para criar um keystore:

  1. Acesse a página TLS Keystores.
  2. Selecione o ambiente (geralmente prod ou test).
  3. Clique em + Keystore.
  4. Especifique o nome do keystore. O nome pode conter apenas caracteres alfanuméricos.
  5. Clique em Add Keystore. O novo armazenamento de chaves 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 com base em um certificado:

  1. Acesse a página TLS Keystores.
  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, 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 pular a validação.
  7. Selecione Salvar para fazer upload do certificado e criar o alias.

Criar um alias a partir de um arquivo JAR (somente keystore)

Para criar um alias com base em um arquivo JAR:

  1. Acesse a página TLS Keystores.
  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, acesse 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. Caso a chave não tenha uma senha, deixe o campo em branco.
  7. Por padrão, a API verifica se o certificado não expirou. Se quiser, selecione Permitir certificado expirado para pular a validação.
  8. Selecione Salvar para fazer upload da chave e do certificado e criar o alias.

Como criar um alias com base em um certificado e uma chave (somente keystore)

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

  1. Acesse a página TLS Keystores.
  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. Caso a chave não tenha uma senha, deixe o campo em branco.
  7. Clique em Escolher arquivo ao lado de Arquivo de chave, acesse 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 pular a validação.
  9. Selecione Salvar para fazer upload da chave e do certificado e criar o alias.

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

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

  1. Acesse a página TLS Keystores.
  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 na lista suspensa "Tipo".
  5. Clique em Choose File ao lado de PKCS12/PFX, navegue até o arquivo que contém a chave e o certificado e clique em Open.
  6. Se a chave tiver uma senha, especifique a Senha do 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. Se quiser, selecione Permitir certificado expirado para pular a validação.
  8. Selecione Salvar para fazer o upload do arquivo e criar o alias.

Criar um alias a partir de um certificado autoassinado (somente keystore)

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

Para criar um alias com base em um certificado autoassinado:

  1. Acesse a página TLS Keystores.
  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 certificado e chave privada 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, este é o CN especificado na criação do certificado.
  • Validade
    O período de validade do certificado representado como duas datas: a data em que começa e termina o 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 a 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 O nome comum (CN, na sigla em inglês) da organização identifica os nomes de domínio totalmente qualificados associados ao certificado. Ele é normalmente composto por um host e um nome de domínio. Por exemplo, api.enterprise.apigee.com, www.apigee.com etc. O tamanho máximo é de 64 caracteres.

Dependendo do tipo de certificado, a 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ó será válido 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
Região administrativa 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 Código do país com duas letras. Exemplo: IN para Índia, US 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 da Internet, um nome DNS, um endereço IP e um identificador uniforme de recursos (URI).

Máximo de 255 caracteres para cada valor. É possível separar os nomes por vírgulas ou pressionando a tecla Enter após cada nome.

N/A Não

Testar um keystore ou um truststore

É possível testar o truststore e o keystore na interface do Edge para verificar se 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 a TLS unidirecional ou bidirecional.

Para testar o TLS unidirecional:

  1. Acesse a página TLS Keystores.
  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 Test. A caixa de diálogo a seguir é exibida, 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. É possível especificar protocolos ou criptografias.
  7. Selecione Testar.

Para testar o TLS bidirecional:

  1. Para o truststore desejado, selecione o botão Test.
  2. Na caixa de diálogo, selecione Mão dupla 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. É possível especificar protocolos ou criptografias.
  8. Selecione Testar.

Adicionar um certificado a um truststore para o TLS bidirecional

Ao usar o TLS bidirecional para conexões de entrada, ou seja, uma solicitação de API no Edge, o truststore contém um certificado ou cadeia de AC para cada cliente com permissão para fazer solicitações ao Edge.

Ao configurar inicialmente o truststore, você pode adicionar todos os certificados para os clientes conhecidos. No entanto, com o tempo, talvez você queira adicionar mais 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 a partir de 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 um alias

Tenha cuidado ao excluir um keystore/truststore ou um alias. Se você excluir um keystore, truststore ou alias que estiver sendo usado por um host virtual, endpoint de destino ou servidor de destino, todas 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 um alias é:

  1. Crie um novo keystore/truststore ou um 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 fazer referência ao novo keystore e ao 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 antigo e ao alias da chave para fazer referência ao novo keystore e ao alias da chave. Se o TargetEndpoint se referir a um TargetServer, atualize a definição do TargetServer para fazer referência ao novo keystore e ao 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 se referir a uma definição do TargetServer e ela fizer referência ao keystore e ao 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 alias.

Excluir um keystore

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

Cuidado: não exclua um keystore até converter 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 exibir o menu de ações e clique em . Se você excluir um alias que está sendo usado por um host virtual ou por um endpoint/servidor de destino de destino, todas as chamadas de API por meio do host virtual ou do servidor de endpoint/destino de destino falharão.

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