La API REST de Cert Safe permite almacenar y recuperar información sobre certificados.

Al utilizar la API REST de Cert Safe, Cert Safe Publisher le permite configurar EJBCA para publicar eventos de emisión y ciclo de vida de certificados a través de HTTPS en un servidor de Cert Safe; consulte Cert Safe Publisher .

Validación del cliente

Existe un sistema de clientes de dos niveles. En la parte superior, se encuentran las cuentas , cada una con varios agentes debajo. Cada organización proporciona una cuenta y puede crear agentes para interactuar con el servicio.

Los agentes son útiles para particionar clientes en una cuenta, pero no son necesarios. Interactuar con el servicio únicamente a través de un cliente de cuenta es perfectamente aceptable.

Un cliente (cuenta o agente) se identifica en el servicio mediante un certificado X.509.

Por ejemplo, para validar el servicio con curl:

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/ 

Datos de ejemplo

Todos los ejemplos de este documento plantean la siguiente situación:

Acme Co. tiene una cuenta bajo la cual han registrado dos agentes, Fred Dobler y Nancy Willson, llamados así por los administradores de sistemas que son responsables de esos clientes.

Fred ha publicado dos certificados en el servicio; Nancy ha publicado 20. Acme Co. utiliza Acme CA como su autoridad de certificación.

Errores y códigos de respuesta

Cert Safe intenta devolver códigos de estado HTTP relevantes a todas las solicitudes. Los códigos de estado de error (4XX y 5XX) se acompañan de un objeto JSON de error que contiene una explicación del error.

A continuación se muestra un ejemplo de respuesta json de error.

{
"error" : " aquí aparece un mensaje de error "
}

Ejemplo de rizo

 > curl -i \
 --key client.key --cert client.crt \
 https: //api.url.com/phil
 HTTP/ 1.1 401 Unauthorized
 ...
 {
	"error" : "attempt to access account `https: //api.url.com/phil' failed. available accounts:
 } 

Listas de recursos

Cert Safe proporciona una interfaz uniforme para los recursos que son listas de otros recursos.

Parámetros de solicitud comunes

detalles

Si es "verdadero", en lugar de devolver una matriz de URI a los recursos, devuelve una matriz de objetos de enlace, que son diccionarios con las dos claves: 'uri' y 'data', que contienen la URI del recurso y el recurso (expandido), respectivamente.

Un objeto de enlace de ejemplo.

 {
	"uri" : "https://api.url.com/Acme%20Co./agents/Nancy%20Willson" ,
	"data" : {
	  "name" : "Nancy%20Willson" ,
	  "lastHeartbeat" : "1389738970" ,
	  "apiCertificate" : {
	    "thumbprint" : {
	      "alg" : "SHA-256" ,
		  "hash" : "c98a6d2d2c9ccb3f63a6494e982f1d05022d4985f2186443e299a5afd55d6a3c"
 },
		 "pem" : "-----BEGIN CERTIFICATE-----\nMIID2zCCAsOgAwIBAgIJAPpN61MIpHHJMA0GCSqGSIb3DQEBBQUAMIGDMQswCQYD\
 }
 }
 } 

Ejemplos de rizos

Con detalles = “verdadero”.

 curl \
 --key client.key --cert client.crt \
	'https://api.url.com/Acme%20Co./agents?details=true'
 [
 {
	  "uri" : "https://api.url.com/Acme%20Co./agents/Fred%20Dobler" ,
	  "data" : {
 	    "name" : "Fred%20Dobler" ,
	    "lastHeartbeat" : "1389738970" ,
	    "apiCertificate" : {
	      "thumbprint" : {
	        "alg" : "SHA-256" ,
	        "hash" : "243f1fddc99c31d3e0fa6124b7f89fbda9e669ca2d6251029b0751cff3b6477c"
 },
	      "pem" : "-----BEGIN CERTIFICATE-----\nMIID2TCCAsGgAwIBAgIJAMnlAFWbfUZOMA0GCSqGSIb3DQEBBQUAMIGCMQswCQYD\
 }
 }
 },
 {
	"uri" : "https://api.url.com/Acme%20Co./agents/Nancy%20Willson" ,
	"data" : {
	  "name" : "Nancy%20Willson" ,
	  "lastHeartbeat" : "1389738970" ,
	  "apiCertificate" : {
	    "thumbprint" : {
	      "alg" : "SHA-256" ,
	      "hash" : "c98a6d2d2c9ccb3f63a6494e982f1d05022d4985f2186443e299a5afd55d6a3c"
 },
		  "pem" : "-----BEGIN CERTIFICATE-----\nMIID2zCCAsOgAwIBAgIJAPpN61MIpHHJMA0GCSqGSIb3DQEBBQUAMIGDMQswCQYD\
 }
 }
 }
 ]

Con detalles != “true”.

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co./agents
 [
	"https://api.url.com/Acme%20Co./agents/Fred%20Dobler" ,
	"https://api.url.com/Acme%20Co./agents/Nancy%20Willson"
 ] 

Parámetros de paginación

Si solicitar todos los elementos de una lista es excesivo, se pueden paginar los resultados configurando cualquiera de los siguientes parámetros. La paginación devuelve una matriz de elementos dentro de un cursor .

*después* El identificador de un elemento después del cual se devolverán elementos.

*antes* El identificador de un elemento antes del cual se devolverán elementos.

*límite* El número máximo de elementos devueltos.

Ejemplos de rizos

Un ejemplo que establece todos los parámetros relacionados con la paginación en la solicitud.

 curl \
 --key client.key --cert client.crt \
	'https://api.url.com/Acme%20Co./certificates?limit=5'

respuesta:

 {
	"paging" : {
	   "before" : "9e3910d77f33896f0d06280f2cd8b632c2e9758e4101af7ee43e6464036a7f62.1389738983" ,
	   "after" : "52fc245a4b2987ca75aff6f9eab946319c53d94ef2e170837eeeadf6d33cabd0.1389738983" ,
	  "next" : "https://api.url.com/Acme%20Co./certificates?limit=5&after=52fc245a4b2987ca75aff6f9eab946319c53d94ef2e170837eeeadf6d33cabd0.1389738983"
 },
	"data" : [
	  "https://api.url.com/Acme%20Co./certificates/9e3910d77f33896f0d06280f2cd8b632c2e9758e4101af7ee43e6464036a7f62/"
 https: //api.url.com/Acme%20Co./certificates/e68fafbac9d1efe4c63ebeb31acb3ea9bcb4c74e1ab652c5fb7d6a37d80f1b7d/"
 https: //api.url.com/Acme%20Co./certificates/4e686b2a8993c7c9ac130785a19c7b530dd0a7c79abc75f09369f0a6b6bae269/"
 https: //api.url.com/Acme%20Co./certificates/93eab1340011da735c6133ecdc521968eb3648a20b710bad5b0cbbc8d4011122/"
 https: //api.url.com/Acme%20Co./certificates/52fc245a4b2987ca75aff6f9eab946319c53d94ef2e170837eeeadf6d33cabd0/
 ]
 }

Un ejemplo que utiliza details=true con paginación.

 curl \
 --key client.key --cert client.crt \
	'https://api.url.com/Acme%20Co./certificates?details=true&limit=2'

respuesta:

 {
	"paging" : {
	  "before" : "e68fafbac9d1efe4c63ebeb31acb3ea9bcb4c74e1ab652c5fb7d6a37d80f1b7d.1389738983" ,
	  "after" : "9e3910d77f33896f0d06280f2cd8b632c2e9758e4101af7ee43e6464036a7f62.1389738983" ,
	  "next" : "https://api.url.com/Acme%20Co./certificates?details=true&limit=2after=9e3910d77f33896f0d06280f2cd8b632c2e9758e4101af7ee43e6464036a7f62.1389738983"
 },
	"data" : [ {
		"uri" : "https://api.url.com/Acme%20Co./certificates/e68fafbac9d1efe4c63ebeb31acb3ea9bcb4c74e1ab652c5fb7d6a37d80f1b7d/" data": {
		"status" : "active" ,
		  "thumbprint" : {
		  "alg" : "SHA-256" ,
		    "hash" : "e68fafbac9d1efe4c63ebeb31acb3ea9bcb4c74e1ab652c5fb7d6a37d80f1b7d"
 },
  		  "timestamp" : "1389738983" ,
		  "revocationReason" : "caComprimise" ,
		  "pem" : "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIJAMdwFqDi3hUUMA0GCSqGSIb3DQEBBQUAMFIxCzAJBgNV\
 }
 },
 {
	  "uri" : "https: //api.url.com/Acme%20Co./certificates/9e3910d77f33896f0d06280f2cd8b632c2e9758e4101af7ee43e6464036a7f62/
	  "data" : {
		"status" : "active" ,
		"thumbprint" : {
		  "alg" : "SHA-256" ,
		  "hash" : "9e3910d77f33896f0d06280f2cd8b632c2e9758e4101af7ee43e6464036a7f62"
 },
		"timestamp" : "1389738983" ,
		"revocationReason" : "privilegeWithdrawn" ,
		"pem" : "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIJAJSbDSeDItscMA0GCSqGSIb3DQEBBQUAMFIxCzAJBgNV\
 }
 }
 ]
 } 

Recursos

OBTENER /:cuenta

Recuperar metadatos sobre una cuenta.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta que se recuperará.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co.
 {
 "lastAgentUpdated" : 1389147041 ,
 "lastAgentHeartbeat" : 1389147041 ,
 "name" : "Acme%20Co." ,
 "cas" : [
 {
 "name" : "Acme CA" ,
 "validCerts" : 5001 ,
 "revokedCerts" : 4000 ,
 "totalCerts" : 9001
 }
 ],
 "agents" : [
 "https://api.url.com/Acme%20Co./agents/Fred%20Dobler" ,
 "https://api.url.com/Acme%20Co./agents/Nancy%20Willson"
 ],
 "contacts" : [ "fred@example.com" , "nancy.example.com" ],
 "creationDate" : 1389147041
 } 

Obtener /:cuenta/agentes

Recupere la lista de agentes registrados en la cuenta .

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta cuyos agentes se recuperan.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co./agents
 [
	"https://api.url.com/Acme%20Co./Fred%20Dobler" ,
	"https://api.url.com/Acme%20Co./agents/Nancy%20Willson"
 ] 

POST /:cuenta/agentes

Registre un nuevo agente en la cuenta . Esta operación solo se puede realizar con el certificado de validación de la cuenta raíz. Todas las solicitudes realizadas con un certificado de agente se rechazarán con un código de error HTTP 403.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta en la que se registra un agente.

Cuerpo de la solicitud

El cuerpo de la solicitud debe ser un objeto json con los siguientes campos:

Nombre: Un nombre único para identificar al agente. Debe ser un pathComponent válido.
certificado: el certificado que utilizará el agente para interactuar con la API, en formato PEM.

Ejemplo de rizo

agente.json

 {
	"name" : "Fran%20Dresser" ,
	"certificate" : "-----BEGIN CERTIFICATE-----\nMIIDzTCCArWgAwIBAgIJAIdzifeP5GrKMA0GCSqGSIb3DQEBBQUAMH0xCzAJBgNV\
 }
 curl \
 -x POST \
 --key client.key --cert client.crt \
 --Header "Content-Type: application/json" \
 --data @agent .json \
 https: //api.url.com/Acme%20Co./agents
 [
	"https://api.url.com/Acme%20Co./agents/Fred%20Dobler"
 ] 

OBTENER /:cuenta/agentes/:agente

Consultar a un agente específico.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Es el mismo valor que el campo de nombre de la cuenta.
cuyo agente es recuperado.
agente: El nombre del agente. Este valor es el mismo que el del campo de nombre del agente recuperado .

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co./agents/Fred%20Dobler
 {
	"name" : "Fred%20Dobler" ,
	"lastHeartbeat" : 1389147892 ,
	"apiCertificate" : {
	 "thumbprint" : {
		"alg" : "SHA-256" ,
		"hash" : "a790e34c004019fb401e18764063053f8eabd718297d5d47f821f9a44628723b"
 },
	 "pem" : "-----BEGIN CERTIFICATE-----\nMIIE4jCCA8qgAwIBAgISESHa7VrcABc10XWhUrsLeaqcMA0GCSqGSIb3DQEBBQUA\}
 } 

ELIMINAR /:cuenta/agentes/:agente

Dar de baja un agente. Esta operación solo se puede realizar con el certificado de la cuenta raíz. Todas las solicitudes realizadas con un certificado de agente se rechazan con un HTTP 403.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta cuyo agente no está registrado.
agente - Nombre del agente. Este valor es el mismo que el del campo de nombre del agente que se está desregistrando.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 --request DELETE \
 https: //api.url.com/Acme%20Co./agents/Fred%20Dobler 

POST /:cuenta/agentes/:agente/latido

Háganos saber que el agente del cliente todavía está vivo.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta que te interesa.
Agente: El nombre del agente. Este valor es el mismo que el del campo de nombre del agente para el que se realiza el latido.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 --request POST \
 https: //api.url.com/Acme%20Co./agents/Fred%20Dobler 

GET /:cuenta/certificados

Recupere una lista de certificados ordenados del más reciente al menos reciente.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta cuyos certificados se recuperan.

Parámetros de la solicitud

Todos los parámetros de solicitud son opcionales.

agente: recupera solo los certificados que hayan sido actualizados por el agente cuyo campo de nombre coincida con este valor.
estado - Recupera solo los certificados cuyo campo de estado sea este valor.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co./certificates
 [
 "https: //api.url.com/Acme%20Co./certificates/dcbc8bfb416999122770b500f9aaa4b73e3b7ec7bb674c8fdc1ab60acb52c272/
 ] 

POST /:cuenta/certificados

Crear una nueva entrada de certificado.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta cuyos certificados se recuperan.

Cuerpo de la solicitud

El cuerpo de la solicitud debe ser un objeto json con los siguientes campos:

estado (obligatorio) - El estado en el campo de estado del certificado.
RevocaciónReason (opcional): El motivo en el campo "motivo" del certificado. El valor predeterminado es "sin especificar". Si el estado del certificado no es "revocado", se considera un error establecer este valor en un valor distinto de "sin especificar".
pem (obligatorio) - El certificado en formato PEM.

Ejemplo de rizo

certificado.json

 {
	"status" : "revoked" ,
	"revocationReason" : "keyComprimise" ,
	"pem" : "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAMlXXOH8xC0QMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV\
 }
 curl \
 -x POST \
 --key client.key --cert client.crt \
 --Header "Content-Type: application/json" \
 --data @certificate .json \
 https: //api.url.com/Acme%20Co./certificates 

GET /:cuenta/certificados/:huella digital del certificado

Una lista de los estados en los que ha estado un certificado identificado por huella dactilar.

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta cuyos certificados se recuperan.
certificate-thumbprint: el hash del certificado del que desea recuperar el historial.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co./certificates/dcbc8bfb416999122770b500f9aaa4b73e3b7ec7bb674c8fdc1ab60acb52c272
 [
 "https: //api.url.com/Acme%20Co./certificates/dcbc8bfb416999122770b500f9aaa4b73e3b7ec7bb674c8fdc1ab60acb52c272/
 ] 

GET /:cuenta/certificados/:huella-digital-del-certificado/:marca-de-tiempo

Recupere un estado específico al que pasó el certificado indicado por certificate-thumbprint en la marca de tiempo .

Parámetros de ruta

Cuenta: El nombre de la cuenta. Este valor es el mismo que el del campo de nombre de la cuenta cuyos certificados se recuperan.
certificate-thumbprint: el hash del certificado para el que desea recuperar un estado específico.
marca de tiempo: el mismo UnixTime que el campo de marca de tiempo del recurso de certificado a recuperar.

Ejemplo de rizo

 curl \
 --key client.key --cert client.crt \
 https: //api.url.com/Acme%20Co./certificates/dcbc8bfb416999122770b500f9aaa4b73e3b7ec7bb674c8fdc1ab60acb52c272/
 {
	"thumbprint" : {
	 "alg" : "SHA-256" ,
	 "hash" : "a790e34c004019fb401e18764063053f8eabd718297d5d47f821f9a44628723b"
 },
	"status" : "active" ,
	"timestamp" : 1389640253 ,
	"revocationReason" : "unspecified" ,
	"pem" : "-----BEGIN CERTIFICATE-----\nMIIE4jCCA8qgAwIBAgISESHa7VrcABc10XWhUrsLeaqcMA0GCSqGSIb3DQEBBQUA\
 } 

Esquema

cursor

Los campos "next" y "prev" apuntan a las páginas anterior y siguiente. "after" es un identificador del último elemento de esta página. "before" es un identificador del primer elemento de esta página. Se llaman así porque "after" es el parámetro de consulta que se usaría para obtener la página siguiente, y "before" es el parámetro de consulta que se usaría para obtener la página anterior.

 {
 “paging” {
 “after”: elemnt identifier,
 “before”: element identifier,
 “next”: uri,
 “prev”: uri
 },
 “data”: [ element ]
 } 

componente de ruta

Una cadena con codificación porcentual . Se espera que un usuario de la interfaz web introduzca y vea el valor porcentual decodificado. Se espera que un usuario de la API realice la codificación y decodificación.

tiempoUnix

Un número entero que representa los milisegundos transcurridos desde la época de Unix. Esto se puede transformar fácilmente en un objeto de fecha en muchos lenguajes. Por ejemplo, en JavaScript:

var date = new Date(unixTime)

impresión del pulgar

Un hachís de algo.

 {
	"alg" : hashAlgorithm,
	"hash" : base64 hash
 } 

algoritmo hash

El conjunto de posibles algoritmos hash podría aumentar en el futuro, pero ningún elemento será eliminado. Actualmente, la lista es la siguiente:

"SHA-256"

agente

 {
 “name”: pathComponent,
 “lastHeartbeat”: unixTime,
 “apiCertificate”: {
 “thumbprint”: thumbprint,
 “pem”: certificate in PEM format
 }
 } 

cuenta

 {
 “lastAgentUpdateTimestamp”: unixTime,
 “lastAgentHeartbeatTimestamp”: unixTime,
 “name”: pathComponent,
 “cas”: [ certificateAuthority ],
 “agents”: [ uri ],
 “contacts”: [ email address ],
 “creationTimestamp”: unixTime
 } 

autoridad de certificación

 {
 “name”: JSON String,
 “validCerts”: positive integer,
 “revokedCerts”: positive integer,
 “totalCerts”: positive integer
 } 

certificado

 {
 “thumbprint”: thumbprint,
 “status”: status,
 “timestamp”: unixTime,
 “revocationReason”: reason,
 “pem”: certificate in PEM format
 } 

estado

Una de las siguientes cadenas:

"sostener"
"activo"
"revocado"
"suspendido"

razón

Una de las siguientes cadenas:

"sin especificar"
"keyComprimise"
"caComprimir"
"aaComprimir"
"afiliación cambiada"
"reemplazado"
"ceseDeOperación"
"certificado en posesión"
"eliminarDeCrl"
"privilegio retirado"

error

 {
 “error”: string
 }