SignServer

Manual

Ver: 3.0

08-01-18

1 Introduction/Scope

The SignServer is an application framework performing cryptographic operations for other applications. It's intended to be used in environments where keys are supposed to be protected in hardware but there isn't possible to connect such hardware to existing enterprise applications or where the operations are considered extra sensitive so the hardware have to protected more carefully. Another usage is to provide a simplified method to provide signatures in different application managed from one location in the company.

The SignServer have been designed for high-availability and can be clustered for maximum

reliability.

The SignServer comes with a RFC 3161 compliant Time-Stamp signer serving requests through http or client-authenticated https. A MRTD (Machine Readable Travel Document, i.e. electronic passport) signer. A PDF signer that adds a signature automatically to a uploaded document and a validation service used to lookup the validation of a given certificate.

From version 3.0 there also exists a mail signer framework that can be used to perform cryptographic operation on emails.

Drawing 1: Overview of a possible set up of a highly available SignServer solution

1.1 Changes from previous versions

1.1.1 Changes between Version 2 and Version 3

• Complete refactorisation of J2EE from EJB2 to EJB3 to simplify further development.

• Renamed component “Service” to “TimedService” since 3.0 supports other services.

• A “TimedService” can now be configured with a 'cron-like' settings to have services executed in other than just periodical intervals.

• A Validation Service API used to validate certificate from different issuers. The Validation Service API have it's own easy to use Web Service used to integrate with other platforms.

• A Group Key Service API used to generate and manage group keys, symmetric or asymmetric.

• Possibility to have customized authorization of requests, not just the built in client certificate authorization list.

• The name SignToken is changed to CryptoToken and introduced a new concept of ExtendedCryptoToken that supports symmetric operations.

• The RMI-SSL interface have been removed and replaced with a JAX-WS interface with a simple client framework supporting different load-balance or high availability policies.

• All request data have changed from serialization to externalization to be easier to translate to other platforms.

• A completely new MailSigner API based upon the JAMES SMTP server to perform automated cryptographic operations on e-mails very similar to the plug-ins for the SignServer.

• Java 1.4 is no longer supported.

• A lot of new JUnit tests in the test suite.

• A PDF Signer that can add a signature to a PDF document through a simple HTML interface.

• PKCS11 Crypto Token to connect to different PKCS11 implementations.

1.1.2 Changes between Version 1 and Version 2

• signserver_server.property file have been removed and replaced with a global configuration store.

• It is now possible to dynamically add and remove available signers

• A new type of component, “Service” that is run on a timely basis, used to perform maintenance or report generation.

• Improved cluster deployment functionality.

• New CLI tools to batch configure the SignServer, and to backup a current configuration. This makes it possible to set-up a configuration in test environment, dump the configuration and configure the same it in production.

2 Document History

3 Quick start of a Simple Time-stamp Server

This section will show how to set up a quick and simple standalone time-stamp server, accepting

time-stamp requests over plain HTTP.

3.1 Required Software

• Java 1.6 (or 1.5) (http://java.sun.com)

• JBoss-4.2.2.GA (http://www.jboss.org)

• Ant version 1.7 (http://ant.apache.org)

• SignServer-3.0 (http://www.signserver.org)

• 1 web-server key-store in Java key-store format (JKS), (make sure that the server certificate have the right host name in it's CN, optional (used for HTTPS))

• 1 Root certificate of the web-server in DER encoding (optional (used for HTTPS)).

• 1 Time-stamp key-store in PKCS12 format
  
  

3.2 Installation Steps

1. First make sure that ant, Java and JBoss is installed properly.

2. Set the JAVA_HOME, JBOSS_HOME and SIGNSERVER_HOME environment variables.

3. Set the SIGNSERVER_NODEID environment variable, it should be a server unique string

identifying the node in a cluster. (optional for one node installations).

4. Unzip the SignServer package and go to it's home directory.

5. If you are going to protect the HTTP communication with SSL, you need a JKS SSL server

key store. Rename the web server key store 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

6. Then copy the signserver_build.properties.sample file to signserver_buld.properties and edit

the file. At least configure the httpsserver.password property. If you are not using https

uncomment the row “j2ee.web-nohttps=true”.

7. Do 'ant deploy' and then start JBoss (JBOSS_HOME\bin\run.sh) in another console.

8. Edit the signserver_cli.properties and set the host name.* properties.

9. Edit the sample-configs/qs_timestamp_configuration.properties file and set the default policy id, the path to the timestamp p12 file and its password.

10. Use the signserver cli to upload the configuration file. (if it's not executive use chmod +x bin/signserver.sh)

bin/signserver.sh setproperties sample-configs/ qs_timestamp_configuration.properties

(In the path section, use '\\' for '\' in windows environment.)

Then run

bin/signserver.sh getconfig 1

Or you could use the signers name

bin/signserver.sh getconfig timestampSigner

And double check the configuration. (Important, the properties are case sensitive).

Finally run

bin/signserver.sh reload 1

To activate the configuration.

11. Run the test-client to see that everything is up.

cd dist-client

java -jar timeStampClient.jar “http://localhost:8080/signserver/tsa?signerId=1”

`

The message “TimeStampRequest Validated” should appear once a second.

Also check JBOSS_HOME/server/default/log/server.log that successful messages appear.

4 Quick start of a Simple Mail Signer

This section will do a fast and minimal configuration of a Mail Signer that will sign all authorized mails sent through it with a PKCS12 cryptographic token.

4.1 Required Software

• Java 1.6 (or 1.5) (http://java.sun.com)

• Ant version 1.7 (http://ant.apache.org)

• SignServer-3.0 (http://www.signserver.org)

• 1 mail signing key-store in PKCS12 format (The key store should have a RFC822Name that matches the sender address that will be replaces by the Simple Mail Signer plug-in). There exists one keystore in src/test/mailsigner_test1.p12 with a RFC822Name of mailsigner@someorg.org that can be used for testing.

4.2 Installation Steps

1. First make sure that Ant and Java is installed properly.

2. Set the JAVA_HOME and SIGNSERVER_HOME environment variables.

3. Set the SIGNSERVER_NODEID environment variable, it should be a server unique string

identifying the node in a cluster. (optional for one node installations).

4. Unzip the SignServer package and go to it's home directory.

5. Then copy the signserver_build.properties.sample file to signserver_buld.properties and edit

the file. First uncomment row “build.mode=MAILSIGNER” to instruct that this installation is a MailSigner and not a SignServer. Then go to the end of the file and fill in the required properties: mailsigner.primarydns, mailsigner.secondarydns and mailsigner.postmaster.

6. Then build the mail signer with the command 'ant' in the SIGNSERVER_HOME directory.

7. Edit the sample-configs/qs_simplemailsigner_configuration.properties file and set the sender and from addresses as well as the path and password to the cryptographic token that should be used.

8. Start the mail signer application with the command: ant run

9. Open up another console, go to SIGNSERVER_HOME and use the signserver CLI to upload the configuration file. (if it's not executive use chmod +x bin/signserver.sh)

bin/signserver.sh setproperties sample-configs/ qs_simplemailsigner_configuration.properties

Then run

bin/signserver.sh getconfig 1

Finally run

bin/signserver.sh reload 1

To activate the configuration.

19. Finally add an authorized SMTP user with the command:
bin/signserver.sh addauthorizeduser <username> <password>

20. Now is the simple mail signer ready to be used for signing outgoing emails. Configure you e-mail client to connect to the MailSigner server using the username and password you just provided and send a mail to a colleague to verify it is signed properly.

5 Terms Used in This Document

6 Overall Architecture

In the 3.0 version the SignServer project have two different builds, one is the classical SignServer and the other is a Mail Processing Server called the MailSigner.

6.1 SignServer

The SignServer is a framework designed to perform different kind of cryptographic operations for different applications.

In the 3.0 version there are three kind of processable services. Signers (used to sign or in other way process requested data). Validation Services used to verify the validity of a certificate against a set of backed issuers. The validation service can be used to simply the integration of PKIs into existing applications. The the third processable service is a group key service framework used to manage and to distribute group keys for different applications, these keys can be both symmetric and asymmetric. In addition to processable services there also exists another concept called Timed Service (called just 'service' in 2.0 edition) which are plug-ins run at defined intervals performing maintenance or reporting routines.

Out-of-the-box are there three Signers ready to be used. They are a MRTD Signer used for signing Machine Readable Travel Documents (also known as Electronic Passports), a Timestamp Signer that can be used to set up a Timestamp Authority and a PDF signer that can be used to automatically sign documents.

The main way of communicating with the SignServer is through a WebService interface (previous versions had a RMI-SSL interface, but that have been replaced by the WS for better platform independence.) but the Timestamp Signer is also available through HTTP communication and the PDF signer have a simple HTML page that allows users to upload documents to be signed.

For an overview of the different concepts in the SignServer see illustration 1. The base component is called Worker which is assigned an id, optionally a name and a configuration. A sub component is a Processable which receives and processes requests. A Processable (optionally) have access to a cryptographic token (CryptoToken) in charge of managing the keys of a Processable. A CryptoToken can be either software or hardware based.

The applications i administrated through a command-line interface, where the properties and access control can be configured.

One SignServer can have multiple services for different purposes.

6.2 MailSigner

The MailSigner is a different build of the SignServer, targeted to perform automated cryptographic operations on e-mails. The MailSigner is an add-on to the James SMTP project and the James SMTP binaries is shipped along with the SignServer package for simplified set-up.

The MailSigner's main component is the MailProcessor which is the base for all MailSigner plug-ins. There exists one ready to use MailSigner called the SimpleMailSigner. It generates a signed SMIME message of all mails sent to through the server.

One instance can have more than one MailProcessor configured. Then will the plug-ins be called by worker id in ascending order.

The MailSigner have similar CLI interface and is administrated much in the same way as the SignServer. The SMTP server have support for SMTP Authentication. For more information about the James SMTP server see http://james.apache.org .

Illustration 1: Components in the SignServer project

7 Available Plug-ins

7.1 Configuring a plug-in

A worker component is configured by entering its class path (and optionally its crypto token class path) in a memory bank called the global configuration and then issuing the reload command. There exists sample configurations for most of the plug-ins in the 'sample-configs' directory.

7.2 SignServer Signers

There currently exists three types of signers. The first one is the time stamp signer generating RFC 3161 compliant timestamps using the Bouncycastle library. A MRTD signer creating 'Machine Reader Travel Document' signatures using the RSA algorithm from pre-padded data. The final signer is a PDF Signer used for automatically signed requested PDF documents.

7.2.1 Time-stamp Signer

The time-stamp signer have the class path: org.signserver.server.signers.TimeStampSigner

7.2.1.1 Overview

The time stamp server generates time stamp tokens and have the support for the following options:

• Set of accepted policies

• Set of accepted algorithms

• Set of accepted extensions

• Accuracy microseconds

• Accuracy milliseconds

• Accuracy seconds

• Included certificate chain (currently doesn't include CRLs)

• Ordering

• TSA name

The time stamp signer currently don't support:

• CRL inclusion

• Signed attributes

• Unsigned attributes

Timestamps requests are served through a http service at the URL:

'http://<host name>/signserver/tsa?signerId=<worker Id>'

If no 'worker Id' parameter is specified then will the id of 1 be used as default.

The time-stamp signer requires a time-stamp certificate with the extended key usage 'time-stamp' only. The extended key usage extension must be critical.

7.2.1.2 Available Properties

The following properties can be configured with the signer:

TIMESOURCE = property containing the class path to the ITimeSource implementation that should be used. (OPTIONAL, default LocalComputerTimeSource)

ACCEPTEDALGORITHMS = A ';' separated string containing accepted algorithms, can be null if it shouldn't be used. (OPTIONAL, Strongly recommended)

Supported Algorithms are: GOST3411, MD5, SHA1, SHA224, SHA256, SHA384, SHA512, RIPEMD128, RIPEMD160, RIPEMD256

ACCEPTEDPOLICIES = A ';' separated string containing accepted policies, can be null if it shouldn't be used. (OPTIONAL, Recommended)

ACCEPTEDEXTENSIONS = A ';' separated string containing accepted extensions, can be null if it shouldn't be used. (OPTIONAL)

DEFAULTTSAPOLICYOID = The default policy ID of the time stamp authority (REQUIRED, if no policy OID is specified in the request then will this value be used.)

ACCURACYMICROS = Accuracy in micro seconds, Only decimal number format, only one of the accuracy properties should be set (OPTIONAL)

ACCURACYMILLIS = Accuracy in milliseconds, Only decimal number format, only one of the accuracy properties should be set (OPTIONAL)

ACCURACYSECONDS = Accuracy in seconds. Only decimal number format, only one of the accuracy properties should be set (OPTIONAL)

ORDERING = The ordering (OPTIONAL), default false.

TSA = General name of the Time Stamp Authority. (OPTIONAL)

7.2.2 MRTD Signer

The MRTD signer have the class path: org.signserver.server.signers.MRTDSigner

7.2.2.1 Overview

The MRTD Signer performs a RSA signing operation on incoming data. The data should already be padded. This signer i used to sign 'Machine Readable Travel Documents' i.e. electronic passports.

7.2.2.2 Available Properties

No configuration properties exists.

7.2.3 PDF Signer

The PDF signer have the class path: org.signserver.server.signers.PDFSigner

7.2.3.1 Overview

The PDF signer signs PDF files and have the support for the following options:

• Reason

• Location

• Rectangle

The PDF signer currently don't support:

• Inclusion of time stamps in the signature

PDF signing requests are served through a http service at the URL:

'http://<host name>/signserver/pdf?signerId=<worker Id>'

If no 'worker Id' parameter is specified then will the id of 1 be used as default.

The PDF signer requires a signing keystore with a signing certificate.

7.2.3.2 Available Properties

The following properties can be configured with the signer:

REASON = The reason included in the PDF signature and displayed by the PDF reader. Default value is “Signed by SignServer”.

LOCATION = The location included in the PDF signature and displayed by the PDF reader. Default value is “SignServer”.

RECTANGLE = The coordinates and size of the visible signature field added to the PDF file. Has the form “llx,lly,uux,uuy”, where llx is lower left x coordinate etc.

7.3 SignServer Validation Service Framework

The validation service framework is used to validate certificates from one or more issuers. It can be used to have one central point of performing revokation statuses to simplify the integration of external PKIs within an enterprise.

The validation service framework also provides a validation cache that can be used to increase performance for those cases a application does multiple lookups of the same certificate within a short period of time.

Out-of-the-Box there exists a DefaultValidationService that should satisfy most use cases but it's possible to develop a custom ValidationService if necessary. See the developer section for more details.

All Validation Services is configured by specifying the org.signserver.validationservice.server.ValidationServiceWorker in the global configuration, then is the actual ValidationService configured in the worker configuration setting the class path in the property TYPE (Not necessary for the DefaultValidationService).

The validation service framework is mostly used with X509v3 certificates but other kinds of certificates is supported as well by design.

Another concept in the Validation Service Framework is that the client also can ask the service to check the type of certificate that the certificate might be used for. A certificate type could be IDENTIFICATION or ELECTRONIC SIGNATURE.

7.3.1 DefaultValidationService

7.3.1.1 Overview

The default validation service have a set of Validators. A validator is responsible to checking the validity against one or more issuers using for example CRL check or OCSP/XKMS lookup or just by checking some database. Currently there are no ready to use validators, these remain to be developed in future versions of the SignServer.

The Default Validation Service supports validations to be cached for some or all issuers for a specified amount of time.

If not configured otherwise will the validation service use the DefaultX509CertTypeChecker that determines the certificate type from the key usage in the certificate. Key Encipherment and Digital Signature indicates a IDENTIFICATION type and Non-reputation indicates ELECTRONIC SIGNATURE.

There exists a validation specific WebService that can be used for platform independent client calls.

The WebService must be enabled during the build and isn't by default. The WebService WSDL file is located at the URL http://<hostname>:8080/signserver/validationws/validationws?wsdl and it contains two calls one is 'isValid' that performs the validation check and the other is a getStatus call that checks the health of the node and its underlying systems. The last calls can be used by clients for monitoring or implementing redundancy.

Important, Due to class path conflict in JBoss 4.2.x own JBoss WebService stack and the JAX-WS stack used by the SignServer must the JBoss WebService stack be removed before the WebService is used. This is done by going to JBOSS_HOME/server/default/deploy and remove the directory jbossws.sar.

7.3.1.2 Available Properties

The following properties can be configured with the default validation service:

The validation service have three types of properties, general properties (that applies for the service and all configured validators), validator properties (that only applies for a specific validator) and issuer properties (that only applies for an issuer configured in a specific validator).

General Properties:

CACHEDISSUERS = A ';' separated list of issuer names (usually issuer DNs) (Optional, no validation is cached if unset.)

CERTTYPECHECKER = Certificate type checker that should be used to determine the type of certificate (Optional, default is org.signserver.validationservice.server.DefaultX509CertTypeChecker)

TIMEINCACHE = Time in seconds a certificates validation should be cached (Optional, default is 10 seconds)

Validator properties:

Validator properties is specified with the prefix of 'validator<validatorId>.' or 'val<validatorId>.' were validator Id should be an integer between 1 and 255. For instance, to specify the type of a validator with an id of 1 then specify 'val1.classpath=some.classpath.SomeClass'. This validator will be initialized with all its validator specific properties (with 'val<id>.' prefix removed) as well as the general ones.

CLASSPATH = Class path to the validator that should be used. (Required for each configured validator)

Issuer properties: Issuer properties are specified as 'val<val id>.issuer<issuer id>.<property>' were issuer id is a positive integer between 1 and 255. All generic and validator specific properties (with the given validator id) will also be propagated to the specific issuer configuration.

CERTCHAIN = The certificate path of the CA certificates used to verify the certificate. Should be a appended BASE64 string. (Required for each configured issuer).

Here is an example configuration of a validation service to clarify things even further

# Set up the worker -> validation service wrapper

GLOB.WORKER1.CLASSPATH= org.signserver.validationservice .server.ValidationServiceWorker

#Uncomment and set class path to custom validation service, othervise is default #used.

#WORKER1.TYPE=

# Name of Service (Optional)

WORKER1.NAME=ValidationService1

# Define TestCA2 and TestCA3 as a cached for 15 seconds, TestCA1 is Not cached.

WORKER1.CACHEDISSUERS=CN=TestCA2;CN=TestCA3

WORKER1.TIMEINCACHE=15

# Define a validator in charge of issuer TestCA1 and TestCA2

WORKER1.VAL1.CLASSPATH=<Class path to some validator>

WORKER1.VAL1.ISSUER1.CERTCHAIN=EFWAASDFADFASDFKASDKFW1231.....

WORKER1.VAL1.ISSUER2.CERTCHAIN=EFWAASDFADFASDFKASDKFW1231.....

# Define a validator in charge of issuer TestCA3

WORKER1.VAL2.CLASSPATH=<Class path to some validator>

WORKER1.VAL2.ISSUER1.CERTCHAIN=EFWAASDFADFASDFKASDKFW1231.....

7.4 SignServer Group Key Service Framework

7.4.0.1 Overview

The group key service framework is used to manage and distribute group keys to clients in an organisation. The keys can be generated on demand or pre-generated at times when the system is not utilized a lot. The group keys can be both symmetric and asymmetric but one service can only distribute one type of key. If several kinds of keys are required should multiple services be set up within the same server.

The group keys are stored encrypted in database. The encryption key can be configured to be switched automatically after a defined number of encryptions to avoid overexposure of the cryptographic data. It is also possible to switch the encryption key manually.

The Framework requires an ExtendedCryptoToken, the difference are that the extended token have additional support for key export and symmetric key operations.

The Group Key Service have CLI commands for administration of the service such as pre-generate keys, manual switch of encryption key and removal of group keys.

The communication to the group key service is mainly done through the main Web Service interface. But other ways of communicating with the server might come in the future.

Authorization to group keys is very important and therefore should a special plug-in be developed that looks up which clients that should have access to a specific group key which fit into the organisation needs. See the authorization chapter of how to develop a customized authorization plug-in.

The basic configuration of a group key service is very similar to that of a validation service. Two entries is required in the global configuration. The first is the class path for the Worker to GroupKeyService wrapper, then a class path reference to the extended crypto token used with the service. If not the default group key service should be used it is possible to define a custom one by specifying its class path in the TYPE worker property.

7.4.0.2 Available Properties

USEPREGENERATION = Setting defining of keys should be pre-generated or generated on the fly when needed. If the pool of pre-generated keys gets empty will new keys always be generated automatically. (Optional, default is true)

ENCKEYALG = Encryption algorithm used to encrypt the group keys stored in database. ( Optional, default is “AES”)

ENCKEYSPEC = Specification of the encryption key. (Optional, default is “256”)

GROUPKEYALG = Defines the type of group keys that this service should generate ( Optional, default is “AES”)

GROUPKEYSPEC = Specification of the generated group keys. (Optional, default is “256”)

KEYSWITCHTHRESHOLD = Setting defining the number of group keys that should be encrypted by the same encryption key before it's switched. (Optional, default is 100000)

7.5 Mail Processors

This section lists the available plug-ins for the MailSigner. These plug-ins are configured in the exact same way with class path of both plug-in and its crypto token.

7.5.1 SimpleMailSigner

7.5.1.1 Overview

The SimpleMailSigner is a plug-in that generates a signed SMIME message from any authorized mail sent through the MailSigner server. It can be used prove the origin of the message to the receivers .

There exists a demo configuration in the 'sample-configs' directory.

7.5.1.2 Available Properties

EXPLAINATIONTEXT = Text attached to the e-mail describing the signature for the recipient. (Optional)

USEREBUILDFROM = Setting indicating if the from field of the SMIME should be altered. (Optional, default is true)

SIGNATUREALG = Setting configuring the signature algorithm that should be used in the SMIME message. (Optional, default is DIGEST_SHA1)

POSTMASTERSIGNS = Indicates if postmaster mail should be signed. (Optional, default is false)

FROMADDRESS = The from email address used if rebuild from is set. (Required if USEREBUILDFROM is true)

FROMNAME = Readable name used in from address field. (Optional)

CHANGEREPLYTO = Indicates if the reply-to field should be altered to the original sender. (Optional, default is false)

REPLYTOADDRESS = The reply to email address if the reply always should be changed to

a default address. (Required if CHANGEREPLYTO is true)

REPLYTONAME = Readable name used in reply-to address field. (Optional)

SIGNERADDRESS = The email address that should be in the sender field. (Required)

SIGNERNAME = Readable name used in sender address field. (Optional)

REQUIRESMTPAUTH = Setting defining if SMTP AUTH should be required to

sign the mail. (Default is true).

8 Available CryptoTokens

There exists three types of crypto tokens (Formerly known as sign tokens), one storing the keys in software, one general for communicating with cryptographic hardware through the PKCS11 interface and one for SmartCards. See the developer section for information about developing support for other HSMs.

8.1 P12CryptoToken

The P12CryptoToken signer have the class path: org.signserver.server.cryptotokens.P12CryptoToken

8.1.1 Overview

A CryptoToken using a PKCS 12 key-store in the file-system. Can only contain one signing key.

In a clustered environment must the key store be at the same location at all nodes.

The P12CryptoToken, doesn't support the destroyKey() method

8.1.2 Available Properties

KEYSTOREPATH : The full path to the key-store to load. (required)

KEYSTOREPASSWORD : The password that locks the key-store. Used for automatic activation.

8.2 PrimeCardHSMCryptoToken

8.2.1 Overview

Using PrimeCardHSM it's possible to use a SmartCard to generate 2048-bit RSA signatures. The SmartCard can perform about one signature a second. PrimeCardHSM is proprietary software by PrimeKey Solutions AB.

PrimeCardHSM requires PCSCD software and SmartCard drivers. See separate documentation about installing PrimeCardHSM.

The PrimeCardHSMCryptoToken, doesn't support the destroyKey() method.

The PrimeCardHSMCryptoToken signer have the class path: org.signserver.server.cryptotokens.PrimeCardHSMCryptoToken

8.2.2 Available Properties

DEFAULTKEY = Hash value of the signing key on the card. See PrimeCardHSM documentation for more information.(Required)

AUTHCODE = Authentication code for automatic activation (Optional).

8.3 PKCS11CryptoToken

8.3.1 Overview

Using PKCS11 it's possible to use a HSM that has a PKCS11 module, such as Utimaco, nCipher or Eracom.

The PKCS11CryptoToken have the class path: org.signserver.server.cryptortokens.PKCS11CryptoToken

8.3.2 Available Properties

DEFAULTKEY = Hash value of the signing key on the card. (Required)

PIN = Authentication code for activation. (Required)

SHAREDLIBRARY = Full path to the library containing the PKCS11 interface. (Required)

SLOT = Slot to use (Required)

8.3.3 Example usage

Edit qs_pdfsigner_configuration.properties and choose the sign token setting for the PKCS11 sign token. Run the following command to set up a PDF signer using the PKCS11 properties configured:

bin/signserver.sh setproperties qs_pdfsigner_configuration.properties

You also need a certificate for the signer. Generate a certificate request with the command:

bin/signserver.sh generatecertreq 8 "CN=PKCS11 Signer token" SHA1WithRSA /tmp/certreq.pem

Add a user in EJBCA with a certificate profile suitable for signing, and enrol for a “Server Certificate” using the public web pages.

Create the certificate chain file with the command:

cat /tmp/cert.pem /tmp/AdminCA1.pem > /tmp/certchain.pem

The signer certificate must be first, and the root CA certificate last.

Upload the signing certificate chain to the signer using the command:

bin/signserver.sh uploadsignercertificatechain 8 GLOB /tmp/certchain.pem

After the certificate chain has been uploaded to the server, the configuration must be reloaded and the server must be restarted. It is not sufficient to only reload the configuration.

9 Setting Authorization Type

9.1 SignServer

By default is client-certificate authentication required for a signature request to be processed. This can be changed with the AUTHTYPE property.

AUTHTYPE = NOAUTH, sets the server to not require any authentication.

AUTHTYPE = CLIENTCERT (default) requires a certificate of all the clients. The certificates must be in the signers access control list and be trusted by the Java distribution, i.e imported in JAVA_HOME/jre/lib/security/cacerts. Authorized clients is configured manually using the CLI interface.

This authorization functionality doesn't work for all use cases. Then it's possible to create a customized authorizer and specify it's class path as value in the AUTHTYPE property. The Processable will then automatically instantiate and use it. How to develop such a plug-in is explained in the developers section.

9.2 MailSigner

The MailSigner support SMTP Authentication which is configured in the build properties. It's then possible to authorize users by adding them manually through the CLI interface. SMTP authorization is global for all MailProcessors.

10 Disabling a Signer

Any Processable worker in the SignServer and MailSigner can be disabled, which means that it won't be executed or be included in the health check.

To disable a worker set the property “DISABLED” to “TRUE”

11 Archiving Responses (SignServer only)

If there is a need to save all generated responses, then set the property “ARCHIVE” to “TRUE” and all generated responses for that signer will be saved to database.

The archived responses can later be extracted from data base using the CLI interface. See the CLI section for more information.

12 The Global Configuration Store

The available workers and its crypto tokens and services is configured in something called the global configuration store that is slightly different from a worker configuration.

Is is dynamically configured and activated immediately. I can contain any type of data (in string representation) and can be of two types, either with global scope or node scope. A Global scoped property can be accessed by all nodes in the cluster while a Node scoped property in only used within a node and cannot be accessed by the other nodes.

12.1 SignServer specific

Database failure is handled differently. If a node looses connection to the database it put itself in a state called 'unsynchronised' and will continue its operation without storing the data to database by using a cached global configuration. It is possible to later resynchronise one nodes cached global configuration data with the database with a CLI command called 'resync'. But it is only possible to sync one of the nodes global configuration to the database.

12.2 MailSigner Specific

The MailSigner doesn't store its data in database but in a regular file handled internally. It have therefore no functionality for database fail-over and cannot be resynchronized. There currently aren't any difference in global and node scoped variables.

13 Timed Services

A Timed Service (formerly called just service) is a task that is run on a timely basis, performing maintenance tasks like changing active key, or it could generate a report.

Currently isn't the SignServer shipped with any services out of the box, but read the developer section about how to write custom services.

A Timed Service framework supports a couple basic properties that is used to calculate when and how a timed service should run. These properties are:

ACTIVE = “TRUE” if the service should be run, otherwise it is disabled.

SINGLETON = “TRUE” if the service only should be run on one of the nodes in the cluster at the time. If it's not set or set to FALSE is the service run simultaneously on all nodes in the cluster. If the node running a singleton service fails will another node sense this and start up the service

INTERVAL = Property that should define the interval i seconds the service should run.

CRON= Property that should define a CRON expression of how often the service should run. It should conform to Unix CRON standard. (One of INTERVAL or CRON is required)

14 The Main WebService Interface

14.1 Overview

New to version 3.0 is the Main WebService interface. It replaces the RMI-SSL interface in version 1.0 and 2.0 for two reasons, the RMI-SSL were based on a commercial library and it only worked for Java clients.

The WebService interface have two calls, the main one is 'process' which takes a collection of process request to a processable worker and returns a collection of process responses, the second one is getStatus that performs a health check of the node and returns an OK message if the node is healthy.

The WebService stack used is the JAX-WS stack from SUN. And the actual process data is a externalized Base64 byte-arrays. The reason why the are externalized is to simply the integration towards non-Java platforms. See the source of the actual request to see how the data is structured.

The getStatus call can be used to implement high-availability towards the client. The Java client API described in the next section have built in support for different high availability policies.

The WebService WSDL file is located at the URL http://<hostname>:8080/signserver/signserverws/signserverws?wsdl

It's possible to turn off the WebService interface by disabling it in the build configuration.

Important, Due to class path conflict in JBoss 4.2.x own JBoss WebService stack and the JAX-WS stack used by the SignServer must the JBoss WebService stack be removed before the WebService is used. This is done by going to JBOSS_HOME/server/default/deploy and remove the directory jbossws.sar.

14.2 Java Client API

Built along with the WebService is a Java API that can be used by clients. It's located in dist-client/signserverwscli and the file signserverws.jar and all the files in the lib directory is required to use the API. The client API have support for different high availability policies to avoid the need for load balance hardware.

The client classes is in the package org.signserver.protocol.ws.client and the main code are SignServerWSClientFactory creating a client using the specified load balance policy, it returns a

ISignServerWSClient that is used to perform the actual process requests.

14.2.1 Load Balance Policies

With version 3.0 is one load balance policy defined and it's called 'CallFirstNodeWithStatusOK' it calls the getStatus method on all the server nodes in the cluster simultaneously and the first node to respond OK it sends its process request to. This to ensure that only one node in the cluster actually performs the signing.

Other future load balance policies could be round robin or that all nodes are called with the requests simultaneously and the first response is used.

14.2.2 CLI Client

Along with the Java Client API is also a CLI utility provided, used mainly for testing but could in some cases be used for scripting as well. Its located in the dist-client/signserverwscli and all the files in the directory and 'lib' subdirectory is required. First edit the file wsclient.properties, there it's possible to define connection properties such as hosts, ports, SSL usage, load balance policy and so on. It is also possible to define the classes used for request generation, what type of request that should be generated and how the response should be analysed. Default is just dummy requests sent to the DummySigner used to test WebService connectivity.

Below is the syntax of the CLI command and can be used to perform continuous requests with a specified rate with a multiple number of concurrent requesting threads. This can be used to test performance of an implemented worker and for stress testing.

Usage:

wsclient <signer Id or Name> <number of requests> <milliseconds between reques

t> <number of threads> <random wait>

Where:

Signer id or name to send requests to, (required parameter)

Number of requests is for each thread (default is '1'), use 'c' or 'continuo

us' for infinite number of requests.

Minimum milliseconds between requests is the least time the client waits bef

ore issuing the next (default is '1000').

Number of threads that will send concurrent requests (default is '1').

Random wait in milliseconds, used for more random test behaviour and is adde

d to the fixed wait time (default is '0').

The client requires a configuration file 'wsclient.properties' to exist in the

same directory as the wscli, see the configuration file for more details.

15 Building and Deploying the SignServer or MailSigner

The building of the SignServer framework is configured by copying the file signserver_build.properties.sample to signserver_build.properties. In this file it's possible to set which database that is going to be used, how the web container should be configured and how many nodes that is in the cluster. After it's configured issue the command 'ant' followed by 'ant deploy' to send it to the application server. Currently is JBoss the only supported application server and it requires the environment variable JBOSS_HOME to be set prior to the deploy command.

How to set-up a highly available SignServer cluster is described in a separate document called

SignServer_3_0_Installation_Guide.pdf that can be downloaded from http://www.signserver.org

The document describes how to set it up in a Cent OS 4.4 environment with two service nodes and

one management node, but should be rather easy to adjust to other platforms.

Building the MailSigner is very similar to the SignServer. Just set the property 'build.mode' to 'MAILSIGNER' in the top of the build configuration file and set the required settings (such as DNS servers) in the bottom of the file. Then build the MailSigner with the command 'ant'.

To start up the MailSigner application issue the command 'ant run'. If you want to debug the application in a IDE such as Eclipse issue the command 'ant debug'. This can be very helpful when developing MailProcessors. In Eclipse create a 'Remote Java Application' debug configuration and have it to connect to port 8000, then set a break point in your code and it will stop there the next time the MailSigner enters that state.

Since the MailSigner is built upon the JAMES SMTP server it is possible to configure the SMTP server more than is available in the build configuration file. This is done in the file extapps/james/apps/james/SAR-INF/config.xml, see the JAMES documentation for more information about what is possible and how to do it.

16 Administrating the SignServer

The SignServer and the MailSigner is administrated using a common CLI interface located in bin/signserver.sh/cmd. Most of the commands work in the same way for both build.

Every worker is identified by a id and optionally a name that can be used in all the CLI commands.

It is possible to do configuration of a worker while it's in production. All configuration commands are cached until a reload command is issued and the configuration becomes active.

There is a special property file for the cli interface called signserver_cli.properties defining which nodes that exists in the cluster. The properties are:

hostname.masternode = Should only contain one of the nodes, specified as the default master node. Used by operations dealing with the database and where not all nodes in the cluster needs to be contacted. It is possible to override this setting in the CLI by using the -host <host name> parameter.

hostname.allnodes = Should contain all the nodes in the cluster, separated by a ';'. Mainly used by the commands getStatus, activateCryptoToken and deactivateCryptoToken.

Its possible to customize the CLI with your own code. How to do this is described in the development section.

16.1 General Commands

These commands applies for all types of workers and works in the same way for both the SignServer and MailSigner.

Get Status Command:

Returns the status of the given worker, it says if its crypto token is active or not and the loaded 'active' configuration. It is possible to get a brief summary or a complete listing for one worker or all configured workers. If all workers are displayed will also all the global configuration parameters be displayed.

Get Configuration Command:

Returns the current worker or global configuration depending on options.

For worker configuration observe that this configuration might not have been activated yet, not until a 'reload' command is issued.

Set Property Command:

Sets a custom property used by the worker or crypto token, see reference for the given Worker and CryptoToken for available properties.

Set Properties Command

Command used to batch a set of properties, both for the global and worker configuration.

It can be used to configure a Signer in a test environment, dump all the properties and upload it into production.

It reads all the configuration properties form a property file and depending on the contents of the key it sets the given property. All properties will be set according to the following defined rule set.