Client HTTP Interface | SignServer

SignServer exposes four HTTP servlets that accept signing and validation requests directly over HTTP, without going through the REST API or a web client. Each servlet accepts GET or POST requests and returns the signed or validated result in the HTTP response body.

Overview

Servlet	Endpoint	Methods	Purpose
Generic Process Servlet	`/signserver/process`	`GET`, `POST`	General-purpose signing and validation requests
Worker Servlet	`/signserver/worker/*`	`GET`, `POST`	Same as Generic Process Servlet, with the Worker fixed in the URL
SOD Process Servlet	`/signserver/sod`	`GET` (certificate), `POST`(sign)	ePassport (MRTD) SOD signing, and Signer certificate retrieval
SOD Process Worker Servlet	`/signserver/sodworker`	`POST`	Same as SOD Process Servlet, with the Worker fixed in the URL

Generic Process Servlet

General-purpose endpoint for signing and validation requests. The Worker is selected with the workerName or workerId parameter.

Request

GET|POST /signserver/process

Request content-type: None, x-www-form-urlencoded, multipart/form-data, or other.

If the request content-type in a POST is specified as something else than x-www-form-urlencoded or multipart/form-data, the message body is not parsed but instead directly passed to the Worker specified by workerName or workerId in the URI's query string.

Request Parameter	Description
`workerName`	Name of the Worker that should handle the request. Required unless `workerId` specified.
`workerId`	ID of the Worker that should handle the request. Required unless `workerName` specified.
`data`	The bytes that should be signed or validated. Required for `x-www-form-urlencoded`.
`filereceivefile`	File upload used with multipart/form-data.
`pdfPassword`	(Optional) Password for changing PDF. This can also be specified using the generic meta data parameters described below, using the key "pdfPassword". Only used by PDF Signer.
`REQUEST_METADATA`	(Optional) Metadata to pass on. Specified in Java properties file syntax.
`REQUEST_METADATA.x`	(Optional) Sets a meta data parameter with the key specified by `x`. Overrides a value using the same key specified in the `REQUEST_METADATA` map.
`encoding`	(Optional) Encoding of the data field. By specifying `base64`, SignServer Base64-decodes the data property before passing it to the Worker.
`processType`	(Optional) The type of request. Valid options: `signDocument`, `validateDocument`, or `validateCertificate`. If not specified, defaults to `signDocument`.

Response

Response content-type depends on the Worker. For validators, the type is text/plain. See Response Codes.

Response content:

Signers return the signed document.
Document validators return a string starting with VALID or INVALID.
Certificate validators return a ;-separated string: validation status code (see below), valid purposes, status message, revocation reason (-1 if not revoked), and revocation date (empty if not revoked).

Validation Status Code	Description
`VALID`	The certificate is valid
`REVOKED`	The certificate has been revoked
`NOTYETVALID`	The certificate is not yet valid
`EXPIRED`	The certificate has expired
`DONTVERIFY`	The certificate does not verify
`CAREVOKED`	The CA certificate has been revoked
`CANOTYETVALID`	The CA certificate is not yet valid
`CAEXPIRED`	The CA certificate has expired
`BADCERTPURPOSE`	The certificate has no valid certificate purpose
`ISSUERNOTSUPPORTED`	The issuer of the certificate is not supported

Worker Servlet

HTTP requests can be sent to the SignServer servlet WorkerServlet located at /signserver/worker/* using either POST or GET.
Requests are forwarded to the GenericProcessServlet, except that the Worker name is taken from the URL. Worker name or ID given through request parameters are ignored.

Request

GET|POST /signserver/worker/* (* denotes a Worker name)

Request content-type: None, x-www-form-urlencoded, multipart/form-data, or other.

Request Parameter	Description
`data`	The bytes that should be signed or validated. Required for `x-www-form-urlencoded`.
`filereceivefile`	File upload used with multipart/form-data.
`pdfPassword`	(Optional) Password for changing PDF. This can also be specified using the generic meta data parameters described below, using the key "pdfPassword". Only used by PDF Signer.
`encoding`	(Optional) Encoding of the data field. By specifying `base64`, SignServer Base64-decodes the data property before passing it to the Worker.

Response

Response content-type depends on the Worker. For validators, the type is text/plain. See Response Codes.

SOD Process Servlet

The SOD Process Servlet receives HTTP POST requests containing data group hashes and creates a MRTD SOD Signer Request and passes it to the specified MRTD SOD Signer. The response from the servlet is the signed security object in binary format.

ePassport Signing Requests

POST /signserver/sod

Request parameters	Description
`workerName`	Name of the Worker to get the certificate from. Required unless `workerId` specified.
`workerId`	Id of the Worker to get the certificate from. Required unless `workerName` specified.
`dataGroup1 to dataGroup16`	The data group hashes that should be put in the SO(d). At least one required.
`encoding`	(Optional) Encoding of the data group hash fields. By specifying `base64`, SignServer Base64-decodes the data property before passing it to the MRTD SOD Signer.
`ldsVersion`	(Optional) Request a specific LDS version: `0107` for V1.7 `0108` for V1.8 If not specified, the version from the configuration is used. If version is V1.8, `unicodeVersion` also needs to be specified.
`unicodeVersion`	(Optional) Unicode version to store in the SOD. Only supported if the LDS version is V1.8. Specify `040000` for Unicode version 4.0.0.

Other Requests

GET /signserver/sod

Request parameters	Description
`workerName`	Name of the Worker to get the certificate from. Required unless `workerId` specified.
`workerId`	Id of the Worker to get the certificate from. Required unless `workerName` specified.
`downloadCert`	If set to `true`, the current Signer certificate is downloaded in binary (DER) format.
`displayCert`	If set to `true`, the current Signer certificate is displayed in text format.

Example Configuration

HTML

 <h1>MRTD SOD Signing</h1>
                    <p>Enter the data for the data groups to be stored on the passport.</p>
                    <p>Note 1: Please provide the hashes of the respective data groups if the signer is configured to accept hashes instead of the actual data.</p>
                    <p>Note 2: When submitting this form using a web browser it is not possible to enter binary data directly into the input fields. Then first base64 encode the data and choose the base64 encoding option and the signer will decode the data before signing it.</p>
                    
                    <form id="requestform" action="../sod" method="post">
                        <h3>Worker</h3>
                        <p>
                            Name: <input type="text" name="workerName"/>
                        </p>
                        
                        <h3>Input</h3>
                        <p>
                            DG1: <input type="text" size="80" name="dataGroup1" value="PJaDAX+eS/M9D77dJr8UP9ct6bndFFRBt18GBAR+oo4="/><br/>
                            DG2: <input type="text" size="80" name="dataGroup2" value="BTfUgfc6dXM0MoBS2jr5YmztlwKOILhJ9hFcIs12UZc="/><br/>
                            DG3: <input type="text" size="80" name="dataGroup3" value="idxq5/Bqn0a1Za8D6rDs4L9gJNNlm346HQNXPP6wtZ0="/><br/>
                            DG4: <input type="text" size="80" name="dataGroup4"/><br/>
                            DG5: <input type="text" size="80" name="dataGroup5"/><br/>
                            DG6: <input type="text" size="80" name="dataGroup6"/><br/>
                            DG7: <input type="text" size="80" name="dataGroup7"/><br/>
                            DG8: <input type="text" size="80" name="dataGroup8"/><br/>
                            DG9: <input type="text" size="80" name="dataGroup9"/><br/>
                            DG10: <input type="text" size="80" name="dataGroup10"/><br/>
                            DG11: <input type="text" size="80" name="dataGroup11"/><br/>
                            DG12: <input type="text" size="80" name="dataGroup12"/><br/>
                            DG13: <input type="text" size="80" name="dataGroup13"/><br/>
                            DG14: <input type="text" size="80" name="dataGroup14"/><br/>
                            DG15: <input type="text" size="80" name="dataGroup15"/><br/>
                            DG16: <input type="text" size="80" name="dataGroup16"/><br/>
                        </p>
                        <!-- if encoding = binary values will not be base64 decoded before use -->
                        <!-- a good test value, base64 encoded is PJaDAX+eS/M9D77dJr8UP9ct6bndFFRBt18GBAR+oo4= -->
                        <p>
                            Encoding of datagroups:<br/>
                            <input type="radio" name="encoding" value="binary"/>None<br/>
                            <input type="radio" name="encoding" value="base64" checked="checked"/>Base64
                        </p>

                        <h3>Options</h3>
                        <p>
                            Request LDS version:<br/>
                            <input type="radio" name="ldsVersion" value="" id="ldsNo" checked="checked"/><label for="ldsNo">Unspecified</label><br/>
                            <input type="radio" name="ldsVersion" value="0107" id="lds0107"/><label for="lds0107">V1.7</label><br/>
                            <input type="radio" name="ldsVersion" value="0108" id="lds0108"/><label for="lds0108">V1.8</label><br/>
                            <label for="unicodeField">Unicode version:</label> <input type="text" size="6" name="unicodeVersion" id="unicodeField" value="040000"/>
                        </p>
                        <details>
                            <summary>Generic meta data</summary>
                            <p>
                                Include additional meta data with the request:<br/>
                                <textarea name="REQUEST_METADATA" cols="40" rows="5"></textarea><br/>
                            </p>
                        </details>
                        
                        <h3>Submit</h3>
                        <p>
                            <input type="submit" name="submit" value="Submit" class="buttonFeatured"/><br />
                        </p>
                        
                        <h3>Other Actions</h3>
                        <p>
                            <input type="submit" name="displayCert" value="Display Signer Certificate" class="buttonNeutral"/><br/>
                        </p>
                        <p>
                            <input type="submit" name="downloadCert" value="Download Signer Certificate" class="buttonNeutral"/><br/>
                        </p>

Response

Response content-type: application/octet-stream. See Response Codes.

SOD Process Worker Servlet

Servlet receiving HTTP POST requests containing data group hashes and creates a MRTD SOD Signer Request and passes it to the specified MRTD SOD Signer. The response from the servlet is the signed security object in binary format.
Requests are forwarded to the SOD Process Servlet, except that the Worker name is taken from the URL. Worker name or ID given through request parameters are ignored.

Request

POST /signserver/sodworker

Request parameters	Description
`dataGroup1 to dataGroup16`	The data group hashes that should be put in the SO(d). At least one required.
`encoding`	(Optional) Encoding of the data group hash fields. By specifying `base64`, SignServer Base64-decodes the data property before passing it to the MRTD SOD Signer.
`ldsVersion`	(Optional) Request a specific LDS version: `0107` for V1.7 `0108` for V1.8 If not specified, the version from the configuration is used. If version is V1.8, `unicodeVersion` also needs to be specified.
`unicodeVersion`	(Optional) Unicode version to store in the SOd. Optional. Only supported if the LDS version is V1.8. Specify `040000` for Unicode version 4.0.0.

Example Configuration

HTML

 <h1>MRTD SOD Signing</h1>
                    <p>Enter the data for the data groups to be stored on the passport.</p>
                    <p>Note 1: Please provide the hashes of the respective data groups if the signer is configured to accept hashes instead of the actual data.</p>
                    <p>Note 2: When submitting this form using a web browser it is not possible to enter binary data directly into the input fields. Then first base64 encode the data and choose the base64 encoding option and the signer will decode the data before signing it.</p>
                    
                    <form id="requestform" action="../sod" method="post">
                        <h3>Worker</h3>
                        <p>
                            Name: <input type="text" name="workerName"/>
                        </p>
                        
                        <h3>Input</h3>
                        <p>
                            DG1: <input type="text" size="80" name="dataGroup1" value="PJaDAX+eS/M9D77dJr8UP9ct6bndFFRBt18GBAR+oo4="/><br/>
                            DG2: <input type="text" size="80" name="dataGroup2" value="BTfUgfc6dXM0MoBS2jr5YmztlwKOILhJ9hFcIs12UZc="/><br/>
                            DG3: <input type="text" size="80" name="dataGroup3" value="idxq5/Bqn0a1Za8D6rDs4L9gJNNlm346HQNXPP6wtZ0="/><br/>
                            DG4: <input type="text" size="80" name="dataGroup4"/><br/>
                            DG5: <input type="text" size="80" name="dataGroup5"/><br/>
                            DG6: <input type="text" size="80" name="dataGroup6"/><br/>
                            DG7: <input type="text" size="80" name="dataGroup7"/><br/>
                            DG8: <input type="text" size="80" name="dataGroup8"/><br/>
                            DG9: <input type="text" size="80" name="dataGroup9"/><br/>
                            DG10: <input type="text" size="80" name="dataGroup10"/><br/>
                            DG11: <input type="text" size="80" name="dataGroup11"/><br/>
                            DG12: <input type="text" size="80" name="dataGroup12"/><br/>
                            DG13: <input type="text" size="80" name="dataGroup13"/><br/>
                            DG14: <input type="text" size="80" name="dataGroup14"/><br/>
                            DG15: <input type="text" size="80" name="dataGroup15"/><br/>
                            DG16: <input type="text" size="80" name="dataGroup16"/><br/>
                        </p>
                        <!-- if encoding = binary values will not be base64 decoded before use -->
                        <!-- a good test value, base64 encoded is PJaDAX+eS/M9D77dJr8UP9ct6bndFFRBt18GBAR+oo4= -->
                        <p>
                            Encoding of datagroups:<br/>
                            <input type="radio" name="encoding" value="binary"/>None<br/>
                            <input type="radio" name="encoding" value="base64" checked="checked"/>Base64
                        </p>

                        <h3>Options</h3>
                        <p>
                            Request LDS version:<br/>
                            <input type="radio" name="ldsVersion" value="" id="ldsNo" checked="checked"/><label for="ldsNo">Unspecified</label><br/>
                            <input type="radio" name="ldsVersion" value="0107" id="lds0107"/><label for="lds0107">V1.7</label><br/>
                            <input type="radio" name="ldsVersion" value="0108" id="lds0108"/><label for="lds0108">V1.8</label><br/>
                            <label for="unicodeField">Unicode version:</label> <input type="text" size="6" name="unicodeVersion" id="unicodeField" value="040000"/>
                        </p>
                        <details>
                            <summary>Generic meta data</summary>
                            <p>
                                Include additional meta data with the request:<br/>
                                <textarea name="REQUEST_METADATA" cols="40" rows="5"></textarea><br/>
                            </p>
                        </details>
                        
                        <h3>Submit</h3>
                        <p>
                            <input type="submit" name="submit" value="Submit" class="buttonFeatured"/><br />
                        </p>
                        
                        <h3>Other Actions</h3>
                        <p>
                            <input type="submit" name="displayCert" value="Display Signer Certificate" class="buttonNeutral"/><br/>
                        </p>
                        <p>
                            <input type="submit" name="downloadCert" value="Download Signer Certificate" class="buttonNeutral"/><br/>
                        </p>

Response

Response content-type: application/octet-stream. See Response Codes.

Response Codes

Status	Meaning
`200 OK`	The request was successful.
`400 Bad Request`	The request could not be fulfilled. Some request data were missing or incorrect.
`401 Unauthorized`	The Worker requires user authentication.
`404 Not Found`	The requested `workerName` or `workerId` does not represent an existing Worker.
`413 Request Entity Too Large`	The data field or uploaded file is too large. See the HTTP_MAX_UPLOAD_SIZE global configuration property.
`500 Internal Server Error`	There was an internal error when processing the request. Typically indicating a configuration problem or unexpected error at the server side.
`503 Service Unavailable`	The Worker is not active, such as the Crypto Token is not activated or similar issue.

Configuration Properties

These global configuration properties apply to all four servlets. For more information, see Global Configuration Properties for the full list and how to set them.

Property	Default	Description
`HTTP_MAX_UPLOAD_SIZE`	`104857600` (100 MB)	Global configuration property that can be set to specify the maximum size (in bytes) that is allowed for an HTTP request.
`HTTP_MAX_UPLOAD_FIELD_COUNT`	`16`	Global configuration property that is set to a default of 16 which typically would support up to around 10 request metadata properties depending on how many other fields are provided. If more fields are needed, the property can be adjusted.
`FILE_SIZE_THRESHOLD`	`1048576` (1 MB)	Global configuration property that can be set to specify the size threshold (in bytes) after which the data is written to disk. The directory uploaded files are temporarily stored to is the default temp directory and can be changed by starting the application server with a different value for the Java property java.io.tmpdir.

Property

Default

Description

HTTP_MAX_UPLOAD_SIZE

104857600 (100 MB)

Global configuration property that can be set to specify the maximum size (in bytes) that is allowed for an HTTP request.

HTTP_MAX_UPLOAD_FIELD_COUNT

16

Global configuration property that is set to a default of 16 which typically would support up to around 10 request metadata properties depending on how many other fields are provided. If more fields are needed, the property can be adjusted.

FILE_SIZE_THRESHOLD

1048576 (1 MB)

Global configuration property that can be set to specify the size threshold (in bytes) after which the data is written to disk.

The directory uploaded files are temporarily stored to is the default temp directory and can be changed by starting the application server with a different value for the Java property java.io.tmpdir.