Version: 4.32

DSS API

Overview

Redtrust is a corporate authentication and signature certificate manager that allows its use in a centralized, secure, and controlled way.

Taking advantage of the centralization of certificates, Redtrust offers a signature service for simple and advanced signatures, following the DSS (Digital Signature Service) standard of OASIS (https://www.oasis-open.org/committees/dss/) and some of its extensions.

This document is intended for integrators who want to use Redtrust DSS signature server.

Methods

The Redtrust document signing service complies with the OASIS DSS standard and some extensions of it.

The service is composed of three methods:

1. `GetAccessibleCertificates`

This method retrieves the list of certificates available for the authenticated user, based on Redtrust authorization policies.

To call this method, authenticate as the user whose certificates you want to retrieve. The response includes a Result object containing the list of accessible certificates.

2. `SignHash`

This method performs a digital signature on a pre-calculated hash using the selected certificate.

You must call the SignHash method and provide:

The hash to be signed
The signature type
The certificate identification details

The service generates a signature in PKCS#1 format. Additional details and examples are provided in the next sections.

3. `SignRequest`

Performs a complete document signing operation based on the OASIS DSS standard.

To use this method, send a valid SignRequest object conforming to the DSS schema and its extensions. This object must include all information required to generate a valid signature.

The server responds with a SignResponse object containing:

A response code and message
The result of the signing process

Refer to the OASIS specification for the structure of these objects:

The following sections explain the required elements in these messages to help you build valid requests and interpret responses.

Authentication

You can send signature requests to three different links, depending on the desired authentication type (assuming you are using SOAP 1.2). You must replace REDTRUST_ID with the DNS or IP of the Redtrust server.

Username and Password

Uses WS-Security UsernameToken headers.
Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/basic

Certificate Authentication

Requires a TLS client certificate.
Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/secure

JWToken Authentication

This method allows authentication via a signed JSON Web Token (JWT), included in the SOAP header as a BinarySecurityToken.

Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/jwtoken
Example header:

    <soapenv:Envelope
        xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
        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"
        xmlns:urn="urn:evolium:redtrust:dss:ws">
    
    <soapenv:Header>
        <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
            urn:evolium:redtrust:dss:ws/RTDSSService/GetAccessibleCertificates
        </wsa:Action>
        <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
            https://localhost:8080/RTDSSService.svc/jwtoken
        </wsa:To>
        <wsse:Security >
        <wsse:BinarySecurityToken
            ValueType="urn:custom:jwt"
            EncodingType="urn:custom:jwt">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoie1widXNlcm5hbWVcIjpcImRldmVsb3BlclwiLFwidXNlcl9pZFwiOjEsXCJkb21haW5cIjpcImxvY2FsLnVzZXJzXCIsXCJyZWZlcmVuY2VcIjpcImE0YjlhYTg1OWQxNTA5YWRjNTE5NDgyM2ExNmFlNDM2YTQ3ZjUwZjI3ZWZjNjU2ODUyMTg5ZWI5NjY4NDBkNGZcIixcImNvbnN1bWVyXCI6XCJEU1NcIn0iLCJuYmYiOjE3NTAwNzc4ODAsImV4cCI6MTc1MDA3ODE4MCwiaWF0IjoxNzUwMDc3ODgwLCJpc3MiOiJSZWR0cnVzdCBBdXRoIEFQSSIsImF1ZCI6IkRTUyJ9.KzNJl0lDEw2rJ7qQZ3dLKMFI9HpugBdGN5j_zRz6_XI</wsse:BinarySecurityToken>
        </wsse:Security>
    </soapenv:Header>
    
    <soapenv:Body>
        <urn:GetAccessibleCertificates/>
    </soapenv:Body>

    </soapenv:Envelope>

The token must be generated by Redtrust.

Transport and Security

The Redtrust DSS API uses SOAP 1.1 or 1.2 over HTTPS for all request and response exchanges.

Request requirements

Only one <SignRequest> element may be included in the SOAP body.
No additional XML elements may appear inside the SOAP body.
UTF-8 encoding must be used.
Arbitrary SOAP headers are permitted.

Response format

The server returns either a <SignResponse> element or a SOAP fault.
No additional XML elements appear in the SOAP body.
If the server cannot parse the DSS request or encounters a SOAP error, a SOAP fault is returned.
If the server successfully processes the request, it returns a DSS result code, even if the signature operation fails.
UTF-8 encoding is used.
Arbitrary SOAP headers may be present.

Security protocols

The Redtrust DSS API complies with the following WS standards:

WS-Security 1.1
WS-Trust (February 2005)
WS-SecureConversation (February 2005)
WS-SecurityPolicy 1.1

WSDL

To download the WSDL with the complete service definition you can access the URL of your server as follows:

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

By default, the connection port is 8080, but this port is configurable through the Redtrust admin console. 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.

In Appendix 1: WSDL you have the WSDL code needed to generate the client in the desired language.

Protocol details

Optional inputs

The OptionalInputs contain additional information associated with the processing of the signature request.

The Redtrust service considers the following OptionalInputs, some of them being defined as mandatory, as specified below:

Generic use
`ServicePolicy`	Future use.
`ClaimedIdentity`	Future use.
`Language`	Defines the language of the descriptive messages contained in the service response (optional).
`AdditionalProfile`	Future use.
`Schemas`	Future use.

Signature input
`SignatureType`	Future use in the timestamp.
`AddTimestamp`	Future use in the timestamp.
`IntendedAudience`	Future use.
`Properties`	Future use.
`KeySelector`	Tells the service which certificate should be used to sign the document using the thumbprint of the document (mandatory).
`AdditionalKeyInfo`	It specifies whether the the certificate specified in `KeySelector` requires PIN verification (optional).
`IncludeObject`	Specifies to the service that an enveloping signature is desired (optional).
`IncludeEContent`	Specifies to the service that an enveloped signature is desired, valid for CMS and CadES signatures (optional).
`SignaturePlacement`	Specifies to the service that an enveloped type signature is desired, valid for XmlDsig and XadES signatures (optional).
`SignedReferences`	Future use.
`SignatureForm`	Determines the level of the signature to be made (optional).
`VisibleSignatureConfiguration`	Specifies the visual representation of the signature in PadES signatures (optional).

Supported modes

Redtrust allows signatures to be made in different modes. The signature mode tells the server how the signature should be packaged with respect to the original document in the following ways:

Enveloped: The signature is enclosed within the document.
Enveloping: The document is inside the signature.
Detached: The signature is a separate object.

The supported modes field can be specified in the signature profile configuration, either as a fixed value or left open, or passed as a parameter in the SignRequest. If a value is provided in the SignRequest, it must be compatible with the values defined in the signature profile.

Depending on the type of document to be sent one or more modes are supported. The OptionalInputs in the SignRequest provided by the protocol are used to indicate the mode in the call. The way to specify the mode differs depending on the type of document:

Document type	Supported signature mode	Specification
XML	Detached	No specification required.
	Enveloped	You must specify the `SignaturePlacement` field. See https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076071 for more information.
	Enveloping	You must specify the `IncludeObject` field. See https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076069 for more information.
CMS	Detached	No specification required.
	Enveloping	You must specify the `IncludeEContent` field. See https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076070 for more information.
PDF	Enveloped	No specification required.

Both SignaturePlacement and IncludeObject must specify the WhichDocument attribute, which contains the document identifier to be signed. If the document isn't found in the SignRequest the server returns a document not found error.

Response

<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=”profile” RequestID=”dss-sign-request-1” 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>

Supported levels

Redtrust allows signatures at different levels. The signature level tells the server what objects to include in the signature. The higher the level, the more information is included in the signature making it more secure, but also harder to create and to validate. The objects that can be included in the signature are: the signature policy, timestamps, certificates of the signature certificate chain, validation of the certificates included in the signature.

Different levels are supported depending on the type of document to be sent:

XML and CMS
Basic	Most basic form of signature, can be XMLDsig or CMS.
BES	Basic form that meets the legal requirements of the directive for advanced electronic signature.
EPES	Basic form to which signature policy information has been added.
ES_T	Adds a timestamp field to protect against repudiation.
ES_C	Adds references to verification data (certificates and revocation lists) to signed documents to allow off-line verification and validation in the future (but doesn't store the data itself).
ES_X	Adds timestamps to references entered by XadES-C to prevent a certificate chain from being compromised in the future.
ES_XL	Adds certificates and revocation lists to signed documents to allow future verification even if the original sources (certificate lookup or revocation lists) are no longer available.
ES_A	Adds the possibility of periodic timestamping (e.g. every year) for archived documents. This prevents documents from being compromised due to weak signatures over a long storage period.

PDF
BES	Basic form that meets the legal requirements of the directive for advanced electronic signature.
EPES	Basic form to which information on the signature policy has been added.
LTV	Equivalent to ES_A.

To indicate the level in the call, use an OptionalInput inside the SignRequest:

<SignatureForm xmlns=”urn:evolium:Redtrust:dss:1.0:core:schema”>XXX</SignatureForm>

The tag value must contain one of the following values:

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:BES

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:EPES

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-T

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-C

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-1

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-2

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-L-1

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-L-2

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-A

urn:oasis:names:tc:dss:1.0:profiles:PadES:forms:LTV

Encapsulation

Redtrust allows to include the document in the signature request in different ways.

This field has to be defined in the SignRequest inside the InputDocuments element. Redtrust currently supports Document elements but doesn't support TransformedData and DocumentHash elements. For more information on the InputDocuments element, see https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076032. For more information about Document, see https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076034.

The following encapsulations are supported depending on the type of document to be sent:

XML

Base64Xml: XML content in base64. InlineXml: XML content directly embedded. EscapedXml: Escaped XML content.

CMS and PDF

Base64Data: Contents of the file encoded in base64. The type of document to be sent must be specified using the MimeType attribute. Supported MimeType are application/pdf for PDF files and text/plain or application/binary for CMS.

Response

<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=”profile” RequestID=”dss-sign-request-1” 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> 

Overview​

Methods​

1. GetAccessibleCertificates​

2. SignHash​

3. SignRequest​

Authentication​

Username and Password​

Certificate Authentication​

JWToken Authentication​

Transport and Security​

Request requirements​

Response format​

Security protocols​

WSDL​

Protocol details​

Optional inputs​

Supported modes​

Supported levels​

Encapsulation​