Versión: Siguiente

DSS API

Vista general

Redtrust es un gestor corporativo de certificados de autenticación y firma que permite su uso de modo centralizado, seguro y controlado.

Aprovechando la centralización de certificados, Redtrust ofrece un servicio de firma para la realización de firma simple y avanzada, siguiendo con el estándar DSS (Digital Signature Service) de OASIS (https://www.oasis-open.org/committees/dss/) y algunas de sus extensiones.

Este documento va destinado a los integradores que quieran hacer uso del servidor DSS de firmas de Redtrust.

Contexto

El servicio de firma de documentos de Redtrust cumple con el estándar DSS de OASIS y algunas extensiones del mismo.

El servicio se compone de tres métodos: (1) un método para recuperar los certificados accesibles para ser usados para firmar con el servicio DSS (a través de las políticas de autorización de Redtrust), (2) otro para realizar firmas utilizando el estándar DSS, y (3) otro para realizar firmas hash.

Para recuperar la lista de certificados a los que se tiene acceso, hay que hacer una llamada al método GetAccessibleCertificates autenticado como el usuario del que quieres recuperar la lista de certificados, y como respuesta obtendrás un objeto Result con la información de la petición.

Para realizar firmas de un hash se ha de realizar una llamada al método SignHash, al cual se le debe pasar el hash a firmar, el tipo de firma que se quiere realizar sobre el mismo e información sobre el certificado a usar. La firma generada es de tipo PKCS#1. En los siguientes apartados se hará una descripción más detallada del método y ejemplos de uso del mismo.

Para hacer una firma hay que hacer una llamada al método SignRequest, al cual se le debe pasar como parámetro un objeto de tipo signRequest. Este objeto debe ser válido para el esquema DSS de OASIS y sus extensiones, y contener toda la información necesaria para que el servicio pueda generar una firma válida. Para obtener información detallada sobre el objeto signRequest puedes consultar la documentación de OASIS al respecto http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076052.

Como respuesta a una llamada al SignRequest se obtiene un objeto signResponse que, al igual que el signRequest, debe ser válido conforme el esquema DSS de OASIS y debe contener un código de respuesta más un mensaje y el resultado del proceso de firma dependiendo de si la firma se ha podido procesar o no. Para obtener información detallada sobre el objeto signResponse puedes consultar la documentación de OASIS al respecto http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076053.

Los siguientes apartados explican el contenido de estos objetos de manera que puedas componer un mensaje válido para el servicio y interpretar la respuesta.

Definición del servicio

Para descargar el WSDL con la definición completa del servicio puede acceder a la URL de su servidor de la siguiente manera:

https://IP_REDTRUST:8080/RTDSSService.svc?wsdl

Por defecto, el puerto de conexión es el 8080, pero este puerto es configurable a través de la web de administración de Redtrust. Del mismo modo, por defecto, el protocolo es HTTPS y el certificado del servicio se autogenera en el momento de la instalación, pero también puede configurarlo desde la web de administración. A la hora de implementar un cliente que acceda al servicio, debe tener en cuenta que necesitará la parte pública del certificado del servicio para que el cliente confíe en el servidor, a no ser que el cliente acepte cualquier certificado.

En el Apéndice 1: WSDL tiene el código WSDL necesario para generar el cliente en el lenguaje deseado.

Transporte y seguridad

En la capa de transporte, el intercambio de petición/respuesta se realiza mediante SOAP 1.1 o 1.2. Para la petición se aplican las siguientes reglas:

Únicamente un elemento <SignRequest> dentro del cuerpo del mensaje SOAP.
No se pueden incluir elementos XML adicionales dentro del SOAP.
La codificación debe ser UTF-8.
Pueden estar presentes cabeceras SOAP arbitrarias.

Para la respuesta se aplican estas:

El servidor devuelve un único elemento <SignResponse> dentro del cuerpo del mensaje SOAP, o un código de error SOAP.
El servidor no incluye elementos XML adicionales en el cuerpo SOAP.
El el caso que el servidor no pueda analizar una petición DSS, o hay algún error con el SOAP, el servidor devuelve un código de error SOAP. En cualquier otro caso devuelve un código de resultado DSS, tanto para firmas satisfactorias como para errores.
La codificación debe ser UTF-8.
Pueden estar presentes cabeceras SOAP arbitrarias.

El protocolo cumple con las especificaciones de seguridad WS-Security 1.1, WS-Trust de febrero de 2005, WS-SecureConversation de febrero de 2005 y WS-SecurityPolicy 1.1.

Existen dos enlaces a los que enviar las peticiones de firma dependiendo del tipo de autenticación que se desee (asumiendo que la versión del protocolo SOAP es 1.2). Debes reemplazar <Redtrust_IP> por el DNS o la IP del servidor Redtrust.

Usuario-Contraseña → https://<Redtrust_IP>:8080/RTDSSService.svc/basic

Certificado → https://<Redtrust_IP>:8080/RTDSSService.svc/secure

Optional inputs

Los OptionalInputs contienen información adicional asociada al procesamiento de la petición de firma.

El servicio de Redtrust contempla los siguientes OptionalInputs, algunos de ellos definidos como obligatorios, tal como se especifica a continuación:

Input genérico
`ServicePolicy`	Uso futuro.
`ClaimedIdentity`	Uso futuro.
`Language`	Define el idioma de los mensajes descriptivos contenidos en la respuesta del servicio (opcional).
`AdditionalProfile`	Uso futuro.
`Schemas`	Uso futuro.

Input de firma
`SignatureType`	Futuro uso en el timestamp.
`AddTimestamp`	Futuro uso en el timestamp.
`IntendedAudience`	Uso futuro.
`Properties`	Uso futuro.
`KeySelector`	Indica al servicio que certificado debe usar para la firma del documento mediante el thumbprint del mismo (obligatorio).
`AdditionalKeyInfo`	Especifica si el certificado especificado en `KeySelector` precisa de verificación por PIN (opcional).
`IncludeObject`	Especifica al servicio que se desea una firma de tipo enveloping (opcional).
`IncludeEContent`	Especifica al servicio que se desea una firma de tipo enveloped, válido para firmas CMS y CadES (opcional).
`SignaturePlacement`	Especifica al servicio que se desea una firma de tipo enveloped, válido para firmas XmlDsig y XadES (opcional).
`SignedReferences`	Uso futuro.
`SignatureForm`	Usado para determinar el nivel de la firma a realizar (opcional).
`VisibleSignatureConfiguration`	Usado para especificar la representación visual de la firma en firmas PadES (opcional).

Modos soportados

Redtrust permite hacer firmas en diferentes modos. El modo de firma indica al servidor como deben de empaquetarse la firma respecto al documento original de las siguientes maneras:

Enveloped: La firma está incluida dentro del documento.
Enveloping: El documento está dentro de la firma.
Detached: La firma es un objeto separado.

Este campo puede especificarse en la configuración del perfil de firma, de manera fija o dejándolo abierto, o enviándolo como parámetro en el SignRequest. En caso de que se especifique en el SignRequest este valor debe ser compatible con los valores especificados en el perfil de firma.

Dependiendo del tipo de documento a enviar se soportan uno o varios modos. Para indicar el modo en la llamada se usan los OptionalInputs dentro del SignRequest que ofrece el protocolo. Dependiendo del tipo de documento, la manera de especificar el modo es diferente:

Tipo de documento	Modo de firma soportado	Especificación
XML	Detached	No hay que especificar nada.
	Enveloped	Hay que especificar el campo `SignaturePlacement`. Consulta https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076071 para más información.
	Enveloping	Hay que especificar el campo `IncludeObject`. Consulta https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076069 para más información.
CMS	Detached	No hay que especificar nada.
	Enveloping	Hay que especificar el campo `IncludeEContent`. Consulte https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076070 para más información.
PDF	Enveloped	No hay que especificar nada.

Tanto SignaturePlacement como IncludeObject deben especificar el atributo WhichDocument, que contiene el identificador de documento que se va a firmar. Si el documento no se encuentra en el SignRequest el servidor devuelve un error de documento no encontrado.

Respuesta

<soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope”  xmlns:xd=”http://www.w3.org/2000/09/xmldsig#”> 
 <soap:Header> 
  … 
 </soap:Header> 
 <soap:Body> 
  <SignRequest Profile=”profile” RequestID=”dss-sign-request-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema”> 
   <OptionalInputs> 
   … 
  <IncludeObject WhichDocument=”ID-document-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema” /> 
   </OptionalInputs> 
   <InputDocuments> 
    <Document ID=”ID-document-1”> 
    … 
    </Document> 
   </InputDocuments> 
  </SignRequest> 
 </soap:Body> 
</soap:Envelope>

Niveles soportados

Redtrust permite realizar firmas en diferentes niveles. El nivel de firma indica al servidor qué objetos incluir en la misma. Cuanto más alto es el nivel, más información se incluye en la firma de manera que es más segura, pero también es más difícil de crear y validar. Los objetos que se pueden incluir en la firma son: la política de firma, sellos de tiempo (timestamp), certificados de la cadena del certificado que firma, validación de los certificados incluidos en la firma.

Este campo puede especificarse en la configuración del perfil de firma, de manera fija o dejándolo abierto, o enviándolo como parámetro en el SignRequest. En caso de que se especifique en el SignRequest este valor debe ser válido para los valores especificados en el perfil de firma.

Dependiendo del tipo de documento a enviar se soportan diferentes niveles:

XML y CMS
Básico	Forma más básica de firma, puede ser XMLDsig o CMS.
BES	Forma básica que simplemente cumple los requisitos legales de la Directiva para firma electrónica avanzada.
EPES	Forma básica a la que se la ha añadido información sobre la política de firma.
ES_T	Añade un campo de sellado de tiempo para proteger contra el repudio.
ES_C	Añade referencias a datos de verificación (certificados y listas de revocación) a los documentos firmados para permitir verificación y validación off-line en el futuro (pero no almacena los datos en sí mismos).
ES_X	Añade sellos de tiempo a las referencias introducidas por XadES-C para evitar que pueda verse comprometida en el futuro una cadena de certificados.
ES_XL	Añade los propios certificados y listas de revocación a los documentos firmados para permitir la verificación en el futuro incluso si las fuentes originales (de consulta de certificados o de las listas de revocación) no estuvieran ya disponibles.
ES_A	Añade la posibilidad de sellado de tiempo periódico (por ejemplo cada año) de documentos archivados. Esto previene que lod documentos puedan ser comprometidos debido a la debilidad de la firma durante un periodo largo de almacenamiento.

PDF
BES	Forma básica que cumple los requisitos legales de la directiva para firma electrónica avanzada.
EPES	Forma básica a la que se la ha añadido información sobre la política de firma.
LTV	Equivalente a ES_A.

Para indicar el nivel en la llamada se usa un OptionalInput dentro del SignRequest:

<SignatureForm xmlns=”urn:evolium:Redtrust:dss:1.0:core:schema”>XXX</SignatureForm>

El valor del tag debe contener uno de los siguientes valores:

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:BES

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:EPES

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-T

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-C

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-1

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-2

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-L-1

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-L-2

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-A

urn:oasis:names:tc:dss:1.0:profiles:PadES:forms:LTV

Encapsulamiento

Redtrust permite incluir el documento en la petición de firma de diferentes maneras.

Este campo tiene que venir definido en el SignRequest dentro del elemento InputDocuments. Redtrust actualmente soporta elementos de tipo Document pero no soporta los elementos TransformedData y DocumentHash. Para más información sobre el elemento InputDocuments puede consultar https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076032. Para más información sobre Document puede consultar https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076034.

Dependiendo del tipo de documento a enviar se soportan los siguientes encapsulamientos:

XML

Base64Xml: Contenido del XML en base64. InlineXml: Contenido del XML directamente incrustado. EscapedXml: Contenido del XML escapado.

CMS y PDF

Base64Data: Contenido del fichero codificado en base64. Se debe especificar el tipo de documento que se va a enviar mediante el atributo MimeType. Los MimeType admitidos son application/pdf para archivos PDF y text/plain o application/binary para CMS.

Respuesta

<soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope”  xmlns:xd=”http://www.w3.org/2000/09/xmldsig#”> 

 <soap:Header> 
  … 
 </soap:Header> 
 <soap:Body> 
  <SignRequest Profile=”profile” RequestID=”dss-sign-request-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema”> 
   <OptionalInputs> 
    … 
    <SignaturePlacement WhichDocument=”ID-document-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema” /> 
   </OptionalInputs> 
   <InputDocuments> 
    <Document ID=”ID-document-1”> 
     <Base64Data MimeType=”application/pdf”>…</Base64Data> 
    </Document> 
   </InputDocuments> 
  </SignRequest> 
 </soap:Body> 
</soap:Envelope> 

Vista general​

Contexto​

Definición del servicio​

Transporte y seguridad​

Optional inputs​

Modos soportados​

Niveles soportados​

Encapsulamiento​