Skip to main content
Version: 4.41

Tutorial: Getting started with the DSS API

Overview​

This guide walks you through getting started with the DSS API by authenticating to the service, retrieving an available signing certificate, and sending a signing request.

By the end of this guide, you will be able to:

  • Authenticate to the DSS service
  • Retrieve the certificates available to a local user
  • Sign a document using the DSS SignRequest operation

Prerequisites​

Before you begin, ensure you have the following tools installed or set up:

  • Access to a Redtrust environment with the DSS service enabled
  • A Redtrust local user account (username@domain) with a policy that allows signature services (see the Where section of a policy to check).
  • A signing certificate available to that user
  • SoapUI, or other HTTP client capable of sending SOAP 1.2 requests
  • A file you want to sign (converted to Base64 for the request).
tip

To convert to Base64 you can use the following command.

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

To convert it back, you can use the following command.

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

Step 1: Create a DSS profile​

Before proceeding with any API request, you have to create a DSS profile in the admin console.

  1. Access the admin console with a role that has access to signature management. If a role has access, you will see the Signature tab on the navigation bar.
  2. Go to Signature and click New.
  3. Add a name, in this example pades-bes-profile.
  4. Select a signature type, in this example PAdES and click Next.
  5. Select a signature level, in this example BES. For more details, see supported levels.
  6. Click Next to all other options and finally Apply.

Step 2: Authenticate to the DSS service​

Making a request to the DSS API requires authentication. The DSS service supports multiple authentication mechanisms, each using a different service endpoint. In this guide, the examples use username and password authentication, which is suitable for initial testing and development. In SoapUI, you authenticate through configuration options. Follow these steps:

  1. Access SOAP UI and click SOAP.

  2. In the New SOAP Project form add the Initial WSDL as https://REDTRUST_IP:8080/RTDSSService.svc.

    note

    By default, the connection port is 8080, but this port is configurable through the Redtrust admin console (from System > Unit > Network ). Similarly, by default, the protocol is HTTPS and the service certificate is auto-generated at the time of installation, but you can also configure it from the admin console. When implementing a client accessing the service, you must take into account that you will need the public part of the service certificate for the client to trust the server, unless the client accepts any certificate.

  3. Click the project name. In the configuration window:

    1. Click WS-Security Configurations (third tab).
    2. Click the green + sign and add the name of the user, for example final.
    3. Click the second green + sign that was enabled and select Username.
    4. Add USERNAME@DOMAIN, for example final@local.users. Close the window to save the changes.

Step 3: Add the base URL​

In SOAP UI, click the + sign next to the GetAccessibleCertificates method and double click Request 1. Add the basic endpoint for username and password authentication:

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

The base URL of the requests depends on the authentication method and deployment configuration

Step 4: Make your first API request​

To make your first API request, call GetAccessibleCertificates to retrieve the certificate thumbprint. To do that, follow these steps from the Request 1 window:

  1. Select the Auth (Basic) tab at the bottom.
  2. In the Authorization menu, select Add New Authorization > Basic.
  3. Back in the request window, go to Outgoing WSS and select the user you just created (in this example final).
  4. Select the WS-A tab at the bottom. Check Add default wsa:Action and Add default wsa:To.

Run the request using the green play button (▶).

Request
<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>

A successful response returns a Result object containing the certificates available to the authenticated user.

Response
<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>

Make a note of the thumbprint of the certificate you want to use to sign.

Step 5: Sign a PDF document​

To sign the document you will call SignRequest. To do that, you will have to configure the method as you did in the previous step, that is, from the Request 1 window:

  1. Select the Auth (Basic) tab at the bottom.
  2. In the Authorization menu, select Add New Authorization > Basic.
  3. Back in the request window, go to Outgoing WSS and select the user you created (in this example final).
  4. Select the WS-A tab at the bottom. Check Add default wsa:Action and Add default wsa:To.

Call SignRequest by clicking on the Request 1 of the method. Bear in mind the following

  • Profile` is the name of the signature profile you created in Step 1
  • The thumbprint is that you obtained in Step 4 and a PDF of the document in Base64. You can use the following example.
  • The request uses profile:XAdES:forms:BES which includes PAdES. Do not replace it with a PAdES URI, as it is not supported by this endpoint.
  • The DSS API is sensitive to request formatting. Small differences in line breaks may affect how requests are processed. If a request returns incomplete or unexpected results, compare it carefully with the provided examples.
  • Include AdditionalKeyInfo only if the certificate requires a PIN.

Request

<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_IN_BASE_64</Base64Data>
               </Document>
            </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

A successful signature is indicated by ResultMajor set to …:Success.

Response

<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">SIGNED_PDF_IN_BASE64</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

Next steps​

  • DSS API Overview
    Learn how the DSS service is structured, which operations it exposes, and how the different components of the API fit together.

  • DSS API Examples
    Explore complete request and response examples for common signing scenarios, including different signature types and formats.

  • DSS API reference
    Find detailed definitions of all DSS request and response elements, including Profile, KeySelector, SignatureForm, and InputDocuments.

  • DSS API methods
    Review all DSS operations, their purpose, and when to use each method.

  • DSS API SignRequest response codes
    Understand the possible outcomes of a signing request and how to interpret success and error responses.

  • DSS API WSDL
    Inspect the service definition used by SOAP clients, including available operations, bindings, and endpoints.

  • DSS API service schemas
    Browse the XML schemas that define the structure and validation rules of DSS requests and responses.

  • DSS API Result response codes
    Learn how to interpret ResultMajor, ResultMinor, and related status information returned by the DSS service.