Crea almacenes de claves y almacenes de confianza mediante la API de Edge Management

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

En este documento, se describe cómo crear, modificar y borrar almacenes de claves y almacenes de confianza para Edge para la nube y para Edge para la nube privada, versiones 4.18.01 y posteriores.

Introducción

Para configurar la funcionalidad que se basa en la infraestructura de clave pública, como TLS, debes crear almacenes de claves y almacenes de confianza que proporcionen las claves y los certificados digitales necesarios.

Para obtener una introducción a los almacenes de claves, los almacenes de certificados de confianza y los alias, consulta Almacenes de claves y almacenes de certificados de confianza.

Crea un almacén de claves

Un almacén de claves es específico de un entorno en tu organización, por ejemplo, el entorno de prueba o de producción. Por lo tanto, si deseas probar el almacén de claves en un entorno de prueba antes de implementarlo en tu entorno de producción, debes crearlo en ambos entornos.

Para crear un almacén de claves en un entorno, haz lo siguiente:

  1. Usa la llamada a la API en esta sección para crear el almacén de claves.
  2. Crea un alias y sube un par de certificado/clave al alias. La forma en que subes el certificado y clave se basa en el formato del par de certificado/clave. En las siguientes secciones, se describe cómo subir cada tipo de par de certificado/clave:

Para crear un almacén de claves, especifica el nombre del almacén de claves en la API de Create a Keystore or Truststore. El nombre del almacén de claves solo puede contener 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"/>'

Respuesta de muestra:

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

Sube un certificado y una clave como un archivo JAR

Primero, debes crear un archivo JAR con tu clave privada, certificado y manifiesto. El archivo JAR debe contener los siguientes archivos y directorios:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

Un JAR de almacén de claves puede contener solo esos tres archivos. Si tienes una cadena de certificados, todos los certificados de la cadena deben agregarse a un solo archivo PEM, en el que el último certificado debe estar firmado por una CA raíz. Los certificados deben agregarse al archivo PEM en el orden correcto, con una línea vacía entre cada certificado, lo que significa lo siguiente:

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

En el directorio que contiene tu par de claves y certificado, crea un directorio llamado /META-INF. Luego, crea un archivo llamado descriptor.properties en /META-INF con el siguiente contenido:

certFile={myCertificate}.pem
keyFile={myKey}.pem

Genera el archivo JAR que contiene tu par de claves y certificado:

jar -cf myKeystore.jar myCert.pem myKey.pem

Agrega descriptor.properties a tu archivo JAR:

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

Ahora puedes subir tus archivos JAR que contienen un certificado y una clave privada con la API de 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"

en el que la opción -F especifica la ruta de acceso al archivo JAR.

En esta llamada, debes especificar lo siguiente:

  • alias_name : Identifica el certificado y la clave en el almacén de claves. Cuando creas un host virtual, haces referencia al certificado y la clave por su nombre de alias.
  • key_pword : Es la contraseña de la clave privada. Omita este parámetro si la clave privada no tiene contraseña.

Verifica que tu almacén de claves se haya subido correctamente:

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

Respuesta de muestra:

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

Sube un certificado y una clave como archivos PEM

Sube archivos PEM que contengan un certificado y una clave privada con la API de Create an 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"

en el que la opción -F especifica las rutas de acceso a los archivos PEM.

En esta llamada, debes especificar lo siguiente:

  • alias_name : Identifica el certificado y la clave en el almacén de claves. Cuando creas un host virtual, haces referencia al certificado y la clave por su nombre de alias.
  • key_pword : Es la contraseña de la clave privada. Omita este parámetro si la clave privada no tiene contraseña.

Verifica que tu almacén de claves se haya subido correctamente:

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

Respuesta de muestra:

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

Sube un certificado y una clave como un archivo PKCS12/PFX

Sube un archivo PKCS12/PFX que contenga un certificado y una clave privada con la API de 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"

en el que la opción -F especifica la ruta de acceso al archivo P12.

En esta llamada, debes especificar lo siguiente:

  • alias_name : Identifica el certificado y la clave en el almacén de claves. Cuando creas un host virtual, haces referencia al certificado y la clave por su nombre de alias.
  • key_pword : Es la contraseña de la clave privada. Omita este parámetro si la clave privada no tiene contraseña.

Verifica que tu almacén de claves se haya subido correctamente:

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

Respuesta de muestra:

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

Crea y sube un certificado y una clave autofirmados

Puedes usar la API de Create an alias by generating a self-signed certificate para crear un certificado y una clave autofirmados, y subirlos a un alias. La siguiente llamada solo especifica la información requerida para crear el certificado autofirmado. Puedes modificar esta llamada para agregar información adicional:

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"

La respuesta debería aparecer de la siguiente manera:

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

Crea un almacén de certificados de confianza

Las APIs que usas para crear un almacén de certificados de confianza son las mismas que se usan para crear un almacén de claves. La única diferencia es que solo subes un archivo de certificado, como un archivo PEM, al almacén de confianza.

Si el certificado es parte de una cadena, debes subir todos los certificados de la cadena por separado al almacén de certificados de confianza o crear un solo archivo que contenga todos los certificados. Debes insertar una línea vacía entre cada certificado en el archivo.

Si deseas subir varios certificados autofirmados que no forman parte de una cadena, usa la misma técnica: si hay varios certificados en los que deseas confiar, súbelos en un solo archivo.

Por lo general, el certificado final está firmado por el emisor del certificado. Por ejemplo, en el almacén de confianza, subes un certificado de cliente,client_cert_1, y el certificado del emisor del certificado de cliente, ca_cert.

Durante la autenticación de TLS bidireccional, la autenticación del cliente se realiza correctamente cuando el servidor envía client_cert_1 al cliente como parte del proceso de protocolo de enlace TLS.

Como alternativa, tienes un segundo certificado, client_cert_2, firmado por el mismo certificado, ca_cert. Sin embargo, no subes client_cert_2 al almacén de certificados de confianza. El almacén de confianza aún contiene client_cert_1 y ca_cert.

Cuando el servidor pasa client_cert_2 como parte del protocolo de enlace TLS, la solicitud se realiza correctamente. Esto se debe a que Edge permite que la verificación de TLS se realice correctamente cuando client_cert_2 no existe en el almacén de certificados de confianza, pero fue firmado por un certificado que existe en el almacén de certificados de confianza. Si quitas el certificado de la AC , ca_cert, del almacén de certificados de confianza, falla la verificación de TLS.

Crea un almacén de confianza vacío en el entorno con Create a Keystore or Truststore, la misma API que usas para crear un almacén de claves:

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

Después de crear el almacén de certificados de confianza, sube el certificado como un archivo PEM al almacén de certificados de confianza con la API de Create an alias from a certificate PEM file:

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"

en el que la opción -F especifica la ruta de acceso al archivo PEM.

Obtén detalles sobre un almacén de claves o almacén de certificados de confianza existente

Verifica tu entorno para ver si hay almacenes de claves existentes con la API de List Keystores and Truststores:

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

Para los clientes de la nube, se proporciona un almacén de claves predeterminado para las organizaciones de prueba gratuita en los entornos de prueba y producción. Deberías ver los siguientes resultados para esta llamada en ambos entornos:

[ "freetrial" ]

Puedes usar este almacén de claves predeterminado para probar tus APIs y enviarlas a producción, pero por lo general, creas tu propio almacén de claves, con tu propio certificado y clave, antes de realizar la implementación en producción.

Para los clientes de la nube privada, el array que se muestra está vacío hasta que creas tu primer almacén de claves.

Verifica el contenido del almacén de claves con la API de Get a Keystore or Truststore. Para un cliente de la nube, deberías ver un solo certificado TLS del servidor , el certificado predeterminado que proporciona Apigee Edge para las cuentas de prueba gratuita.

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

La respuesta debería aparecer de la siguiente manera:

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

Obtén detalles sobre un alias

Obtén una lista de todos los alias de un almacén de claves con la API de List aliases:

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

La respuesta debería aparecer de la siguiente manera:

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

Para obtener toda la información sobre un alias, como la fecha de vencimiento y la entidad emisora, usa la API de Get alias y especifica el nombre del 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}"

La respuesta debería aparecer de la siguiente manera:

{
  "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 descargar el certificado de un alias, usa la API de Export a certificate for an 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"

La respuesta debería aparecer de la siguiente manera:

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

Si tienes un certificado vencido y deseas renovarlo, puedes descargar una solicitud de firma de certificado (CSR). Luego, envías la CSR a tu CA para obtener un certificado nuevo. Para generar una CSR para un alias, usa la API de Generate a CSR for an 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"

La respuesta debería aparecer de la siguiente manera:

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

Agrega un certificado a un almacén de certificados de confianza para TLS bidireccional

Cuando se usa TLS bidireccional para conexiones entrantes, es decir, una solicitud a la API en Edge, el almacén de certificados de confianza contiene un certificado o una cadena de CA para cada cliente que puede realizar solicitudes a Edge.

Cuando configuras el almacén de confianza por primera vez, puedes agregar todos los certificados para los clientes conocidos. Sin embargo, con el tiempo, es posible que desees agregar certificados adicionales al almacén de certificados de confianza a medida que agregues clientes nuevos.

Para agregar certificados nuevos a un almacén de confianza que se usa para TLS bidireccional, haz lo siguiente:

  1. Asegúrate de usar una referencia al almacén de certificados de confianza en el host virtual.
  2. Sube un certificado nuevo al almacén de confianza como se describió anteriormente en Crea un almacén de confianza.

  3. Actualiza la referencia del almacén de confianza para establecerla en el mismo valor. Esta actualización hace que Edge vuelva a cargar el almacén de confianza y el certificado nuevo.

    Consulta Modifica una referencia para obtener más información.

Borra un almacén de claves o almacén de certificados de confianza, o un alias

Debes tener cuidado cuando borres un almacén de claves o almacén de certificados de confianza, o un alias. Si borras un almacén de claves, un almacén de certificados de confianza o un alias que usa un host virtual, un extremo de destino o un servidor de destino, fallarán todas las llamadas a la API a través del host virtual o el extremo o el servidor de destino.

Por lo general, el proceso que usas para borrar un almacén de claves o almacén de certificados de confianza, o un alias es el siguiente:

  1. Crea un almacén de claves o almacén de confianza, o un alias nuevos como se describió anteriormente.
  2. Para las conexiones entrantes, es decir, una solicitud a la API en Edge, actualiza la configuración del host virtual para hacer referencia al nuevo almacén de claves y al alias de clave.
  3. Para las conexiones salientes, es decir, de Apigee a un servidor de backend, haz lo siguiente:
    1. Actualiza la configuración de TargetEndpoint para cualquier proxy de API que haga referencia al almacén de claves y al alias de clave anteriores para hacer referencia al nuevo almacén de claves y al alias de clave. Si tu TargetEndpoint hace referencia a un TargetServer, actualiza la definición de TargetServer para hacer referencia al nuevo almacén de claves y al alias de clave.
    2. Si se hace referencia al almacén de claves y al almacén de certificados de confianza directamente desde la definición de TargetEndpoint, entonces debes volver a implementar el proxy. Si TargetEndpoint hace referencia a una definición de TargetServer, y la definición de TargetServer hace referencia al almacén de claves y al almacén de certificados de confianza, no es necesario volver a implementar el proxy.
    3. Confirma que tus proxies de API funcionen correctamente.
    4. Borra el almacén de claves o almacén de certificados de confianza, o el alias.

Consulta Actualiza el certificado en un alias para obtener más información.

Borra un almacén de claves o almacén de confianza

Puedes borrar un almacén de claves o almacén de confianza con la API de 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

Si borras y vuelves a crear un almacén de claves o almacén de certificados de confianza que usa un host virtual, entonces debes volver a implementar tus proxies de API.

Borra un alias

Puedes borrar un alias en un almacén de claves o almacén de certificados de confianza con la API de 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}