DSS API

Vista general

Redtrust es un gestor corporativo de certificados de autenticación y firma que permite su uso de forma centralizada, segura y controlada.

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

Este documento está dirigido a integradores que deseen utilizar el servidor de firma DSS de Redtrust.

Métodos

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

El servicio ofrece tres métodos principales:

1. GetAccessibleCertificates

Esta operación recupera la lista de certificados disponibles para el usuario autenticado, según las políticas de autorización de Redtrust.

Para llamarla, autentícate como el usuario cuyos certificados deseas consultar. La respuesta incluye un objeto Result con la lista de certificados accesibles.

2. SignHash

Esta operación realiza una firma digital sobre un hash previamente calculado utilizando el certificado seleccionado.

Debes llamar a la operación SignHash y proporcionar:

• El hash que se va a firmar
• El tipo de firma
• Los datos de identificación del certificado

El servicio genera una firma en formato PKCS#1. Las secciones siguientes ofrecen más detalles y ejemplos.

3. SignRequest

Realiza una operación completa de firma de documentos basada en el estándar DSS de OASIS.

Para usar esta operación, envía un objeto SignRequest válido conforme al esquema DSS y sus extensiones. Este objeto debe contener toda la información necesaria para generar una firma válida.

El servidor responde con un objeto SignResponse que contiene:

• Un código de respuesta y un mensaje
• El resultado del proceso de firma

Consulta la especificación OASIS para la estructura de estos objetos:

• signRequest
• signResponse

Las siguientes secciones explican los elementos requeridos para que puedas construir solicitudes válidas e interpretar las respuestas.

Autenticación

Puedes enviar solicitudes de firma a tres enlaces distintos, según el tipo de autenticación que desees usar (suponiendo que utilizas SOAP 1.2). Debes reemplazar REDTRUST_ID por el DNS o la IP del servidor Redtrust.

Usuario y contraseña

• Utiliza cabeceras WS-Security UsernameToken.
• Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/basic

Autenticación con certificado

• Requiere un certificado de cliente TLS.
• Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/secure

Autenticación con JWToken

Este método permite autenticarse mediante un JSON Web Token (JWT) firmado, incluido en la cabecera SOAP como un BinarySecurityToken.

• Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/jwtoken
• Cabecera de ejemplo:

    <soapenv:Envelope
        xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:urn="urn:evolium:redtrust:dss:ws">
    
    <soapenv:Header>
        <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
            urn:evolium:redtrust:dss:ws/RTDSSService/GetAccessibleCertificates
        </wsa:Action>
        <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
            https://localhost:8080/RTDSSService.svc/jwtoken
        </wsa:To>
        <wsse:Security >
        <wsse:BinarySecurityToken
            ValueType="urn:custom:jwt"
            EncodingType="urn:custom:jwt">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoie1widXNlcm5hbWVcIjpcImRldmVsb3BlclwiLFwidXNlcl9pZFwiOjEsXCJkb21haW5cIjpcImxvY2FsLnVzZXJzXCIsXCJyZWZlcmVuY2VcIjpcImE0YjlhYTg1OWQxNTA5YWRjNTE5NDgyM2ExNmFlNDM2YTQ3ZjUwZjI3ZWZjNjU2ODUyMTg5ZWI5NjY4NDBkNGZcIixcImNvbnN1bWVyXCI6XCJEU1NcIn0iLCJuYmYiOjE3NTAwNzc4ODAsImV4cCI6MTc1MDA3ODE4MCwiaWF0IjoxNzUwMDc3ODgwLCJpc3MiOiJSZWR0cnVzdCBBdXRoIEFQSSIsImF1ZCI6IkRTUyJ9.KzNJl0lDEw2rJ7qQZ3dLKMFI9HpugBdGN5j_zRz6_XI</wsse:BinarySecurityToken>
        </wsse:Security>
    </soapenv:Header>
    
    <soapenv:Body>
        <urn:GetAccessibleCertificates/>
    </soapenv:Body>

    </soapenv:Envelope>

El token debe ser generado por Redtrust.

Transporte y seguridad

La API DSS de Redtrust utiliza SOAP 1.1 o 1.2 sobre HTTPS para el intercambio de solicitudes y respuestas.

Requisitos de la solicitud

• Solo se puede incluir un elemento <SignRequest> en el cuerpo SOAP.
• No se deben incluir elementos XML adicionales en el cuerpo.
• Se debe usar codificación UTF-8.
• Se permiten cabeceras SOAP arbitrarias.

Formato de la respuesta

• El servidor devuelve un elemento <SignResponse> o una falta SOAP.
• No se incluyen elementos XML adicionales en el cuerpo.
• Si hay un error de formato o protocolo, se devuelve una falta SOAP.
• Si la solicitud es válida, se devuelve un código de resultado DSS (incluso si la firma falla).
• Se usa codificación UTF-8.
• Se permiten cabeceras SOAP arbitrarias.

Protocolos de seguridad

La API DSS de Redtrust cumple con los siguientes estándares WS:

• WS-Security 1.1
• WS-Trust (febrero de 2005)
• WS-SecureConversation (febrero de 2005)
• WS-SecurityPolicy 1.1

WSDL

Para descargar el WSDL con la definición completa del servicio, accede a la siguiente URL:

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

Por defecto, el puerto de conexión es 8080, aunque puede configurarse desde la consola de administración de Redtrust. También por defecto, el protocolo es HTTPS y el certificado del servicio se genera automáticamente durante la instalación, aunque puede modificarse desde la consola. Para que un cliente confíe en el servidor, necesitará la parte pública del certificado, a menos que acepte cualquier certificado.

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

Detalles del protocolo

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>