Estás viendo la documentación de Apigee Edge.
Ve a la
documentación de Apigee X. info
En este documento, se describe cómo crear, modificar y borrar almacenes de claves y de confianza para Edge de la versión 4.17.09 y anteriores de la nube privada.
Información acerca de los almacenes de claves y de confianza
Los almacenes de claves y de confianza definen repositorios de certificados de seguridad que se usan para la encriptación TLS. 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 TLS en el servidor, el almacén de claves del servidor le presenta el certificado del servidor (certificado público) al cliente. Luego, el cliente valida ese certificado con una AC, como Symantec o VeriSign.
En la TLS bidireccional, tanto el cliente como el servidor mantienen un almacén de claves con su propio certificado y su clave privada que se usan 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 certificado que recibe un cliente TLS está firmado por una AC válida, el cliente envía una solicitud a la AC para autenticar el certificado. Por lo general, un cliente TLS usa un almacén de confianza para validar los certificados autofirmados que recibe del servidor TLS o los certificados que no están firmados por una 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 que recibió 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 te proporciona la AC 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 para el público, 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 la AC firma el último certificado o un certificado autofirmado
- Clave privada como un 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 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, los certificados deben estar en orden, de modo que el primer certificado del archivo sea el que se usa para TLS, seguido de la cadena de certificados, en orden, hasta el 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 mismas. 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 muestra 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á definido por un archivo PEM, puedes convertirlo en 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-----
Luego, los archivos son compatibles con el formato PEM y puedes usarlos en un almacén de claves o en un almacén de confianza sin convertirlos en 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. Los certificados deben estar en orden y el último debe ser un certificado raíz o un certificado 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 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, debes crear tu propio almacén de claves, con tu propio certificado y clave, antes de realizar la implementación 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.
Para verificar el contenido del almacén de claves, usa la API de Get a Keystore or Truststore. En el caso de un cliente de nube, deberías ver un solo certificado TLS del servidor, el certificado predeterminado que proporciona Apigee Edge para las cuentas de prueba gratuitas.
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:
- 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. - En el menú de la IU de administración de Edge, selecciona Administrador > Certificados de TLS.
Obtén 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 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="GoDaddy.com, Inc.", 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:
- 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. - En el menú de la IU de administración de Edge, selecciona Administrador > Certificados de TLS.
En la IU de Edge, puedes especificar con qué anticipación Edge indica 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, 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:
- Crea un archivo JAR que contenga tu certificado y clave privada.
- 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, el certificado y un manifiesto. El archivo JAR 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 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
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 a la API de Create a Keystore or 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 tus archivos JAR que contengan un certificado y una clave privada con 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
en la que 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 creas un host virtual, haces referencia al certificado y a 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 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. 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 TLS de dos vías, la autenticación del cliente se realiza correctamente cuando el servidor envía client_cert_1 al cliente como parte del proceso 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 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 con Create a Keystore or 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 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.
Cómo borrar un almacén de claves o almacén truststore
Puedes borrar un almacén de claves o de confianza con la API de Delete a Keystore or 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 almacén de confianza que usa un host virtual o un extremo, objetivo o servidor de destino, fallarán todas las llamadas a la API a través del host virtual o el extremo, objetivo o servidor de destino.