DSS API reference

This page describes the cross-cutting rules and common fields for the Redtrust DSS API:

• how you authenticate
• how SOAP messages must look
• how you express signing modes, levels, and document encapsulation

If you want a guided walkthrough, start with the tutorial.
If you want copy/paste payloads for common scenarios, use the examples page.

Endpoints and authentication

Redtrust exposes three service endpoints (examples below assume SOAP 1.2):

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

• Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/jwtoken
• You authenticate with a signed JWT in the SOAP header as a BinarySecurityToken.
• Redtrust generates the token.

Transport and message constraints

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

Request constraints

• Put only one SignRequest element in the SOAP body.
• Do not include additional elements inside the SOAP body.
• Use UTF-8 encoding.
• You can include arbitrary SOAP headers.

Response constraints

• The server returns either a SignResponse element or a SOAP fault.
• No additional XML elements appear in the SOAP body.
• When the server cannot parse the DSS request, or encounters a SOAP error, a SOAP fault is returned.
• When 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 service listens on port 8080. You can configure the port and the HTTPS certificate in the Redtrust admin console. Your client needs to trust the service certificate unless you configure the client to accept any certificate.

See WSDL.

SignRequest common fields

You pass signing jobs through SignRequest (SOAP body). The request uses:

• Profile (the signature profile configured in Redtrust)
• RequestID (optional, but strongly recommended for tracing)
• OptionalInputs (common knobs such as certificate selection and signature form)
• InputDocuments (the document you want to sign)

Optional inputs

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

info

Some optional inputs defined by the OASIS DSS specification are currently not used by Redtrust. These fields are accepted for schema compatibility but have no effect on the signature process.

The following inputs are not currently supported:

• ServicePolicy
• ClaimedIdentity
• AdditionalProfile
• Schemas
• SignatureType
• AddTimestamp
• IntendedAudience
• Properties
• SignedReferences

Generic input
Language	Defines the language of the descriptive messages contained in the service response (optional).

Signature input
KeySelector	Tells the service which certificate should be used to sign the document using its thumbprint (mandatory). This mechanism is specific to the Redtrust DSS implementation and is used across all signing profiles.
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).

The visual representation part of the signature is located inside the VisibleSignatureConfiguration tag and contains:

Input	Description
VisibleSignaturePolicy	Contains the text GeneralPolicy, which is the only visual representation policy accepted by Redtrust.
VisibleSignaturePosition	Specifies the location (counting from the lower left corner) and size in pixels of the display.
VisibleSignatureItemsConfiguration	Contains a sequence of elements that indicate how the visual signature will look like. For example SignatureReason indicates a reason, SignatureProductionPlaceindicates a signing location, SignerContactInfo indicates a signer contact information, CustomText that indicates that the visual representation of the signature will contain a descriptive text of the certificate, namely the content of SubjectName, and SignerImage indicating where is the image to embed as a visual signature.

Supported signature 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.

One or more modes are supported depending on the type of document to be sent . 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.

When you use SignaturePlacement or IncludeObject, set WhichDocument to the identifier of the document you want to sign.

Supported signature levels

The signature level tells the server what objects to include in the signature, for example the signature policy, timestamps, certificates of the signature certificate chain and validation of the certificates included in the signature. Higher levels include more data and are more secure but require more processing.

XML and CMS

Level	Description
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

Level	Description
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.

SignatureForm

To set a level, add SignatureForm inside OptionalInputs and use one of the supported URNs. They have to follow this format.

SignatureForm xmlns="urn:evolium:Redtrust:dss:1.0:core:schema">URN</

The URN value must be one of the following:

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

Document encapsulation

You provide the document to sign under InputDocuments in the SignRequest. Redtrust currently supports Document elements but doesn't support TransformedData and DocumentHash elements.

info

For more information, check thee InputDocuments and Document sections of the Oasis documentation.

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 include application/pdf for PDF files and text/plain or application/binary for CMS.