Você está lendo 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 versão 4.17.09 e anteriores da nuvem privada.
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 de 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), 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 usados para autenticação mútua. - Um truststore contém certificados usados para verificar os certificados recebidos como
parte do handshake de TLS.
No TLS unidirecional, um truststore não é necessário 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 em que confia. Em seguida, quando o cliente recebe um certificado de 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 certificado. 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 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 e o servidor TLS podem usar um truststore. Um truststore é necessário ao realizar o TLS bidirecional quando o Edge atua como o servidor TLS.
Os certificados podem ser emitidos por uma autoridade de certificação (CA) ou autoassinados pela chave privada gerada. Se você tiver acesso a uma CA, siga as instruções fornecidas por sua CA 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 o openssl.
Implementação de um keystore e truststore no Edge
No Edge, um keystore contém um ou mais arquivos JAR, em que o arquivo JAR contém um:
- Certificado TLS como um arquivo PEM: um certificado assinado por uma autoridade de certificação (CA), uma cadeia de certificados em que o último certificado é assinado por uma CA ou um certificado autoassinado cert.
- Chave privada como um arquivo PEM. O Edge oferece suporte a tamanhos de chave de até 2048 bits. Uma senha longa é opcional.
Um truststore é semelhante a um keystore, exceto que ele contém apenas certificados como um arquivo PEM, mas não chaves privadas.
Se o certificado fizer parte de uma cadeia, o keystore/truststore precisará conter todos os certificados na cadeia, como arquivos PEM individuais ou como um único arquivo. Se você usar um único arquivo, então os certificados precisarão estar em ordem, em que o primeiro certificado no arquivo é o certificado usado para TLS, seguido pela cadeia de certificados, em ordem, até o 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 e a chave TLS 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 por um arquivo PEM, você poderá convertê -los 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 arquivos de texto arquivos e estiverem incluídos em:
-----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 truststore sem serem convertidos em um arquivo PEM.
Se você tiver uma cadeia de certificados e quiser usá-la em um keystore ou truststore, então você pode 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 certificado precisa ser um certificado raiz ou um certificado 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 seu ambiente em busca de keystores atuais usando a List Keystores e Truststores API:
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 essa chamada em ambos os ambientes:
[ "freetrial" ]
É possível usar esse keystore padrão para testar suas APIs e enviá-las para produção, mas normalmente você cria seu próprio keystore, com seu próprio certificado e chave, antes de fazer a implantação 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 um cliente da nuvem, você verá um único certificado TLS do servidor , o certificado padrão que o Apigee Edge fornece para contas de teste sem custo financeiro.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:passwordA resposta vai aparecer como:
{ "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" }
Também é possível conferir essas informações na interface de gerenciamento do Edge:
- Faça login na interface 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. - No menu da interface de gerenciamento do Edge, selecione Admin > TLS Certificates.
Receber detalhes do certificado TLS
É possível usar a API Get Cert Details from a Keystore or Truststore para conferir detalhes sobre certificados TLS em o keystore, como data de validade e emissor. Primeiro, receba 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:passwordExemplo de resposta:
{ "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" }
Em seguida, use o valor da propriedade certs para receber 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="GoDaddy.com, Inc.", 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 conferir essas informações na interface de gerenciamento do Edge:
- Faça login na interface 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. - No menu da interface de gerenciamento do Edge, selecione Admin > TLS Certificates.
Na interface 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 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 implantar no ambiente de produção, será necessário criá-lo em ambos os ambientes.
A criação de um keystore é um processo de duas etapas:
- Crie um arquivo JAR que contenha o certificado e a chave privada.
- Crie o keystore e faça upload do arquivo JAR.
Criar um arquivo JAR que contenha 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 do keystore para a Create a Keystore or Truststore API. 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, é possível fazer upload dos arquivos JAR que contêm um certificado e uma chave privada usando a Upload a JAR file to a Keystore API:
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 keystore. Ao criar um host virtual, você referencia o certificado e a chave pelo nome do alias.password: a senha da chave privada. Omitir esse parâmetro se a chave privada não tiver senha.
Verifique se o keystore 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ê transmite o arquivo de certificado como um arquivo PEM em vez de um arquivo JAR.
Se o certificado fizer parte de uma cadeia, será necessário 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 de cliente, client_cert_1, e do certificado do emissor do certificado de 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 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 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 da CA
, ca_cert, do
truststore, a verificação TLS falhará.
Crie um truststore vazio no ambiente usando Create a Keystore or 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 para o 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 -F opção especifica
o caminho para o arquivo PEM.
Excluir um keystore ou truststore
É possível 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 pelo host virtual ou endpoint/destino/servidor de destino vão falhar.