Recursos

La API REST de gestión de certificados proporciona las siguientes URL de recursos base:

Cada recurso proporciona puntos finales de interacción:

• Los puntos finales bajo el recurso /ca_management/ permiten manipular las CA, por ejemplo, activar y desactivar una CA. ENTERPRISE

• El recurso /ca/ permite recuperar certificados de CA, CRL, etc. ENTERPRISE

• El recurso /certificate/ maneja la inscripción de certificados, la revocación y otros flujos de trabajo relacionados con la administración de certificados.

• El recurso /configdump/ gestiona la importación y exportación de configuraciones (editores, autoridades de certificación, roles, etc.) a través de la herramienta ConfigDump . ENTERPRISE

• El recurso /cryptotoken/ gestiona la activación, desactivación y generación de claves de tokens criptográficos. ENTERPRISE

• El recurso /endentity/ gestiona la gestión de entidades finales. ENTERPRISE

Para obtener un conjunto completo de todos los puntos finales, entradas requeridas, respuestas y otras descripciones de puntos finales, consulte la Referencia de API REST o pruébelo en la interfaz de usuario de Swagger .

Generar un CSR y solicitar un certificado usando Bash

Puede usar OpenSSL, jq y cURL ( versión >7.57) para crear una clave y una CSR, crear una carga JSON que contenga la CSR y luego inscribirse para obtener un certificado de servidor TLS usando el archivo de configuración y el script a continuación.

Ejemplo de flujo de trabajo de revocación

Siga el ejemplo a continuación para verificar primero el estado de revocación de un certificado y luego revocarlo.

En este ejemplo, el DN del certificado es CN=CA1 y el número de serie (en hexadecimal) es 5CB3D42686039768D973E5694BF205377AF6 .

1. Para comprobar el estado de revocación del certificado, llame al método REST GET /v1/certificate/{issuer_dn}/{certificate_serial_number}/revocationstatus :

   curl -X GET -s \

   --cert-type P12 \

   --cert "/opt/jboss/p12/SuperAdmin.p12:foo123" \

   -H "accept: application/json"

   "https://localhost:8443/ejbca/ejbca-rest-api/v1/certificate/CN%3DCA1/5CB3D42686039768D973E5694BF205377AF6/revocationstatus"

2. Desde la respuesta a continuación, puede confirmar que el certificado está activo.

   {

   "issuer_dn" : "CN=CA1" ,

   "serial_number" : "5CB3D42686039768D973E5694BF205377AF6" ,

   "revocation_reason" : "NOT_REVOKED" ,

   "revoked" : false

   }

3. Para revocar el certificado, llame al método REST PUT /v1/certificate/{issuer_dn}/{certificate_serial_number}/revoke :

   curl -X PUT -s \

   --cert-type P12 \

   --cert "/opt/jboss/p12/SuperAdmin.p12:foo123" \

   -H "accept: application/json"

   "https://localhost:8443/ejbca/ejbca-rest-api/v1/certificate/CN%3DCA1/5CB3D42686039768D973E5694BF205377AF6/revoke?reason=KEY_COMPROMISE"

4. Confirme con la respuesta que el certificado se ha revocado correctamente:

   {

   "issuer_dn" : "CN=HT_REMOVAL_CA" ,

   "serial_number" : "5CB3D42686039768D973E5694BF205377AF6" ,

   "revocation_reason" : "KEY_COMPROMISE" ,

   "revocation_date" : "2019-05-27T15:02:56Z" ,

   "message" : "Successfully revoked" ,

   "revoked" : true

   }

Solicitar un almacén de claves PKCS#12 mediante Python

Para solicitar un almacén de claves PKCS#12 mediante Python, haga lo siguiente:

1. Instale el módulo requests_pkcs12 usando pip.

   requests_pkcs12 install pip3

2. Autentíquese con el certificado de cliente almacenado en superadmin.p12 y solicite un archivo PKCS12 para la entidad final python .

   import json

   from requests_pkcs12 import post

   response = post( 'https://myca:8443/ejbca/ejbca-rest-api/v1/certificate/enrollkeystore' ,

   json = {

   'username' : 'python' ,

   'password' : 'foo123' ,

   'key_alg' : 'RSA' ,

   'key_spec' : '2048'

   },

   headers = {

   'content-type' : 'application/json'

   },

   pkcs12_filename = '/srv/superadmin.p12' ,

   pkcs12_password = 'foo123' ,

   verify = '/srv/truststore.pem' )

   print (json.dumps(json.loads(response.content), indent = 4 , sort_keys = True ))

Solicitar un almacén de claves PKCS#12 mediante Node.js

Para solicitar un almacén de claves PKCS#12 mediante Node.js, haga lo siguiente:

1. Instale el módulo node.js llamado node-fetch.

   npm install node-fetch

2. Crea un script que se parezca a esto:

   const fs = require( 'fs' );

   const https = require( 'https' );

   const fetch = require( 'node-fetch' );

   // Load the keystore used to authenticate to the REST API

   const pfx = fs.readFileSync( 'RA_Administrator.p12' );

   const passphrase = 'foo123' ;

   const agent = https.Agent({ pfx, passphrase });

   // Load the enrollment code for the end entity

   const enrollmentCode = 'foo123'

   // Name of the end entity

   const deviceName = 'Company Device 1'

   // Request renewal of the device certificate

   fetch( 'https://nautilus:8443/ejbca/ejbca-rest-api/v1/endentity/' + deviceName + '/setstatus' , {

   agent: agent,

   method: 'post' ,

   body: JSON.stringify({

   "password" : enrollmentCode,

   "token" : "P12" ,

   "status" : "NEW"

   }),

   headers: { 'Content-Type' : 'application/json' },

   })

   .then(res => {

   if (res.status != 200) {

   console.log( 'Renewal failed with status code ' + res.status + '.' )

   } else {

   console.log( 'Renewal succeeded! Requesting new device certificate from EJBCA...' )

   fetch( 'https://nautilus:8443/ejbca/ejbca-rest-api/v1/certificate/enrollkeystore' , {

   agent: agent,

   method: 'post' ,

   body: JSON.stringify({

   "username" : deviceName,

   "password" : enrollmentCode,

   "key_alg" : "RSA" ,

   "key_spec" : "2048"

   }),

   headers: { 'Content-Type' : 'application/json' },

   })

   .then(res => res.json())

   .then(json => console.log(json))

   . catch (error => console.log(error))

   }

   })

   . catch (error => console.log(error))

Búsqueda de certificados

Para buscar certificados con múltiples criterios de búsqueda, utilice el método de búsqueda .

Búsqueda de certificados versión 2

Para buscar certificados con múltiples criterios de búsqueda, paginación y clasificación, utilice el método de búsqueda versión 2.

Búsqueda de entidades finales

Se pueden buscar entidades finales mediante la API v1. Los criterios de búsqueda admitidos son:

• CONSULTA

• PERFIL_DE_ENTIDAD_FINAL

• PERFIL_DE_CERTIFICADO

• CA, ESTADO

• MODIFICADO ANTES

• MODIFICADO DESPUÉS

Tenga en cuenta que QUERY permite realizar búsquedas con el nombre de la entidad final, el nombre distinguido del sujeto y el nombre alternativo del sujeto.

Búsqueda de entidades finales versión 2

La API de búsqueda v2 también admite la ordenación. La ordenación se permite mediante:

• NOMBRE DE USUARIO

• DN_SUJETO

• NOMBRE ALT. DEL ASUNTO

• PERFIL_DE_ENTIDAD_FINAL

• PERFIL_DE_CERTIFICADO

• ESTADO

• HORA DE ACTUALIZACIÓN

• HORA DE CREACIÓN

Los resultados se pueden ordenar de forma ascendente (ASC) o descendente (DESC). Tenga en cuenta que en la búsqueda v2, el parámetro current_page debe empezar en 1 y, si se necesitan más resultados, el número de página debe incrementarse secuencialmente en futuras consultas. No se permite omitir páginas ni acceder a páginas arbitrarias al buscar con este punto final.

Agregar entidad final

EMPRESA Esta es una característica de EJBCA Enterprise.

Para agregar una entidad final usando el punto final endentity , se puede usar un JSON como este:

y cURL:

Después de agregar una entidad final como esa, puede inscribirse en un almacén de claves PKCS#12 con el punto final de certificado/enrollkeystore :

y cURL:

Exportación de configuración con ConfigDump

EMPRESA Esta es una característica de EJBCA Enterprise.

La exportación e importación de configuraciones admiten parámetros como ignoreerrors, include, exclude , etc. Para obtener más información sobre los parámetros disponibles, consulte Swagger UI , la referencia de la API REST generada o la herramienta ConfigDump .

La configuración se puede exportar de diferentes maneras: la configuración completa, por tipo, por tipo y configuración, o como un archivo ZIP que contiene la exportación ConfigDump con formato YAML.

Importar configuración con ConfigDump

EMPRESA Esta es una característica de EJBCA Enterprise.

Los datos JSON para la parte del cuerpo de una solicitud POST de importación siguen la convención: los valores de los atributos son exactamente los mismos que cuando se importa o exporta a través de la CLI de ConfigDump con archivos YAML.

Un ejemplo de cuerpo JSON para importar un único perfil de aprobación:

Y el comando cURL esperado para el cuerpo JSON anterior:

Codificación de solicitud de certificado

Una excepción como la siguiente puede deberse a un problema de codificación:

 IOException while decoding certificate request from PEM: -----END CERTIFICATE REQUEST

El problema se puede resolver reemplazando manualmente los saltos de línea con \n .

Cómo encontrar la causa de los códigos de error devueltos al cliente

Cuando recibe un mensaje de error, como HTTP 404 (BAD_REQUEST), la causa suele encontrarse en un mensaje devuelto como parte del error HTTP. La causa completa del error también suele estar visible en el archivo de registro del servidor para que la consulten los administradores.

Conversión de respuestas en formato DER a PEM

Los archivos DER binarios suelen tener extensiones .cer, .crt o .der, mientras que los archivos PEM se especifican estrictamente con encabezados PEM -----BEGIN / END CERTIFICATE----- y saltos de línea cada 64 caracteres. Más detalles en RFC7468 .

Algunas llamadas REST devuelven un certificado DER codificado en base64 dentro del cuerpo de la respuesta JSON para transferir los datos binarios en una estructura JSON. Se identifica con "response_format": "DER" en el propio JSON y se puede convertir a PEM cuando sea necesario.

Por ejemplo, después de una llamada exitosa a /v1/certificate/pkcs10enroll, la salida JSON contendrá un objeto de certificado en base64, que se puede extraer:

Los datos base64 se pueden decodificar en el formato binario DER:

Puedes convertirlo a PEM, por ejemplo con openssl:

y openssl también se puede utilizar para ir y venir entre PEM y DER: