Esta página foi traduzida pela API Cloud Translation.

Como criar keystores e truststores usando a API Edge Management

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 o Cloud e para o Edge para a nuvem privada versão 4.18.01 e posteriores.

Observação: os exemplos de API abaixo fazem solicitações ao URL da API Edge Management para o Cloud: https://api.enterprise.apigee.com. Para instalações de nuvem privada, substitua esse URL por https://MS_IP:8080, em que MS_IP é o endereço IP do servidor de gerenciamento.

Introdução

Para configurar a funcionalidade que depende da infraestrutura de chave pública, como o TLS, é preciso criar keystores e truststores que forneçam as chaves e os certificados digitais necessários.

Para ver uma introdução a keystores, truststores e aliases, consulte Keystores e Truststores.

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.

Para criar um keystore em um ambiente:

Use a chamada de API nesta seção para criar o keystore.
Crie um alias e faça upload de um par de certificados/chaves para ele. A maneira de fazer upload do certificado e da chave é baseada no formato do par de certificado/chave. As seções a seguir descrevem como fazer upload de cada tipo de par de certificados/chaves:
Observação: recomendamos o uso do formato PEM para chaves e certificados sempre que possível. Para mais informações, consulte Formatos de arquivo de certificado compatíveis.

Para criar um keystore, especifique o nome dele para a API Create a Keystore ou Truststore. O nome do keystore pode conter apenas caracteres alfanuméricos:

curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'

Exemplo de resposta:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

Faça upload de um certificado e uma chave como um arquivo JAR

Primeiro, crie um arquivo JAR com sua 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

Um JAR do keystore pode conter apenas esses três arquivos. Se você tiver uma cadeia de certificados, todos os certificados dela precisarão ser anexados a um único arquivo PEM, em que o último certificado seja assinado por uma CA raiz. Os certificados precisam ser anexados ao arquivo PEM na ordem correta, com uma linha vazia entre cada certificado, o que significa que:

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

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 seu arquivo JAR:

jar -uf myKeystore.jar META-INF/descriptor.properties

Agora é possível fazer upload dos arquivos JAR que contêm um certificado e uma chave privada usando a API Create an alias from a JAR or PKCS file:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

em que a opção -F especifica o caminho para o arquivo JAR.

Nessa chamada, você especifica:

alias_name: 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.
key_pword: 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Exemplo de resposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Fazer upload de um certificado e uma chave como arquivos PEM

Faça upload de arquivos PEM que contenham um certificado e uma chave privada usando a API Criar um alias a partir de arquivos PEM de certificados e chaves:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

em que a opção -F especifica os caminhos para os arquivos PEM.

Nessa chamada, você especifica:

alias_name: 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.
key_pword: 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Exemplo de resposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Faça upload de um certificado e uma chave como um arquivo PKCS12/PFX

Faça upload de um arquivo PKCS12/PFX que contenha um certificado e uma chave privada usando a API Create an alias from a JAR or PKCS file:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

em que a opção -F especifica o caminho para o arquivo P12.

Nessa chamada, você especifica:

alias_name: 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.
key_pword: 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Exemplo de resposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Criar e fazer upload de um certificado e uma chave autoassinados

Use a API Create an alias by generate a autoassinado Certificate da API para criar um certificado e uma chave autoassinados e fazer upload deles para um alias. A chamada a seguir especifica apenas as informações necessárias para criar o certificado autoassinado. Você pode modificar essa chamada para adicionar mais informações:

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

A resposta deve aparecer como:

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

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ê só faz upload de um arquivo de certificado, como um arquivo PEM, para o truststore.

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. Insira uma linha vazia entre cada certificado no arquivo.

Se você quiser fazer upload de vários certificados autoassinados que não fazem parte de uma cadeia, use a mesma técnica: se houver vários certificados em que você quer confiar, faça upload deles em um único 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, 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.

Se preferir, 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 de TLS seja bem-sucedida quando client_cert_2 não existe no truststore, mas foi assinado por um certificado existente no truststore. 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 -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

Depois de criar o truststore, faça upload do certificado como um arquivo PEM no truststore usando a API Criar um alias a partir de um arquivo PEM de certificado:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

em que a opção -F especifica o caminho para o arquivo PEM.

Receber detalhes sobre um keystore ou um truststore existente

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

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

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 as APIs e enviá-las para produção. No entanto, normalmente você cria um keystore próprio, com um certificado e uma chave próprios, antes de implantar 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

A resposta deve aparecer como:

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

Receber detalhes sobre um alias

Acesse uma lista de todos os aliases de um keystore usando a API List aliases:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

A resposta deve aparecer como:

[
  "alias1",
  "alias2",
  "alias3",
]

Para receber todas as informações sobre um alias, como data de validade e emissor, use a API Acessar alias e especifique o nome do alias:

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

A resposta deve aparecer como:

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

Para fazer o download do certificado para um alias, use a API Exportar um certificado para um alias:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

A resposta deve aparecer como:

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

Se você tiver um certificado expirado e quiser renová-lo, faça o download de uma solicitação de assinatura de certificado (CSR, na sigla em inglês). Em seguida, envie a CSR para a AC para obter um novo certificado. Para gerar uma CSR para um alias, use a API Gerar um CSR para um alias:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

A resposta deve aparecer como:

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

Adicionar um certificado a um truststore para TLS bidirecional

Ao usar o TLS bidirecional para conexões de entrada, ou seja, uma solicitação de API no Edge, o truststore contém um certificado ou uma cadeia de CA para cada cliente com permissão para fazer solicitações ao Edge.

Ao configurar inicialmente o truststore, você pode adicionar todos os certificados dos clientes conhecidos. No entanto, com o tempo, talvez você queira adicionar outros certificados ao truststore à medida que adicionar novos clientes.

Para adicionar novos certificados a um truststore usado para TLS bidirecional:

Verifique se você está usando uma referência ao truststore no host virtual.
Faça upload de um novo certificado para o truststore, conforme descrito acima em Criar um truststore.
Atualize a referência do truststore para defini-lo com o mesmo valor. Essa atualização faz com que o Edge recarregue o truststore e o novo certificado.

Consulte Como modificar uma referência para saber mais.

Excluir keystore/truststore ou alias

Tenha cuidado ao excluir um keystore/truststore ou um alias. Se você excluir um keystore, truststore ou alias que está sendo usado por um host virtual, endpoint de destino ou servidor de destino, todas as chamadas de API por meio do host virtual ou do servidor de endpoint/destino de destino falharão.

Normalmente, o processo usado para excluir um keystore/truststore ou um alias é:

Crie um keystore/truststore ou um alias novo, conforme descrito acima.
Para conexões de entrada, ou seja, uma solicitação de API no Edge, atualize a configuração do host virtual para fazer referência ao novo keystore e ao alias da chave.
Para conexões de saída, ou seja, da Apigee para um servidor de back-end:
1. Atualize a configuração do TargetEndpoint para todos os proxies de API que faziam referência ao keystore e ao alias da chave antigos para fazer referência ao novo keystore e ao alias da chave. Se o TargetEndpoint fizer referência a um TargetServer, atualize a definição dele para referenciar o novo keystore e o alias da chave.
2. Se o keystore e o truststore forem referenciados diretamente na definição do TargetEndpoint, será necessário reimplantar o proxy. Se o TargetEndpoint se referir a uma definição de TargetServer e essa definição fizer referência ao keystore e ao truststore, nenhuma reimplantação do proxy será necessária.
3. Confirme se os proxies da API estão funcionando corretamente.
4. Exclua o keystore/truststore ou o alias.

Consulte Atualizar o certificado em um alias para mais informações.

Excluir um keystore ou um truststore

É possível excluir um keystore ou um truststore usando a API Delete a Keystore or Truststore:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName

Se você excluir e recriar um keystore ou um truststore que estiver sendo usado por um host virtual, será necessário reimplantar os proxies de API.

Excluir um alias

É possível excluir um alias em um keystore ou truststore usando a API Excluir alias:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}