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 do 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 fornecem 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, 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 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 dela precisarão ser anexados em um único arquivo PEM, em que o último certificado precisa ser assinado por uma AC 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 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 você pode 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 repositório 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 PEM Criar um alias com base em 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"

A opção -F especifica os caminhos para os arquivos PEM.

Nessa chamada, você especifica:

alias_name: identifica o certificado 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.
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 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 repositório 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 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 esta 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 da seguinte forma:

{
  "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.

Para 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 o upload deles em um único arquivo.

O certificado final normalmente é assinado pelo emissor do certificado. Por exemplo, no truststore, faça 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 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 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 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 o upload do certificado como um arquivo PEM no 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"

A opção -F especifica o caminho para o arquivo PEM.

Receber detalhes sobre um keystore ou um truststore existente

Verifique se há keystores existentes no seu ambiente usando a API List Keystores and 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 avaliação sem custo financeiro nos ambientes de teste e de produção. Você verá os seguintes resultados dessa chamada nos dois ambientes:

[ "freetrial" ]

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

Para clientes de nuvem privada, a matriz retornada fica vazia até que você crie seu primeiro keystore.

Verifique o conteúdo do keystore usando a API Get a Keystore ou Truststore. Para um cliente de nuvem, você vê 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 será exibida da seguinte forma:

{
 "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 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 será exibida da seguinte forma:

[
  "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 será exibida da seguinte forma:

{
  "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 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 será exibida da seguinte forma:

-----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 CA para obter um novo certificado. Para gerar uma CSR para um alias, use a API Gerar uma 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 será exibida da seguinte forma:

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

Adicionar um certificado a um truststore para o 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 cadeia de AC para cada cliente com permissão para fazer solicitações ao Edge.

Ao configurar inicialmente o truststore, você pode adicionar todos os certificados para os clientes conhecidos. No entanto, com o tempo, talvez você queira adicionar mais 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-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 um alias

Tenha cuidado ao excluir um keystore/truststore ou um alias. Se você excluir um keystore, truststore ou alias que estiver 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 endpoint/servidor de destino de destino vão falhar.

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

Crie um novo keystore/truststore ou um alias, 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 antigo e ao alias da chave para fazer referência ao novo keystore e ao alias da chave. Se o TargetEndpoint se referir a um TargetServer, atualize a definição do TargetServer para fazer referência ao novo keystore e ao alias da chave.
2. Se o keystore e o truststore forem referenciados diretamente na definição de TargetEndpoint, será necessário reimplantar o proxy. Se o TargetEndpoint se referir a uma definição do TargetServer e ela 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 alias.

Consulte Atualizar o certificado em um alias para saber mais.

Excluir um keystore ou um truststore

É possível excluir um keystore ou um 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 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 Delete alias:

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