Version: 4.41

Tutorial: Signing documents using MTOM with DSS

This tutorial shows you how to send documents to the Digital Signature Service (DSS) using MTOM (Message Transmission Optimization Mechanism). You use SoapUI to send a SignRequest that references the document as a MIME attachment instead of embedding it as Base64.

By the end of this tutorial, you will have a working MTOM-based signing request that returns a valid DSS SignResponse.

Background

MTOM is a SOAP mechanism for sending large binary data efficiently. Instead of embedding the document as Base64 inside the SOAP body, the client sends the document as a MIME attachment and references it from the SOAP message using XOP.

In DSS, MTOM changes how the document is transported, not how it is processed. The signing logic remains the same, but the request uses a dedicated MTOM-enabled endpoint and an xop:Include reference instead of Base64Data.

Before you start

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).
At least one signing certificate available to that user
SoapUI, or other HTTP client capable of sending SOAP 1.2 requests

This tutorial builds on an existing, functional DSS setup in SoapUI. If you cannot successfully send a standard (non-MTOM) SignRequest, check the getting started tutorial before proceeding.

Step 1: Create an MTOM request in SoapUI

Create a new SignRequest (or duplicate an existing one).
Set the request URL to the MTOM endpoint.

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

Configure authentication and WS-Addressing exactly as you do for standard DSS requests, described in Step 4 of the Getting started tutorial.

Step 2: Add the document as an attachment

Open the Attachments tab in SoapUI.
Add the PDF file you want to sign.
Set the contentID of the attachment (for example: test.pdf).

Step 3: Force the attachment part to `BODY`

SoapUI does not allow you to select BODY as the attachment part through the UI. To do it manually:

Close SoapUI. If you make changes to the XML with it open, SoapUI can overwrite changes.
Find the project XML. The name of the file will be PROJECT_NAME-soapui-project.xml (for example RTDSSService-soapui-project.xml).

In the MTOM interface, look for the definition of the attachment and change <con:part xsi:nil="true"/> for BODY. The end result should be similar to this:

<con:attachment>
  <con:name>MyDocument.pdf</con:name>
  <con:contentType>application/pdf</con:contentType>
  <con:contentId>test.pdf</con:contentId>
  <con:part>BODY</con:part>
  <con:url>C:/path/to/MyDocument.pdf</con:url>
</con:attachment>

Save the changes and start SoapUI.
Select the request and go to Request Properties panel (usually below the project navigation) and set Force MTOM to true.

Step 4: Build the MTOM SignRequest

Now you can make the request as follows. Bear in mind the following:

The attachment's contentID must match the xop:Include href="cid:..." value exactly.
In MTOM, you still use the Base64Data element, but you replace the base64 text with an xop:Include reference to the MIME attachment.
Profile is the name of the Signature profile you created in Redtrust.
Although the signed document is a PDF, this service exposes PAdES signing under the XAdES profile namespace. Do not replace the SignatureForm value with a PAdES URI.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema">
   <soap:Body>
      <SignRequest Profile="YOUR_DSS_PROFILE" RequestID="YOUR_DSS_PROFILE" 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="DOCUMENT_ID" xmime:contentType="application/pdf" xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
                <Base64Data MimeType="application/pdf">
                  <xop:Include href="cid:CONTENT_ID" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
                </Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

Request example

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema">
   <soap:Body>
      <SignRequest Profile="pades-bes-profile" RequestID="pades-bes-profile" 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#">5F5162563AFF01EB353D346C8B786AAA2A0CFB09</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" xmime:contentType="application/pdf" xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
                <Base64Data MimeType="application/pdf">
                  <xop:Include href="cid:test.pdf" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
                </Base64Data>
            </Document>
         </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

Step 5: Send the request and check the result

If everything is configured correctly, DSS returns a SignResponse with the signed document in the Attachment tab of the 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">
                <xop:Include href="cid:http://tempuri.org/1/639058938559817471" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
              </Base64Signature>
          </SignatureObject>
        </SignResponse>
    </s:Body>
  </s:Envelope>

Next steps

See the DSS API reference for more detail information about request elements.

Background​

Before you start​

Step 1: Create an MTOM request in SoapUI​

Step 2: Add the document as an attachment​

Step 3: Force the attachment part to BODY​

Step 4: Build the MTOM SignRequest​

Step 5: Send the request and check the result​

Next steps​