DSS 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.
In the response you get a Result object, with a ResultStatus in success status indicating that no error has occurred. You also get a ResultMessage with a descriptive message and a ResultData object which is a list of Certificate objects.
Each Certificate object contains the information necessary for its use. For example the following:
| Parameters | Description |
|---|---|
needPin | To know if you need a PIN to use it. |
thumbprint | Identifier used in SignHash, SignRequest expiration to know if it's expired or not. |
alias | Name given to the certificate from the Redtrust configuration. |
issue or subject | Information extracted directly from the certificate for those fields or the thumbprint itself. |
X509Data | Public part of the certificate. The content of this attribute is Base64 encoded so that it can be included in the response. |
filter | Optional filter for the returned certificate list. Matches any string contained in the certificate subject field. If omitted or empty, the service returns all 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.
The input parameters of the method are:
| Parameters | Description |
|---|---|
toSignHash | Base64 encoded binary hash. |
thumbprint | Fingerprint of the certificate. |
certificatePin | Certificate PIN (Optional). |
algorithm | Hashing algorithm, accepted values are RSA_SHA1, RSA_SHA256, RSA_SHA512, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512. |
In response you get a Result object with the following fields:
| Field | Description |
|---|---|
| ResultStatus | Result code, SUCCESS if the signature was successful. |
| ResultMessage | Message describing the result of the operation. |
| ResultData | Contains the result of the operation if the signature was successful (Optional). |
See Result response codes of this document for possible error codes you may get in the response.
3. SignRequest
Performs a complete document signing operation based on the OASIS DSS standard.
To use this method, send a valid SignRequest object that conforms to the DSS schema and its extensions. The request specifies the signature profile, the
signing certificate, and the input document. The server responds with a SignResponse object containing:
- A response code and message
- The result of the signing operation
Request structure
The following fields form the core of most signing requests. Depending on the signature profile configuration, some fields can be forced by the profile and omitted from the request.
| Field | Location | Description |
|---|---|---|
Profile | SignRequest attribute | Identifies the signature profile configured in Redtrust. The profile can force the signature mode, level, and other options. |
RequestID | SignRequest attribute | Identifier returned in the response to help correlate requests and responses. |
OptionalInputs | SignRequest body | Optional inputs that influence how the signature is produced. |
KeySelector | OptionalInputs | Selects the signing certificate (typically by thumbprint). |
AdditionalKeyInfo | OptionalInputs | Additional key information required by the certificate, such as a PIN. |
SignatureForm | OptionalInputs | Signature form used by the service to validate and process the request. |
| Signature mode element | OptionalInputs | Specifies how the signature relates to the document when the profile does not force it (for example, enveloped, enveloping, or detached). |
InputDocuments | SignRequest body | Container for the document or documents to sign. |
Document | InputDocuments | Input document. The ID attribute can be referenced by other elements in the request. |
| Document content element | Document | Supplies the document content (binary or XML), depending on the signing scenario. |
For complete request and response examples, see DSS API examples.
For detailed definitions, supported values, and constraints for DSS elements such as Profile, SignatureForm, and InputDocuments, see the DSS API reference.
For the normative structure of DSS messages, see the OASIS specification: