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

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 para Edge para la versión 4.17.09 y anteriores de la nube privada.

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

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

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

    En 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 que certificado con una autoridad de certificación (AC), como Symantec o VeriSign.

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

    En TLS unidireccional, no se requiere un almacén de confianza si el certificado está firmado por una AC válida. Si el botón certificado que recibe un cliente de TLS está firmado por una AC válida; luego, el cliente realiza una solicitud a la AC para autenticarlo. Un cliente de TLS suele usar un almacén de confianza para validar certificados autofirmados recibidos del servidor TLS o certificados que no estén firmados por AC 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 en función de 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 firmado por sí mismo. Debido a que es un certificado autofirmado, el cliente no puede validarlo con una AC. En su lugar, 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 recibido del servidor.

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

Una autoridad certificadora (AC) puede emitir los certificados, o bien se pueden autofirmar con la clave privada que generas. Si tienes acceso a una AC, sigue las instrucciones que se proporcionan CA para generar claves y emitir certificados. Si no tienes acceso a una AC, puedes generar un certificado autofirmado con una de las muchas herramientas gratuitas disponibles públicamente, 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: un certificado firmado por una autoridad certificadora (AC), una cadena de certificados en la que el último certificado está firmado por una AC, o una certificado.
  • Clave privada como archivo PEM. Edge admite tamaños de clave de hasta 2048 bits. Una frase de contraseña es opcional.

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

Si el certificado forma parte de una cadena, el almacén de claves o el almacén de confianza deben contener todos los certificados ya sea como archivos PEM individuales o como un solo archivo. Si usas un solo archivo, certificados deben estar en orden, donde el primer certificado del archivo sea el que se usa para TLS la cadena de certificados, en orden, al certificado de la AC. 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 igual. La diferencia es que, cuando creas un almacén de claves, pasas 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.

Información acerca del formato de los archivos de certificado y clave

En los ejemplos de este documento, se muestran el certificado y la clave TLS definidos como archivos PEM, los cuales cumplen con el formato X.509. Si tu certificado o clave privada no están definidas por un archivo PEM, puedes convertir a un archivo PEM con 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 encerrados en lo siguiente:

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

o:

-----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 de confianza sin convertirlos a un archivo PEM.

Si tienes una cadena de certificados y deseas usarla en un almacén de claves o de confianza, puedes combinar todos los certificados en un solo archivo PEM con una línea nueva entre cada certificado. El certificados deben estar en orden, y el último debe ser un certificado raíz o 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

Usa la API de List Keystores and Truststores para verificar si hay almacenes de claves existentes en tu entorno:

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

Para los clientes de Cloud, 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 de esta llamada para ambos entornos:

[ "freetrial" ]

Puedes usar este almacén de claves predeterminado para probar tus APIs y enviarlas a producción, pero Por lo general, crea tu propio almacén de claves con tu certificado y tu clave antes de implementarlo en producción.

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

Comprueba el contenido del almacén de claves a través de la Obtén una API de almacén de claves o de almacén de confianza. Para un cliente de la nube, deberías ver TLS de un solo servidor certificado predeterminado que Apigee Edge proporciona 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 de Edge en https://enterprise.apigee.com (nube) o http://<ms-ip>:9000 (local), donde <ms-ip> es la dirección IP del nodo del servidor de administración.
  2. En el menú de la IU de administración de Edge, selecciona Administrador > Certificados TLS.

Obtener detalles del certificado TLS

Puedes usar la API de Get Cert Details from a Keystore or 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 en que te interesa. En este ejemplo, se recupera información del almacén de claves llamado "freetrial".

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 de Edge en https://enterprise.apigee.com (en la nube) o http://<ms-ip>:9000 (local), donde <ms-ip> es la dirección IP del nodo del servidor de administración.
  2. En el menú de la IU de administración de Edge, selecciona Administrador > Certificados TLS.

En la IU de Edge, puedes especificar la anticipación con la que Edge indica que se realizará un certificado que venzan. 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, por ejemplo, el entorno de prueba o 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.

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

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

Crea un archivo JAR que contenga tu certificado y clave privada.

Crea un archivo JAR con tu clave privada, certificado y un manifiesto. El archivo JAR debe contienen 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 el nombre del almacén de claves en el Crear un almacén de claves o una API de 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 contener un certificado y una clave privada mediante el Sube un archivo JAR a una API de almacén de claves:

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

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

En esta llamada, especificas dos parámetros de consulta:

  • alias: Identifica el certificado y la clave en el almacén de claves. Cuando se crea un host virtual, se hace referencia al certificado y clave por su nombre de alias.
  • password: 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 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 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 pasas el archivo de certificado como un archivo PEM en lugar de un archivo 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 del archivo. Por lo general, el emisor del certificado firma el certificado final. Para Por ejemplo, en el almacén de confianza, subes un certificado de cliente, client_cert_1, y el certificado de cliente certificado de la entidad emisora, 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 sube client_cert_2 a la almacén 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 confianza, pero fue firmado por un certificado que existe en el almacén de confianza. Si quitas el certificado de la AC, ca_cert, del almacén de confianza, la verificación de TLS fallará.

Crea un almacén de confianza vacío en el entorno mediante Crear un Keystore o Truststore, que es 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 archivo PEM al almacén de confianza con la API de Upload a Certificate to a Truststore:

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 la que la opción -F especifica la ruta de acceso al archivo PEM.

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

Puedes borrar un almacén de claves o un almacén de confianza a través de la Borra una API de almacén de claves o de almacén de confianza:

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 destino endpoint/destino/servidor, todas las llamadas a la API a través del host virtual o del extremo o servidor de destino fallará...