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.
Background
The Redtrust document signing service complies with the OASIS DSS standard and some extensions of it.
The service is composed of three methods: (1) one method to retrieve accessible certificates to be used for signing with the DSS service (through Redtrust authorization policies), (2) one to perform signatures using the DSS standard, and (3) one to perform hash signatures.
To retrieve the list of accessible certificates, you have to call the GetAccessibleCertificates
method authenticated as the user from whom you want to retrieve the list of certificates. As a response you obtain a Result
object with the information of the request.
To sign a hash, you have to call the SignHash
method, providing the hash to sign, the type of signature you want to perform on it and information about the certificate to use. The generated signature is of type PKCS#1. The following sections provide a more detailed description of the method and examples of its use.
To sign, you have to call the SignRequest
method, to which you must pass an object of type signRequest
as a parameter. This object must be valid for the OASIS DSS schema and its extensions and must contain all the necessary information for the service to generate a valid signature. For detailed information about the signRequest
object please refer to the OASIS documentation http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076052.
The response to a SignRequest
call returns a signResponse
object, which like the signRequest
, must be valid according to the OASIS DSS schema and must contain a response code plus a message and the result of the signature process (depending on whether the signature could be processed). For detailed information about the signResponse
object, please refer to the OASIS documentation http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076053.
The following sections explain the contents of these objects so that you can compose a valid message to the service and interpret the response.
Service definition
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 administration web. 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 administration web. 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.
Transport and security
In the transport layer, the request/response exchange is done via SOAP 1.1 or 1.2. For the request the following rules apply:
- Only one
<SignRequest>
element within the SOAP message body. - No additional XML elements may be included within the SOAP.
- Encoding must be UTF-8.
- Arbitrary SOAP headers may be present.
The following apply to the response:
- The server returns a single
<SignResponse>
element within the SOAP message body, or a SOAP error code. - The server doesn't include additional XML elements in the SOAP body.
- If the server can't parse a DSS request, or there is an error with the SOAP, the server returns a SOAP error code. In any other case a DSS result code will be returned, both for successful signatures and errors.
- Encoding must be UTF-8.
- Arbitrary SOAP headers may be present.
The protocol complies with the security specifications WS-Security 1.1, WS-Trust February 2005, WS-SecureConversation February 2005 and WS-SecurityPolicy 1.1.
You can send signature requests to two 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.
User-Password → https://REDTRUST_IP:8080/RTDSSService.svc/basic
Certificate → https://REDTRUST_IP:8080/RTDSSService.svc/secure
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. | |
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.
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.
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. |
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>