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

Estás viendo la documentación de Apigee Edge.
Ve a la documentación de Apigee X.
Información

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

Introducción

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

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

Crea un almacén de claves

Un almacén de claves es específico de un entorno de tu organización, por ejemplo, el entorno de prueba o producción. Por lo tanto, si deseas probar el almacén de claves en un entorno de pruebas antes de implementarlo en el 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 que se proporciona 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 la clave se basa en el formato del par 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 su nombre en la API de Create a Keystore o 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 se deben adjuntar a un solo archivo PEM, en el que el último certificado debe estar firmado por una AC raíz. Los certificados se deben adjuntar al archivo PEM en el orden correcto, con una línea vacía entre cada uno de ellos. Esto significa lo siguiente:

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

En el directorio que contiene el par de claves y el 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 el par de claves y el 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 contengan un certificado y una clave privada mediante la API para crear un alias desde un archivo JAR o 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"

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

En esta llamada, especificarás 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. Omite este parámetro si la clave privada no tiene contraseña.

Verifica que el 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 mediante la API para crear un alias a partir de archivos PEM de claves y certificados:

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 ejemplo anterior, la opción -F especifica las rutas a los archivos PEM.

En esta llamada, especificarás 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. Omite este parámetro si la clave privada no tiene contraseña.

Verifica que el 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 mediante la API Crea un alias desde un archivo JAR o 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"

En el ejemplo anterior, la opción -F especifica la ruta al archivo P12.

En esta llamada, especificarás 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. Omite este parámetro si la clave privada no tiene contraseña.

Verifica que el 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 Crea un alias mediante la generación de un certificado autofirmado para crear un certificado y una clave autofirmados, y subirlos a un alias. La siguiente llamada especifica solo la información necesaria 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"
}

Crear un almacén de confianza

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

Si el certificado forma parte de una cadena, debes subir todos los certificados de la cadena por separado al almacén de confianza o crear un solo archivo que contenga todos los certificados. Debes insertar una línea vacía entre cada certificado del 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 de la entidad emisora del certificado de cliente, ca_cert.

Durante la autenticación TLS bidireccional, la autenticación del cliente se realiza de forma correcta 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 debes subir client_cert_2 al almacén de confianza. El almacén de confianza todavía 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 con éxito. Esto se debe a que Edge permite que la verificación de TLS tenga éxito cuando el cliente_cert_2 no existe en el almacén de confianza, pero tiene la firma del certificado existente en el almacén de confianza. Si quitas el certificado de CA, ca_cert, del almacén de confianza, fallará la verificación de TLS.

Crea un almacén de confianza vacío en el entorno con Create a Keystore o 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 confianza, sube el certificado como un archivo PEM al almacén de confianza mediante la API Crea un alias a partir de un archivo 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"

En el ejemplo anterior, la opción -F especifica la ruta al archivo PEM.

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

Verifica si hay almacenes de claves existentes en tu entorno 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

Los clientes de la nube disponen de un almacén de claves predeterminado para las organizaciones de prueba gratuita tanto en los entornos de prueba como de producción. Deberías ver los siguientes resultados de esta llamada para ambos entornos:

[ "freetrial" ]

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

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

Verifica el contenido del almacén de claves con la API de Get a Keystore o Truststore. Para un cliente de la nube, deberías ver un certificado TLS de un solo 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 para los almacenes de claves con la API de List alias:

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

Si quieres descargar el certificado para un alias, usa la API de Exporta un certificado para un 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 quieres renovarlo, puedes descargar una solicitud de firma de certificado (CSR). Luego, envía la CSR a tu CA para obtener un certificado nuevo. Si deseas generar una CSR para un alias, usa la API de Genera una CSR para un 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 confianza para la TLS bidireccional

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

Cuando configuras inicialmente el almacén de confianza, 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 confianza a medida que agregas 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 confianza en el host virtual.
  2. Sube un certificado nuevo al almacén de confianza como se describió con anterioridad 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, un almacén de confianza o un alias

Debes tener cuidado cuando borres un almacén de claves, un almacén de confianza o un alias. Si borras un almacén de claves, un almacén 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 que se realicen a través del host virtual, o el extremo o servidor de destino de destino.

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

  1. Crea un almacén de claves, un almacén de confianza o un alias nuevo 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 almacén de claves y al alias de la clave nuevos.
  3. En el caso de las conexiones salientes, es decir, desde Apigee hasta un servidor de backend:
    1. Actualiza la configuración de TargetEndpoint para cualquier proxy de API que hiciera referencia al almacén de claves y al alias de clave anteriores para hacer referencia al almacén de claves y al alias de la clave nuevos. Si tu TargetEndpoint hace referencia a un TargetServer, actualiza la definición de TargetServer para hacer referencia al almacén de claves y al alias de la clave nuevos.
    2. Si se hace referencia al almacén de claves y al almacén de confianza directamente desde la definición de TargetEndpoint, debes volver a implementar el proxy. Si el TargetEndpoint hace referencia a una definición de TargetServer y esta hace referencia al almacén de claves y al almacén de confianza, no es necesario volver a implementar el proxy.
    3. Confirma que los proxies de tu API funcionen correctamente.
    4. Borra el almacén de claves, el almacén de confianza o el alias.

Para obtener más información, consulta Actualiza el certificado en un alias.

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

Puedes borrar un almacén de claves o un almacén de confianza con la API de Delete a Keystore o 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 un almacén de confianza que usa un host virtual, debes volver a implementar los proxies de API.

Borra un alias

Puedes borrar un alias de un almacén de claves o un almacén 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}