SignServer Upgrade Notes

The following SignServer Upgrade Notes provide important information on changes and requirements to be aware of when upgrading SignServer.

Upgrading to a major version may require manual changes in the database structures, and changes needed are listed in the respective Database Schema Change section per release below. Minor releases are generally plug-in upgrades performed by deploying the new software. These changes are described in the Notice section per minor release below.

For details of new features and improvements in a respective release, see the SignServer Release Notes and for instructions on upgrading SignServer, see Upgrade SignServer.

Upgrade Notes

SignServer 6.3.x to SignServer 7.0.x

No database changes required.

SignServer 7.0.0 Notice

Upgrade of application server and other prerequisites may be needed. For more information, see the SignServer Installation Prerequisites section.

SignServer 6.2.x to SignServer 6.3.x

No database changes required.

SignServer 6.1.x to SignServer 6.2.x

No database changes required.

SignServer 6.0.x to SignServer 6.1.x

No database changes required.

SignServer 5.11.x to SignServer 6.0.x

SignServer 6.0.0 Notice

New packages need to be added to logger

In SignServer 6.0, some code has been migrated to the com.keyfactor package. To configure the log level for these classes, perform the following operation against the JBoss CLI:

/opt/wildfly/bin/jboss-cli.sh --connect '/subsystem=logging/logger=com.keyfactor:add(level=INFO)'

Default timestamp format changed for MSAuthCodeSigner and AppxSigner

The default timestamp format used by the MSAuthCodeSigner and AppxSigner has been changed from the legacy Authenticode format (AUTHENTICODE) to the standard RFC 3161-compliant format (RFC3162).

If existing workers are configured using a legacy MSAuthCodeTimestampSigner, you must explicitly set the worker property TIMESTAMP_FORMAT to the value AUTHENTICODE to continue using the legacy format.

Changed signature algorithm used by the SignServer SignClient option for signing request

The signature algorithm used to sign the request when using the -signrequest option with an ECDSA key has been changed. As of SignServer 6.0, the algorithm uses a digest algorithm matching the key size (e.g. SHA256withECDSA for secp256r1 keys, SHA384 for secp384r1 keys). The change is a result of changes in the underlying JJWT library. For more information on the -signrequest option, see signdocument.

SignServer 5.10.x to SignServer 5.11.x

No database changes required.

SignServer 5.11.2 Notice

Changes to MSAuthCodeSigner and MSAuthCodeCMSSigner

For MSAuthCodeCMSSigner the signingTime signed CMS attribute is no longer included in the signature output.

This change has been done to make signatures deterministic, and also is the behavior of the MSAuthCodeSigner and also MS SignTool.

The signature output from MSAuthCodeCMSSigner is now DER encoded. Previously, it was BER but re-encoded to DER in SignClient (when -clientside flag is used) but in order for MSAuthCodeCMSSigner to be useful also without SignClient this is now done already in the signer.

From this version the signature output from MSAuthCodeCMSSigner and MSAuthCodeSigner for PE files has been changed back to the way it was before 5.8.0 where digest algorithm identifiers included the NULL parameters in the same way as the output from SignTool.

SignServer 5.11.x Notice

Changes to the default P11 library definitions

The presets for SoftHSMv2 now have the library name "SoftHSM 2". This is a part of synchronizing the default list of definitions with the definitions from EJBCA.

Changes to Worker Properties

Worker property names if entered in lower case are now converted to upper case assuming locale English.

SignServer 5.8.x to SignServer 5.9.x

Database changes might be required if running PostgreSQL and upgrading to SignServer 5.9.1, see SignServer Upgrade Notes#Database Schema Change for Key Wrapping using PostgreSQL.

SignServer 5.9.1 Notice

Changes to the Algorithm for Discovering Keys using P11NG

Previously, when using the P11NGCryptoToken (which uses P11NG), keys were mapped from PKCS#11 to SignServer in the same way as with the PKCS11CryptoToken. That is, a key was only listed (and usable) if there was both a private key object and a certificate object in the device.

As of SignServer 5.9.1, it is no longer required to have a certificate object in the HSM and you can instead choose to have a public key object. The change enables support for HSMs such as AWS CloudHSM that do not support certificate objects.

In addition to listing keys with a certificate object, keys without a certificate object will now also be listed. Consequently, after upgrading to SignServer 5.9.1, keys may be displayed that were previously not visible, for example, keys generated with another non-SignServer or non-Java tool, or leftover keys from failed key generations.

If you want to clean out unwanted keys, you can use the SignServer p11ng-tool or any preferred HSM vendor tool.

Database Schema Change for Key Wrapping using PostgreSQL

Database object-relational mapping (ORM) has been upgraded to correct an issue with key wrapping not working when running PostgreSQL.

If you deploy SignServer 5.9.1 on an existing database, you need to recreate the keydata table. Note that recreating the table will result in the loss of any data in the keydata table. This should typically not be an issue, as key wrapping did not work on PostgreSQL previously.

Recreating the table is only needed if you deploy SignServer 5.9.1 on an existing database and is not necessary on a fresh installation, or if you are not using the key wrapping feature.

To recreate the keydata table in the SignServer database, execute the following SQL statements (and change the database user name if you use a user name other than "signserver".

DROP TABLE keydata;
CREATE TABLE KeyData (
  keyAlias character varying(255) NOT NULL,
  wrappingKeyAlias character varying(255) NOT NULL,
  wrappingCipher bigint NOT NULL,
  keyData text NOT NULL,
  certData text NOT NULL
);

ALTER TABLE ONLY KeyData
    ADD CONSTRAINT keydata_pkey PRIMARY KEY (keyAlias);

ALTER TABLE public.keydata OWNER TO signserver; 

SignServer 5.9.0 Notice

Changes to Decoding of Username and Password in Client Interfaces

The username and password used as part of HTTP Basic Authentication in the client interfaces are now expected to be UTF-8 encoded regardless of the platform encoding where SignServer is running.

SignServer 5.6.x to SignServer 5.8.x

No database changes required.

SignServer 5.8.0 Notice

Changes to TimeStampSigner, ExtendedTimeStampSigner and timestamp SignClient Subcommand

Time-stamp requests with a structure not matching RFC#3161 are now being rejected. For the signers, the time-stamp response will contain a rejection with the failure code badDataFormat(5).

SignServer 5.8.2 Notice

Updated Dependency Affecting Logging Configuration of CLI and Standalone Applications

The logging framework has been updated from version 1 to the latest version 2. In order to still support the current configuration files for most CLI and standalone applications, those are running with a compatibility bridge and system property log4j1.compatibility=true set. This means that the current configuration (in most cases conf/log4j.properties) should still be working. However, if the user has modified this and added a more advanced configuration it might not be supported in version 2.

The TimeMonitor application is an example where we had to change to version 2 configuration. For that reason, the TimeMonitor application is not running with the compatibility flag and instead of using the timemonitor-log4j.properties a new timemonitor-log4j2.properties file is used. Note that any custom modifications in the old timemonitor-log4j.properties file needs to be manually migrated to the new timemonitor-log4j2.properties file in order to be kept.

SignServer 5.5.x to SignServer 5.6.x

No database changes required.

SignServer 5.6.0 Notice

Changes to signdocument and validatedocument SignClient Subcommand

When using protocol HTTP, specifying -workername or -workerid is no longer required, as you can instead use the -servlet option to point directly at the /worker servlet addressing a worker. For more information, see signdocument and validatedocument.

SignServer 5.4.x to SignServer 5.5.x

No database changes required.

SignServer 5.5.0 Notice

Changes to the Internal Structure of Signed JAR Files

SignServer 5.5.0 includes the following changes made to the output of signed JAR files produced by the JArchive Signer (and from SignClient, if client-side hashing is used):

• If the original JAR file contained directory entries, these are now kept in the signed file.
• The "META-INF/" directory and the "META-INF/MANIFEST.MF" file are now positioned at the beginning of the signed JAR file.

The changes (DSS-2221) were made to better align with the output from the jarsigner tool and to workaround an issue consuming the JAR files in some versions of Java.

SignServer 5.3.x to SignServer 5.4.x

No database changes required.

SignServer 5.2.x to SignServer 5.3.x

No database changes required.

SignServer 5.1.x to SignServer 5.2.x

No database changes required.

SignServer 5.2.0 Notice

Deprecation/removal of AdminGUI

The old Administration GUI as been deprecated (in Enterprise) and removed (in Community). Please use the Administration Web interface instead, now available in both editions.

Statistics Collector Implementations Removed

The statistics collectors implementations and support for the StatisticsManager interfaces have been removed.

SignServer 5.0.x to SignServer 5.1.x

No database changes required.

SignServer 5.1.0 Notice

New Internal Format for Client Authorization Rules

The internal format for client authorization rules has been changed in version 5.1.0 as a result of added support for matching on RDN and alternative names.

• Existing rules will be available as before.
• Existing rules will be upgraded to the new format when/if the rules are edited.
• New rules will be added in the new format when using the Admin Web. If using the Admin CLI for editing client authorization rules, please use the new authorizedclients Administration CLI command instead of the legacy ones (addauthorizedclient, removeauthorizedclient and listauthorizedclient) as those will not recognize the new type of rules.
• If running in a cluster (i.e. multiple nodes with shared database), keep in mind that:
  • Rules in the new format will not be available to nodes running an older version until the nodes are upgraded.
  • Making a configuration change in a node running an older version overwrites any new rules added from a node with the new version. You are recommended to avoid making configuration changes in workers until all nodes have been upgraded to the same version.

SignServer 4.4.x to SignServer 5.0.x

No database changes required.

SignServer 5.0.0 Notice

• Building and running SignServer on Java 7 is no longer supported. See the Prerequisites section of the installation guide.
• SignServer now requires a Java EE 7+ application server. Support for JBoss AS 7 and JBoss EAP 6 has thus been dropped. For more information on required software, see the Prerequisites section of the installation guide.
• The log field TSA_TIMESTAMPREQUEST_NOUNCE has been renamed to TSA_TIMESTAMPREQUEST_NONCE.
• Due to an Apache POI library issue, signing MSI files using SignClient in client-side hashing mode when running on Windows using Java 9 or later, leaves open files handles until the Java process exits.

SignServer 4.3.x to SignServer 4.4.x

No database changes required.

SignServer 4.4.1 Notice

• Running SignClient with SignServer running on GlassFish V3 has not been completely tested for this release.

SignServer 4.4.0 Notice

• By default CACHE_PRIVATEKEY is now enabled for all signers. To get the old behavior for a signer, set CACHE_PRIVATEKEY=false.
• By default the CESeCore keystore cache is now disabled. To get the old behavior it needs to be explicitly enabled in conf/cesecore.properties
  Note that it cannot be enabled when using the new one-time crypto and is a global setting.

SignServer 4.2.x to SignServer 4.3.x

Database Schema Changes: table added: "KeyData"

Hibernate will try to add this table during startup of the application server. However, if the database user used by the data store does not have enough privileges the table has to be created manually. Refer to doc/sql-scripts/create-tables-signserver-*.sql for the definitions for your DBMS.

Changed Default Values for Algorithms

Default values for digest and signature algorithms have now changed to use SHA-256. Explicitly specified algorithms will remain with the specified values.

SignServer 4.1.x to SignServer 4.2.x 

No database changes required.

SignServer 4.2.0 Notice

The security audit logger (configured in databaseprotection.properties) is now case sensitive when it comes to the key aliases. Make sure your keys are pointed out with the right name. Specifically, if the default sample keystore with alias 'dbstorekey' was used it should now be changed to 'dbStoreKey' as that is the correct name in the keystore.

SignServer 4.0.x to SignServer 4.1.x

No database changes required.

SignServer 4.1.0 Notice

• There is now a web-based administration interface that by default is enabled and available on an URL like https://localhost:8443/signserver/adminweb.
• If you are customizing the SignServer public web to be embedded in a frame, note that SignServer now uses the X-FRAME-OPTIONS HTTP header, preventing web GUIs from being framed in modern browsers.

SignServer 3.7.x to SignServer 4.0.x

Database Schema Changes

Two new columns in the signerconfigdata table were added. Hibernate will try to add those columns during startup of the application server. However, if the database user used by the data store does not have enough privileges (i.e. no alter table rights), the table has to be altered manually according to the following.

For Oracle

ALTER TABLE signerconfigdata ADD signerName VARCHAR(255);
ALTER TABLE signerconfigdata ADD signerType VARCHAR(255);

For MySQL

ALTER TABLE signerconfigdata ADD signerName VARCHAR(255);
ALTER TABLE signerconfigdata ADD signerType VARCHAR(255);

After manually changing the database schema the application server should be restarted.

• During startup of SignServer, each worker configuration will be checked and if an empty signerName column is found the name will be populated with the value from the NAME worker property.

• During startup of SignServer each worker configuration without a worker type will get a worker type populated by loading the worker and checking the type of the implementation.

SignServer 4.0.0 Notice 

• The way to specify a worker's implementation class name in properties form has changed. Previously it was specified as: GLOB.WORKER4711.CLASSPATH=org.signserver.module.pdfsigner.PDFSigner but should now be specified as a worker property: WORKER4711.IMPLEMENTATION_CLASS=org.signserver.module.pdfsigner.PDFSigner. Exported configurations might have to be adapted. SignServer will try to upgrade existing configurations during startup.
• Each worker configuration should now contain a worker property TYPE, specifying the type of worker such as UNKNOWN, PROCESSABLE, TIMED_SERVICE, SPECIAL or CRYPTO_WORKER. Existing workers will get this worker property populated during the startup.
• Previously deprecated crypto token implementations has been removed: SoftCryptoToken, HardCodedCryptoToken, OldPKCS11CryptoToken, and PrimeCardHSMCryptoToken.
  For SoftCryptoToken and HardCodedCryptoToken, used for demonstration purposes, use KeystoreCryptoToken with the supplied sample configuration.
  For OldPKCS11CryptoToken, configurations should be upgraded to use PKCS11CryptoToken.
• The TimeStampSigner now generates RFC 5816-compliant time stamps with the ESSCertIDv2 attribute. To get the old behavior, specify SHA1 as the certificate digest algorithm, using the new CERTIFICATE_DIGEST_ALGORITHM worker property.
• For the TimeStampSigner the default behavior is now to always require the ACCEPTEDPOLICIES property to be set to a list of accepted requested policies (or empty to disallow requesting a policy). For backwards-compatibility, set the new ACCEPTANYPOLICY property to "true".
• Deprecated scripts in the bin folder have been removed. Use the following replacement scripts available:
  admingui.sh => signserver-gui
  client.sh => signclient
  signserver.sh => signserver

SignServer 3.6.x to SignServer 3.7.x

Configuration file name change

The SignServer build/deployment configuration file has been renamed from signserver_build.properties to signserver_deploy.properties. When upgrading from an earlier version the existing configuration file should be renamed accordingly. The Ant script will complain if a file with the old name is found.

Changes needed when using soft keystore crypto tokens

Pay attention to changes needed when using soft keystore crypto tokens as described in the Notice section below.

Changes needed for PKCS#11 crypto token library definitions

The old way of specifying PKCS#11 libraries by referencing the path to the dynamic library as a worker property for a crypto worker has been deprecated in favor of using named library definitions.

To continue using the old way, you need to make sure there is a defined named library using the same path as manually specified by the worker. If the library is not among the pre-defined libraries, it is possible to add new definitions in the deploy properties.

For security reasons, it is also possible to disable any of the pre-defined library definitions.

Dependency Upgraded: XML Security Library

The XML Security library has been updated to version 1.5.8 and its dependency to version 2.7.2. This fixes a potential security vulnerability in earlier versions and requires special handling if JBoss is used. See: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0107

Dependency Upgraded: Commons Collections Library

The Commons Collections library has been updated to version 3.2.2. This might also need to be take care of in the application server. See the Notice section below.

SignServer 3.7.0 Notice

• The new KeystoreInConfigCryptoToken is not supported under GlassFish 2.
• HardCodedCryptoToken is no longer supported for most use cases. Previously, the token could have been configured in Certificate or Document validators as those required a token to function. Since long this has not been required and if any of your validators has this token configured it should be removed or they might give an error.
• SoftCryptoToken is no longer supported. The token was mainly used for quick demo setups but does not support the API in 3.7. Use KeystoreCryptoToken or KeystoreInConfigCryptoToken instead.
• The KeystoreCryptoToken will no longer use the first available key when signing if DEFAULTKEY has not been set. Please configure your KeystoreCryptoTokens to have a DEFAULTKEY property set. Having a defined DEFAULTKEY is not needed if using runtime-decided keys (using the AliasSelector interfaces).

SignServer 3.7.1 Notice

The Commons Collections library has been updated to version 3.2.2.

This fixes a potential security vulnerability in earlier versions. See also the relevant "Fix Commons Collections Security issue in JBoss 7 and earlier" and "Fix Security issues in JBoss EAP" sections of the installation guide to make sure the issue is also addressed in the application server.

SignServer 3.7.3 Notice

• The renewsigner admin CLI command will no longer prompt for an authcode when the -authcode CLI argument is omitted, use the new -authprompt option to get an interactive prompt. When the authcode is not given (or prompted for), the command will not automatically (re)activate the token.

SignServer 3.5.x to SignServer 3.6.x

No database changes required. 

SignServer 3.4.x to SignServer 3.5.x

Database Schema Changes: tables removed

The following tables are no longer used by SignServer and can optionally be removed:

• enckeydata
• groupkeydata

Dependency Upgraded

The XML Security library has been updated. See the Notice section below.

SignServer 3.5.2 Notice

• The XML Security library has been updated to version 1.5.7. This fixes security vulnerability in earlier versions as well as a performance issue. See: CVE-2013-4517: Java XML Signature DoS Attack. See also the "Fix XML Security library issue" sections in the Install Guide for the extra steps needed when using JBoss 5 and 7 respectively.

SignServer 3.5.0 Notice

• The XML Security library has been updated to version 1.5.5. This version is not compatible with the version bundled with JBoss 5. For the XML support to  work when running on JBoss 5 the XML Security library and its dependencies  should be put in JBOSS_HOME/lib/endorsed. To help with that an Ant target  can be run: $ bin/ant j2ee:copy-xmlsec
• Support for the group key framework has been discontinued.

SignServer 3.3.x to SignServer 3.4.x

Database Schema Change: table renamed

A table was renamed to GlobalConfigData. For Oracle, this table was previously called "GLOBALCONFIG" while for all other it was called "GlobalConfigurationData".

• Oracle: "GLOBALCONFIG" was renamed to "GlobalConfigData"
• Databases other than Oracle: "GlobalConfigurationData" was renamed to "GlobalConfigData"

For Oracle

RENAME GLOBALCONFIG TO GlobalConfigData;

For MySQL

RENAME TABLE GlobalConfigurationData TO GlobalConfigData;

Hibernate

Hibernate will not rename this table but add it as a new one. For an existing installation, it is instead recommended to manually rename the table (using the RENAME statements described above) to not loose the existing configuration.

Database Schema Change: table added: AuditRecordData

Hibernate will try to add this table during startup of the application server. However, if the database user used by the data store does not have enough privileges the table has to be created manually. See doc/sql-scripts/create-tables-signserver34-*.sql for the definitions for your DBMS.

SignServer 3.4.0 Notice

• The category for the system logger has changed from org.signserver.server.log.ISystemLogger to org.signserver.server.log.SignServerLog4jDevice.

SignServer 3.2.x to SignServer 3.3.x

Database Schema Change

A new column in the ArchiveData table were added. Hibernate will try to add this column during startup of the application server. However, if the database user used by the data store does not have enough privileges (ie. no alter table rights) the table has to be altered manually according to the following examples. Note that after manually changing the database schema, the application server should be restarted.

For Oracle

ALTER TABLE ARCHIVEDATA ADD DATAENCODING NUMBER(10,0);

For MySQL

ALTER TABLE ArchiveData ADD dataEncoding int(11) DEFAULT NULL;

Dependency Upgraded

The BouncyCastle library has been upgraded to version 1.47. Users running Oracle JDK and JBoss will have to replace all bc*.jar copied to JBoss with the 1.47 version jars available under lib/ext/1.6/.

SignServer 3.3.0 Notice

• Apache Ant 1.8.0 or later is now required to build SignServer.
• The property "custom.commandfactory" is no longer supported. See the manual for how to add custom Admin or Client CLI commands.
• The Admin CLI no longer supports the "-host" argument and ignores it if present.
• The default archiver called OldDatabaseArchiver has changed the format of the data part of the XML serialized ArchiveData from an byte array to a  base64 encoded String. The change is transparent for Java clients using SignServer-Common.jar for parsing the ArchiveData but other clients might need to be updated.
• As an alternative to the OldDatabaseArchiver a new archiver called Base64DatabaseArchiver can also be used.

SignServer 3.2.3 Notice

• Same internal API changes has been done as part of DSS-528. If you have custom code some changes might be required.

SignServer 3.2.2 Notice

• Support for the cluster classloader has been deprecated and support for it will be dropped in a future release.
• The status property "INSYNC" is now called "TIMESOURCE0_INSYNC". Applications relaying on the name of this property should be updated.
• The time stamp signer will now log PROCESS_SUCCESS with the value false in case the response has a status other than GRANTED.

SignServer 3.2.1 Notice

• In signserver_build.properties the property "useclusterclassloader" now defaults to false. To still use the deprecated clusterclassloader this  needs to be set explicitly to true.
• In signserver_build.properties the property "includemodulesinbuild" now defaults to true. To not have all modules built in this needs to be set to explicitly to false.
• The fix of DSS-371 introduced a change in the EJB interface. Applications using that interface should run version >=3.2.1 on both client and server side.