Crea almacenes de claves y almacenes de confianza para la versión 4.17.09 y versiones anteriores de la nube privada

Estás consultando la documentación de Apigee Edge.
Consulta 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 de Edge para la versión de nube privada 4.17.09 y anteriores.

Información acerca de los almacenes de claves y los almacenes de confianza

Los almacenes de claves y los almacenes de confianza definen los repositorios de los certificados de seguridad que se usan para la encriptación TLS. La principal diferencia entre ambos es dónde se usan en el proceso de protocolo de enlace TLS:

  • Un almacén de claves contiene un certificado TLS y una clave privada que se usa para identificar la entidad durante el protocolo de enlace TLS.

    En la TLS unidireccional, cuando un cliente se conecta al extremo de TLS en el servidor, el almacén de claves del servidor presenta el certificado del servidor (certificado público) al cliente. Luego, el cliente valida ese certificado con una autoridad certificadora (CA), como Symantec o VeriSign.

    En la TLS bidireccional, el cliente y el servidor mantienen un almacén de claves con su propio certificado y clave privada que se usa para la autenticación mutua.
  • Un truststore contiene certificados que se usan para verificar los certificados recibidos como parte del protocolo de enlace TLS.

    En la TLS unidireccional, no se requiere un almacén de confianza si el certificado está firmado por una CA válida. Si el certificado que recibe un cliente de TLS está firmado por una CA válida, el cliente enviará una solicitud a la CA para autenticar el certificado. Por lo general, un cliente de TLS usa un almacén de confianza para validar los certificados autofirmados que se reciben del servidor TLS o los que no están firmados por una CA de confianza. En esta situación, el cliente propaga su almacén de confianza con certificados en los que confía. Luego, cuando el cliente recibe un certificado de servidor, el certificado entrante se valida con los certificados de su almacén de confianza.

    Por ejemplo, un cliente TLS se conecta a un servidor TLS en el que el servidor usa un certificado autofirmado. Debido a que es un certificado autofirmado, el cliente no puede validarlo con una CA. En cambio, el cliente precarga el certificado autofirmado del servidor en su almacén de confianza. Luego, cuando el cliente intenta conectarse al servidor, usa su almacén de confianza para validar el certificado que recibió del servidor.

    En el caso de TLS bidireccional, tanto el cliente de TLS como el servidor de TLS pueden usar un almacén de confianza. Se requiere un almacén de confianza cuando se realiza una TLS bidireccional cuando Edge actúa como el servidor de TLS.

Una autoridad certificadora (CA) puede emitir los certificados o se pueden autofirmar con la clave privada que generes. Si tienes acceso a una CA, sigue las instrucciones que esta proporcione para generar claves y emitir certificados. Si no tienes acceso a una CA, puedes generar un certificado autofirmado mediante una de las muchas herramientas gratuitas disponibles de forma pública, como openssl.

Implementa un almacén de claves y un almacén de confianza en Edge

En Edge, un almacén de claves contiene uno o más archivos JAR, en los que el archivo JAR contiene lo siguiente:

  • Certificado TLS como archivo PEM, ya sea un certificado firmado por una autoridad certificadora (CA), una cadena de certificados en la que el último certificado esté firmado por una CA o un certificado autofirmado.
  • Clave privada como archivo PEM. Edge admite tamaños de clave de hasta 2,048 bits. La frase de contraseña es opcional.

Un almacén de confianza es similar a un almacén de claves, con la excepción de que solo contiene certificados como archivo PEM, pero no contiene claves privadas.

Si el certificado es parte de una cadena, el almacén de claves o almacén de confianza debe contener todos los certificados de la cadena, ya sea como archivos PEM individuales o como un solo archivo. Si usas un solo archivo, debes asegurarte de que el primero del archivo sea el que se usa para TLS seguido de la cadena de certificados del certificado de CA. Debes insertar una línea vacía entre cada certificado del archivo.

Edge proporciona una API que puedes usar para crear almacenes de claves y almacenes de confianza. Las APIs reales son las mismas. La diferencia es que, cuando creas un almacén de claves, se pasa un archivo JAR que contiene el certificado y la clave privada. Cuando creas un almacén de confianza, solo pasas el certificado como un archivo PEM.

Acerca del formato de los archivos de certificación y de claves

En los ejemplos de este documento, se muestran el certificado y la clave de TLS definidos como archivos PEM, que cumplen con el formato X.509. Si tu certificado o clave privada no están definidos por un archivo PEM, puedes convertirlos en uno PEM con el uso de utilidades como openssl.

Sin embargo, muchos archivos .crt y .key ya están en formato PEM. Si estos archivos son de texto y están incluidos:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

o bien

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

Entonces, los archivos serán compatibles con el formato PEM y podrás usarlos en un almacén de claves o un almacén de confianza sin convertirlos a un archivo PEM.

Si tienes una cadena de certificados y deseas usarla en un almacén de claves o almacén de confianza, puedes combinar todos los certificados en un solo archivo PEM con una línea nueva entre cada certificado. Los certificados deben estar en orden y el último debe ser un certificado raíz o uno intermedio firmado por un certificado raíz:

-----BEGIN CERTIFICATE-----
(Your Primary TLS certificate)
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
(Intermediate certificate)
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
(Root certificate or intermediate certificate signed by a root certificate)
-----END CERTIFICATE-----

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

Comprueba si hay algún almacén de claves existente en tu entorno con la API de List Keystores and Truststores:

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

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 las API y enviarlas a producción, pero, por lo general, debes crear 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 estará vacío hasta que crees tu primer almacén de claves.

Para comprobar el contenido del almacén de claves, usa la API de Get a Keystore o Truststore. Para los clientes de la nube, deberías ver un solo certificado TLS, el certificado predeterminado que proporciona Apigee Edge para las cuentas de prueba gratuita.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

La respuesta debería aparecer de la siguiente manera:

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

También puedes ver esta información en la IU de administración de Edge:

  1. Accede a la IU de administración perimetral en https://enterprise.apigee.com (nube) o http://<ms-ip>:9000 (local), en el que <ms-ip> es la dirección IP del nodo del servidor de administración.
  2. En el menú de la IU de administración perimetral, selecciona Administrador > Certificados TLS.

Obtener detalles del certificado TLS

Puedes usar la API de Get Cert Details de un Keystore o de Truststore para ver detalles sobre los certificados TLS en el almacén de claves, como la fecha de vencimiento y el emisor. Primero, obtén el nombre del certificado que te interesa. En este ejemplo, se recupera información para un almacén de claves llamado “prueba gratuita”.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

Respuesta de muestra:

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

Luego, usa el valor de la propiedad certs para obtener los detalles del certificado:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password

Respuesta de muestra:

{
 "certInfo" : [ {
   "expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
   "isValid" : "Yes",
   "issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O=&quot;GoDaddy.com, Inc.&quot;, L=Scottsdale, ST=Arizona, C=US",
   "subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
   "subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
   "validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
   "version" : 3
 } ],
 "name" : "example.apigee.net.crt"
}

También puedes ver esta información en la IU de administración de Edge:

  1. Accede a la IU de administración perimetral en https://enterprise.apigee.com (nube) o http://<ms-ip>:9000 (local), en el que <ms-ip> es la dirección IP del nodo del servidor de administración.
  2. En el menú de la IU de administración perimetral, selecciona Administrador > Certificados TLS.

En la IU de Edge, puedes especificar la anticipación con la que Edge indicará que un certificado vencerá. De forma predeterminada, la IU destaca los certificados programados para vencer en los próximos 10 días.

Crea un almacén de claves

Un almacén de claves es específico de un entorno de tu organización, como 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 tu entorno de producción, debes crearlo en ambos entornos.

La creación de un almacén de claves es un proceso de dos pasos:

  1. Crea un archivo JAR que contenga el certificado y la clave privada.
  2. Crea el almacén de claves y sube el archivo JAR.

Crea un archivo JAR que contenga el certificado y la clave privada

Crea un archivo JAR con tu clave privada, certificado y un manifiesto. Debe contener los siguientes archivos y directorios:

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

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 tu par de claves y el certificado:

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

Agrega descriptor.properties al archivo JAR:

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

Crea el almacén de claves y sube el archivo JAR

Para crear un almacén de claves en un entorno, solo debes especificar su nombre en la API de Create a Keystore o Truststore. El nombre solo puede contener caracteres alfanuméricos:

curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password

Respuesta de muestra:

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

Después de crear un almacén de claves con nombre en un entorno, puedes subir los archivos JAR que contengan un certificado y una clave privada mediante la API de Upload a JAR file to a Keystore:

curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password

donde la opción -F especifica la ruta de acceso al archivo JAR.

En esta llamada, especificarás dos parámetros de consulta:

  • alias: 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.
  • password: Es la contraseña de la clave privada. Omite este parámetro si la clave privada no tiene contraseña.

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

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password

Respuesta de muestra:

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

Crea un almacén de confianza

Las API 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 debes pasar el archivo del certificado como un archivo PEM en lugar de un JAR.

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. Incluye una línea nueva entre cada certificado en el 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 de forma correcta. Esto se debe a que Edge permite que la verificación de TLS se realice de forma correcta cuando client_cert_2 no existe en el almacén de confianza, pero tiene la firma de un certificado que existe en él. Si quitas el certificado de CA, ca_cert, del almacén de confianza, la verificación de TLS fallará.

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 -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

Sube el certificado como un archivo PEM al almacén de confianza mediante la API de Subir un certificado a un almacén de confianza:

curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password

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

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

Para borrar un almacén de claves o un almacén de confianza, usa la API de Delete a Keystore o Truststore:

curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password

Respuesta de muestra:

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

Si borras un almacén de claves o un almacén de confianza que usa un host virtual o un extremo/destino/servidor de destino, fallarán todas las llamadas a la API a través del host virtual o el servidor de extremo/destino de destino.