Referencia de la API DSS

Esta página describe las reglas transversales y los campos comunes de la API DSS de Redtrust:

• cómo se realiza la autenticación
• cómo deben estructurarse los mensajes SOAP
• cómo se expresan los modos de firma, los niveles y la encapsulación de documentos

Si quieres una guía paso a paso, empieza por el tutorial.
Si quieres payloads listos para copiar y pegar para escenarios habituales, usa la página de ejemplos.

Endpoints y autenticación

Redtrust expone tres endpoints de servicio (los ejemplos siguientes asumen SOAP 1.2):

Usuario y contraseña

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

Autenticación mediante certificado

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

Autenticación mediante JWToken

• Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/jwtoken
• Te autenticas mediante un JWT firmado en la cabecera SOAP como BinarySecurityToken.
• Redtrust genera el token.

Transporte y restricciones de mensajes

La API DSS de Redtrust utiliza SOAP 1.1 o 1.2 sobre HTTPS para todos los intercambios de peticiones y respuestas.

Restricciones de las peticiones

• Incluye solo un elemento SignRequest en el cuerpo SOAP.
• No incluyas elementos adicionales dentro del cuerpo SOAP.
• Usa codificación UTF-8.
• Puedes incluir cabeceras SOAP arbitrarias.

Restricciones de las respuestas

• El servidor devuelve un elemento SignResponse o un SOAP fault.
• No aparecen elementos XML adicionales en el cuerpo SOAP.
• Cuando el servidor no puede analizar la petición DSS o encuentra un error SOAP, se devuelve un SOAP fault.
• Cuando el servidor procesa correctamente la petición, devuelve un código de resultado DSS, incluso si la operación de firma falla.
• Se utiliza codificación UTF-8.
• Pueden aparecer cabeceras SOAP arbitrarias.

Protocolos de seguridad

La API DSS de Redtrust cumple 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, puedes acceder a la URL de tu servidor de la siguiente forma:

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

Por defecto, el servicio escucha en el puerto 8080. Puedes configurar el puerto y el certificado HTTPS en la consola de administración de Redtrust. Tu cliente debe confiar en el certificado del servicio, salvo que lo configures para aceptar cualquier certificado.

Consulta WSDL.

Campos comunes de SignRequest

Los trabajos de firma se envían mediante SignRequest (cuerpo SOAP). La petición utiliza:

• Profile (el perfil de firma configurado en Redtrust)
• RequestID (opcional, pero muy recomendable para trazabilidad)
• OptionalInputs (opciones comunes como selección de certificado y forma de firma)
• InputDocuments (el documento que quieres firmar)

Entradas opcionales

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

info

Algunos inputs opcionales definidos por la especificación OASIS DSS no se utilizan actualmente en Redtrust. Estos campos se aceptan por compatibilidad con el esquema, pero no tienen ningún efecto en el proceso de firma.

Los siguientes inputs no están soportados actualmente:

• ServicePolicy
• ClaimedIdentity
• AdditionalProfile
• Schemas
• SignatureType
• AddTimestamp
• IntendedAudience
• Properties
• SignedReferences

Entrada genérica
Language	Define el idioma de los mensajes descriptivos contenidos en la respuesta del servicio (opcional).

Entrada de firma
KeySelector	Indica al servicio qué certificado debe usarse para firmar el documento mediante su huella digital (obligatorio). Este mecanismo es específico de la implementación DSS de Redtrust y se utiliza en todos los perfiles de firma.
AdditionalKeyInfo	Indica si el certificado especificado en KeySelector requiere verificación mediante PIN (opcional).
IncludeObject	Indica al servicio que se desea una firma en modo enveloping (opcional).
IncludeEContent	Indica al servicio que se desea una firma en modo enveloped; válido para firmas CMS y CAdES (opcional).
SignaturePlacement	Indica al servicio que se desea una firma de tipo enveloped; válido para firmas XmlDSig y XAdES (opcional).
SignedReferences	Uso futuro.
SignatureForm	Determina el nivel de la firma que se va a generar (opcional).
VisibleSignatureConfiguration	Especifica la representación visual de la firma en firmas PAdES (opcional).

La parte de representación visual de la firma se encuentra dentro de la etiqueta VisibleSignatureConfiguration y contiene:

Entrada	Descripción
VisibleSignaturePolicy	Contiene el texto GeneralPolicy, que es la única política de representación visual admitida por Redtrust.
VisibleSignaturePosition	Especifica la posición (contando desde la esquina inferior izquierda) y el tamaño en píxeles de la visualización.
VisibleSignatureItemsConfiguration	Contiene una secuencia de elementos que indican cómo será la firma visible.

Modos de firma soportados

Redtrust permite realizar firmas en distintos modos. El modo de firma indica al servidor cómo debe empaquetarse la firma con respecto al documento original de las siguientes formas:

• Enveloped: La firma se incluye dentro del documento.
• Enveloping: El documento se incluye dentro de la firma.
• Detached: La firma es un objeto independiente.

El campo de modos compatibles puede especificarse en la configuración del perfil de firma, ya sea como un valor fijo o dejándolo abierto, o bien pasarse como parámetro en el SignRequest. Si proporcionas un valor en el SignRequest, debe ser compatible con los valores definidos en el perfil de firma.

Se admite uno o varios modos según el tipo de documento que se envíe. Los OptionalInputs del SignRequest definidos por el protocolo se utilizan para indicar el modo en la llamada. La forma de especificar el modo varía en función del tipo de documento:

Tipo de documento	Modo de firma compatible	Especificación
XML	Detached	No se requiere ninguna especificación.
	Enveloped	Debes especificar el campo SignaturePlacement. Consulta https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076071 para obtener más información.
	Enveloping	Debes especificar el campo IncludeObject. Consulta https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076069 para obtener más información.
CMS	Detached	No se requiere ninguna especificación.
	Enveloping	Debes especificar el campo IncludeEContent. Consulta https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076070 para obtener más información.
PDF	Enveloped	No se requiere ninguna especificación.

Cuando utilices SignaturePlacement o IncludeObject, establece WhichDocument con el identificador del documento que quieres firmar.

Niveles de firma soportados

El nivel de firma indica al servidor qué objetos debe incluir en la firma, por ejemplo la política de firma, los sellos de tiempo, los certificados de la cadena del certificado de firma y la validación de los certificados incluidos en la firma. Los niveles más altos incluyen más datos y ofrecen mayor seguridad, pero requieren más procesamiento.

XML y CMS

Nivel	Descripción
Basic	Forma más básica de firma, puede ser XMLDsig o CMS.
BES	Forma básica que cumple los requisitos legales de la directiva para la firma electrónica avanzada.
EPES	Forma básica a la que se ha añadido información de la política de firma.
ES_T	Añade un campo de sello de tiempo para proteger frente a la repudiación.
ES_C	Añade referencias a los datos de verificación (certificados y listas de revocación) a los documentos firmados para permitir la verificación y validación sin conexión en el futuro (pero no almacena los datos en sí).
ES_X	Añade sellos de tiempo a las referencias introducidas por XAdES-C para evitar que una cadena de certificados se vea comprometida en el futuro.
ES_XL	Añade certificados y listas de revocación a los documentos firmados para permitir la verificación futura incluso si las fuentes originales (búsqueda de certificados o listas de revocación) ya no están disponibles.
ES_A	Añade la posibilidad de aplicar sellos de tiempo periódicos (por ejemplo, cada año) a documentos archivados. Esto evita que los documentos se vean comprometidos por firmas débiles durante un periodo de almacenamiento prolongado.

PDF

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

SignatureForm

Para establecer un nivel, añade SignatureForm dentro de OptionalInputs y utiliza uno de los URN compatibles. Deben seguir este formato:

SignatureForm xmlns="urn:evolium:Redtrust:dss:1.0:core:schema">URN</

El valor del URN debe ser uno de los siguientes:

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

Encapsulación de documentos

Proporcionas el documento que quieres firmar en InputDocuments dentro del SignRequest. Actualmente, Redtrust admite elementos Document, pero no admite los elementos TransformedData ni DocumentHash.

info

Para obtener más información, consulta las secciones InputDocuments y Document de la documentación de Oasis.

Se admiten las siguientes encapsulaciones según el tipo de documento que se envíe:

XML

Base64Xml: contenido XML en base64.
InlineXml: contenido XML incrustado directamente.
EscapedXml: contenido XML escapado.

CMS y PDF

Base64Data: contenido del archivo codificado en base64. Debes especificar el tipo de documento que se envía mediante el atributo MimeType.

Los valores de MimeType compatibles incluyen application/pdf para archivos PDF y text/plain o application/binary para CMS.