Este documento descreve como criar, modificar e excluir keystores e truststores do Edge
para a versão 4.17.09 e anteriores da nuvem privada.
Nuvem privada :
Sobre keystores e truststores
Os keystores e truststores definem repositórios de certificados de segurança usados para a 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.
Um truststore contém certificados usados para verificar os certificados recebidos como
parte do handshake de TLS.
Observação :consulte Sobre o TLS/SSL para conferir diagramas que mostram o
uso de keystores e truststores na troca de chaves TLS.Os certificados podem ser emitidos por uma autoridade certificadora (AC) ou autoassinados pela
chave privada gerada. 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 AC, 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 certificadora
(CA), 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 oferece suporte a chaves de até 2.048 bits. Uma frase de acesso é
opcional.
Um repositório de confiança é semelhante a um keystore, exceto por conter apenas certificados como um arquivo PEM, mas sem
chaves privadas.
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 precisam estar em ordem, em que o primeiro certificado no arquivo é o usado para TLS, seguido
pela cadeia de certificados, em ordem, até o certificado de AC. É preciso 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ê transmite um arquivo JAR que contém o
certificado e a chave privada. Ao criar um repositório de chaves de confiança, você transmite apenas o certificado como um arquivo PEM.
Os exemplos neste documento mostram o certificado e a chave TLS definidos como arquivos PEM, que 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 o 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.
Se você tiver uma cadeia de certificados e quiser usá-la em um keystore ou truststore,
combine 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
Verifique se há keystores no seu 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 do Cloud, um keystore padrão é fornecido para organizações de teste sem custo financeiro nos ambientes de teste e de produção. Você vai encontrar os seguintes resultados para essa chamada em ambos
os ambientes:
[ "freetrial" ]
É possível usar esse keystore padrão para testar as APIs e enviá-las para produção, mas normalmente você
cria seu próprio keystore, com seu próprio certificado e chave, antes de implantar na produção.
Para clientes de 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 de nuvem, você vai encontrar 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:password
A resposta vai aparecer assim:
{
"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 Administrador > Certificados TLS .
Conferir os detalhes do certificado TLS
É possível usar a API
Get Cert Details from a Keystore or Truststore para conferir detalhes sobre certificados TLS no
keystore, como data de validade e emissor. Primeiro, obtenha o nome do certificado em que você tem interesse. Este exemplo extrai informações do 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 conferir 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 IU de gerenciamento do Edge, selecione Administrador > Certificados TLS .
Na interface do Edge, você pode 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
Observação :um keystore só pode conter um único par de certificado/chave. Não
faça upload de mais de um par de certificado/chave para o keystore.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.
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.
Crie um arquivo JAR
que contenha o certificado e a chave privada.
Crie um arquivo JAR com sua chave privada, 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
Crie o keystore e faça o upload do
arquivo JAR.
Para criar um keystore em um ambiente, basta especificar o nome do keystore para a API Criar um 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, é possível fazer upload de arquivos JAR que
contêm um certificado e uma chave privada usando a API
Fazer upload de um arquivo JAR para um 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 keystore. 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 uma 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 repositório de confiança
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 JAR.
Observação :é necessário criar um repositório de confiança no Edge como parte da configuração
do TLS bidirecional entre um cliente TLS e o Edge, em que o Edge atua como servidor TLS. Ao configurar
a loja de certificados de confiança no Edge, faça upload do certificado que você recebeu do cliente. Durante o handshake
de TLS, o Edge usa o certificado no truststore para validar o certificado que ele recebe do
cliente. Se o certificado fizer parte de uma cadeia, faça o upload de todos os certificados da cadeia separadamente
para o repositório de confiança ou crie um único arquivo contendo todos os certificados. Inclua uma nova linha entre
cada certificado no arquivo. O certificado final geralmente é assinado pelo emissor do certificado. Por
exemplo, na 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 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 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 nele. Se você remover o certificado
da AC, ca_cert, do
repositório de confiança, a verificação de TLS vai 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 para o repositório de certificados usando a API
Fazer upload de um certificado para um repositório de certificados :
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
É possível excluir um keystore ou truststore usando a API
Excluir um keystore ou 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 um endpoint/alvo/servidor de destino, todas as chamadas de API pelo host virtual ou pelo endpoint/servidor de destino vão falhar.
