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

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 a nuvem privada 4.17.09 e anteriores.

Sobre keystores e truststores

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 de 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 CSI ou VeriSign.

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

    No TLS unidirecional, não será 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 geralmente 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 em que confia. 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. Por ser 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 no 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. É necessário ter um truststore ao executar o TLS bidirecional quando o Edge atuar 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 gerada por você. Se você tiver acesso a uma AC, siga as instruções fornecidas por ela para gerar chaves e emitir certificados. Se você não tiver acesso a uma CA, gere um certificado autoassinado usando uma das muitas ferramentas sem custo financeiro disponíveis publicamente, como o openssl.

Como implementar um keystore e um truststore no Edge

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

  • certificado TLS como um arquivo PEM: um certificado assinado por uma autoridade de certificação (CA), uma cadeia de certificados em que o último é assinado por uma CA ou um certificado autoassinado.
  • Chave privada como um arquivo PEM. O Edge oferece suporte a tamanhos de chave de até 2.048 bits. A senha longa é opcional.

Um truststore é semelhante a um keystore, exceto pelo fato de conter apenas certificados como um arquivo PEM, mas sem chaves privadas.

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

O Edge fornece 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ê transmite um arquivo JAR que contém o certificado e a chave privada. Ao criar um truststore, você transmite 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 estiverem definidos em um arquivo PEM, converta-os em um arquivo PEM usando utilitários como o OpenSSL.

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

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

ou

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

Os arquivos serão compatíveis com o formato PEM e poderão ser usados em um keystore ou no 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, 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-----

Receber detalhes sobre um keystore atual

Verifique se há keystores no seu ambiente usando a API List Keystores e Truststores:

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

Para clientes de 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 essa chamada nos dois ambientes:

[ "freetrial" ]

É possível usar esse keystore padrão para testar suas APIs e enviá-las para produção. No entanto, normalmente você cria seu próprio keystore, com seu certificado e chave, antes de implantá-las na produção.

Para clientes de nuvem privada, a matriz retornada está vazia até que você crie o primeiro keystore.

Verifique o conteúdo do keystore usando a API Receber um Keystore ou Truststore. Para um cliente de nuvem, você verá um certificado TLS de servidor único, o certificado padrão que o Apigee Edge oferece 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 estas informações na interface de gerenciamento do Edge:

  1. Faça login na IU de gerenciamento de borda 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 de borda, selecione Administrador > Certificados TLS.

Receber detalhes do certificado TLS

Use a API Get Cert Details from a Keystore ou Truststore para consultar detalhes sobre certificados TLS no keystore, como data de validade e emissor. Primeiro, consiga o nome do certificado em que você tem interesse. 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 obter 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 estas informações na interface de gerenciamento do Edge:

  1. Faça login na IU de gerenciamento de borda 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 interface de gerenciamento de borda, selecione Administrador > Certificados TLS.

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

Criar um keystore

Um keystore é específico de 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, crie-o nos dois ambientes.

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

  1. Crie um arquivo JAR contendo o certificado e a 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 seu 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

Crie o keystore e faça upload do arquivo JAR

Para criar um keystore em um ambiente, basta especificar o nome do keystore para a API Create a Keystore ou 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, faça upload dos arquivos JAR que contenham um certificado e uma chave privada usando a API Fazer upload de um arquivo 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, você especifica 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 upload do keystore foi feito 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ê transmite o arquivo de certificado como um arquivo PEM, em vez de um arquivo JAR.

Se o certificado fizer parte de uma cadeia, faça upload de todos os certificados da cadeia separadamente para o truststore ou crie um único arquivo com todos os certificados. Inclua uma nova linha entre cada certificado no arquivo. O certificado final geralmente é 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 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 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 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 do TLS seja bem-sucedida quando client_cert_2 não existe no truststore, mas foi assinado por um certificado existente nele. Se você remover o certificado de CA, ca_cert, do truststore, a verificação de TLS falhará.

Crie um truststore vazio no ambiente usando Criar um 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 Upload a Certificate to a 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 um truststore

É possível excluir um keystore ou um 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 um 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 do servidor de endpoint/destino de destino falharão.