SignServer Installation

This section provides a step-by-step guide for installing SignServer.

For information on upgrading from an earlier version of SignServer, refer to the SIGNSERVER_HOME/doc/RELEASE_NOTES.txt and UPGRADE.txt. Information on implemented features and changes in the release can be found in the SIGNSERVER_HOME/doc/RELEASE_NOTES.txt.

The SignServer installation is described in the following steps:

Server Installation

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/warning.svg 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 displayed on the top or bottom of this page.

1) Check Prerequisites

Make sure all required software is installed:

  • Java:
    OpenJDK 8, Oracle Java 8, or OpenJDK 11*****

  • Application server:
    JBoss EAP 7.x, WildFly 9, 10, 11, 14, or Payara Server 4.1.1.x**

  • Database:
    MySQL or MariaDB 5.5/10.3.12, PostgreSQL 9.x, Oracle Database 10/11g, or without database (***).

  • Deployment tool:
    Apache Ant 1.9 or later

  • Build tool (optional****):
    Apache Maven 3.x or later

* When using Oracle JDK the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for JDK need to be enabled via uncommenting the line crypto.policy=unlimited in jre/lib/security/java.security file, since parts of SignServer API make use of strong cryptography algorithms. Further information on this can be found in Oracle documentation on the JCE.
** Experimental support for Payara. Currently uses EclipseLink instead of Hibernate.
*** See SignServer without Database
**** Only required when building the software from source
***** Building is currently only supported with Java 8 and running on Java 11 is only supported with an application server that supports Java 11, such as WildFly 14.

2) Unpack SignServer

Download and unzip the latest SignServer Enterprise Edition from your PrimeKey download area or use the latest SignServer Community Edition release archive from SourceForge.

Note that SignServer is available in the following different distributions:

  • signserver-5.x.y-bin.zip: The binary distribution (recommended).

  • signserver-5.x.y.zip: The mixed distribution. Contains the sources and all required libraries. This distribution requires you to build SignServer before deploying, see 3) Build SignServer.

  • signserver-5.x.y-src.tar.gz: The source-only tarball distribution. This distribution cannot 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-5.x.y-bin.zip
unzip signserver-5.x.y-bin.zip

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

3) Build SignServer

Skip this step if you downloaded the binary distribution (recommended) and proceed to step 4) Set Environment Variables.

If you instead downloaded the mixed distribution, or checked out the latest version from SVN and want to build SignServer yourself before copying it to the target server, you need to perform the following steps on your build machine.

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/warning.svg Before running Maven (mvn) commands, make sure you have a secure Maven installation that does not contact the Central repository over insecure HTTP. Ensure that the URL for the Central repository is specified with HTTPS (and/or use an internal repository).

For an example on how to override the default Maven settings in ~/.m2/settings.xml, refer to the sample-maven-settings-community.xml.

mvn help:effective-settings

To set the edition (generates res/edition.properties) run:

bin/ant init

To build from the sources run:

mvn install -DskipTests

4) Set Environment Variables

APPSRV_HOME

Set APPSRV_HOME to point to your application server installation (/opt/{jboss, wildfly}, could be a symbolic link:

export APPSRV_HOME=/opt/{jboss, wildfly}

The APPSRV_HOME variable is used when deploying to the application server and could for example be set in your .bashrc or similar file, or be provided every time the deploy command is executed.

SIGNSERVER_NODEID

Set SIGNSERVER_NODEID to a unique ID for the server:

export SIGNSERVER_NODEID=node1

The SIGNSERVER_NODEID variable should be available to the application server and might need to be set in /etc/environment or similar. The variable is generally not mandatory but if not set, warnings will be printed in the log.

5) Set up Database

Skip this step and instead see SignServer without Database if you want 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.

The following is described in this step:

Database Account

Create a database and database user for SignServer. For more information, refer to documentation from the respective database vendor.

Table Creation and Indexes

The application server will attempt to create tables during startup of SignServer and if the database user does not have table create permissions, the tables must be created manually. For information on database schemas for different databases, refer to doc/sql-scripts/create-tables-signserver-*.sql.

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 to start. Refer to doc/sql-scripts/create-index-signserver.sql.

MariaDB binlog Format Configuration

For MariaDB, 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 specific folder. For WildFly server driver jar file may be the placed into the following directory:

{APPSRV_HOME}/modules/system/layers/base/. For example, MySQL JDBC Driver must be placed into this directory:

{APPSRV_HOME}/modules/system/layers/base/com/mysql/main/com.mysql.jdbc_5.1.5.jar

Configure Database Driver for WildFly, GlassFish or Paraya Application Server:

For JBoss EAP7, and WildFly it is not sufficient to drop the JAR archive with a database JDBC driver into the deployments directory. Instead, the following steps need to be performed (for MySQL or MariaDB):

  1. Create the necessary directories (relative to JBoss EAP base directory):

    • On WildFly Application Server:

      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 EAP 7.0 (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. In the created directory, create the JDBC module configuration file module.xml with the following contents:

    • MySQL: Replace the path mysql.jar with the full name of your jar file, for example, com.mysql.jdbc_5.1.5.jar

      :

      <?xml version="1.0" encoding="UTF-8"?>
      <module xmlns="urn:jboss:module:1.0" name="com.mysql">
      <resources>
      <resource-root path="com.mysql.jdbc_5.1.5.jar"/>
      </resources>
      <dependencies>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
      </dependencies>
      </module>

    • MariaDB: Use the full name of your jar file as path, for example org.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="org.mariadb-java-client-1.1.2.jar"/>
      </resources>
      <dependencies>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
      </dependencies>
      </module>
    • PostgreSQL: Use the full name of your jar file as path, for example org.postgresql-9.1-903.jdbc4.jar:

      <?xml version="1.0" encoding="UTF-8"?>
      <module xmlns="urn:jboss:module:1.0" name="org.postgresql">
      <resources>
      <resource-root path="org.postgresql-9.1-903.jdbc4.jar"/>
      </resources>
      <dependencies>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
      </dependencies>
      </module>
  4. Register the driver using the following commands:

    • Using JBoss EAP CLI administration tool, run script {APPSRV_HOME}/bin/jboss-cli.sh or similar:

      and connect to the running Application Server, using the following command: [disconnected /] connect localhost .

      Once connected, issue the following commands, to register your driver and datasource:

      /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
    • For MariaDB, mariadb-java-client-1.1.2.jar, run:

      /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, run:

      /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 Application Server Admin Console: http://localhost:4848.

  2. Click Resources > JDBC > Connection Pools.

  3. Add a new Pool. For example, Name: MySQLPool.

  4. Specify the following:
    databaseName: signserver
    password: signserver
    portNumber 3306
    serverName: localhost
    user: signserver

  5. To test the configuration, click Ping.

  6. Click Resources > JDBC > JDBC Resources.

  7. Add new:
    JNDI Name: jdbc/SignServerDS
    Pool Name: MySQLPool

Configure Data Source for JBoss EAP 7 or WildFly

The following shows an example configuration of a MariaDB data source using the {APPSRV_HOME}/bin/jboss-cli.sh with the driver installed as described in the previous step Configure database driver for JBoss EAP 7 or WildFly.

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/warning.svg Note that the --enabled=true option should be set for JBoss EAP 7.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

Restart the application server.

6) Configure Web Server Key Stores

Configure the Web Server keystore following the instructions in one of the following sections:

GlassFish/Payara SSL Configuration

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

WildFly 9 / JBoss EAP 7.0 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 appropriate 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")

Note that WildFly by default imposes a limit of 10 MB on HTTP post size. To allow signing larger files, the limits may be increased on the HTTP/HTTPS listeners by updating the values of the max-post-size attribute in the following code examples.

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/warning.svg If a larger limit than the default 10 MB is specified for HTTPS listeners, check that the max-post-size value was updated in the standalone.xml file after running the CLI command. If the value was not updated in the XML file, stop the application server and manually update the max-post-size value in the standalone.xml file before starting the application server again.

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, max-post-size="10485760")
:reload

Set the limit on the HTTP (8080) listener:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name="max-post-size", value="1048576000")

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, max-post-size="10485760")

Set up the public SSL port which does not 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", max-post-size="10485760")
reload

WildFly 10/11/14 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.

Remove existing listeners to make Wildfly allow configuring httpspriv interface with 8443 port:

/subsystem=undertow/server=default-server/http-listener=default:remove
:reload
/subsystem=undertow/server=default-server/https-listener=https:remove
:reload
/socket-binding-group=standard-sockets/socket-binding=http:remove
:reload
/socket-binding-group=standard-sockets/socket-binding=https:remove
:reload

Configure interfaces using the appropriate 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")

Note that WildFly by default imposes a limit of 10 MB on HTTP post size. To allow signing larger files, the limits may be increased on the HTTP/HTTPS listeners by updating the values of the max-post-size attribute in the following code examples.

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/warning.svg On application server Wildfly 10: If a larger limit than the default 10 MB is specified for HTTPS listeners, check that the max-post-size value was updated in the standalone.xml file after running the CLI command. If the value was not updated in the XML file, stop the application server and manually update the max-post-size value in the standalone.xml file before starting the application server again.

Configure httpspriv(https) listener:

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")
:reload
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="keystore/truststore.jks", keystore-relative-to="jboss.server.config.dir", keystore-password="changeit")
:reload
/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding="httpspriv", security-realm="SSLRealm", verify-client=REQUIRED, max-post-size = "10485760", enable-http2="true")

Configure default(http) listener:

/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=default:add(socket-binding=http, max-post-size = "1048576000", enable-http2="true")
/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Configure httpspub(https) listener:

Set up the public SSL port which does not 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",max-post-size = "10485760", enable-http2="true")

Configure remoting (http) listener:

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, max-post-size = "10485760", enable-http2="true")

7) Configure Application Server

Configure the application server following the instructions in the sections:

Fix Web Service Problem in JBoss EAP 7 / 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 slow, make sure to wait before reloading:

:reload

JBoss EAP 7 / WildFly URI Encoding

Configure the URI encoding:

/system-property=org.apache.catalina.connector.URI_ENCODING:remove()
/system-property=org.apache.catalina.connector.URI_ENCODING:add(value=UTF-8)
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:remove()
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)
:reload

Fix XML Security Library Issue 1 in JBoss EAP

On Linux/Unix systems, use the following command:

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, use the following command:

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\

On Linux/Unix systems, edit ${APPSRV_HOME}/modules/org/apache/xalan/main/module.xml file to set the correct driver jar versions:

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

Fix Security Issues in JBoss EAP

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

Install Hibernate in GlassFish 3

If you are using GlassFish 3 and run with a database, it is recommended 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 a text editor.

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

Database Configuration

Select database management system unless it is the default MySQL/MariaDB:

database.name=mysql

For information on how to configure for signed audit logs in the database, see Signed log.

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.

10) Access SignServer

After startup, you can use different user interfaces to access SignServer.

Command Line Interface

The SignServer Admin CLI is started using bin/signserver and can be tested using the following command:

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

Graphical User Interface

For more information on the SignServer Administration GUI (AdminGUI), see Administration GUI.

Start the SignServer AdminGUI using the following script:

bin/signserver-gui

Web Interface

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

Run the following to temporarily allow all valid client certificates to administer the SignServer Administration GUI:

bin/signserver wsadmins -allowany

For more information on the SignServer Administration Web (AdminWeb), see Administration Web.

Alternative Installation: SignServer without Database

As of SignServer 3.2.3, it is possible to operate SignServer without a database management system and instead rely on SignServer to manage persistence using local files.

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/warning.svg Note that all features of SignServer are not supported without having a database and the performance and scalability characteristics might differ. Currently, archiving to local files is not supported.

To increase throughput it is recommended to disable the key usage counter, as every request would otherwise have to lock and update that file. For more information, see the property DISABLEKEYUSAGECOUNTER in the section Limiting the number of signatures.

images/s/en_GB/7901/58be3fa11e9ad58113c0ea45e7063389a7c7d344/_/images/icons/emoticons/error.svg Upgrading to a later version should normally be handled automatically during the first startup. Please read the UPGRADE.txt document and create a backup of the file-based database files before attempting to run a later version.

Configuration

In signserver_deploy.properties, set database.name to nodb:

database.name=nodb

Set the location for the local file-based database:

database.nodb.location=/path/to/filedb

Ensure to specify a path to a location where SignServer can write files. The default value is empty. If a relative path is used, it is most likely relative to the application server's working directory. The directory should either point to an existing SignServer file database, or be completely empty. If the directory is empty, SignServer will create the initial database structure at startup.

Structure of Data

The file-based database uses a number of files in the specified directory. Read/write synchronization is handled internally in the application and it is thus not supported to manually change files while the application server is running. Generally, it is neither supported to have multiple application servers running with SignServer using the same database directory.

Migrating to/from Database

When migrating either to or from another database management system, without setting up all worker configurations from scratch, it is recommended to use the admin command dumpproperties to dump the current configuration to a file, and then on the new system use setproperties followed by the reload command for every worker id.

Note that the dumpproperties command will not include the list of authorized clients and these need to be set up again in the new system. To check for authorized clients, run the admin command listauthorizedclients.