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