Versión: 4.41

Tutorial: Primeros pasos con la API DSS

Visión general

Esta guía te acompaña en los primeros pasos con la API DSS: autenticación en el servicio, obtención de un certificado de firma disponible y envío de una solicitud de firma.

Al finalizar esta guía, podrás:

Autenticarte en el servicio DSS
Obtener los certificados disponibles para un usuario local
Firmar un documento mediante la operación SignRequest

Antes de empezar

Antes de empezar, asegúrate de disponer de lo siguiente:

Acceso a un entorno de Redtrust con el servicio DSS habilitado
Una cuenta de usuario local de Redtrust (usuario@dominio) con una política que permita servicios de firma (consulta la sección Dónde de la política)
Un certificado de firma disponible para ese usuario
SoapUI u otro cliente HTTP capaz de enviar solicitudes SOAP 1.2
Un archivo que quieras firmar (convertido a Base64 para la solicitud)

tip

Para convertir un archivo a Base64, puedes usar el siguiente comando.

[System.IO.File]::WriteAllText("RUTA_AL_ARCHIVO_DE_DESTINO.txt",[System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("RUTA_AL_ARCHIVO_DE_ORIGEN.pdf")))

Para convertirlo de nuevo al formato original, puedes usar el siguiente comando.

[System.IO.File]::WriteAllBytes("RUTA_AL_ARCHIVO_DE_DESTINO.pdf",[System.Convert]::FromBase64String([System.IO.File]::ReadAllText("RUTA_AL_ARCHIVO_DE_ORIGEN.txt")))

Paso 1: Crea un perfil DSS

Antes de realizar cualquier solicitud a la API, tienes que crear un perfil DSS en la consola de administración.

Accede a la consola de administración con un rol que tenga acceso a la gestión de firmas. Si el rol tiene acceso, verás la pestaña Firma en la barra de navegación.
Ve a Firma y haz clic en Nuevo.
Añade un nombre, en este ejemplo pades-bes-profile.
Selecciona un tipo de firma, en este ejemplo PAdES, y haz clic en Siguiente.
Selecciona un nivel de firma, en este ejemplo BES. Para más información, consulta los niveles soportados.
Haz clic en Siguiente en el resto de opciones y finalmente en Aplicar.

Paso 2: Autentícate en el servicio DSS

Para realizar una solicitud a la API DSS es necesario autenticarse. El servicio DSS admite varios mecanismos de autenticación, cada uno con un endpoint distinto. En esta guía, los ejemplos utilizan autenticación mediante nombre de usuario y contraseña, adecuada para pruebas iniciales y desarrollo. En SoapUI, la autenticación se configura mediante opciones específicas. Sigue estos pasos:

Abre SoapUI y haz clic en SOAP.
En el formulario New SOAP Project, añade el Initial WSDL: https://REDTRUST_IP:8080/RTDSSService.svc.

nota
Por defecto, el puerto de conexión es 8080, aunque se puede configurar desde la consola de administración de Redtrust (Sistema > Unidad > Red). Del mismo modo, por defecto el protocolo es HTTPS y el certificado del servicio se genera automáticamente durante la instalación, aunque también puedes configurarlo desde la consola. Al implementar un cliente que acceda al servicio, debes tener en cuenta que necesitarás la parte pública del certificado del servicio para que el cliente confíe en el servidor, salvo que el cliente acepte cualquier certificado.
Haz clic en el nombre del proyecto. En la ventana de configuración:
1. Haz clic en WS-Security Configurations (tercera pestaña).
2. Haz clic en el icono verde + y añade el nombre del usuario, por ejemplo final.
3. Haz clic en el segundo icono verde + y selecciona Username.
4. Añade USUARIO@DOMINIO, por ejemplo final@local.users. Cierra la ventana para guardar los cambios.

Paso 3: Añade la URL base

En SoapUI, haz clic en el icono + junto al método GetAccessibleCertificates y haz doble clic en Request 1. Añade el endpoint base para la autenticación mediante usuario y contraseña:

https://REDTRUST_IP:8080/RTDSSService.svc/basic

nota

La URL base de las peticiones depende del método de autenticación y de la configuración del despliegue.

Paso 4: Realizar la primera petición a la API

Para realizar tu primera petición a la API, llama a GetAccessibleCertificates para obtener la huella digital (o thumbprint) del certificado. Desde la ventana Request 1, sigue estos pasos:

Selecciona la pestaña Auth (Basic) en la parte inferior.
En el menú Authorization, selecciona Add New Authorization > Basic.
De vuelta en la ventana de la petición, ve a Outgoing WSS y selecciona el usuario que acabas de crear.
Selecciona la pestaña WS-A en la parte inferior y marca Add default wsa:Action y Add default wsa:To.

Ejecuta la petición con el botón de reproducción verde (▶).

Petición

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:dss:ws">
   <soap:Header/>
   <soap:Body>
      <urn:GetAccessibleCertificates>
         <urn:filter></urn:filter>
      </urn:GetAccessibleCertificates>
   </soap:Body>
</soap:Envelope>

Una respuesta correcta devuelve un objeto Result con los certificados disponibles para el usuario autenticado.

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>my-certificate</b:alias>
                <b:certificateHandler>16</b:certificateHandler>
                <b:expiration>2028-03-11T14:05:30</b:expiration>
                <b:issuer>Ceres</b:issuer>
                <b:needPin>false</b:needPin>
                <b:needReason>false</b:needReason>
                <b:subject>EIDAS CERTIFICADO PRUEBAS - 99999972C</b:subject>
                <b:thumbprint>5F5162563AFF01EB353D346C8B786AAA2A0CFB09</b:thumbprint>
                <b:type>PRIVATE</b:type>
            </b:Certificate>
            </b:ResultData>
            <b:TotalItems>1</b:TotalItems>
        </Result>
    </GetAccessibleCertificatesResponse>
</s:Body>
</s:Envelope>

Anota el thumbprint del certificado que quieras usar para firmar.

Paso 5: Firma un documento PDF

Para firmar el documento, llama a SignRequest. Para ello, tienes que configurar el método igual que en el paso anterior, es decir, desde la ventana Request 1:

Selecciona la pestaña Auth (Basic) en la parte inferior.
En el menú Authorization, selecciona Add New Authorization > Basic.
De vuelta en la ventana de la petición, ve a Outgoing WSS y selecciona el usuario que creaste (en este ejemplo, final).
Selecciona la pestaña WS-A en la parte inferior y marca Add default wsa:Action y Add default wsa:To.

Llama a SignRequest haciendo clic en Request 1 del método. Ten en cuenta lo siguiente:

Profile es el nombre del perfil de firma que creaste en el paso 1.
La huella digital es la que obtuviste en el paso 4, junto con el PDF del documento en Base64. Puedes usar el siguiente ejemplo.
La petición utiliza profile:XAdES:forms:BES, que incluye PAdES. No lo sustituyas por una URI de PAdES, ya que este endpoint no la admite.
La API DSS es sensible al formato de las peticiones. Pequeñas diferencias en los saltos de línea pueden afectar a cómo se procesan. Si una petición devuelve resultados incompletos o inesperados, compárala cuidadosamente con los ejemplos proporcionados.
Incluye AdditionalKeyInfo solo si el certificado requiere un PIN.

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/>
      <soap:Body>
         <SignRequest Profile="DSS_PROFILE" RequestID="dss-sign-request-1" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
            <OptionalInputs>
               <Language xmlns="urn:oasis:names:tc:dss:1.0:core:schema">en-US</Language>
            <KeySelector xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
               <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>
            <AdditionalKeyInfo xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
               <KeyInfo Id="Pin" xmlns="http://www.w3.org/2000/09/xmldsig#"></KeyInfo>
            </AdditionalKeyInfo>
            </OptionalInputs>
            <InputDocuments>
               <Document ID="ID-document-1">
                  <Base64Data MimeType="application/pdf">PDF_EN_BASE_64</Base64Data>
               </Document>
            </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

Una firma correcta se indica cuando ResultMajor tiene el valor …:Success.

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" Profile="pades-bes-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">PDF_FIRMADO_EN_BASE64</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

Próximos pasos

Visión general
Aprende cómo se estructura el servicio DSS, qué operaciones expone y cómo encajan entre sí los distintos componentes de la API.
Ejemplos de la API DSS
Explora ejemplos completos de peticiones y respuestas para escenarios de firma habituales, incluidos distintos tipos y formatos de firma.
Referencia de la API DSS
Consulta definiciones detalladas de todos los elementos de petición y respuesta de DSS, incluidos Profile, KeySelector, SignatureForm e InputDocuments.
Métodos DSS
Revisa todas las operaciones de DSS, su propósito y cuándo usar cada método.
Códigos de respuesta de SignRequest
Comprende los posibles resultados de una petición de firma y cómo interpretar las respuestas de éxito y error.
WSDL
Inspecciona la definición del servicio que utilizan los clientes SOAP, incluidas las operaciones disponibles, los bindings y los endpoints.
Esquemas del servicio
Examina los esquemas XML que definen la estructura y las reglas de validación de las peticiones y respuestas de DSS.
Códigos de respuesta de Result
Aprende a interpretar ResultMajor, ResultMinor y la información de estado relacionada que devuelve el servicio DSS.

Visión general​

Antes de empezar​

Paso 1: Crea un perfil DSS​

Paso 2: Autentícate en el servicio DSS​

Paso 3: Añade la URL base​

Paso 4: Realizar la primera petición a la API​

Paso 5: Firma un documento PDF​

Próximos pasos​