Installation Guide

1. Check prerequisites

Make sure all required softwares are installed:

• Java: Sun/Oracle JDK 6 Update 10 or later or OpenJDK*
• Application server: JBoss 4.2.3.GA**, JBoss 5.1.0.GA or GlassFish Server Open Source Edition 2.1.1
• Database: HypersonicSQL (bundled with JBoss), MySQL 5.1 or Oracle Database 10/11g
• Build tool: Apache Ant 1.7.1 or later

* The ODFSigner has issues with OpenJDK. Please see DSS-168 for a workaround.
** JBoss 4.2.3.GA is available in two different versions (standard and JDK6) which differens in web services stacks. The one called JBoss 4.2.3.GA-JDK6 should be used.

2. Unpack SignServer

Download and unzip the latest SignServer release archive from SourceForge or for the absolutly latest unstable version checkout from the Subversion (SVN) repository.

3. Set environment variables

export APPSRV_HOME=/opt/jboss-4.2.3.GA
                        

export ANT_HOME=/usr/share/ant
                        

export ANT_OPTS="-Xmx512m -XX:MaxPermSize=128m"
                        

export SIGNSERVER_HOME=/opt/signserver
                        

export SIGNSERVER_NODEID=node1
                        

4. Setup database

Create a database and user for SignServer. The application server will try to create tables during startup of SignServer but if the database user does not have table create permissions or if you run on Glassfish the tables must be created manually. See doc/howtos/create-tables-signserver32-*.sql.

Copy the driver for your database to the application server lib folder.

For GlassFish also configure a connection pool and JNDI resource:

1. Go to the Admin Console: http://localhost:4848
2. Click on Resources -> JDBC -> Connection Pools
3. Add a new Pool. For instance: Name: MySQLPool
4. Fill in:
   databaseName: signserver
   password: signserver
   portNumber 3306
   serverName: localhost
   user: signserver
5. Click Ping to test
6. Click on Resources -> JDBC -> JDBC Resources
7. Add new:
   JNDI Name: jdbc/SignServerDS
   Pool Name: MySQLPool

4. Configure web server keystores

For JBoss if you are going to protect the HTTP communication with SSL, you need a JKS SSL server keystore. Rename the web server keystore to tomcat.jks at put it in a 'p12' subdirectory. Also place the web server root certificate in DER encoding in the same directory, call it rootcert.cer.

For GlassFish enable client authentication for http-listener-2 and manually update the keystores with the right certificates.

5. Configure application server

    <property name="webServiceHost">${jboss.bind.address}</property>

6. Configure build

Copy signserver_build.properties.sample to signserver_build.properties and open it for editing in your favorite text editor.

cp signserver_build.properties.sample signserver_build.properties
                    

appserver.type=jboss
                        

#j2ee.web-nohttps=true
                        

httpserver.privhttps=8181
                        

datasource.jndi-name=SignServerDS
datasource.jndi-name-prefix=jdbc/
                        

database.name=mysql
                        

database.url=jdbc:mysql://127.0.0.1:3306/signserver
database.driver=com.mysql.jdbc.Driver
database.username=signserver
database.password=signserver
                        

signserverws.enabled=true
genericws.enabled=true
validationws.enabled=true
adminws.enabled=true
                        

module.xmlsigner.enabled=true
module.xmlsigner.include=true
...
                        

module.log4j.enabled=true
module.log4j.include=true
                        

useclusterclassloader=true
                        

7. Build and deploy SignServer

Run "ant deploy" to build SignServer and deploy it to the selected application server. If the configuration changed since the last build run the clean target first.

ant clean deploy
                    

Start the application server and verify that SignServer was deployed and database tables were created.

8. Accessing SignServer

After startup a few different user interfaces are available.

bin/signserver.sh getstatus brief all
Assuming JBoss JNDI provider...
===========================================
Executing Command on host : localhost
===========================================


Current version of server is : SignServer 3.2-svn
                    

bin/admingui.sh	
						

Loading signers

Signers (and other workers) can be loaded in two different ways. Either using "module add" or by setting properties using "setproperty" or "setproperties" etc.

bin/signserver.sh modules add dist-server/MODULE.mar CONFIGURATION
                        

bin/signserver.sh setproperties doc/sample-configs/CONFIGURATION.PROPERTIES
                        

After adding or changing a property for a worker (either with "module add" or by any of the "setpropery" or "setproperties" commands) the configuration needs be applied by issuing the reload command with the ID of the worker.

bin/signserver.sh reload 4711
                    

Quick start demo Timestamp signer

This is a quick start guide to quickly get you setup with a demo Time Stamp service (TSA according to RFC3161). It will let you quickly get a feeling how the structure of the SignServer works, so you can move on to more advanced features described in the manual.

1. Make sure the tsa module is built in by setting module.tsa.enabled=true and module.tsa.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the Timestamp demo configuration and notice the generated worker ID (in this example 1):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_timestamp_configuration.properties
3. Activate the configuration with:
   $ bin/signserver.sh reload 1
4. You can check the status and configuration with:
   $ bin/signserver.sh getstatus complete all
5. Run the test client to see that everything is up:
   $ bin/client.sh timestamp http://localhost:8080/signserver/process?workerName=TimeStampSigner
   The message "TimeStampRequest validated" should appear once a second. Also check JBOSS_HOME/server/default/log/server.log or GLASSFISH_HOME/domains/domain1/logs/server.log that successful messages appear.

Quick start demo PDF signer

To install the PDF signer you can issue the following commands (either instead of the TSA or in addition to the TSA).

1. Make sure the pdfsigner module is built in by setting module.pdfsigner.enabled=true and module.pdfsigner.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the PDF signer demo configuration and notice the generated worker ID (in this example 2):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_pdfsigner_configuration.properties
3. Activate the configuration with:
   $ bin/signserver.sh reload 2
4. You can check the status and configuration with:
   $ bin/signserver.sh getstatus complete all

You can now, with your web browser, access the URL http://localhost:8080/signserver/demo/pdfsign.jsp to get PDF documents signed.

Quick start demo OOXML signer

To install the OOXML signer you can issue the following commands.

1. Make sure the ooxmlsigner module is built in by setting module.ooxmlsigner.enabled=true and module.ooxmlsigner.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the OOXML signer demo configuration and notice the generated worker ID (in this example 3):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_ooxmlsigner_configuration.properties
3. Activate the configuration with:
   $ bin/signserver.sh reload 3
4. You can check the status and configuration with:
   $ bin/signserver.sh getstatus complete all

You can now, with your web browser, access the URL http://localhost:8080/signserver/demo/ooxmlsign.jsp to get any Office Open XML documents signed (ex: MS Office 2007 Word document, Excel document, Power Point presentation...).

Quick start demo ODF signer

To install the ODF signer you can issue the following commands.

1. Make sure the odfsigner module is built in by setting module.odfsigner.enabled=true and module.odfsigner.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the ODF signer demo configuration and notice the generated worker ID (in this example 4):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_odfsigner_configuration.properties
3. Activate the configuration with:
   $ bin/signserver.sh reload 4
4. You can check the status and configuration with:
   $ bin/signserver.sh getstatus complete all

You can now, with your web browser, access the URL http://localhost:8080/signserver/demo/odfsigner.jsp to get any Open Document Format documents signed (ex: documents produced by OpenOffice.org or LibreOffice).

Quick start demo XML signer

To install the demo XML signer you can issue the following commands.

1. Make sure the xmlsigner module is built in by setting module.xmlsigner.enabled=true and module.xmlsigner.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the XML signer demo configuration and notice the generated worker ID (in this example 5):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_xmlsigner_configuration.properties
3. Activate the configuration with:
   # bin/signserver.sh reload 5
   
4. You can check the status and configuration with:
   $ bin/signserver.sh getstatus complete all

You can now, with your web browser, access the URL http://localhost:8080/signserver/demo/xmlsign.jsp to get XML documents signed.

Quick start demo XML validator

An XML validator validates the signature of an XML document. It uses a certificate validation service worker for validating the certificate so that worker has to be configured first.

To install a certificate validation service worker issue the following commands:

1. Load the configuration and notice the worker ID (in this example: 6):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_validator_dummy_configuration.properties
2. Activate the configuration with:
   $ bin/signserver.sh reload 6
   
3. The status of the Worker can now be viewed with:
   $ bin/signserver.sh getstatus complete CertValidationWorker
   

Then to install the XML validator you can issue the following commands:

1. Make sure the xmlvalidator module is built in by setting module.xmlvalidator.enabled=true and module.xmlvalidator.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the XML validator demo configuration and notice the generated worker ID (in this example 7):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_xmlvalidator_configuration.properties
3. Verify the configuration with (notice that VALIDATIONSERVICEWORKER is set to "CertValidationWorker"):
   $ bin/signserver.sh getconfig 7
   
4. Activate the configuration with:
   $ bin/signserver.sh reload 7
   
5. The status of the Validator can now be viewed with:
   $ bin/signserver.sh getstatus complete DemoXMLValidator
   

Now the SignServer APIs can be used to request XML documents to be validated by the DemoXMLValidator worker.

Quick start demo MRTD SOD signer

The MRTD SOD signer takes as input data group hashes and creates a signed SO(d). This means that the signserver will function as a Document Signer for ePassports.

To install the MRTD SOD signer you can issue the following commands:

1. Make sure the mrtdsodsigner module is built in by setting module.mrtdsodsigner.enabled=true and module.mrtdsodsigner.include=true in signserver_build.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
2. Load the MRTD SOD signer demo configuration and notice the generated worker ID (in this example 8):
   $ bin/signserver.sh setproperties doc/sample-configs/qs_mrtdsodsigner_configuration.properties
3. Activate the configuration with:
   $ bin/signserver.sh reload 8
   
4. The status of the signer can now be viewed with:
   $ bin/signserver.sh getstatus complete mrtdsodsigner
   

Now the SignServer APIs can be used to send MRTD SOD sign requests the MRTDSODSigner.
Also you can use the HTML page http://localhost:8080/signserver/demo/mrtdsodsign.jsp to enter requests and get the SOd back. This HTML form also functions as a sample to show how you can make HTTP requests from the personalisation system to the Document Signer.

bin/signserver.sh setproperties doc/sample-config/qs_mrtdsodsigner_configuration.properties
bin/signserver.sh getconfig 9
bin/signserver.sh reload 9
bin/signserver.sh generatecertreq 9 "C=SE,CN=MRTD SOD Signer" SHA256WithRSA mrtdsodsigner.req

cat cert.pem cacert.pem > certchain.pem
bin/signserver.sh uploadsignercertificate 9 glob cert.pem
bin/signserver.sh uploadsignercertificatechain 9 glob certchain.pem
bin/signserver.sh reload 9

Clustered SignServer 3.0 CentOS 4.4 Installation Guide

Installation guide describing step-by-step how to setup a SignServer cluster on CentOS 4.4. Even if the document is specific for this OS is should be quite easy to adopt it to other environments as well. It can be downloaded here either as PDF or viewed as HTML

Clustered SignServer 2.0 CentOS 4.4 Installation Guide

Version 2.0 of the same documentation.PDF HTML