Saltar al contenido principal
Versión: 4.41

Ejemplos de la API DSS

Esta sección proporciona ejemplos de peticiones y respuestas SOAP para operaciones habituales compatibles con la API DSS de Redtrust. Usa estos ejemplos como punto de partida al crear o probar peticiones DSS, o cuando quieras entender cómo se expresan escenarios de firma concretos mediante el protocolo DSS.

Si es la primera vez que trabajas con la API DSS, empieza por el tutorial Primeros pasos con la API DSS.

Todos los ejemplos de esta guía comparten las siguientes características:

  • Utilizan SOAP 1.2.
  • Los ejemplos de autenticación usan WS-Security UsernameToken. Algunas secciones también incluyen métodos de autenticación alternativos cuando es relevante.
  • Las peticiones se envían al endpoint de la API DSS expuesto por Redtrust.
  • Cada petición incluye una cabecera WS-Addressing Action que identifica la operación que se invoca.

En cada ejemplo se incluyen el sobre SOAP y la cabecera completos para que puedas copiar y pegar las peticiones directamente al realizar pruebas.

Cómo usar estos ejemplos​

Estos ejemplos son intencionadamente mínimos y se centran en la estructura de las peticiones y respuestas DSS.

Se asume que:

  • Ya tienes acceso a un entorno de Redtrust con el servicio DSS habilitado
  • Sabes qué método de autenticación y qué endpoint debes usar
  • Tienes configurado un perfil de firma DSS válido en Redtrust
  • Ya conoces la huella digital del certificado que quieres usar

Para una guía paso a paso que incluya la configuración del entorno y de SoapUI, consulta el tutorial Primeros pasos con la API DSS.

Descubrimiento de certificados GetAccessibleCertificates​

Usa este ejemplo para obtener la lista de certificados disponibles para el usuario autenticado. Puedes añadir un filtro con los valores ecc o eidas.

   <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:dss:ws">
      <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
         <wsse:Security 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">
            <wsse:UsernameToken wsu:Id="0001">
               <wsse:Username>USERNAME</wsse:Username>
               <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
               <wsu:Created>2024-11-15T11:28:30.080Z</wsu:Created>
            </wsse:UsernameToken>
         </wsse:Security>
         <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/GetAccessibleCertificates</wsa:Action>
         <wsa:To>https://IP_REDTRUST:8080/RTDSSService.svc/basic</wsa:To>
      </soap:Header>
      <soap:Body>
         <urn:GetAccessibleCertificates/>
            <urn:filter></urn:filter>
      </soap:Body>
   </soap:Envelope>

El ejemplo devuelve los certificados sobre los que el usuario usuario@dominio tiene permisos en el servicio de firma. Estos certificados incluyen tanto los personales del usuario como aquellos a los que tiene acceso mediante una política.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/GetAccessibleCertificatesResponse</a:Action>
   </s:Header>
   <s:Body>
      <GetAccessibleCertificatesResponse xmlns="urn:evolium:redtrust:dss:ws">
         <Result xmlns:b="http://schemas.datacontract.org/2004/07/RTDSSService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <b:ResultStatus>SUCCESS</b:ResultStatus>
            <b:ResultMessage>Operation finalized successfully</b:ResultMessage>
            <b:ResultData i:type="b:ArrayOfCertificate">
               <b:Certificate>
                  <b:X509Data>...</b:X509Data>
                  <b:alias>EIDAS CERTIFICADO PRUEBAS - 99999999R</b:alias>
                  <b:certificateHandler>6017</b:certificateHandler>
                  <b:expiration>2024-11-05T14:04:20</b:expiration>
                  <b:issuer>Ceres</b:issuer>
                  <b:needPin>false</b:needPin>
                  <b:needReason>false</b:needReason>
                  <b:subject>EIDAS CERTIFICADO PRUEBAS - 99999999R</b:subject>
                  <b:thumbprint>06F13CCD80E271D5355B3BEA322B8CBCE25B35F6</b:thumbprint>
                  <b:type>PRIVATE</b:type>
               </b:Certificate>
            </b:ResultData>
            <b:TotalItems>1</b:TotalItems>
         </Result>
      </GetAccessibleCertificatesResponse>
   </s:Body>
</s:Envelope>

Firma basada en hash con SignHash​

Usa este ejemplo cuando quieras generar una firma (PKCS#1) a partir de un hash precomputado. Puedes especificar tanto el identificador como la huella digital del certificado elegido para realizar la llamada.

nota

La funcionalidad de firma de hashes no está habilitada por defecto con la licencia del servicio de firma y debe solicitarse al equipo de soporte.

Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:dss:ws">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
        <wsse:Security 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">
            <wsse:UsernameToken wsu:Id="UsernameToken-5F01A1638C9F9A33A1173167092288930">
                <wsse:Username>USERNAME</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
                <wsu:Created>2024-11-15T11:42:02.889Z</wsu:Created>
            </wsse:UsernameToken>
        </wsse:Security>
        <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignHash</wsa:Action>
        <wsa:To>https://IP_REDTRUST:8080/RTDSSService.svc/basic</wsa:To>
    </soap:Header>
   <soap:Body>
      <urn:SignHash>
         <!--Optional:-->
         <urn:toSignHashB64>ybWpO/j3yCfUhzWEWqdHcDgyQ8l5CWwea6Hj+GpI2CA=</urn:toSignHashB64>
         <!--Optional:-->
         <urn:thumbprint>THUMBPRINT</urn:thumbprint>
         <!--Optional:-->
         <!--<urn:certificatePin>?</urn:certificatePin>-->
         <!--Optional:-->
         <urn:algorithm>RSA_SHA256</urn:algorithm>
      </urn:SignHash>
   </soap:Body>
</soap:Envelope>
Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignHashResponse</a:Action>
   </s:Header>
   <s:Body>
      <SignHashResponse xmlns="urn:evolium:redtrust:dss:ws">
         <Result xmlns:b="http://schemas.datacontract.org/2004/07/RTDSSService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <b:ResultStatus>SUCCESS</b:ResultStatus>
            <b:ResultMessage>Operation finalized successfully</b:ResultMessage>
            <b:ResultData i:type="c:string" xmlns:c="http://www.w3.org/2001/XMLSchema">JCtCs3wdvCl1Ql0tstzkMczNmNxcnaLNospXPB/miOi++fbG+jP6dTRvBwhJ4triE8TXxXMs5aVyCkl0oj+WumoO2zRGZSSk1mcbjrYuKP8m+gj5yp0bOGGPbvAIaphhqV87oU+2kcyCtNt32E0QQGRGW6kr+ADPctOFOD5loV84hRUqAw8AJQX20XjlKtzkhaDGBQFMGVUODAId/ywpxCYIQOetRXWcLfCNHQE/C4+jaNwamvPTGlVhn0Vr6xWAoN0/BKBk5eDVOynX7J2zl7TErkVrZ4WA2cIbxxuq2vj1MUMV89dDB54E4cc7UduYKzMIj0iEJ+19NL47NM96iQ==</b:ResultData>
         </Result>
      </SignHashResponse>
   </s:Body>
</s:Envelope>

Firma DSS con SignRequest​

Todas las firmas basadas en documentos en la API DSS se realizan mediante la operación SignRequest.

Aunque los ejemplos de esta sección se centran en distintos estándares de firma (XAdES, CAdES, PAdES), niveles (BES, T, LTV, EPES) y modos (enveloped, enveloping, detached), todos comparten la misma estructura de alto nivel de la petición.

  • Cabecera SOAP con WS-Security y WS-Addressing
  • SignRequest: especifica un perfil de firma
  • OptionalInputs: conjunto de entradas opcionales (selección de certificado, forma de firma y funcionalidades opcionales) que controlan cómo se genera la firma
  • InputDocuments: documento de entrada que se va a firmar

El propio elemento SignRequest es común a todos los escenarios de firma. Las diferencias entre firmas XAdES, CAdES y PAdES, así como entre niveles (BES, T, LTV, EPES) y modos (enveloped, enveloping, detached), se expresan mediante:

  • El atributo Profile, que identifica el perfil de firma definido en Redtrust.
  • Un elemento KeySelector, que se utiliza para seleccionar el certificado de firma (normalmente mediante la huella digital).
  • Un elemento Document dentro de InputDocuments, que contiene los datos que se van a firmar.

Los siguientes ejemplos se centran en estas diferencias.

Expresar el modo de firma​

El modo de firma define cómo se relaciona la firma con el documento firmado.

El modo puede quedar fijado en la configuración del perfil de firma o dejarse abierto y proporcionarse en la SignRequest. Si se indica un modo en la petición, debe ser compatible con los valores definidos en el perfil de firma.

Los siguientes fragmentos muestran cómo expresar cada modo en la petición.

XML enveloping
<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="DSS_PROFILE" RequestID="" 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>
XML enveloped
<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="DSS_PROFILE" RequestID="" 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>

XAdES​

XAdES (XML Advanced Electronic Signature) es un conjunto de extensiones de XmlDSig que lo hacen adecuado para la firma electrónica, de acuerdo con la Directiva 1999/93/CE de la Unión Europea. Uno de los puntos fuertes de XAdES es que los documentos firmados electrónicamente mediante este sistema pueden mantenerse válidos durante largos periodos de tiempo.

XAdES BES​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma XAdES de nivel BES en modo enveloped, enveloping o detached. El nivel BES es el más básico de las firmas avanzadas, tal como se describe en la sección Niveles soportados. Cada modo se describe en Modos soportados.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para XAdES. El nombre debe ser XAdES, con el nivel BES seleccionado (forzado o no), el modo enveloped seleccionado (forzado o no), el algoritmo de firma dependerá del certificado (normalmente RSA) y el algoritmo de digestión será SHA256.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar un certificado personal.
XAdES BES enveloped​
Petición

En este ejemplo:

  • SignatureForm se establece en XAdES BES.
  • SignaturePlacement especifica el modo enveloped y el documento que se va a firmar.
  • El documento XML se proporciona como Base64XML.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="XAdES-BES-Enveloped-RSA-SHA256" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
            <SignaturePlacement WhichDocument="ID-document-1"/>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64XML>...</Base64XML>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>
Respuesta

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor, una etiqueta SignaturePtr, que es una referencia a la ubicación del documento dentro de la respuesta, y, por último, la etiqueta Base64XML, que contiene el documento con la firma incrustada codificada en Base64.

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="XAdES-BES-Enveloped-RSA-SHA256" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <OptionalOutputs>
            <dss:DocumentWithSignature xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:rt="urn:evolium:redtrust:dss:1.0:core:schema" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#">
               <dss:Document ID="ID-document-1">
                  <dss:Base64XML>...</dss:Base64XML>
               </dss:Document>
            </dss:DocumentWithSignature>
         </OptionalOutputs>
         <SignatureObject>
            <SignaturePtr WhichDocument="ID-document-1"/>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>
XAdES BES enveloping​

En este ejemplo:

  • SignatureForm se establece en XAdES BES.
  • IncludeObject especifica el modo enveloping y apunta al documento.
  • El documento XML se proporciona como InlineXML.
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="XAdES enveloping" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
            <IncludeObject WhichDocument="ID-document-1"/>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <InlineXML>
                  <Document>
                     <Chapter>Text</Chapter>
                  </Document>
               </InlineXML>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene la firma con el documento incrustado codificado en Base64.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="XAdES enveloping" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3275">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>
XAdES BES detached​

En este ejemplo:

  • SignatureForm se establece en XAdES BES.
  • No se incluye ningún elemento de modo (SignaturePlacement / IncludeObject), por lo que la firma es detached (o el modo está forzado por el perfil).
  • El documento XML se proporciona como EscapedXML.
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="XAdES-BES-Detached" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <EscapedXML>&lt;Document>&lt;Chapter>Text&lt;/Chapter>&lt;/Document></EscapedXML>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene la firma codificada en Base64.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="XAdES-BES-Detached" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3275">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

XAdES T enveloped​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma XAdES de nivel T en modo enveloped. El nivel T añade una marca de tiempo a la firma, tal como se describe en la sección Niveles compatibles. El modo enveloped incrusta la firma dentro del documento original, tal como se describe en la sección Modos compatibles.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para XAdES. El nombre debe ser XAdES, con el nivel T seleccionado (forzado o no), el modo enveloped seleccionado (forzado o no), el algoritmo de firma dependerá del certificado (normalmente RSA), el algoritmo de digestión será SHA256 y debe haber al menos un TSP válido seleccionado como primario o secundario.
  • Debe existir un certificado con el identificador indicado en la petición, protegido con PIN.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar un certificado personal.

En esta petición:

  • SignatureForm se establece en XAdES T (ES-T).
  • AdditionalKeyInfo proporciona el PIN del certificado.
  • SignaturePlacement especifica el modo enveloped y el documento que se va a firmar.
  • El documento XML se proporciona como Base64XML.
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="XAdES-T-Forced-Enveloped-Forced-RSA-SHA256" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <AdditionalKeyInfo>
               <KeyInfo Id="Pin" xmlns="http://www.w3.org/2000/09/xmldsig#">PIN_DEL_CERTIFICADO</KeyInfo>
            </AdditionalKeyInfo>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:ES-T</SignatureForm>
            <SignaturePlacement WhichDocument="ID-document-1"/>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64XML>...</Base64XML>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>
Respuesta

La respuesta muestra el estado general de la petición en la etiqueta ResultMajor, una etiqueta SignaturePtr, que es una referencia a la ubicación del documento dentro de la respuesta, y, por último, la etiqueta Base64XML, que contiene el documento con la firma incrustada codificada en Base64. La firma incluye una marca de tiempo, que protege la firma frente a la repudiación.

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="XAdES-T-Forced-Enveloped-Forced-RSA-SHA256" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <OptionalOutputs>
            <dss:DocumentWithSignature xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:rt="urn:evolium:redtrust:dss:1.0:core:schema" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#">
               <dss:Document ID="ID-document-1">
                  <dss:Base64XML>...</dss:Base64XML>
               </dss:Document>
            </dss:DocumentWithSignature>
         </OptionalOutputs>
         <SignatureObject>
            <SignaturePtr WhichDocument="ID-document-1"/>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

XAdES EPES enveloped​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma XAdES de nivel EPES (con política de firma), en modo enveloped. El nivel EPES es equivalente al nivel BES, con la diferencia de que se define una política de firma, tal como se describe en la sección Niveles soportados. El modo enveloped incrusta la firma dentro del documento original, tal como se describe en la sección Modos compatibles.

Las firmas FacturaE utilizan un perfil XAdES EPES (política de firma). Los requisitos base son los mismos para todas las versiones de FacturaE; las únicas diferencias son el nombre del perfil, la política (OID/URL + hash) y el esquema XML contra el que debe validar el documento de entrada.

Requisitos

  • Debe existir un perfil de firma FacturaE en Redtrust (XAdES + enveloped, con BES/EPES según la configuración). El nombre debe ser FacturaE_3.0 o FacturaE_3.1_3.2.
  • Debe existir un certificado de firma y debe ser accesible desde el contexto de la petición (el identificador usado en la petición debe corresponder a un certificado real).
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita a ese usuario firmar documentos (o el certificado debe ser el certificado personal del usuario, según el modelo).
  • El documento de entrada debe ser un XML FacturaE válido conforme al esquema definido en la URL http://www.facturae.gob.es/formato/Versiones%20anteriores/B)%20Versi%C3%B3n%203.0/Facturae30.xml para la versión 3.0 o https://www.facturae.gob.es/formato/Versiones/Facturaev3_2.xml para la versión 3.1. Redtrust no valida el XML frente al esquema.

Las políticas que debes incluir deben contener la siguiente información:

FacturaE (3.0)

  • Identifier: http://www.facturae.gob.es/ signature policy facturae format/signature-policy facturae format v3_0.pdf
  • Hash algorithm: sha1
  • Hash: HQvPemjDslVpcNmaJPpbHzhdZ50=

FacturaE (3.2)

  • Identifier: http://www.facturae.es/politica_de_firma_formato_facturae/politica_de_firma_formato_facturae_v3_1.pdf
  • Hash algorithm: sha1
  • Hash: Ohixl6upD6av8N7pEvDABhEL6hM=

En este ejemplo:

  • Profile selects a FacturaE profile that includes the signature policy.
  • Mode and level are forced by the profile, so the request does not need additional mode/level elements.
  • The XML document is provided as Base64XML.
Petición para 3.0
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="XAdES-Facturae_3.0-EPES_Forced-Enveloped-RSA-SHA256" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:EPES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64XML>...</Base64XML>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>
Petición para 3.1/3.2
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="XAdES-Facturae_3.1_3.2-EPES-Forced-Enveloped-Forced-RSA-SHA2" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignaturePlacement WhichDocument="ID-document-1"/>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64XML>...</Base64XML>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La respuesta muestra el estado general de la petición en la etiqueta ResultMajor, una etiqueta SignaturePtr, que es una referencia a la ubicación del documento dentro de la respuesta, y, por último, la etiqueta Base64XML, que contiene el documento con la firma incrustada codificada en Base64. Al incluir la política de firma en el perfil, la firma contendrá esa información y será válida como factura electrónica 3.0, siempre que el documento de entrada sea válido conforme al esquema. Redtrust no valida el formato XML; es tu responsabilidad validar el formato, si es necesario, antes de enviar la petición al servicio.

Respuesta para 3.0
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="XAdES-Facturae_3.0-EPES_Forced-Enveloped-RSA-SHA256" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3275">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>
Respuesta para 3.1/3.2

La respuesta muestra el estado general de la petición en la etiqueta ResultMajor, una etiqueta SignaturePtr, que es una referencia a la ubicación del documento dentro de la respuesta, y, por último, la etiqueta Base64XML, que contiene el documento con la firma incrustada codificada en Base64. Al incluir la política de firma en el perfil, la firma contendrá esa información y será válida como factura electrónica 3.2, siempre que el documento de entrada sea válido conforme al esquema. Redtrust no valida el formato XML; es tu responsabilidad validar el formato antes de enviar la petición al servicio.

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="XAdES-Facturae_3.1_3.2-EPES-Forced-Enveloped-Forced-RSA-SHA2" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <OptionalOutputs>
            <dss:DocumentWithSignature xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:rt="urn:evolium:redtrust:dss:1.0:core:schema" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#">
               <dss:Document ID="ID-document-1">
                  <dss:Base64XML>...</dss:Base64XML>
               </dss:Document>
            </dss:DocumentWithSignature>
         </OptionalOutputs>
         <SignatureObject>
            <SignaturePtr WhichDocument="ID-document-1"/>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

CAdES (CMS Advanced Electronic Signature)​

CAdES (CMS Advanced Electronic Signature) es un conjunto de extensiones de CMS que lo hacen adecuado para la firma electrónica, de acuerdo con la Directiva 1999/93/CE de la Unión Europea. Al igual que XAdES, uno de los puntos fuertes de CAdES es que los documentos firmados electrónicamente mediante CAdES pueden mantenerse válidos durante largos periodos de tiempo.

A continuación se muestran algunos ejemplos de uso de la API DSS de Redtrust para firmar documentos con CAdES.

CAdES BES enveloping​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma CAdES de nivel BES en modo enveloping. El nivel BES es el más básico de las firmas avanzadas, tal como se describe en la sección Niveles soportados. El modo enveloping incrusta el documento original dentro de la firma, tal como se describe en la sección Modos soportados.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para CAdES. El nombre debe ser CAdES, con el nivel BES seleccionado (forzado o no), el modo enveloping seleccionado (forzado o no), el algoritmo de firma dependerá del certificado (normalmente RSA) y el algoritmo de digestión será SHA256.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar el certificado personal del usuario.

La petición muestra el elemento KeyInfo con la huella digital del certificado con el que se va a firmar, la etiqueta SignatureForm, que especifica que el nivel será BES, la etiqueta IncludeEContent, que indica que el modo debe ser enveloping, y el documento XML que se va a firmar, codificado en Base64 dentro de la etiqueta Base64Data.

En este ejemplo:

  • SignatureForm se establece en BES.
  • IncludeEContent solicita una firma en modo enveloping (incrusta el contenido).
  • El documento de entrada se proporciona como Base64Data.
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="CAdES-BES-Enveloping" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <IncludeEContent/>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="text/plain">RmljaGVybyBkZSBwcnVlYmEgYSBmaXJtYXI=</Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene la firma con el documento incrustado codificado en Base64.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="CAdES-BES-Enveloping" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

CAdES BES detached​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma CAdES de nivel BES en modo detached. El nivel BES es el más básico de las firmas avanzadas, tal como se describe en la sección Niveles soportados. El modo detached genera una firma separada del documento, tal como se describe en la sección Modos soportados.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para CAdES. El nombre debe ser CAdES, con el nivel BES seleccionado (forzado o no), el modo detached seleccionado (forzado o no), el algoritmo de firma dependerá del certificado (normalmente RSA) y el algoritmo de digestión será SHA256.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar el certificado personal del usuario.

En este ejemplo:

  • SignatureForm se establece en BES.
  • Se omite IncludeEContent, por lo que la firma es detached (o el modo está forzado por el perfil).
  • El documento de entrada se proporciona como Base64Data.
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="CAdES-BES-Detached" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <dss:Language xmlns:dss="urn:oasis:names:tc:dss:1.0:core:schema">en-US</dss:Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="text/plain">RmljaGVybyBkZSBwcnVlYmEgYSBmaXJtYXI=</Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La petición muestra el elemento KeyInfo con la huella digital del certificado con el que se va a firmar, la etiqueta SignatureForm, que especifica que el nivel será BES, y el documento XML que se va a firmar, codificado en Base64 dentro de la etiqueta Base64Data. La ausencia de la etiqueta IncludeEContent indica que se utiliza el modo forzado en el perfil o, si el modo detached no está forzado, que se aplica el comportamiento por defecto.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="CAdES-BES-Detached" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene la firma codificada en Base64.

PAdES​

PAdES (PDF Advanced Electronic Signature) es un conjunto de extensiones de PDF y de la norma ISO 32000-1 que lo hacen adecuado para la firma electrónica, de acuerdo con la Directiva 1999/93/CE de la Unión Europea.

A continuación se muestran algunos ejemplos de uso de la API DSS de Redtrust para firmar documentos con PAdES.

PDF BES​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma PAdES de nivel BES. El nivel BES es el más básico de las firmas avanzadas, tal como se describe en la sección Niveles soportados. PAdES solo admite el modo enveloped, tal como se describe en la sección Modos compatibles.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para PAdES. El nombre debe ser PAdES, con el nivel BES seleccionado (forzado o no) y el modo enveloped. El algoritmo de firma dependerá del certificado (normalmente RSA) y el algoritmo de digestión será SHA256.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar el certificado personal del usuario.

En este ejemplo:

  • SignatureForm se establece en BES.
  • El documento de entrada es un PDF que se proporciona como Base64Data con MimeType="application/pdf".
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://REDTRUST_IP:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="PAdES_BES" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <Language>en-US</Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="application/pdf">...</Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La respuesta muestra el estado general de la solicitud en la etiqueta ResultMajor, una etiqueta Base64Signature que contiene el archivo PDF con la firma codificada en Base64.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="PAdES_BES" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

Firma PDF BES visible​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma PAdES de nivel BES con representación visual de la firma. El nivel BES es el más básico de las firmas avanzadas, tal como se describe en la sección Niveles soportados. PAdES solo admite el modo enveloped, tal como se describe en la sección Modos soportados.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para PAdES. El nombre debe ser PAdES, con el nivel BES seleccionado (forzado o no), el modo enveloped seleccionado, el algoritmo de firma dependerá del certificado (normalmente RSA) y el algoritmo de digestión será SHA256.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar el certificado personal del usuario.

En este ejemplo:

  • VisibleSignatureConfiguration define la firma visible (posición y elementos mostrados).
  • SignatureForm se establece en BES.
  • El documento de entrada es un PDF que se proporciona como Base64Data con MimeType="application/pdf".
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://[IP_REDTRUST]:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="PAdES_BES" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <q1:VisibleSignatureConfiguration xmlns:q1="urn:oasis:names:tc:dssx:1.0:profiles:VisibleSignatures:schema#">
               <q1:VisibleSignaturePolicy>GeneralPolicy</q1:VisibleSignaturePolicy>
               <q1:VisibleSignaturePosition d4p1:type="q1:PixelVisibleSignaturePositionType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                  <q1:PageNumber>1</q1:PageNumber>
                  <q1:x>30</q1:x>
                  <q1:y>30</q1:y>
                  <q1:Width>200</q1:Width>
                  <q1:Height>60</q1:Height>
               </q1:VisibleSignaturePosition>
               <q1:VisibleSignatureItemsConfiguration>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>CustomText</q1:ItemName>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureReason</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Razón de firma</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureProductionPlace</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Barcelona</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerContactInfo</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Usuario de Redtrust (usuario.Redtrust@evolium.com)</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
               </q1:VisibleSignatureItemsConfiguration>
            </q1:VisibleSignatureConfiguration>
            <Language>en-US</Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="application/pdf">...</Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La parte de representación visual de la firma se encuentra dentro de VisibleSignatureConfiguration. La firma tendría el aspecto que se muestra en la siguiente representación:

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene el archivo PDF con la firma codificada en Base64.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="PAdES_BES" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

Firma PDF BES visible con imagen de firma​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma PAdES de nivel BES con representación visual de la firma que incluye una imagen. El nivel BES es el más básico de las firmas avanzadas, tal como se describe en la sección Niveles soportados. PAdES solo admite el modo enveloped, tal como se describe en la sección Modos soportados.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para PAdES. El nombre debe ser PAdES, con el nivel BES seleccionado (forzado o no), el modo enveloped seleccionado; el algoritmo de firma dependerá del certificado (normalmente RSA) y el algoritmo de digestión será SHA256.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar el certificado personal del usuario.

En este ejemplo:

  • VisibleSignatureConfiguration define la firma visible e incluye SignerImage.
  • SignatureForm se establece en BES.
  • El documento de entrada es un PDF que se proporciona como Base64Data con MimeType="application/pdf".
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://IP_REDTRUST:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="PAdES_BES" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <q1:VisibleSignatureConfiguration xmlns:q1="urn:oasis:names:tc:dssx:1.0:profiles:VisibleSignatures:schema#">
               <q1:VisibleSignaturePolicy>GeneralPolicy</q1:VisibleSignaturePolicy>
               <q1:VisibleSignaturePosition d4p1:type="q1:PixelVisibleSignaturePositionType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                  <q1:PageNumber>1</q1:PageNumber>
                  <q1:x>30</q1:x>
                  <q1:y>20</q1:y>
                  <q1:Width>200</q1:Width>
                  <q1:Height>75</q1:Height>
               </q1:VisibleSignaturePosition>
               <q1:VisibleSignatureItemsConfiguration>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureReason</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Razón de firma</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureProductionPlace</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Barcelona</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>CustomText</q1:ItemName>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerContactInfo</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Usuario Demo (user@demo.com)</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerImage</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueURIType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>https://upload.wikimedia.org/wikipedia/commons/thumb/a/af/Miguel_de_Cervantes_signature.svg/1280px-Miguel_de_Cervantes_signature.svg.png</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
               </q1:VisibleSignatureItemsConfiguration>
            </q1:VisibleSignatureConfiguration>
            <Language>en-US</Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="application/pdf"><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://IP_REDTRUST:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="PAdES_BES" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <q1:VisibleSignatureConfiguration xmlns:q1="urn:oasis:names:tc:dssx:1.0:profiles:VisibleSignatures:schema#">
               <q1:VisibleSignaturePolicy>GeneralPolicy</q1:VisibleSignaturePolicy>
               <q1:VisibleSignaturePosition d4p1:type="q1:PixelVisibleSignaturePositionType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                  <q1:PageNumber>1</q1:PageNumber>
                  <q1:x>30</q1:x>
                  <q1:y>20</q1:y>
                  <q1:Width>200</q1:Width>
                  <q1:Height>75</q1:Height>
               </q1:VisibleSignaturePosition>
               <q1:VisibleSignatureItemsConfiguration>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureReason</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Razón de firma</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureProductionPlace</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Barcelona</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>CustomText</q1:ItemName>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerContactInfo</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Usuario Demo (user@demo.com)</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerImage</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueURIType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>https://upload.wikimedia.org/wikipedia/commons/thumb/a/af/Miguel_de_Cervantes_signature.svg/1280px-Miguel_de_Cervantes_signature.svg.png</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
               </q1:VisibleSignatureItemsConfiguration>
            </q1:VisibleSignatureConfiguration>
            <Language>en-US</Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="application/pdf">...</Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

La parte de representación visual de la firma se encuentra dentro de la etiqueta VisibleSignatureConfiguration.

En este caso, al especificar CustomText y SignerImage, el espacio en el que aparece la firma se comparte entre el SubjectName del certificado y la imagen, tal como se muestra en la siguiente imagen:

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="PAdES_BES" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

La respuesta muestra el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene el archivo PDF con la firma codificada en Base64.

Firma PDF LTV​

Este ejemplo describe cómo realizar una llamada al servicio para generar una firma PAdES de nivel LTV. El nivel LTV es el formato de firma de larga duración, que permite su validación en el futuro, tal como se describe en la sección Niveles soportados. PAdES solo admite el modo enveloped, tal como se describe en la sección Modos soportados.

Requisitos

  • Debe existir un perfil de firma en Redtrust definido para PAdES. El nombre debe ser PAdES, con el nivel LTV seleccionado (forzado o no), el modo enveloped seleccionado, el algoritmo de firma dependerá del certificado (normalmente RSA), el algoritmo de digestión será SHA256 y debe haber al menos un TSP válido seleccionado como primario o secundario.
  • Debe existir un certificado con el identificador indicado en la petición.
  • Debe existir un usuario usuario@dominio.
  • Debe existir una política de uso que permita al usuario utilizar el certificado para firmar documentos o usar el certificado personal del usuario.

En este ejemplo:

  • SignatureForm se establece en LTV.
  • El perfil debe estar configurado con una fuente de sellado de tiempo (TSP) válida, ya que LTV requiere marcas de tiempo.
  • El documento de entrada es un PDF que se proporciona como Base64Data con MimeType="application/pdf".
Petición
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsse:Security 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">
         <wsse:UsernameToken wsu:Id="0001">
            <wsse:Username>USERNAME</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
            <wsu:Created>2024-11-15T12:14:44.617Z</wsu:Created>
         </wsse:UsernameToken>
      </wsse:Security>
      <wsa:Action>urn:evolium:redtrust:dss:ws/RTDSSService/SignRequest</wsa:Action>
      <wsa:To>https://IP_REDTRUST:8080/RTDSSService.svc/basic</wsa:To>
   </soap:Header>
   <soap:Body>
      <SignRequest Profile="DSS_PROFILE" RequestID="PAdES-LTV" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <OptionalInputs>
            <q1:VisibleSignatureConfiguration xmlns:q1="urn:oasis:names:tc:dssx:1.0:profiles:VisibleSignatures:schema#">
               <q1:VisibleSignaturePolicy>GeneralPolicy</q1:VisibleSignaturePolicy>
               <q1:VisibleSignaturePosition d4p1:type="q1:PixelVisibleSignaturePositionType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                  <q1:PageNumber>1</q1:PageNumber>
                  <q1:x>30</q1:x>
                  <q1:y>20</q1:y>
                  <q1:Width>200</q1:Width>
                  <q1:Height>75</q1:Height>
               </q1:VisibleSignaturePosition>
               <q1:VisibleSignatureItemsConfiguration>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureReason</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Razón de firma</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignatureProductionPlace</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Barcelona</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>CustomText</q1:ItemName>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerContactInfo</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueStringType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <q1:ItemValue>Usuario Demo (user@demo.com)</q1:ItemValue>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
                  <q1:VisibleSignatureItem>
                     <q1:ItemName>SignerImage</q1:ItemName>
                     <q1:ItemValue d4p1:type="q1:ItemValueImageType" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
                        <Base64Data>...</Base64Data>
                     </q1:ItemValue>
                  </q1:VisibleSignatureItem>
               </q1:VisibleSignatureItemsConfiguration>
            </q1:VisibleSignatureConfiguration>
            <Language>en-US</Language>
            <KeySelector>
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector>
            <SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:PAdES:forms:LTV</SignatureForm>
         </OptionalInputs>
         <InputDocuments>
            <Document ID="ID-document-1">
               <Base64Data MimeType="application/pdf">...</Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

En la respuesta puedes ver el estado global de la petición en la etiqueta ResultMajor y una etiqueta Base64Signature que contiene el archivo PDF con la firma codificada en Base64.

Si abres el archivo resultante con Adobe Acrobat Reader DC, puedes comprobar la firma en el panel de firmas.

Respuesta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="PAdES-LTV" Profile="DSS_PROFILE" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">...</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

Próximos pasos​