Criar keystores e truststores para a nuvem privada na versão 4.17.09 e anteriores

Você está vendo a documentação do Apigee Edge.
Consulte a documentação do Apigee X.

Neste documento, descrevemos como criar, modificar e excluir keystores e truststores do Edge para a nuvem privada versão 4.17.09 e anteriores.

Sobre keystores e truststores

Os keystores e truststores definem repositórios de certificados de segurança usados para criptografia TLS. A principal diferença entre os dois é onde eles são usados no processo de handshake do TLS:

  • Um keystore contém um certificado TLS e uma chave privada usados para identificar a entidade durante o handshake do TLS.

    No TLS unidirecional, quando um cliente se conecta ao endpoint TLS no servidor, o keystore do servidor apresenta o certificado do servidor (certificado público) ao cliente. Em seguida, o cliente valida esse certificado com uma autoridade de certificação (CA, na sigla em inglês), como a Symantec ou a VeriSign.

    No TLS bidirecional, o cliente e o servidor mantêm um keystore com o próprio certificado e a chave privada usada para a autenticação mútua.
  • Um truststore contém certificados usados para verificar os certificados recebidos como parte do handshake de TLS.

    No TLS unidirecional, não é necessário um truststore se o certificado for assinado por uma CA válida. Se o certificado recebido por um cliente TLS for assinado por uma CA válida, o cliente fará uma solicitação à CA para autenticar o certificado. Um cliente TLS normalmente usa um truststore para validar certificados autoassinados recebidos do servidor TLS ou certificados que não são assinados por uma CA confiável. Nesse cenário, o cliente preenche o truststore com certificados confiáveis. Em seguida, quando o cliente recebe um certificado do servidor, o certificado recebido é validado em relação aos certificados no truststore.

    Por exemplo, um cliente TLS se conecta a um servidor TLS em que o servidor usa um certificado autoassinado. Como é um certificado autoassinado, o cliente não pode validá-lo com uma CA. Em vez disso, o cliente pré-carrega o certificado autoassinado do servidor em seu truststore. Em seguida, quando o cliente tenta se conectar ao servidor, ele usa o truststore para validar o certificado recebido do servidor.

    Para o TLS bidirecional, o cliente TLS e o servidor TLS podem usar um truststore. Um truststore é necessário ao executar o TLS bidirecional quando o Edge atua como o servidor TLS.

Os certificados podem ser emitidos por uma autoridade de certificação (CA, na sigla em inglês) ou podem ser autoassinados pela chave privada que você gera. Se você tiver acesso a uma CA, siga as instruções fornecidas por ela para gerar chaves e emitir certificados. Se você não tiver acesso a uma CA, poderá gerar um certificado autoassinado usando uma das muitas ferramentas sem custo financeiro disponíveis publicamente, como openssl.

Como implementar um keystore e um truststore no Edge

No Edge, um keystore contém um ou mais arquivos JAR, em que o arquivo JAR contém:

  • Certificado TLS como um arquivo PEM: um certificado assinado por uma autoridade de certificação (CA, na sigla em inglês), uma cadeia de certificados em que o último certificado é assinado por uma CA ou um certificado autoassinado.
  • Chave privada como um arquivo PEM. O Edge é compatível com tamanhos de chave de até 2.048 bits. Uma senha longa é opcional.

Um truststore é semelhante a um keystore, mas contém apenas certificados como um arquivo PEM, mas nenhuma chave privada.

Se o certificado fizer parte de uma cadeia, o keystore/truststore precisará conter todos os certificados da cadeia, como arquivos PEM individuais ou como um único arquivo. Se você usar um único arquivo, os certificados precisarão estar na ordem em que o primeiro certificado no arquivo é o certificado usado para TLS, seguido pela cadeia de certificados, na ordem, para o certificado da CA. É necessário inserir uma linha vazia entre cada certificado no arquivo.

O Edge oferece uma API que você usa para criar keystores e truststores. As APIs reais são as mesmas. A diferença é que, ao criar um keystore, você passa um arquivo JAR que contém o certificado e a chave privada. Ao criar um truststore, você passa apenas o certificado como um arquivo PEM.

Sobre o formato dos arquivos de certificado e chave

Os exemplos neste documento mostram o certificado TLS e a chave definidos como arquivos PEM, que 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ê 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 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.

Se você tiver uma cadeia de certificados e quiser usá-la em um keystore ou truststore, poderá combinar todos os certificados em um único arquivo PEM com uma nova linha entre cada certificado. Os certificados precisam estar em ordem, sendo que 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-----

Ver detalhes sobre um keystore existente

Verifique se há algum keystore no ambiente usando a API List Keystores and Truststores:

curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

Para clientes da nuvem, um keystore padrão é fornecido para organizações de teste sem custo financeiro nos ambientes de teste e produção. Você verá os seguintes resultados para esta chamada para os dois ambientes:

[ "freetrial" ]

É possível usar esse repositório de chaves padrão para testar suas APIs e enviá-las para produção, mas normalmente você cria o próprio armazenamento de chaves, com certificado e chave próprios, antes de implantá-lo na produção.

Para clientes da nuvem privada, a matriz retornada fica vazia até que você crie seu primeiro keystore.

Verifique o conteúdo do keystore usando a API Get a Keystore or Truststore. Para clientes da nuvem, você verá um certificado TLS de servidor único, que é o certificado padrão fornecido pelo Apigee Edge para contas de avaliação sem custo financeiro.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

A resposta deve aparecer como:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Também é possível ver essas informações na IU de gerenciamento do Edge:

  1. Faça login na IU de gerenciamento do Edge em https://enterprise.apigee.com (nuvem) ou http://<ms-ip>:9000 (local), em que <ms-ip> é o endereço IP do nó do servidor de gerenciamento.
  2. No menu da IU de gerenciamento do Edge, selecione Admin > Certificados TLS.

Acessar detalhes do certificado TLS

Você pode usar a API Get Cert Details from a Keystore or Truststore para ver detalhes sobre certificados TLS no keystore, como data de validade e emissor. Primeiro, consiga o nome do certificado em que você está interessado. Este exemplo busca informações para o keystore chamado "freetrial".

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

Exemplo de resposta:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Em seguida, use o valor da propriedade "certs" para ver os detalhes do certificado:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password

Exemplo de resposta:

{
 "certInfo" : [ {
   "expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
   "isValid" : "Yes",
   "issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O=&quot;GoDaddy.com, Inc.&quot;, L=Scottsdale, ST=Arizona, C=US",
   "subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
   "subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
   "validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
   "version" : 3
 } ],
 "name" : "example.apigee.net.crt"
}

Também é possível ver essas informações na IU de gerenciamento do Edge:

  1. Faça login na IU de gerenciamento do Edge em https://enterprise.apigee.com (nuvem) ou http://<ms-ip>:9000 (local), em que <ms-ip> é o endereço IP do nó do servidor de gerenciamento.
  2. No menu da IU de gerenciamento do Edge, selecione Admin > Certificados TLS.

Na IU do Edge, é possível especificar com que antecedência o Edge indica que um certificado expirará. Por padrão, a IU destaca todos os certificados programados para expirar nos próximos 10 dias.

Criar um keystore

Um keystore é específico para um ambiente na sua organização, por exemplo, o ambiente 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, será necessário criá-lo nos dois ambientes.

A criação de um keystore é um processo de duas etapas:

  1. Crie um arquivo JAR que contenha seu certificado e sua chave privada.
  2. Crie o keystore e faça upload do arquivo JAR.

Crie um arquivo JAR contendo o certificado e a chave privada

Crie um arquivo JAR com a chave privada, o certificado e um manifesto. O arquivo JAR precisa conter os seguintes arquivos e diretórios:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

No diretório que contém o par de chaves e o certificado, crie um diretório chamado /META-INF. Em seguida, crie um arquivo chamado descriptor.properties em /META-INF com o seguinte conteúdo:

certFile={myCertificate}.pem
keyFile={myKey}.pem

Gere o arquivo JAR que contém o par de chaves e o certificado:

jar -cf myKeystore.jar myCert.pem myKey.pem

Adicione descriptor.properties ao arquivo JAR:

jar -uf myKeystore.jar META-INF/descriptor.properties

Criar o keystore e fazer upload do arquivo JAR

Para criar um keystore em um ambiente, basta especificar o nome dele para a API Create a Keystore or Truststore. O nome só pode conter caracteres alfanuméricos:

curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password

Exemplo de resposta:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystore"
}

Depois de criar um keystore nomeado em um ambiente, você pode fazer upload dos arquivos JAR que contêm um certificado e uma chave privada usando a API Upload a JAR para uma keystore:

curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password

em que a opção -F especifica o caminho para o arquivo JAR.

Nessa chamada, especifique dois parâmetros de consulta:

  • alias: identifica o certificado e a chave no armazenamento de chaves. Ao criar um host virtual, você faz referência ao certificado e à chave pelo nome do alias.
  • password: a senha da chave privada. Omita esse parâmetro se a chave privada não tiver senha.

Verifique se o armazenamento de chaves foi enviado corretamente:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password

Exemplo de resposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Criar um truststore

As APIs usadas para criar um truststore são as mesmas usadas para criar um keystore. A única diferença é que você passa o arquivo cert como um arquivo PEM em vez de um arquivo JAR.

Se o certificado fizer parte de uma cadeia, você precisará fazer upload de todos os certificados na cadeia separadamente para o truststore ou criar um único arquivo contendo todos os certificados. Inclua uma nova linha entre cada certificado no arquivo. O certificado final normalmente é assinado pelo emissor do certificado. Por exemplo, no truststore, 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 bidirecional do TLS, a autenticação do cliente é bem-sucedida quando o servidor envia client_cert_1 ao 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 client_cert_1 e ca_cert.

Quando o servidor passa client_cert_2 como parte do handshake do 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 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 TLS falhará.

Crie um truststore vazio no ambiente usando Create a Keystore ou Truststore, a mesma API usada para criar um keystore:

curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

Faça upload do certificado como um arquivo PEM no truststore usando a API Fazer upload de um certificado para um Truststore:

curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password

em que a opção -F especifica o caminho para o arquivo PEM.

Excluir um keystore ou truststore

Você pode excluir um keystore ou truststore usando a API Delete a Keystore or Truststore:

curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password

Exemplo de resposta:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystoreName"
}

Se você excluir um keystore ou truststore que está sendo usado por um host virtual ou endpoint/destino/servidor de destino, todas as chamadas de API por meio do host virtual ou endpoint de destino/servidor de destino falharão.