O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Como criar keystores e truststores usando a API Edge Management

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 Cloud e para o Edge para nuvem privada versões 4.18.01 e mais recentes.

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

Introdução

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

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

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, será necessário criá-lo 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 certificado/chave para o alias. A maneira de fazer upload do certificado e chave é baseada no formato do par de certificado/chave. As seções a seguir descrevem como fazer upload de cada tipo de par de certificado/chave:
Observação: recomendamos usar o 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 do keystore na API Criar um keystore ou truststore. O nome do keystore só pode conter 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"
}

Fazer upload de um certificado e uma chave como um arquivo JAR

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

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

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

Agora é possível fazer upload dos arquivos JAR que contêm um certificado e uma chave privada usando a API Criar um alias de um arquivo JAR ou PKCS:

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 o keystore. Ao criar um host virtual, você referencia o certificado e a chave pelo seu nome de alias.
key_pword : 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 -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 de arquivos PEM de certificado e chave:

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 o keystore. Ao criar um host virtual, você referencia o certificado e a chave pelo seu nome de alias.
key_pword : 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 -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 um arquivo PKCS12/PFX file

Faça upload de um arquivo PKCS12/PFX que contenha um certificado e uma chave privada usando a API Criar um alias de um arquivo JAR ou PKCS:

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 o keystore. Ao criar um host virtual, você referencia o certificado e a chave pelo seu nome de alias.
key_pword : 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 -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

É possível usar a API Criar um alias gerando um certificado autoassinado 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. É possível 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 vai 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, será necessário fazer upload de todos os certificados na cadeia separadamente para o truststore ou criar um único arquivo contendo 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ê confia, faça upload deles em um único arquivo.

O certificado final é normalmente 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 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 para o cliente como parte do processo de handshake 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 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 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 para o truststore usando a API Criar um alias 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 truststore existente

Verifique se há keystores no ambiente usando a API Listar keystores e truststores:

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

Para clientes da nuvem, um keystore padrão é fornecido para organizações de teste sem custo financeiro nos ambientes de teste e de produção. Os seguintes resultados vão aparecer para essa chamada para os dois ambientes:

[ "freetrial" ]

É possível usar esse keystore padrão para testar as APIs e enviá-las para a 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 do Private Cloud, a matriz retornada fica 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 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

A resposta vai aparecer como:

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

Receber detalhes sobre um alias

Receba uma lista de todos os aliases de um keystore usando a API Listar 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 vai aparecer como:

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

Para receber todas as informações sobre um alias, como data de validade e emissor, use a API Receber 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 vai 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 de um alias, use a Exportar um certificado para um alias API:

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 vai 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 à CA para receber um novo certificado. Para gerar uma CSR para um alias, use a Gerar uma CSR para um alias API:

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 vai 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 para o Edge, o truststore contém um certificado ou uma cadeia de CA para cada cliente autorizado a fazer solicitações para o Edge.

Ao configurar o truststore inicialmente, é possível adicionar todos os certificados dos clientes conhecidos. No entanto, com o tempo, talvez seja necessário adicionar mais certificados ao truststore à medida que você adiciona 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-la como o mesmo valor. Essa atualização faz com que o Edge recarregue o truststore e o novo certificado.

Consulte Modificar uma referência para mais informações.

Excluir um keystore/truststore ou alias

É necessário ter cuidado ao excluir um keystore/truststore ou 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 pelo host virtual ou endpoint/servidor de destino vão falhar.

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

Crie um novo keystore/truststore ou alias, conforme descrito acima.
Para conexões de entrada, ou seja, uma solicitação de API para o Edge, atualize a configuração do host virtual para referenciar o novo keystore e o alias de 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 referenciaram o keystore e o alias de chave antigos para referenciar o novo keystore e o alias de chave. Se o TargetEndpoint referenciar um TargetServer, atualize a definição do TargetServer para referenciar o novo keystore e o alias de 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 referenciar uma definição do TargetServer e a definição do TargetServer referenciar o keystore e o truststore, não será necessário reimplantar o proxy.
3. Confirme se os proxies de API estão funcionando corretamente.
4. Exclua o keystore/truststore ou alias.

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

Excluir um keystore ou truststore

É possível excluir um keystore ou truststore usando a API Excluir um keystore ou 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 truststore que está sendo usado por um host virtual, então 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}