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

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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

Sobre keystores e truststores

Keystores e truststores definem repositórios de certificados de segurança usados para TLS criptografia. A principal diferença entre os dois é o local em que são usados no handshake de TLS processo:

  • Um keystore contém um certificado TLS e uma chave privada usados para identificar o 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 confirma se certificado com uma autoridade de certificação (CA), como Symantec ou VeriSign.

    No TLS bidirecional, tanto o cliente quanto o servidor mantêm um keystore com seu próprio certificado e chave privada usada para autenticação mútua.
  • Um truststore contém certificados usados para verificar os certificados recebidos como 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 AC 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 AC confiável. Nesse cenário, o cliente preenche o truststore com certificados que ele confia. Então, quando o cliente recebe um certificado do servidor, o certificado de entrada é validada em relação aos certificados no truststore.

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

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

Os certificados podem ser emitidos por uma autoridade certificadora (CA, na sigla em inglês) ou autoassinados pela a chave privada que você gera. Se você tiver acesso a uma AC, siga as instruções fornecidas pela sua AC 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.

Implementar um keystore e 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 uma cadeia de certificados em que o último certificado é assinado por uma AC ou um certificado certificado.
  • Chave privada como um arquivo PEM. O Edge oferece suporte a 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 nenhum chaves privadas.

Se o certificado fizer parte de uma cadeia, o keystore/truststore deve conter todos os certificados no cadeia, seja como arquivos PEM individuais ou como um único arquivo. Se você usar um único arquivo, o certificados precisam estar na ordem em que o primeiro certificado no arquivo for o certificado usado para o TLS seguido pela cadeia de certificados, em ordem, para o certificado de CA. Você deve inserir uma linha vazia entre cada certificado no arquivo.

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

Sobre o formato do 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á converter 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 textos e estão 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 podem ser usados em um keystore ou truststore sem convertê-los em um arquivo PEM.

Se você tem uma cadeia de certificados e quer usá-la em um repositório de chaves ou truststore, você pode combinar todos os certificados em um único arquivo PEM com uma nova linha entre cada certificado. A 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-----

Receber detalhes sobre um keystore existente

Verifique se há keystores no seu ambiente usando a ferramenta Listar 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 no ambientes de teste e produção. Você verá os seguintes resultados para esta chamada para ambos ambientes:

[ "freetrial" ]

É possível usar esse keystore padrão para testar suas APIs e enviá-las para produção, mas é normalmente criam seu próprio keystore, com seu certificado e sua chave, antes de implantar na produção.

Para clientes da nuvem privada, a matriz retornada fica vazia até que você crie a primeira um repositório de chaves de acesso.

Verifique o conteúdo do armazenamento de chaves usando o comando Consiga uma API Keystore ou Truststore. Para um cliente da nuvem, você deve ver um TLS de servidor único é 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 será exibida assim:

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

Também é possível ver essas informações na interface de gerenciamento de borda:

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

Acessar detalhes do certificado TLS

Você pode usar o Acessar detalhes do certificado de uma API Keystore ou Truststore para ver detalhes sobre os certificados TLS em do keystore, como data de validade e emissor. Primeiro, consiga o nome do certificado em em que você tem interesse. Este exemplo busca informações para o keystore chamado "teste sem custo financeiro".

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"
}

Depois, use o valor da propriedade "certs" para acessar 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 interface de gerenciamento de borda:

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

Na interface do Edge, você pode especificar com quanto tempo de antecedência o Edge indica que um certificado será expirar. Por padrão, a interface destaca os certificados programados para expirar nos próximos 10 dias.

Criar um keystore

Um keystore é específico para um ambiente na sua organização, como o ambiente de teste ou de produção de nuvem. Portanto, se você quiser testar o keystore em um ambiente de teste antes da implantação para o ambiente de produção, é preciso criá-lo em ambos os 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.

Criar um arquivo JAR contendo seu certificado e sua chave privada

Crie um arquivo JAR com sua chave privada, certificado e um manifesto. O arquivo JAR deve contêm os seguintes arquivos e diretórios:

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

No diretório que contém seu par de chaves e 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 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 no Criar uma API 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 conter um certificado e uma chave privada usando o Faça upload de um arquivo JAR em uma API 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.

Nesta chamada, você especifica dois parâmetros de consulta:

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

Verifique se o upload do keystore está correto:

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 a única diferença é que você passa o arquivo do certificado como um arquivo PEM em vez de JAR.

Se o certificado fizer parte de uma cadeia, faça o upload de todos os certificados nela separadamente. ao 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. Para exemplo: no truststore, você faz upload de um certificado do cliente, client_cert_1, e do certificado do cliente certificado do emissor, 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 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 precisa faça o upload de client_cert_2 no 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, o solicitação for bem-sucedida. Isso ocorre porque o Edge permite que a verificação TLS tenha êxito quando client_cert_2 não existe na truststore, mas foi assinado por um certificado que existe no truststore. Se você remover a CA certificado ca_cert do truststore, a verificação TLS falha.

Crie um truststore vazio no ambiente usando Criar um Keystore ou Truststore, a mesma API que você usa 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 o Faça upload de um certificado para uma API 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

É possível excluir um keystore ou truststore usando o Exclua uma API 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 um truststore que está sendo usado por um host virtual ou um destino endpoint/destino/servidor, todas as chamadas de API por meio do host virtual ou do endpoint/servidor de destino vai falhar...