Como criar keystores e truststores usando a API de gerenciamento de borda

Você está vendo a documentação do Apigee Edge.
Consulte a documentação do Apigee X.

Neste documento, descrevemos como criar, modificar e excluir keystores e truststores para o Edge para a nuvem e para Edge para a nuvem privada versões 4.18.01 e posteriores.

Introdução

Para configurar a funcionalidade que depende de uma infraestrutura de chave pública, como TLS, você precisa criar keystores e truststores que forneçam as chaves e certificados digitais necessários.

Para ver 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, será necessário criá-lo nos dois ambientes.

Para criar um keystore em um ambiente:

  1. Use a chamada de API nesta seção para criar o keystore.
  2. Crie um alias e faça o upload de um par de certificado/chave para o alias. A maneira como você faz upload do certificado e da chave se baseia no formato do par de certificado/chave. As seções a seguir descrevem como fazer upload de cada tipo de par de certificado/chave:

Para criar um keystore, especifique o nome dele para a API Create a Keystore or 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 de uma chave como um arquivo JAR

Primeiro, é necessário criar um arquivo JAR com sua chave privada, um 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 precisarão 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 um, o que significa:

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

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

Agora é possível fazer upload de seus arquivos JAR que contêm um certificado e uma chave privada usando a API Create a 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 armazenamento de chaves 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 de uma chave como arquivos PEM

Faça upload de arquivos PEM que contenham um certificado e uma chave privada usando a API Create a alias from certificate and key PEM files:

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 armazenamento de chaves 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"
}

Faça upload de um certificado e de 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 a 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 armazenamento de chaves 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

Use a API Criar um alias gerando um certificado autoassinado para criar um certificado e uma chave autoassinados e fazer o 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 outras 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 o upload de um arquivo cert, como um arquivo PEM, para o truststore.

Se o certificado fizer parte de uma cadeia, você precisará fazer upload de todos os certificados da cadeia separadamente para o truststore ou criar um único arquivo contendo todos os certificados. É necessário inserir 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 confiáveis, 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 bidirecional do TLS, 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 o 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 do TLS, a solicitação é bem-sucedida. Isso ocorre porque o Edge permite a verificação por TLS quando o 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 TLS falhará.

Crie um truststore vazio no ambiente usando Create a 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 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.

Receba detalhes sobre um keystore ou truststore existente

Verifique se há algum keystore no 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 da 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 esta chamada para os dois ambientes:

[ "freetrial" ]

É possível usar esse repositório de chaves padrão para testar suas APIs e enviá-las para produção, mas normalmente você cria o próprio armazenamento de chaves, com certificado e chave próprios, antes de implantá-lo na produção.

Para clientes da 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 or Truststore. Para clientes da nuvem, você verá um certificado TLS de servidor único, que é 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 deve aparecer como:

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

Ver detalhes sobre um alias

Receba uma lista de todos os aliases de um keystore usando a API Aliases da lista:

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 a data de validade e o 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 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, você envia a CSR à CA para receber um novo certificado. Para gerar uma CSR para um alias, use a API Generate a CSR for a 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 o TLS bidirecional

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

Quando você configura inicialmente o truststore, pode adicionar todos os certificados dos clientes conhecidos. No entanto, com o tempo, convém adicionar mais certificados ao truststore ao adicionar novos clientes.

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

  1. Verifique se você está usando uma referência ao truststore no host virtual.
  2. Faça upload de um novo certificado para o truststore, conforme descrito acima em Criar um truststore.

  3. 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 saber mais.

Excluir um keystore/truststore ou um alias

Tenha cuidado ao excluir um repositório de chaves/confiança ou um alias. Se você excluir um repositório de chaves, um truststore ou um alias que esteja sendo usado por um host virtual, endpoint de destino ou servidor de destino, todas as chamadas de API pelo host virtual ou endpoint de destino/servidor de destino falharão.

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

  1. Crie um novo keystore/truststore ou alias como descrito acima.
  2. Para conexões de entrada, o que significa uma solicitação de API no Edge, atualize a configuração do host virtual para fazer referência ao novo keystore e alias de chave.
  3. 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 repositório de chaves e ao alias de chave antigos. Se o TargetEndpoint fizer referência a um TargetServer, atualize a definição do TargetServer para fazer referência ao novo keystore e alias de chave.
    2. Se o keystore e o truststore forem referenciados diretamente na definição de TargetEndpoint, você precisará reimplantar o proxy. Se o TargetEndpoint fizer referência a uma definição de TargetServer e a definição de TargetServer fizer referência ao keystore e truststore, nenhuma reimplantação de 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 truststore

Você pode excluir um keystore ou 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 truststore que esteja sendo usado por um host virtual, será necessário reimplantar seus proxies de API.

Excluir um alias

Você pode 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}