Versions Compared

Version Old Version 2 New Version Current
Changes made by

Servicios Digitales de Aragón

Servicios Digitales de Aragón

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

A continuación se de detalla cada uno de los servicios de los cuales dispone la API Rest de SIFE

Code Block
Base_URL: preaplicaciones.aragon.es/sife/services

1.- Servicios

Todos los servicios del API están autenticados. Se requiere un código de aplicación y una contraseña

...

Code Block
Authorization: BasicX YWNjb3VudDE6MTExMTExMTA=

1.1.- Digital Signature Service

Conjunto de métodos que permiten realizar operaciones de firma electrónica, firmar, elevar una firma, validar certificado, validar una firma, validar un timestamp, etc. Se trata de un servicio REST que se encuentra disponible en ${Base_URL}/v1/dss/

1.1.1.- Metodo 'extendSignature”

...

Método que eleva la firma que se le pasa como parámetro a un nivel superior, por ejemplo de CAdES-B a CAdES-T o CAdES-A.

...

El método 'extendSignature' no modificará los datos almacenados en CCSV en ningún momento, únicamente realizará la elevación y devolverá el resultado.

Petición

Nombre

Tipo

Descripción

ExtensionParameters

ExtensionParameters

Parámetros necesarios para la elevación de una firma

...

  • Tanto para el atributo “signature” como para el atributo “detachedContent” en el caso de que se establezca un CSV, se va a intentar cargar la información de la firma y del documento desde el repositorio documental respectivamente. En el caso de que no exista se producirá un error

  • Para el atributo “signature”, en el caso de no indicar CSV, es obligatorio completar los valores de “data”. Si esto no se hace se devolverá un error.

  • El atributo detachedContent es opcional, únicamente se completará si se está intentando realizar la elevación de una firma detached. En cuyo caso es necesario completar,

    • Si se utiliza el documento completo para la elevación, el valor de “data”

    • Si se utiliza el hash del documento, el valor de “digestValue” y “digestAlgorithm”.

Respuesta

En el caso de que la operación se realice de forma satisfactoria, SIFE devolverá un código 200 y el cuerpo de la respuesta tendrá la siguiente estructura

...

No todos los errores están controlados y se manda como respuesta con estructura JSON. A la hora de procesar la respuesta hay que tener esto en cuenta.

Ejemplos de invocación

A continuación se muestran ejemplos de invocación al método, en concreto se muestra el JSON que debe contener el body de la llamada POST.

...

Elevación CAdES-A documento completo

Code Block
{
   "signature":{
      "data":"PGRzOlNpZ25hdHVyZSB4bWxucz"   # Firma a elevear codificada en base 64
   },
   "detachedContent":{
      "digestValue":"Ca/QShcf4w",           # Hash del documento codificado en base 64
      "digestAlgorithm":"SHA256"            # Algoritmo utilizado el cálculo del Hash
   },
   "signatureLevel":"CAdES_A"               # Nivel al que se quiere elevar la firma
}

1.1.2.- Metodo 'validateSignature”

...

Verifica una firma contra @firma. Se debe enviar la firma a verificar y el documento original si la firma es detached. Este método puede invocarse pasando como parámetro el contenido completo del documento, a través de su hash o indicando su CCSV.

Se devolverá un informe de verificación con el resultado, indicando si la firma es válida, o si la firma es inválida o la razón por la cual no se ha verificado correctamente la firma.

Petición

Nombre

Tipo

Descripción

Params

VerificationParameters

Parámetros necesarios para la verificación de la firma

...

  • Tanto para el atributo “signature” como para el atributo “detachedContent” en el caso de que se establezca un CSV, se va a intentar cargar la información de la firma y del documento desde el repositorio documental respectivamente. En el caso de que no exista se producirá un error

  • Para el atributo “signature”, en el caso de no indicar CSV, es obligatorio completar los valores de “data”. Si esto no se hace se devolverá un error.

  • El atributo detachedContent es opcional, únicamente se completará si se está intentando realizar la validación de una firma detached. En cuyo caso es necesario completar,

    • Si se utiliza el documento completo para la elevación, el valor de “data”

    • Si se utiliza el hash del documento, el valor de “digestValue” y “digestAlgorithm”.

Respuesta

En el caso de que la operación se realice de forma satisfactoria, SIFE devolverá un código 200 y el cuerpo de la respuesta tendrá la siguiente estructura

...

No todos los errores están controlados y se manda como respuesta con estructura JSON. A la hora de procesar la respuesta hay que tener esto en cuenta

Ejemplos de invocación

A continuación se muestran ejemplos de invocación al método, en concreto se muestra el JSON que debe contener el body de la llamada POST.

...

Verificación de la firma a partir del hash del documento

Code Block
{
   "signature":{
      "data":"MIIclAYJKoZIhvcNAQc"        # Firma a validar codificada en base 64
   },
   "detachedContent":{
      "digestValue":"Ca/QShcf4w/CRE"      # Hash del documento codificado en base 64
      "digestAlgorithm":"SHA512"          # Algoritmo utilizado el cálculo del Hash
   },
   "signatureFormat":"CAdES"              # Formato de la firma
}

2.- Anexos

2.1.- Objetos comunes

2.1.1.- ExtensionParameters

Nombre

Tipo

Descripción

signature

SifeDocument

Firma a elevar

detachedContent

SifeDocument

Origen de datos correspondiente con la firma en caso de firmas detached

signatureLevel

SignatureLevel

Nivel deseado para la firma (T,XL, A)

2.1.2.- SifeDocument

Nombre

Tipo

Descripción

digestValue

String

Hash del documento codificado en base 64

digestAlgorithm

DigestAlgorithm

Algoritmo de digest utilizado para calcular el hash

data

String

Documento codificado en base 64

mimetype

String

Tipo del documento.

Ej: application/pdf, application/xml

csv

String

Identificador del documento en CCSV

csvSignatureId

String

Identificador de la firma del documento en CCSV

sifeIdentifer

String

Identificador interno de SIFE para documentos temporales

name

String

Nombre del documento

2.1.3.- VerificationReport

Nombre

Tipo

Descripción

validationTime

String

Fecha en la que se ha realizado la validación de la firma 

Ej: 2020-05-05T13:19:56Z

signatures

List<SignatureStatus>

Estado de cada una de las firmas que contiene la firma original

indication

Indication

Resultado global de la validación de la firma

errors

List<VerificationError>

Errores en la verificación

signatureLevel

SignatureLevel

Nivel de firma

signatureFormat

SignatureFormat

Formato de firma

2.1.4.- SignatureStatus

Nombre

Tipo

Descripción

indication

Indication

Resultado global de validación de la firma

errors

List<VerificationError>

Errores en la verificación

signingDate

String

Fecha de firma

Ej: 2020-05-05T13:19:56Z

signatureExpirationDate

String

Fecha de caducidad de la firma. Correspondera a la fecha de firma o a la fecha del sello de tiempo si la hay

Ej: 2020-05-05T13:19:56Z

policy

String

Datos de la politica de firma seguida

signatureLevel

SignatureLevel

Nivel de firma

signingCertificate

CertificateStatus

Certificado de firma utilizado

certificates

List<CertificateStatus>

Certificados procesados

timestamps

List<TimeStampStatus>

Sellos de tiempo de la firma (si los hay)

2.1.5.- VerificationError

Nombre

Tipo

Descripción

code

String

Código del error producido

description

String

Descripción del error producido

2.1.6.- CertificateStatus

Nombre

Tipo

Descripción

serialNumber

String

Número de serie

subjectPrincipal

String

Titular

issuerPrincipal

String

Emisor

errors

List<VerificationError>

Errores en la verificación

validFrom

String

Fecha desde la que es válido

Ej: 2020-05-05T13:19:56Z

validTo 

String

Fecha hasta la que es válido

Ej: 2020-05-05T13:19:56Z

elements

Map<String, String>

Cada uno de los elementos extraídos del certificado (Vacío para certificados de sello de tiempo

status

Status

Estado de validación

x509Certificate

String

Contenido del certificado codificado en base 64

2.1.7.- TimestampStatus

Nombre

Tipo

Descripción

serialNumber

String

Numero de serie asignado por el prestador al token

indication

Indication

Resultado global de la validación del sello

errors

List<VerificationError>

Errores en la verificación

type

TimeStampType

Tipo de sello, de firma o de archivo

creationDate

String

Fecha del sellado de tiempo

Ej: 2020-05-05T13:19:56Z

tsaCertificate

CertificateStatus

Estado del certificado

timestampTokenData

String

Datos del sellado de tiempo codificados en base 64

timestampToken

TimestampToken

Token de sello

2.1.8.- TimestampToken

Nombre

Tipo

Descripción

serialNumber

String

Identificador del sello de tiempo

nonce

String

expires

String

Fecha de espiración

Ej: 2020-05-05T13:19:56Z

generationDate

String

Fecha de generación

Ej: 2020-05-05T13:19:56Z

encoded

String

Contenido del token codificado en base 64

hash

String

Hash del mensaje codificado en base 64

content

String

Contenido sobre el que se han realizado las acciones codificado en base 64

tsaName

String

tsaPolicyOID

String

certificates

List<String>

Certificados utilizados codificados en base 64

 

2.2.- Tipos enumerados

2.2.1.- SignatureLevel

Valor

XAdES_C

XAdES_X

XAdES_XL

XAdES_A

XAdES_BASELINE_LTA

XAdES_BASELINE_LT

XAdES_BASELINE_T

XAdES_BASELINE_B

CAdES_BASELINE_LTA

CAdES_BASELINE_LT

CAdES_BASELINE_T

CAdES_BASELINE_B

CAdES_C

CAdES_XL

CAdES_A

PAdES_BASELINE_LTA

PAdES_BASELINE_LT

PAdES_BASELINE_T

PAdES_BASELINE_B

PAdES_LTV

ASiC_S_BASELINE_LTA

ASiC_S_BASELINE_LT

ASiC_S_BASELINE_T

ASiC_S_BASELINE_B

ASiC_E_BASELINE_LTA

ASiC_E_BASELINE_LT

ASiC_E_BASELINE_T

ASiC_E_BASELINE_B

WSS

CMS_CMS

2.2.2.- DigestAlgorithm

Valor

SHA1

SHA224

SHA256

SHA384

SHA512

MD2

MD5

2.2.3.- Indication

Valor

VALID

INVALID

2.2.4.- SignatureFormat

Valor

XAdES

CAdES

PAdES

ASiC_S

ASiC_E

WSS

CMS

2.2.5.- Status

Nombre

Valor

GOOD

GOOD

REVOKED

REVOKED

EXPIRED

EXPIRED

UNKNOWN

UNKNOWN

NOT_CHECKED

NOT_CHECKED

2.2.6.- TimestampType

Nombre

Valor

SIGNATURE_TIMESTAMP

SIGNATURE_TIMESTAMP

ARCHIVE_TIMESTAMP

ARCHIVE_TIMESTAMP

 

2.1.- Errores generales al consumir la API

Causa

Código

Mensaje

Aplicación no encontrada en SIFE

401

User account not found

Aplicación no encontrada en PAU

401

Ha ocurrido un error al invocar a la plataforma de autorizacion de usuarios

La ip no está en la lista de ip's permitidas

403

El servicio no ha sido autorizado : La ip no está en la lista de ip's permitidas

Aplicación no autorizada para el uso de un método en particular

403

El servicio no ha sido autorizado : No se ha encontrado una relación entre las dos aplicaciones

Operación que utiliza un sello de órgano no permitido

400

STAMP_NOT_AUTHORIZED

...