Integration

JavaDoc

The JavaDoc for SignServer is available at SIGNSERVER_HOME/target/site/apidocs/index.html after running "mvn javadoc:aggregate".

Client Web Service

The SignServer ClientWS interface can be used to request signings from SignServer.

The WSDL file is located at the URL http://<hostname>:8080/signserver/ClientWSService/ClientWS?wsdl and locally in the sources under modules/SignServer-Client-ClientWS/xml-resources/web-service-references/ClientWS/wsdl/localhost_8080/signserver/ClientWSService/ClientWS.wsdl.

Operations

processData

Generic operation for request signing of any binary (or character) data.

Parameters:

  • worker (string)
    Name of worker in SignServer which should handle the request.
  • metadata (sequence of key-value pairs)
    Optional additional request data. For instance the PDFSigner accepts the PDF password as a request data.
  • data (base64Binary)
    The document/data to process.

Output:

  • archiveId (string)
    Identifier for the request if archiving was used.
  • data (base64Binary)
    The signed binary/document.
  • metadata (sequence of key-value pairs)
    Any optional additional response data.
  • requestId (integer)
    Identifier for the request/response.
  • signerCertificate (base64Binary)
    The signer certificate in binary format if available.

Faults:

  • RequestFailedException
  • InternalServerException

processSOD

Operation for requesting an SOD to be created and signed.
The ePassport production system calls this operation to get an SOD for the supplied data groups.

Parameters:

  • worker (string)
    Name of worker in SignServer which should be used for constructing the SOD.
  • metadata (sequence of key-value pairs)
    Optional additional request data. Not used.
  • sodData (a sodRequest structure)
    The sodRequest should contain a sequence of datagroups (id 1-16 and their values), optionally also the version of the LDS to use and the version of Unicode.

Output:

  • archiveId (string)
    Identifier for the request if archiving was used.
  • data (base64Binary)
    The SOD binary.
  • metadata (sequence of key-value pairs)
    Any optional additional response data.
  • requestId (integer)
    Identifier for the request/response.
  • signerCertificate (base64Binary)
    The signer (DS) certificate in binary format if available.

Faults:

  • RequestFailedException
  • InternalServerException

The old Web Services interface

The SignServerWS is the old web services interface now replaced by SignServer ClientWS. It was new to version 3.0 and at the time replaced the RMI-SSL interface from version 1.0 and 2.0 for two reasons, the RMI-SSL were based on a commercial library and it only worked for Java clients.

The SignServerWS WSDL file is located at the URL http://<hostname>:8080/signserver/signserverws/signserverws?wsdl

The interface has two calls, the main one is 'process' which takes a collection of process request to a processable worker and returns a collection of process responses, the second one is getStatus that performs a health check of the node and returns an OK message if the node is healthy.

Notice: All though the SignServerWS interface uses web services the actual process data is base64 encoded byte arrays in a special binary format. You will have to lookup the Java source code for the exact format of the request and response data. An alternative is to instead use the much simpler Web Server Interface or the newer ClientWS interface.

The getStatus call can be used to implement high-availability towards the client. The Java client API described in the next section have built in support for different high availability policies.

It's possible to turn off the WebService interface by disabling it in the build configuration.

This interface is only supported using HTTPS. The reason is that JBoss 4 does not rewrite the protocol part of the WSDL URL so we had to hard code it for it to work with HTTPS. For details about this see DSS-327.

Since SignServer >=3.2.1 it is possible to supply extra request data called RequestMetadata containing key/value pairs that can be used by the signers. For instance the PDFSigner uses this feature to let the client supply a PDF password.

Java Client API

Built along with the WebService is a Java API that can be used by clients. It's available in the file lib/SignServer-Client-SignServerWS.jar (the old SignServerWS interface) and lib/SignServer-Client-ClientWS.jar (the ClientWS interface).

SigningAndValidation API

The SigningAndValidation API is a wrapper around the previous mentioned API in order to have a simplified interface that also is the same regardless if WebService or EJB Remote calls are used.

To use the API include the file lib/SignServer-Client-SigningAndValidationAPI.jar.

Sample Code

Signing and validating an XML document

try {
    System.setProperty("javax.net.ssl.trustStore", "p12/truststore.jks");
    System.setProperty("javax.net.ssl.trustStorePassword", "changeit");
  
    ISigningAndValidation signserver = new SigningAndValidationWS("localhost", 8442, true);

    // Document to sign
    byte[] unsigned = "<document><name>Some content</name></document>".getBytes();
    byte[] signed;

    // Signing
    GenericSignResponse signResp = signserver.sign("DemoXMLSigner", unsigned);
    signed = signResp.getProcessedData();
    System.out.println("Signed: " + new String(signed));

    // Validating
    GenericValidationResponse validateResp = signserver.validate("DemoXMLValidator", signed);
    System.out.println("Valid: " + validateResp.isValid());

    if(validateResp.getSignerCertificate() != null) {
        if(validateResp.getSignerCertificate() instanceof X509Certificate) {
            X509Certificate signerCert = (X509Certificate) validateResp.getSignerCertificate();
            System.out.println("Signed by: " + signerCert.getSubjectDN().getName());
        }
    }
} catch (Exception ex) {
    ex.printStackTrace();
}                                   

Web Server 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/demo/xmlsign.jsp (multipart/form-data) and /signserver/demo/genericsign.jsp (x-www-form-urlencoded).

  • 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

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

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.

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

Samples

  • See /signserver/demo/mrtdsodsign.jsp.

SODProcessWorkerServlet

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.
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/demo/mrtdsodsign.jsp.

Client Command Line Interface (CLI)

Requests can be sent to the workers using the Client CLI. After building SignServer the script bin/signclient can be run.

$ bin/signclient
usage: signclient <signdocument | validatedocument | timestamp | validatecertificate | signdatagroups>

signdocument

Request signing of a document using HTTP(s) or web services.

usage: signdocument <-workername WORKERNAME | -workerid WORKERID>
                    [options]
Request a document to be signed by SignServer
 -data             Data to send to the worker.
 -host             Server name or IP address. Default: localhost
 -indir            Directory to read input files from. Required if
                   outdir specified. Can not be combined with infile
                   or outfile.
 -infile           File to read data to send to the worker from.
 -keyalias         Alias of the key in the keystore to use for
                   authentication.
 -keystore         Keystore with private key and certificate for
                   client certificate authentication.
 -keystorepwd      Password for reading the keystore.  If keystore is
                   specified but not this keystore password option,
                   the CLI will instead prompt for the password.
 -metadata         Additional meta data to send to the signer. The
                   parameters should be given in the form KEY=VALUE.
                   This option can be given multiple times.
 -onefirst         In batch mode, don't send all requests until the
                   first succeeds. This is primary to prevent too many
                   incorrect password attempts. Default if username
                   is provided and -startall not provided.
 -outdir           Directory to write output files to. Required if
                   indir specified. Can not be combined with infile
                   or outfile.
 -outfile          File to write the result to. If not specified the
                   result is written to stdout.
 -password         Password for authentication. If username is
                   specified but not this password option, the CLI
                   will instead prompt for the password.
 -pdfpassword      Password for changing the PDF (if required).
 -port             Server port. Default: 8080 (for HTTP), 8442 for
                   HTTPS and 8443 for HTTPS with client
                   authentication.
 -protocol         Method of interacting with SignServer. HTTP,
                   CLIENTWS or WEBSERVICES. Default: HTTP.
 -removefromindir  Specify this flag to have the successfully
                   processed input files removed from indir.
 -servlet          Servlet to call. Default /signserver/process
 -startall         In batch mode, send all requests at once, without
                   waiting for the first to succeed. Default unless
                   username is provided or -onefirst provided.
 -threads          Number of threads for sending the requests. Only
                   allowed in batch mode, i.e. when indir and outdir
                   are specified. Default: 1.
 -truststore       Keystore with trusted certificates to use with
                   HTTPS.
 -truststorepwd    Password for the keystore with trusted
                   certificates. If truststore is specified but not
                   this truststore password option, the CLI will
                   instead prompt for the password.
 -username         Username for authentication.
 -workerid         ID of worker which should perform the operation.
 -workername       Name of worker which should perform the operation.

Sample usages:
a) signdocument -workername XMLSigner -data "<root/>"
b) signdocument -workername XMLSigner -infile /tmp/document.xml
c) signdocument -workerid 2 -data "<root/>" -truststore truststore.jks
-truststorepwd changeit
d) signdocument -workerid 2 -data "<root/>" -keystore superadmin.jks
-truststorepwd foo123
e) signdocument -workerid 2 -data "<root/>" -metadata param1=value1
-metadata param2=value2
f) signdocument -workerid 3 -indir ./input/ -removefromindir -outdir
./output/ -threads 5

validatedocument

Request a document to be validated.

usage: validatedocument <-workername WORKERNAME | -workerid WORKERID>
                        [options]
Request a document to be validated by SignServer
 -data             Data to send to the worker.
 -host             Server name or IP address. Default: localhost
 -infile           File to read data to send to the worker from.
 -keyalias         Alias of the key in the keystore to use for
                   authentication.
 -keystore         Keystore with private key and certificate for
                   client certificate authentication.
 -keystorepwd      Password for reading the keystore.  If keystore is
                   specified but not this keystore password option,
                   the CLI will instead prompt for the password.
 -metadata         Additional meta data to send to the signer. The
                   parameters should be given in the form KEY=VALUE.
                   This option can be given multiple times.
 -password         Password for authentication.
 -port             Server port. Default: 8080 (for HTTP), 8442 for
                   HTTPS and 8443 for HTTPS with client
                   authentication.
 -protocol         Method of interaction with SignServer.
                   WEBSERVICES, or HTTP. Default: WEBSERVICES.
 -servlet          URL to the webservice servlet. Default:
                   /signserver/signserverws/signserverws?wsdl
 -truststore       Keystore with trusted certificates to use with
                   HTTPS.
 -truststorepwd    Password for the keystore with trusted
                   certificates. If truststore is specified but not
                   this truststore password option, the CLI will
                   instead prompt for the password.
 -username         Username for authentication.
 -workerid         ID of worker which should perform the operation.
 -workername       Name of worker which should perform the operation.

Sample usages:
a) validatedocument -workername XMLValidator -data "<root><Signature...
b) validatedocument -workername XMLValidator -infile /tmp/signed.xml
c) validatedocument -workerid 2 -infile /tmp/signed.xml -truststore
truststore.jks -truststorepwd changeit
d) validatedocument -workerid 2 -infile /tmp/signed.xml -keystore
superadmin.jks -truststorepwd foo123
e) validatedocument -workername XMLValidator -protocol HTTP -infile
/tmp/signed.xml
f) validatedocument -workername XMLValidator -infile /tmp/signed.xml -metadata param1=value1 -metadata param2=value2

timestamp

$ bin/signclient timestamp
usage: timestamp <options> [url]
 -base64                Give this option if the stored request/reply
                        should be base64 encoded, default is not.
 -certreq               Request signer certificate
 -help                  Print this message.
 -infile <file>         File containing message to time stamp.
 -inrep <file>          Input file containing an earlier stored base64
                        encoded response, to verify.You must specify the
                        verify flag also.
 -inreq <file>          Input file containing an earlier stored request to
                        use instead of creating a new. You must specify
                        the request flag also.
 -instr <string>        String to be time stamped, if neither instr or
                        infile is given, the client works in test-mode
                        generating it's own message.
 -keyalias <arg>        Alias of the key in the keystore to use for
                        authentication.
 -keystore <arg>        Keystore with private key and certificate for
                        client certificate authentication.
 -keystorepwd <arg>     Password for reading the keystore.  If keystore is
                        specified but not this keystore password option,
                        the CLI will instead prompt for the password.
 -outrep <file>         Output file to store the recevied TSA reply, if
                        not given the reply is not stored.
 -outreq <file>         Output file to store the sent TSA request, if not
                        given the request is not stored.
 -print                 Prints content of a request, response and/or token
 -reqpolicy <oid>       Request timestamp issued under a policy OID
 -signerfile <file>     Input file containing the PEM encoded certificate
                        of the TSA signer.Used to verify a stored
                        response.
 -sleep <num>           Sleep a number of milliseconds after each request.
                        Default 1000 ms.
 -truststore <arg>      Keystore with trusted certificates to use with
                        HTTPS.
 -truststorepwd <arg>   Password for the keystore with trusted
                        certificates. If truststore is specified but not
                        this truststore password option, the CLI will
                        instead prompt for the password.
 -url <url>             Url of TSA, e.g.
                        http://127.0.0.1:8080/signserver/process?workerId=
                        1.
 -verify                Give this option if verification of a stored reply
                        should be done, work together with inrep and
                        cafile. If given, no request to the TSA will
                        happen.

Sample usages:
a) timestamp -url http://localhost:8080/signserver/tsa?workerName=TimeStampSigner
b) timestamp -print -inreq query.tsq
c) timestamp -print -inrep reply.tsr

validatecertificate

Request a certificate to be validated by the specified service.

usage: Usage: java -jar validate.jar <options>

 -cert <cert-file>              Path to certificate file (DER or PEM)
                                (Required).
 -certpurposes <certpurposes>   A ',' separated string containing
                                requested certificate purposes.
 -der                           Certificate is in DER format.
 -help                          Display this info
 -hosts <hosts>           A ',' separated string containing the
                                hostnames of the validation service nodes.
                                Ex 'host1.someorg.org,host2.someorg.org'.
                                When using the HTTP protocol, only one
                                host name can be specified. (Required).
 -pem                           Certificate is in PEM format (Default).
 -port <port>                   Remote port of service (Default is 8080 or
                                8442 for SSL).
 -protocol <protocol>           Protocol to use, either WEBSERVICES or
                                HTTP. Default: WEBSERVICES.
 -service <service-name>        The name or ID of the validation service
                                to process request. (Required)
 -silent                        Don't produce any output, only return
                                value.
 -truststore <jks-file>         Path to JKS truststore containing trusted
                                CA for SSL Server certificates.
 -truststorepwd <password>      Password to unlock the truststore.

The following values is returned by the program that can be used when scripting.
  -2   : Error happened during execution
  -1   : Bad arguments
   0   : Certificate is valid
   1   : Certificate is revoked
   2   : Certificate is not yet valid
   3   : Certificate have expired
   4   : Certificate doesn't verify
   5   : CA Certificate have been revoked
   6   : CA Certificate is not yet valid
   7   : CA Certificate have expired
   8   : Certificate have no valid certificate purpose

Sample usages:
a) validatecertificate -service CertValidationWorker -hosts localhost -cert
    certificate.pem
b) validatecertificate -service 5806 -hosts localhost -cert certificate.pem
    -truststore p12/truststore.jks -truststorepwd changeit
c) validatecertificate -service CertValidationWorker -hosts localhost
    -cert certificate.pem -protocol HTTP

signdatagroups

Sign the specified data groups and produce an SOd (MRTD).

$ bin/signclient signdatagroups
usage: signdatagroups <options>
Request MRTD data groups to be signed
 -data <arg>            Data to send to the worker.
 -encoding <arg>        Encoding of the data option. None or base64.
                        Default: none.
 -host <arg>            Server name or IP address. Default: localhost
 -keyalias <arg>        Alias of the key in the keystore to use for
                        authentication.
 -keystore <arg>        Keystore with private key and certificate for
                        client certificate authentication.
 -keystorepwd <arg>     Password for reading the keystore.  If keystore is
                        specified but not this keystore password option,
                        the CLI will instead prompt for the password.
 -metadata <arg>        Additional meta data to send to the signer. The
                              parameters should be given in the form KEY=VALUE.
                              This option can be given multiple times.
 -password <arg>        Password for authentication. If username is
                        specified but not this password option, the CLI
                        will instead prompt for the password.
 -port <arg>            Server port. Default: 8080 (for HTTP), 8442 for
                        HTTPS and 8443 for HTTPS with client
                        authentication.
 -protocol <arg>        Method of interacting with SignServer. HTTP or
                        CLIENTWS. Default: HTTP.
 -repeat <arg>          Run the operation this number of times. Default: 1
 -servlet <arg>         Servlet to call. Default /signserver/sod
 -truststore <arg>      Keystore with trusted certificates to use with
                        HTTPS.
 -truststorepwd <arg>   Password for the keystore with trusted
                        certificates. If truststore is specified but not
                        this truststore password option, the CLI will
                        instead prompt for the password.
 -username <arg>        Username for authentication.
 -workerid <arg>        ID of worker which should perform the operation.
 -workername <arg>      Name of worker which should perform the operation.

Sample usages:
a) signdatagroups -workername MRTDSODSigner -data "1=value1&2=value2&3=value3"
b) signdatagroups -workername MRTDSODSigner -data "1=value1&2=value2&3=value3" -metadata param1=value1 -metadata param2=value2

Administration Web Service

The SignServer AdminWS can be used for remote administration of SignServer over client authenticated HTTPS. Access is granted based on a list of certificate serial number and issuer distinguished name pairs. Currently there is only one access level and all administrators granted access will be able to perform all operations.

The WSDL file is located at the URL http://<hostname>:8080/signserver/AdminWSService/AdminWS?wsdl

Authorizing administrators can be done using the Admin CLI command "wsadmins".

Usage: signserver wsadmins -add -certserialno <certificate serial number (in hex)> -issuerdn <issuer DN>
Usage: signserver wsadmins -add -cert <PEM or DER file>
Usage: signserver wsadmins -remove -certserialno <certificate serial number (in hex)> -issuerdn <issuer DN>
Usage: signserver wsadmins -list
Example 1: signserver wsadmins -add -certserialno 123abcdef -issuerdn "C=SE, CN=Neo Morpheus"
Example 2: signserver wsadmins -add -cert cert.pem
Example 3: signserver wsadmins -remove -certserialno 123abcdef -issuerdn "C=SE, CN=Neo Morpheus"
Example 4: signserver wsadmins -list

Notice that the certificate serial number should be entered as the hexadecimal representation (leading zeros and upper/lowercase is not significant). Also notice that the issuer DN currently should be entered in the reversed order and with spaces after each component. In the example above the issuer DN from the certificate actually is "CN=Neo Morpheus, C=SE".

An administrator can also be added by supplying a client certificate as an argument. The serial number and issuer DN is then taken from that certificate.

To troubleshoot an "Administrator not authorized to resource" see the logs for how SignServer interprets the serialnumber and subject DN. Example:

19:00:33,946 INFO  [AdminWS] ADMIN OPERATION; subjectDN=C=SE, O=Markus Organization, OU=Internal Testing 1, CN=External RA Admin 1; serialNumber=4a3442e98e3ce428; issuerDN=C=SE, O=Markus Organization, OU=Internal Testing 1, CN=MarkusAdminCA1; authorized=false; operation=getWorkers; arguments=
                    

Apache HTTP Server as proxy

This section will show you examples on how the Apache Web Server (version 2.2.20) can be used as a proxy in front of SignServer. This guide is only informative, you should also always consult the current Apache documentation for the modules used. The proxy could be used for multiple reasons including:

  • Use standard ports (80, 443) instead of unprivileged ports used by the application server
  • Making workers accessible through more nice looking URLs.
    For example "http://tsa.example.com" instead of "http://example.com:8080/signserver/tsa?workerName=TimeStampSigner1"
  • Use any of the access control and authentication mechanism available in Apache
  • Redirect HTTP traffic to HTTPS
  • Only accepting requests to specified locations

As the requests should go through the proxy you will probably want to configure the application server to only listen to localhost and/or use a firewall blocking the application server ports from external requests. To configure JBoss to only listen to localhost set the following properties in signserver_deploy.properties:

httpsserver.bindaddress.pubhttp=127.0.0.1
httpsserver.bindaddress.pubhttps=127.0.0.1
httpsserver.bindaddress.privhttps=127.0.0.1

Install the Apache web server and enable required modules (the following commands are for Ubuntu but should be similar in other distributions as well):

$ sudo apt-get install apache2
$ cd /etc/apache2/mods-enabled/
$ sudo ln -s ../mods-available/proxy.load proxy.load
$ sudo ln -s ../mods-available/proxy_http.load proxy_http.load
$ sudo ln -s ../mods-available/proxy_ajp.load proxy_ajp.load
$ sudo ln -s ../mods-available/proxy_balancer.load proxy_balancer.load
$ sudo ln -s ../mods-available/rewrite.load rewrite.load
$ sudo ln -s ../mods-available/ssl.load ssl.load

Example: Rewrite URLs for TSA (using mod_proxy and mod_rewrite)

A sample configuration how to fix up nice URLs for time-stamping so that you can point your TSA clients to http://tsa.example.com/ instead of http://tsa.example.com:8080/signserver/process?workerName=TimeStampSigner1.
This configuration combines mod_proxy with mod_rewrite to be able to set the workerName or workerId, so you can have different TSAs available on different URLs.

<VirtualHost tsa.example.com:80>
    ServerName tsa.example.com
    ServerAlias tsa.example.com
    CustomLog /var/log/apache2/access.log combined

    RewriteEngine on
    RewriteLogLevel 5
    RewriteLog "/var/log/apache2/rewrite.log
    RewriteRule ^/$ /?workerName=TimeStampSigner1 [PT]

    ProxyRequests Off
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyPass / http://127.0.0.1:8080/signserver/process
    ProxyPassReverse / http://127.0.0.1:8080/signserver/process
</VirtualHost>

Example: Rewrite URLs and redirect to HTTPS (using AJP)

The following example configures three virtual hosts. The first signserver.example.com:80 just redirects all requests to use HTTPS and thus the virtual host signserver.example.com:443. The second virtual host is configured to proxy requests to the /signserver path on the application server using the AJP protocol. It is also configured to use HTTPS with a server certificate. The last virtual hosts auth.signserver.example.com using an additonal IP address is configured to require client certificate authentication.

Notice: Some application servers (i.e. JBoss 4) might have problems writing the correct port number in the endpoint URL in the web services WSDL file when using a proxy (i.e. writing 8443 instead of 443).

<VirtualHost signserver.example.com:80>
    ServerName signserver.example.com
    ServerAlias signserver.example.com

    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}

    # Configure log
    LogLevel warn
    ErrorLog /var/log/apache2/error.log
    CustomLog /var/log/apache2/access.log combined

</VirtualHost>

<VirtualHost signserver.example.com:443>
    ServerName signserver.example.com
    ServerAlias signserver.example.com

    ProxyRequests Off
    <Proxy balancer://mycluster-3>
        BalancerMember ajp://localhost:8009/signserver
    </Proxy>
    ProxyPass / balancer://mycluster-3/

    RewriteEngine   On

    # Treat requests to / and /signserver/ as the same for web services endpoints to work.
    RewriteCond     %{THE_REQUEST}  /signserver/
    RewriteRule     ^/signserver/(.*)$ /$1 [PT]

    # Configure secure SSL for this server using SSL certificate generated by EJBCA
    SSLEngine on
    SSLCipherSuite HIGH
    SSLProtocol all -SSLv2
    SSLCertificateFile /home/markus/Documents/PrimeKey/MarkusCA/example.com/signserver.example.com-cert.pem
    SSLCertificateKeyFile /home/markus/Documents/PrimeKey/MarkusCA/example.com/signserver.example.com-key.pem

    # Configure log
    LogLevel warn
    ErrorLog /var/log/apache2/error.log
    CustomLog /var/log/apache2/access.log combined
</VirtualHost>

# Note: auth.signserver.example.com must have a different IP address
<VirtualHost auth.signserver.example.com:443>
    ServerName auth.signserver.example.com
    ServerAlias auth.signserver.example.com

    ProxyRequests Off
    <Proxy balancer://mycluster-4>
        BalancerMember ajp://localhost:8009/signserver
    </Proxy>
    ProxyPass / balancer://mycluster-4/

    RewriteEngine   On
    # Treat requests to / and /signserver/ as the same for web services endpoints to work.
    RewriteCond     %{THE_REQUEST}  /signserver/
    RewriteRule     ^/signserver/(.*)$ /$1 [PT]

    # Configure secure SSL for this server using SSL certificate generated by EJBCA
    SSLEngine on
    SSLCipherSuite HIGH
    SSLProtocol all -SSLv2
    SSLCertificateFile /home/markus/Documents/PrimeKey/MarkusCA/example.com/auth.signserver.example.com-cert.pem
    SSLCertificateKeyFile /home/markus/Documents/PrimeKey/MarkusCA/example.com/auth.signserver.example.com-key.pem

    SSLVerifyClient require
    SSLVerifyDepth 1
    SSLCACertificateFile /home/markus/Documents/PrimeKey/MarkusCA/example.com/truststore.pem

    # Configure log
    LogLevel warn
    ErrorLog /var/log/apache2/error.log
    CustomLog /var/log/apache2/access.log combined
</VirtualHost>

Example: Granting access to specific workers only

This example shows how it is possible to limit access to only specified resources.

If you are going to grant different users access to different workers always remember to first deny access from the root location. The reason is that there are other ways to access a worker than the "/worker/*" or "/sodworker/*" pattern. For instance /process, /tsa, /pdf and /sod etc as well as using the web services interfaces /signserverws, /SignServerWSService, /validationws, /ValidationWSService and /ClientWSService all can be used to invoke any worker.

If you instead relay on SignServer to do the authentication/authorization it could still be good from a security point to only grant access to the locations you intend to use. In that case you would probably want to also give access to the web services interfaces, /worker and /process etc.

Also remember if you are proxying from multiple virtual hosts (i.e. if you have one with and one without client authentication as in the example above) that you might want to add the access restrictions to all of them.

    ...
    # First, deny access globally and then only give access to resources explicitly
    <Location />
    	Order Deny,Allow
    	Deny from all
    </Location>

    # Allow index page
    <LocationMatch "^/$">
	Order Allow,Deny
	Allow from all
    </LocationMatch>

    # Allow demo web pages
    <Location /demo/>
	Order Allow,Deny
	Allow from all
    </Location>

    # Allow documentation
    <Location /doc/>
	Order Allow,Deny
	Allow from all
    </Location>

    # Allow web page resources
    <LocationMatch "\.(css|js|jpg|png)$">
	Order Allow,Deny
	Allow from all
    </LocationMatch>
    
    # Allow the Admin interface
    <Location /AdminWSService/>
	Order Allow,Deny
	Allow from all
    </Location>

    # Grant everybody access to the XMLSigner
    <Location /worker/XMLSigner>
	Order Allow,Deny
	Allow from all
    </Location>
                        
    # Grant everybody access to the MRTDSODSigner
    <Location /sodworker/MRTDSODSigner>
        Order Allow,Deny
        Allow from all
    </Location>

    # Grant valid users access to the CMSSigner
    <Location /worker/CMSSigner>
	Order Allow,Deny
        Allow from all
        AuthType Basic
        AuthName "Restricted CMSSigner access"
    	AuthUserFile /home/markus/.htpasswd
    	Require valid-user
    </Location>
    ...