Client HTTP Interface

GenericProcessServlet

HTTP requests can be sent to the SignServer servlet GenericProcessServlet located at /signserver/process using either POST or GET.

URL:

/signserver/process

Method:

GET or POST

Request content-type:

None, "x-www-form-urlencoded", "multipart/form-data" or other*

Request parameters:

  • 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.

  • filerecievefile - File upload used with multipart/form-data.

  • pdfPassword - Password for changing PDF. This can also be specified using the generic meta data parameters described below, using the key "pdfPassword". Optional and only used by PDFSigner.

  • REQUEST_METADATA - Meta data to pass on. Specified in Java properties file syntax. Optional.

  • REQUEST_METADATA.x - Sets a meta data parameter with the key specified by x. Overrides a value using the same key specified in the REQUEST_METADATA map. Optional.

  • encoding - Encoding of the data field. Optional. By specifying "base64" SignServer Base64-decodes the data property before passing it to the worker.

  • processType - The type of request. Can be any of "signDocument", "validateDocument", or "validateCertificate". Optional. If not specified, defaults to "signDocument".

Response code:

  • HTTP 200 (OK): The request was successfull

  • HTTP 400 (Bad Request): The request could not be fulfilled. Some request data were missing or incorrect etc.

  • HTTP 401 (Unauthorized): The worker requires user authentication

  • HTTP 404 (Not Found): The requested workerName or workerId does not represent an existing worker

  • HTTP 413 (Request Entity Too Large): The data field or uploaded file is too large. See the HTTP_MAX_UPLOAD_SIZE global configuration property.

  • HTTP 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.

  • HTTP 503 (Service Unavailable): The worker is not active, its crypto token is not activated or similar

Response content-type:

Depending on the worker, text/plain for the validators.

Response content:

The signed document for signers.
A string starting with "VALID" or "INVALID" for document validators. *Note to integrators: In future versions of SignServer there might be more information added after VALID/INVALID, such as a ;-separated list of additional information or more lines with information.
A ;-separated string containing validation status code (see list below), valid purposes, status message, revocation reason (-1 if not revoked), and revocation date (empty when not revoked) for certificate validators.

Validation status codes:

  • 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 doesn't 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

* 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.

Configuration

HTTP_MAX_UPLOAD_SIZE = Global configuration property that can be set to specify the maximum size (in bytes) of the HTTP request. Defaut: "104857600" (100 MB).

FILE_SIZE_THRESHOLD = Global configuration property that can be set to specify the size threshold (in bytes) after which the data is written to disk Default: "1048576" (1 MB). The directory uploaded files are temporarly 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.

Samples

  • HTTP GET:
    http://localhost:8080/signserver/process?workerName=DemoXMLSigner&data=%3Croot%3Ehej2%3C/root%3E
    http://localhost:8080/signserver/process?workerName=DemoXMLSigner&encoding=base64&data=PGhlajI%2Bb2s8L2hlajI%2BCg%3D%3D

  • HTTP POST with multipart/form-data or x-www-form-urlencoded:
    For example see /signserver/clientweb/genericfile.xhtml (multipart/form-data) and /signserver/clientweb/genericdirect.xhtml (x-www-form-urlencoded).

    Example with cURL:

    curl -F workerName=PDFSigner -F file=@sample.pdf --output sample-signed.pdf http://localhost:8080/signserver/process

  • HTTP POST with other content-type:
    See the TimeStampClient.

  • Samples of content output for certificate validation:

    • VALID;;This certificate is valid;-1;

    • ISSUERNOTSUPPORTED;;Issuer of given certificate isn't supported;-1;

    • REVOKED;;This certificate is revoked;3;1376565200519

WorkerServlet

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.

URL:

/signserver/worker/* (* denotes a worker name)

Method:

GET or POST

Request content-type:

None, "x-www-form-urlencoded", "multipart/form-data" or other*

Request parameters:

  • data - The bytes that should be signed or validated. Required for x-www-form-urlencoded.

  • filerecievefile - File upload used with multipart/form-data.

  • pdfPassword - Password for changing PDF. Optionally and only used by PDFSigner.

  • encoding - Encoding of the data field. Optional. By specifying "base64" SignServer Base64-decodes the data property before passing it to the worker.

Response code:

  • HTTP 200 (OK): The request was successfull

  • HTTP 400 (Bad Request): The request could not be fulfilled. Some request data were missing or incorrect etc.

  • HTTP 401 (Unauthorized): The worker requires user authentication

  • HTTP 404 (Not Found): The requested workerName or workerId does not represent an existing worker

  • HTTP 413 (Request Entity Too Large): The data field or uploaded file is too large

  • HTTP 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.

  • HTTP 503 (Service Unavailable): The worker is not active, its crypto token is not activated or similar

Response content-type:

Depending on the worker

Samples

SODProcessServlet

Servlet recieving HTTP POST requests containing data group hashes and creates a MRTDSODSignerRequest and passes it to the specified MRTDSODSigner. The response from the servlet is the signed security object in binary format.

ePassport Signing Requests

URL:

/signserver/sod

Method:

POST

Request parameters:

  • 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.

  • dataGroup1 to dataGroup16 - The data group hashes that should be put in the SO(d). At least one required.

  • encoding - Encoding of the data group hash fields. Optional. By specifying "base64" SignServer Base64-decodes the data property before passing it to the MRTDSODSigner.

  • ldsVersion - Request a specific LDS version: "0107" for V1.7 or "0108" for V1.8. Optional. If not specified the version from the configuration is used. If version is V1.8 unicodeVersion also needs to be specified.

  • unicodeVersion - Unicode version to store in the SOd. Optional. Only supported if ldsVersion "0108" specified. Specify "040000" for Unicode version 4.0.0.

Response code:

The same response codes as for the GenericProcessServlet are used.

Response content-type:

application/octet-stream

Other Requests

URL:

/signserver/sod

Method:

GET

Request parameters:

  • 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.

Samples

SODProcessWorkerServlet

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

URL:

/signserver/sodworker

Method:

POST

Request parameters:

  • dataGroup1 to dataGroup16 - The data group hashes that should be put in the SO(d). At least one required.

  • encoding - Encoding of the data group hash fields. Optional. By specifying "base64" SignServer Base64-decodes the data property before passing it to the MRTDSODSigner.

  • ldsVersion - Request a specific LDS version: "0107" for V1.7 or "0108" for V1.8. Optional. If not specified the version from the configuration is used. If version is V1.8 unicodeVersion also needs to be specified.

  • unicodeVersion - Unicode version to store in the SOd. Optional. Only supported if ldsVersion "0108" specified. Specify "040000" for Unicode version 4.0.0.

Response code:

The same response codes as for the GenericProcessServlet are used.

Response content-type:

application/octet-stream

Samples

See /signserver/clientweb/mrtdsod.xhtml.