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

Você está visualizando 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 do 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 é 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 de mão única, 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 à AC para autenticar o certificado. Um cliente TLS normalmente usa um repositório de confiança 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 repositório de certificados de confiança 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. 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. 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 repositório de confiança. 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 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 gratuitas 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. 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ê 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.

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 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. O Os certificados precisam estar em ordem e o último certificado precisa ser um certificado raiz ou um 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 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.

Confira 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 gratuitas.

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:

  1. 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.
  2. No menu da interface de gerenciamento de borda, selecione Administrador > Certificados TLS.

Acessar 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, consiga o nome do certificado em 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=&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 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 interface de gerenciamento de borda, selecione Administrador > Certificados TLS.

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, 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:

  1. Crie um arquivo JAR com o certificado e a chave privada.
  2. 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 deve contêm 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 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.

Nessa 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 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. O 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. 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 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 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 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 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 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 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.