Esta página foi traduzida pela API Cloud Translation.

Como criar keystores e truststores usando a API Edge Management

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

Observação: os exemplos de API abaixo fazem solicitações ao URL do API Edge Management para a nuvem: 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 funcionalidades que dependem da infraestrutura de chave pública, como o TLS, você precisa: criar keystores e truststores que forneçam as chaves e os certificados digitais necessários.

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

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.

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 ele. Forma de upload do certificado e chave é baseada no formato do par certificado/chave. As seções a seguir descrevem como fazer o upload 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 para o menu Criar um Keystore ou Truststore. O nome do repositório de chaves 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"
}

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

Primeiro, crie um arquivo JAR com sua chave privada, certificado e um manifesto. O JAR deve 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 eles da cadeia precisam ser anexados a um único arquivo PEM, em que o último certificado precisa ser assinado por uma AC raiz. Os certificados devem 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 seu par de chaves e certificado, crie um diretório chamado /META-INF: Depois, crie um arquivo chamado Descriptor.properties em /META-INF com o conteúdo a seguir:

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

Adicionar descriptor.properties a seu arquivo JAR:

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

Agora você pode carregar seus arquivos JAR que contêm um certificado e uma chave privada usando o Crie um alias com base em uma API de 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 em repositório de chaves. Ao criar um host virtual, você faz referência ao certificado e à chave pela alias exclusivo.
key_pword: a senha da chave privada. Omitir esse parâmetro se a chave privada não tiver senha.

Verifique se o upload do keystore está correto:

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 de uma chave como arquivos PEM

Faça upload de arquivos PEM que contenham um certificado e uma chave privada usando o Crie um alias com base na API do certificado e dos principais arquivos PEM:

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 em repositório de chaves. Ao criar um host virtual, você faz referência ao certificado e à chave pela alias exclusivo.
key_pword: a senha da chave privada. Omitir esse parâmetro se a chave privada não tiver senha.

Verifique se o upload do keystore está correto:

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 PKCS12/PFX arquivo

Faça upload de um arquivo PKCS12/PFX que contenha um certificado e uma chave privada usando o Crie um alias com base em uma API de 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 em repositório de chaves. Ao criar um host virtual, você faz referência ao certificado e à chave pela alias exclusivo.
key_pword: a senha da chave privada. Omitir esse parâmetro se a chave privada não tiver senha.

Verifique se o upload do keystore está correto:

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

Crie e faça upload de um certificado autoassinado chave

Você pode usar o Gere um alias gerando uma API de certificado autoassinado para gerar um certificado autoassinado e e fazer o upload delas para um alias. A chamada a seguir especifica apenas as informações necessárias para crie 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 será exibida assim:

{
  "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 A única diferença é que você só carrega um arquivo de certificado, como um arquivo PEM, no truststore.

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. Você deve inserir um valor entre cada certificado no arquivo.

Se você quiser fazer upload de vários certificados autoassinados que não fazem parte de uma cadeia, use o método mesma técnica: se houver vários certificados em que você quer confiar, faça upload deles em um único arquivo.

O certificado final normalmente é assinado pelo emissor do certificado. Por exemplo, na truststore, faz upload de um certificado do cliente,client_cert_1, e do certificado certificado, 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 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 truststore. O truststore ainda contém client_cert_1 e ca_cert.

Quando o servidor passa client_cert_2 como parte do handshake de TLS, a solicitação é bem-sucedida. Isso é porque o Edge permite a verificação TLS quando o client_cert_2 não existe no 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 falhará.

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

Obter detalhes sobre um existente keystore ou truststore

Verifique se há keystores no seu ambiente usando a ferramenta Listar keystores and 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 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 no a 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

A resposta será exibida assim:

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

Receber detalhes sobre um alias

Receba uma lista de todos os aliases de um armazenamento de chaves usando o método List aliases da API:

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

A resposta será exibida assim:

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

Para obter todas as informações sobre um alias, como data de validade e emissor, use o Get 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 será exibida assim:

{
  "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 o Exporte um certificado para uma API de 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 será exibida assim:

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

Se você tiver um certificado expirado e quiser renová-lo, poderá fazer o download de um certificado solicitação (CSR). Em seguida, envie a CSR à sua AC para receber um novo certificado. Para gerar uma CSR para um alias, use o Gere uma CSR para uma API de 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 será exibida assim:

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

Adicionar um certificado a um truststore para TLS bidirecional

Ao usar 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 com permissão para fazer solicitações ao Edge.

Ao configurar inicialmente o truststore, é possível 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 Crie um truststore.
Atualize a referência do truststore para defini-la 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 mais informações.

Excluir um keystore/truststore ou alias

Tenha cuidado ao excluir um keystore/truststore ou um alias. Se você excluir um keystore, o truststore ou alias usado por um host virtual, endpoint ou servidor de destino, todos As chamadas de API por meio do host virtual ou do endpoint/servidor de destino 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 de host virtual para fazer referência ao novo keystore e o alias de chave.
Em conexões de saída, que significam 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 antigo keystore e o alias da chave para fazer referência ao novo keystore e o alias da chave. Se o TargetEndpoint faz referência a um TargetServer, atualize a definição de TargetServer para fazer referência ao novo keystore e alias da chave.
2. Se o keystore e o truststore forem referenciados diretamente do TargetEndpoint reimplante o proxy. Se o TargetEndpoint fizer referência a um a definição de TargetServer e a definição de TargetServer referenciam o keystore e 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 Atualize o certificado em um alias para saber mais.

Excluir um keystore ou truststore

É possível excluir um keystore ou truststore usando o Exclua uma API 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 usado por um host virtual, reimplante os proxies de API.

Excluir um alias

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

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