SignServer
Search signserver.org for:

Integration

Integration

JavaDoc

The JavaDoc for SignServer is available at SIGNSERVER_HOME/tmp/doc/index.html after running "ant javadoc".

Web Services

New to version 3.0 is the Main WebService interface. It replaces the RMI-SSL interface in 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 WebService interface have 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.

The WebService stack used is the JAX-WS stack from SUN. And the actual process data is a externalized Base64 byte-arrays. The reason why the are externalized is to simply the integration towards non-Java platforms. See the source of the actual request to see how the data is structured.

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.

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

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

Important, Due to class path conflict in JBoss 4.2.x own JBoss WebService stack and the JAX-WS stack used by the SignServer must the JBoss WebService stack be removed before the WebService is used. This is done by going to JBOSS_HOME/server/default/deploy and remove the directory jbossws.sar.

Java Client API

Built along with the WebService is a Java API that can be used by clients. It's located in dist-client/signserverwscli and the file signserverws.jar and all the files in the lib directory is required to use the API. The client API have support for different high availability policies to avoid the need for load balance hardware.

The client classes is in the package org.signserver.protocol.ws.client and the main code are SignServerWSClientFactory creating a client using the specified load balance policy, it returns a ISignServerWSClient that is used to perform the actual process requests.

Load Balance Policies

With version 3.0 is one load balance policy defined and it's called 'CallFirstNodeWithStatusOK' it calls the getStatus method on all the server nodes in the cluster simultaneously and the first node to respond OK it sends its process request to. This to ensure that only one node in the cluster actually performs the signing.

Other future load balance policies could be round robin or that all nodes are called with the requests simultaneously and the first response is used.

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 signingandvalidationapi.jar as well as all JAR-files in the lib-folder available in SIGNSERVER_HOME/dist-client/signingandvalidationapi/.

Sample Code

*** Signing and validating an XML document ***
try {
    ISigningAndValidation signserver = new SigningAndValidationWS("localhost", 8080);

    // 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();
}                                   
*** MRTD Signing ***
try {
    ISigningAndValidation signserver = new SigningAndValidationWS("localhost", 8080);

    // Bytes to sign
    ArrayList<byte[]> bytesToSign = new ArrayList<byte[]>();
    bytesToSign.add("Sample data 1".getBytes());
    bytesToSign.add("Sample data 2".getBytes());

    // Signing
    MRTDSignResponse signResp = (MRTDSignResponse) signserver.process("MRTDSigner", new MRTDSignRequest(1234, bytesToSign), new RequestContext());

    System.out.println("Certificate: " + signResp.getSignerCertificate());

    if(signResp.getProcessedData() instanceof Collection) {
        Collection<byte[]> signed = (Collection) signResp.getProcessedData();
        for(byte[] data : signed) {
            System.out.println("Signed: " + new String(Base64.encode(data)));
        }
    }
} 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.
  • encoding - Encoding of the data field. Optional. By specifying "base64" SignServer Base64-decodes the data property before passing it to the worker.
Response code: 200 (OK) or other in case of failure (i.e. 500 internal server error)
Response content-type: Depending on the worker

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

*** 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/xmlsign.html (multipart/form-data) and /signserver/genericsign.html (x-www-form-urlencoded).

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

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.
Response code: 200 (OK) or other in case of failure (i.e. 500 internal server error)
Response content-type: application/octet-stream
*** Samples ***
  • See /signserver/mrtdsodsign.html.