Installation Guide

Server installation

Note
Make sure you are reading the version of the manual corresponding to the software version you are about to install. The version of the manual is written in the top of this page. See doc/README.txt within the release package for information about how to build this manual for your version.

1. Check prerequisites

Make sure all required softwares are installed:

  • Java: OpenJDK 7, Oracle JDK 7* or OpenJDK 8**
  • Application server: JBoss AS 7.1.1, JBoss EAP 6.x, GlassFish Server Open Source Edition 3.1.2, WildFly 9 or Payara Server 4.1.1.162***
  • Database: MySQL or MariaDB 5.5, PostgreSQL 9.x, Oracle Database 10/11g or without****
  • Deployment tool: Apache Ant 1.8.0 or later
  • Build tool (optional*****): Apache Maven 3

* When using Oracle JDK you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK for the parts of SignServer that makes use of strong crypto to work. The policy files can be found at the same place as the JDK download at Oracle. Further information on this can be found in the Oracle documentation on the JCE.
** If supported by the application server.
*** Experimental support for Payara. Currently uses EclipseLink instead of Hibernate.
**** See SignServer without Database
***** Only required when building the software from source

2. Unpack SignServer

Download and unzip the latest SignServer Community Edition release archive from SourceForge.

Note that SignServer is available in different distributions:

  • signserver-4.x.y-bin.zip:
    The binary distribution (recommended)
  • signserver-4.x.y.zip:
    The mixed distribution. Contains the sources as well as all required libraries. This requires you to build SignServer before deploying.
  • signserver-4.x.y-src.tar.gz:
    The source-only tarball distribution. This one can not be deployed without first gathering all the dependencies and then building it. If you choose this one you are on your own.

Make sure to compare the checksums as provided on https://signserver.org/download.html or from a by PrimeKey provided download site.

sha256sum signserver-4.x.y-bin.zip
unzip signserver-4.x.y-bin.zip

Alternatively, you can checkout the latest unstable version from version the Subversion (SVN) repository. Note that as with the mixed distribution this one needs to be built before deploying.

3. Build SignServer

Skip this step if you downloaded the binary distribution (recommended).

If you instead downloaded the mixed disribution or checked out from SVN and want to build SignServer your self before copying it to the target server then you need to peform the following steps on your build machine.

Note: Before running any of the Maven (mvn) commands you must make sure you have a secure Maven installation that does not contact the Central repository over insecure HTTP. You should make sure that the URL for the Central repository is specified with HTTTPS (and/or to use an internal repository).
See sample-maven-settings-community.xml for an example on how one can override the default Maven settings in ~/.m2/settings.xml.

mvn help:effective-settings

Then to build the sources run:

mvn install -DskipTests

4. Set environment variables

APPSRV_HOME

Set APPSRV_HOME to point to your application server installation (/opt/jboss could be a symbolic link).

export APPSRV_HOME=/opt/jboss

This variable is used when deploying to the application server and could for instance be set in your .bashrc or similar file or provided everytime the deploy command is executed.

SIGNSERVER_NODEID

Set SIGNSERVER_NODEID to an unique ID for the server.

export SIGNSERVER_NODEID=node1

This variable should be available to the application server so it might have to be set in /etc/environment or similar. It is normally not required to have it set but without it there will be warnings printed in the log.

5. Setup database

Skip this section and instead follow the instructions in SignServer without Database if you decide to run SignServer without a database management system.

If you are using a database you will need to get a JDBC driver from the database vendor.

Database account

Create a database and database user for SignServer. Please, refer to the database vendor's documentation for how to do that.

Table creation and indexes

The application server will try to create tables during startup of SignServer but if the database user does not have table create permissions the tables must be created manually. See doc/sql-scripts/create-tables-signserver-*.sql for the database schemas for different databases.

In order to improve performance the appropriate database indices should also be applied. This is extra important for the AuditRecordData table which otherwise will make SignServer slower and slower to start. See doc/sql-scripts/create-index-signserver.sql.

MariaDB binlog format configuration

For MariaDB you will have to set binlog_format to "row", for instance in /etc/mysql/my.cnf:

binlog_format=row

Configure database driver for GlassFish/Payara

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

Configure database driver for JBoss AS 7, JBoss EAP 6 or WildFly

In JBoss 7/EAP6/WildFly it is not enough to just drop the JAR archive with a database JDBC driver into the deployments directory. Instead you will have to perform the following steps (for MySQL or MariaDB):

  1. Create the necessary directories (relative to JBoss 7 base directory):
    On JBoss 7.1.1 or EAP 6.0:
    mkdir -p modules/com/mysql/main/
    
    On JBoss 7.2 or EAP 6.1:
    mkdir -p modules/system/layers/base/com/mysql/main/
    
    Or for MariaDB, mariadb-java-client-1.1.2.jar:
    mkdir -p modules/org/mariadb/main/
    
    On JBoss 7.2, EAP 6.1 (or later) or WildFly:
    mkdir -p modules/system/layers/base/org/mariadb/main/
    
  2. Place the mysql.jar or mariadb.jar file in the directory you just created.
  3. Create, in the created directory, the JDBC module configuration file module.xml with the following contents (replace mysql.jar with the full name of your jar file for example mysql-connector-java-5.1.18-bin.jar):
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
      <resources>
        <resource-root path="mysql.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
      </dependencies>
    </module>
    
    Or for MariaDB, mariadb-java-client-1.1.2.jar:
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.mariadb">
      <resources>
        <resource-root path="mariadb-java-client-1.1.2.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
      </dependencies>
    </module>
    
  4. Register the driver by running the following two commands in the JBoss 7 CLI administration tool:
    /subsystem=datasources/jdbc-driver=com.mysql.jdbc.Driver:add(driver-name=com.mysql.jdbc.Driver,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource)
    :reload
    
    Or for MariaDB, mariadb-java-client-1.1.2.jar:
    /subsystem=datasources/jdbc-driver=org.mariadb.jdbc.Driver:add(driver-name=org.mariadb.jdbc.Driver,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource)
    :reload
    

For PostgreSQL you would use the following values instead:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.postgresql">
  <resources>
    <resource-root path="postgresql-9.1-903.jdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
/subsystem=datasources/jdbc-driver=org.postgresql.Driver:add(driver-name=org.postgresql.Driver,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
:reload

Configure data source for GlassFish/Payara

For GlassFish/Payara 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

Configure data source for JBoss AS 7.1

The examples are for installing a MariaDB datasource using the jboss-cli with the driver installed as described above.

A normal datasource (Note: no --enabled=true for JBoss AS 7.1):

data-source add --name=signserverds --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/signserver" --jndi-name="java:/SignServerDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="signserver" --password="signserver" --validate-on-match=true --background-validation=false --prepared-statements-cache-size=50 --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED --check-valid-connection-sql="select 1;"

Then restart the application server.

Configure data source for JBoss EAP 6 or WildFly

The examples are for installing a MariaDB datasource using the jboss-cli with the driver installed as described above.

A normal datasource (Note: --enabled=true for JBoss EAP 6.x):

data-source add --name=signserverds --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/signserver" --jndi-name="java:/SignServerDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="signserver" --password="signserver" --validate-on-match=true --background-validation=false --prepared-statements-cache-size=50 --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED --check-valid-connection-sql="select 1;" --enabled=true

Then restart the application server.

6. Configure web server keystores

GlassFish/Payara SSL configuration

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

JBoss 7/EAP 6 SSL configuration

Copy the keystore file as JBOSS7_HOME/standalone/configuration/keystore/keystore.jks and the trust store as JBOSS7_HOME/standalone/configuration/keystore/truststore.jks.

Configure interfaces using the approproate bind address (i.e. 0.0.0.0 or 127.0.0.1).

/interfaces=/interface=http:add(inet-address="0.0.0.0")
/interfaces=/interface=httpspub:add(inet-address="0.0.0.0")
/interfaces=/interface=httpspriv:add(inet-address="0.0.0.0")

Set-up the private port which requires client certificate. Use appropriate values for key-alias (hostname), password (keystore password), ca-certificate-password (truststore password), and supported protocols.

/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/subsystem=web/connector=httpspriv:add(protocol=HTTP/1.1, scheme=https, socket-binding=httpspriv, secure=true)
/subsystem=web/connector=httpspriv/ssl=configuration:add(key-alias="localhost")
/subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=password, value="serverpwd")
/subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=certificate-key-file, value="${jboss.server.config.dir}/keystore/keystore.jks")
/subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=verify-client, value=true)
/subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=ca-certificate-password, value="changeit")
/subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=ca-certificate-file, value="${jboss.server.config.dir}/keystore/truststore.jks")
/subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=protocol,value="TLSv1,TLSv1.1,TLSv1.2")

Set-up the public SSL port which doesn't require the client certificate. Use appropriate values for key-alias (hostname), password (keystore password), and supported protocols.

/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442",interface="httpspub")
/subsystem=web/connector=httpspub:add(protocol=HTTP/1.1, scheme=https, socket-binding=httpspub, secure=true)
/subsystem=web/connector=httpspub/ssl=configuration:add(key-alias="localhost")
/subsystem=web/connector=httpspub/ssl=configuration:write-attribute(name=password, value="serverpwd")
/subsystem=web/connector=httpspub/ssl=configuration:write-attribute(name=certificate-key-file, value="${jboss.server.config.dir}/keystore/keystore.jks")
/subsystem=web/connector=httpspub/ssl=configuration:write-attribute(name=protocol,value="TLSv1,TLSv1.1,TLSv1.2")

If the server is not so fast, we have to wait a little before we can reload, otherwise it will be bad

:reload

WildFly 9 SSL configuration

Copy the keystore file as WILDFLY_HOME/standalone/configuration/keystore/keystore.jks and the trust store as WILDFLY_HOME/standalone/configuration/keystore/truststore.jks.

Configure interfaces using the approproate bind address (i.e. 0.0.0.0 or 127.0.0.1).

/interface=http:add(inet-address="0.0.0.0")
/interface=httpspub:add(inet-address="0.0.0.0")
/interface=httpspriv:add(inet-address="0.0.0.0")

Secure the CLI by removing the http-remoting-connector from using the http port and instead use a separate port 4447.

/subsystem=remoting/http-connector=http-remoting-connector:remove
/subsystem=remoting/http-connector=http-remoting-connector:add(connector-ref="remoting",security-realm="ApplicationRealm")
/socket-binding-group=standard-sockets/socket-binding=remoting:add(port="4447")
/subsystem=undertow/server=default-server/http-listener=remoting:add(socket-binding=remoting)
:reload

Set-up the private port which requires client certificate. Use appropriate values for key-alias (hostname), password (keystore password), ca-certificate-password (truststore password), and supported protocols.

/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="keystore/keystore.jks", keystore-relative-to="jboss.server.config.dir", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="keystore/truststore.jks", keystore-relative-to="jboss.server.config.dir", keystore-password="changeit")
/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding="httpspriv", security-realm="SSLRealm", verify-client=REQUIRED)

Set-up the public SSL port which doesn't require the client certificate.

/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442",interface="httpspub")
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding="httpspub", security-realm="SSLRealm")
reload

7. Configure application server

Fix web service problem in JBoss AS 7/EAP 6/WildFly

Configure WSDL web-host rewriting to use the request host. Needed for webservices to work correctly when requiring client certificate.

/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)

If the server is not so fast, we have to wait a little before we can reload, otherwise it will be bad

:reload

JBoss 7 and Oracle JDK BouncyCastle issues

When using Oracle JDK and JBoss 7 you need to install BC jars as a module in JBoss 7. See JBAS-7882.

How to install modules are described in docs.jboss.org/author/display/MODULES/Defining+a+module.

Fix XML Security library issue 1 in JBoss 7

JBoss 7 bundles version 1.5.1 of the XML Security library. The library bundled with SignServer is not properly overriding the JBoss-bundled version. To work around this issue copy the JAR file from SignServer into JBoss' modules directory and modifiy the descriptor to use the new version.

On Linux/Unix systems the following command can be used:

cp lib/ext/xmlsec-1.5.8.jar $APPSRV_HOME/modules/org/apache/santuario/xmlsec/main/

On Windows systems the following command can be used:

copy lib\ext\xmlsec-1.5.8.jar %APPSRV_HOME%\modules\org\apache\santuario\xmlsec\main\

Edit $APPSRV_HOME/modules/org/apache/santuario/xmlsec/main/module.xml to use the correct version:

<resource-root path="xmlsec-1.5.8.jar"/>

Fix XML Security library issue 2 in JBoss 7

JBoss 7 bundles version 2.7.1 of the Xalan library. The library bundled with SignServer is not properly overriding the JBoss-bundled version. To work around this issue copy the JAR files from SignServer into JBoss' modules directory and modifiy the descriptor to use the new version.

On Linux/Unix systems the following command can be used:

cp lib/ext/xalan-2.7.2.jar lib/ext/serializer-2.7.2.jar $APPSRV_HOME/modules/org/apache/xalan/main/

On Windows systems the following command can be used:

copy lib\ext\xalan-2.7.2.jar %APPSRV_HOME%\modules\org\apache\xalan\main\
copy lib\ext\serializer-2.7.2.jar %APPSRV_HOME%\modules\org\apache\xalan\main\

Edit $APPSRV_HOME/modules/org/apache/xalan/main/module.xml to use the correct versions:

<resource-root path="serializer-2.7.2.jar"/>
<resource-root path="xalan-2.7.2.jar"/>

Commons Collections Security issue in JBoss 7 and earlier

JBoss 7 bundles version 3.2.1 of Commons Collections which has potential security issues. SignServer uses version 3.2.2. Perform similar changes as in the previous section to have JBoss use the 3.2.2 version instead.

Fix Security issues in JBoss EAP

Make sure to apply the relevant security patches from Red Hat. Pay special attention to the above mentioned XML Security and Commons Collections libraries etc.

Install Hibernate in GlassFish 3

If you are using GlassFish 3 and run with a database you will have to install Hibernate. Run pkg install in the GlassFish folder:

./bin/pkg install hibernate

8. Configure deployment

Copy conf/signserver_deploy.properties.sample to conf/signserver_deploy.properties and open it for editing in your favorite text editor.

cp conf/signserver_deploy.properties.sample conf/signserver_deploy.properties

Database configuration

Select database management system

database.name=mysql

See Signed log for how to configure for signed audit logs in the database.

9. Deploy SignServer

Run "bin/ant deploy" to build the configuration and deploy it to the selected application server.

bin/ant deploy

Start the application server and verify that SignServer was deployed.

9. Accessing SignServer

After startup a few different user interfaces are available.

Command Line Interface

bin/signserver getstatus brief all
Current version of server is : SignServer EE 4.0.0

Graphical User Interface

bin/signserver-gui

Web Interface

Point your web browser to http://localhost:8080/signserver for demo web pages and local documentation.

Signer setup

After server installation the different signers can be setup using the SignServer CLI.

Loading signers

Signers (and other workers) can be loaded by setting properties using "setproperty" or "setproperties" etc.

setproperties

The "setproperties" command loads all the properties from a property file that can define one or many signers. The code for the signers needs to be deployed to the application server together with SignServer either by setting includemodulesinbuild=true to include all modules or by setting individual module.MODULENAME.enabled=true properties in signserver_deploy.properties.

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

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

bin/signserver reload 4711

Quick start demo setup

This is a quick start guide to quickly get you setup with a crypto token and a set of workers/signers for testing and demonstration purposes.

Setup a sample crypto token

Set up a crypto token called CryptoTokenP12 which uses a keystore-based token:

$ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties

Activate the configuration using the assigned worker ID that was printed (for instance 1):

$ bin/signserver reload 1

Add sample workers

Workers can then be set up using the setproperties followed by the reload command. Sample configurations are available in doc/sample-configs which by default uses the sample crypto token:

$ bin/signserver setproperties doc/sample-configs/CONFIGURATION.properties

Activate the configuration using the assigned worker ID that was printed (for instance 2):

$ bin/signserver reload 2

See the following section for some example for specific workers.

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_deploy.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
  2. Setup the keystore crypto token (if not already done) and activate it with its ID:
    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties

    Update the crypto token's KEYSTOREPATH property to point to a PKCS#12 keystore containing keys and
    certificate suitable for timestamp signing (the sample keystore in res/test/dss10/dss10_tssigner1.p12 can be used).
    Update the keystore password and set the crypto token's default key.
    $ bin/signserver setproperty 1 KEYSTOREPATH $SIGNSERVER_HOME/res/test/dss10/dss10_tssigner1.p12
    $ bin/signserver setproperty 1 KEYSTOREPASSWORD foo123
    $ bin/signserver setproperty 1 DEFAULTKEY "TS Signer 1"
    $ bin/signserver reload 1
  3. Load the Timestamp demo configuration and notice the generated worker ID (in this example 2):
    $ bin/signserver setproperties doc/sample-configs/timestamp.properties
  4. Activate the configuration with:
    $ bin/signserver reload 2
  5. You can check the status and configuration with:
    $ bin/signserver getstatus complete all
  6. Run the test client to see that everything is up:
    $ bin/signclient 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_deploy.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
  2. Setup the keystore crypto token (if not already done) and activate it with its ID:
    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties

    Update the crypto token's KEYSTOREPATH property to point to a PKCS#12 keystore containing keys and
    certificate suitable for document signing (the sample keystore in res/test/dss10/dss10_signer1.p12 can be used).
    Update the keystore password and set the crypto token's default key.
    $ bin/signserver setproperty 1 KEYSTOREPATH $SIGNSERVER_HOME/res/test/dss10/dss10_signer1.p12
    $ bin/signserver setproperty 1 KEYSTOREPASSWORD foo123
    $ bin/signserver setproperty 1 DEFAULTKEY "Signer 1"
    $ bin/signserver reload 1
  3. Load the PDF signer demo configuration and notice the generated worker ID (in this example 3):
    $ bin/signserver setproperties doc/sample-configs/pdfsigner.properties
  4. Activate the configuration with:
    $ bin/signserver reload 3
  5. You can check the status and configuration with:
    $ bin/signserver getstatus complete all

You can now access the URL http://localhost:8080/signserver/demo/pdfsign.jsp with your web browser to get PDF 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 setproperties doc/sample-configs/validator_dummy.properties
  2. Activate the configuration with:
    $ bin/signserver reload 6
  3. The status of the Worker can now be viewed with:
    $ bin/signserver 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_deploy.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 setproperties doc/sample-configs/xmlvalidator.properties
  3. Verify the configuration with (notice that VALIDATIONSERVICEWORKER is set to "CertValidationWorker"):
    $ bin/signserver getconfig 7
  4. Activate the configuration with:
    $ bin/signserver reload 7
  5. The status of the Validator can now be viewed with:
    $ bin/signserver 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_deploy.properties before building and deploying SignServer. Alternativly, set includemodulesinbuild=true to have all modules built in.
  2. Setup the soft crypto token (if not already done) and activate it with its ID:
    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
    $ bin/signserver reload 1
  3. Load the MRTD SOD signer demo configuration and notice the generated worker ID (in this example 8):
    $ bin/signserver setproperties doc/sample-configs/mrtdsodsigner.properties
  4. Activate the configuration with:
    $ bin/signserver reload 8
  5. The status of the signer can now be viewed with:
    $ bin/signserver 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.

Production configuration with HSM

To install a production signer using an HSM instead of the CryptoTokenP12, make a copy of doc/sample-configs/pkcs11-crypto.properties and configure the necessary properties for the HSM and apply that file using setproperties and reload with its worker ID.
(note after changing properties in the file it needs to be loaded again with setproperties)

Now when configuring a worker make sure to have the worker property CRYPTOTOKEN=CryptoTokenP11.

Before starting with an HSM installation you should read the about the PKCS11CryptoToken in the plugins section of the manual.

bin/signserver setproperties doc/sample-configs/pkcs11-crypto.properties
bin/signserver reload 9
bin/signserver setproperties doc/sample-configs/mrtdsodsigner.properties
bin/signserver setproperty 10 CRYPTOTOKEN CryptoTokenP11
bin/signserver reload 10
bin/signserver activatecryptotoken 9 tokenpin
bin/signserver generatecertreq 9 "C=SE,CN=MRTD SOD Signer" SHA256WithRSA mrtdsodsigner.req

Where 9 is the workerId that you got when running the 'setproperties' command for the pkcs11 crypto token.
Tokenpin is the password for the HSM slot configured in the properties file.
This will create a certificate request that you can get signed by your CA. When you have received the response you can import it and the CA certficate. If you have the returned signer certificate as cert.pem and the CA certificate as cacert.pem, then:

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

Hint: you can use EJBCA to create keys on a PKCS#11 HSM using clientToolBox.
ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/ETcpsdk/lib/linux-x86_64/libcryptoki.so 2048 DSSignKey 5

Upgrade

See SIGNSERVER_HOME/doc/RELEASE_NOTES.txt and UPGRADE.txt for information about upgrading from an earlier version of SignServer.