SignServer

Manual

Ver: 3.1.1

     09-09-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.

1.1 Changes from previous versions

1.1.1Changes between Version 3.0 and Version 3.1

• ●.A new Cluster Class Loader, simplifying the management of customized workers in a cluster. All the resource data including the classes themselves are stored in database and accessible from all nodes simultaneously. It is also possible to run multiple versions of the same worker in the same SignServer cluster, this is useful when migrating a worker to new code since both the old and new worker can be run at the same time. 

• ●.PDF Signer, Time-Stamp Authority and MRTD and their specific libraries have been moved into separate module archives (MAR files) that have to be uploaded to the SignServer installation before usage. 

• ●.For minor changes see the change log at http://jira.primekey.se 

• ●.Installation packages for Linux/Windows of both SignServer and MailSigner using generation software from Bitrock. 

1.1.2 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.3 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

Table of Contents

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, you2 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 all properties starting with 'hostname.'

10. Use the signserver cli to upload the Time-Stamp Authority module to the SignServer . (if it's not executive use chmod +x bin/signserver.sh)

bin/signserver.sh module add dist-server/tsa.mar demo

This command uploads the Time-Stamp related code to the cluster and creates a demo configuration with a preconfigured soft key store and certificate.

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

Then run

bin/signserver.sh getconfig 1

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/process?workerId=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

Since 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.

Since 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 .

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.2 Time-stamp Signer

Important, From 3.1 must the Time-Stamp Authority module be uploaded to the SignServer before it can be used. This is done with the command:
'bin/signserver.sh module add dist-server/tsa.mar'

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

7.2.2.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/process?workerId=<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.2.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.3 MRTD Signer

Important, From 3.1 must the MRTD Signer module be uploaded to the SignServer before it can be used. This is done with the command:
'bin/signserver.sh module add dist-server/mrtdsigner.mar'

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

7.2.3.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.3.2 Available Properties

No configuration properties exists.

7.2.4 PDF Signer

Important, From 3.1 must the PDF Signer module be uploaded to the SignServer before it can be used. This is done with the command:
'bin/signserver.sh module add dist-server/pdfsigner.mar'

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

7.2.4.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/process?workerId=<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.4.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.3.2 The Validation CLI interface.

There exists a Java CLI tool that can be used to check the validity of a certificate from scripts. It supports a clustered SignServer installation by using the “Use first host that response OK” policy.

When compiling, make sure that setting validationclient.enabled is set to “true” in the build properties. The client is found in dist-client/validationclient. Just copy the validate.jar and all the files in the 'lib' directory to the location where you want to use the client.

Use the client with 'java -jar validate.jar <options>'.

Here is a list of available options:

 -cert <cert-file> : Path to certificate file (DER or PEM) (Required).

 -certpurposes <certpurposes>  : A ',' separated string containing requested certificate purposes.

 -der                           : Certificate is in DER format.

 -help                          : Display this info

 -hosts <hosts>                 : A ',' separated string containing the hostnames of the validation service nodes. Ex 'host1.someorg.org,host2.someorg.org' (Required)

 -pem                          : Certificate is in PEM format (Default).

 -port <port>                   : Remote port of service (Default is 8080 or 8442 for SSL).

 -service <service-name>        : The name or id of the validation service to process request. (Required)

 -silent                        : Don't produce any output, only return value.

 -truststore <jks-file>         : Path to JKS truststore containing trusted CA for SSL Server certificates.(for HTTPS connections)

 -truststorepwd <password>      : Password to unlock the truststore.

The following return values is used:

  -2   : Error happened during execution

  -1   : Bad arguments

   0   : Certificate is valid

   1   : Certificate is revoked

   2   : Certificate is not yet valid

   3   : Certificate have expired

   4   : Certificate doesn't verify

   5   : CA Certificate have been revoked

   6   : CA Certificate is not yet valid

   7   : CA Certificate have expired.

   8   : Certificate have no valid certificate purpose.

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

Important, From 3.1 must the SimpleMailSigner module be uploaded to the MailSigner before it can be used. This is done with the command:
'bin/signserver.sh module add dist-server/simplemailsigner.mar'

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 four types of crypto tokens (Formerly known as sign tokens), two for 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.cryptotokens.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.

8.4 SoftCryptoToken

8.4.1 Overview

The SoftCryptoToken is a simple token managing it's own soft keys instead through a pkcs12. It can be used for test and demonstration purposes. The keys are stored in the worker's properties and is generated when genCertificateRequest is called. One key is used for all purposes and a new key is generated for every certificate request.

The method destroyKey is not supported.

The SoftCryptoToken have the class path: org.signserver.server.cryptotokens.SoftCryptoToken

8.4.2 Available Properties

KEYDATA =   The serialized KeyPair generated by genCertificateRequest, usually is this setting configured by the SoftCryptoToken itself.

KEYALG = The algorithm used when generating new keys. (Optional, default is “RSA”)

KEYSPEC =   The key specification used when generating new keys. (Optional, default is “2048”)

8.4.3 Example usage

First change the global property of WORKER<ID>.CRYPTOTOKEN.CLASSPATH of the worker you want to use the SoftCryptoToken with. After reload will an empty and inactive SoftCryptoToken be created.

Then generate a certificate request with the command, in this step will new keys be generated

bin/signserver.sh generatecertreq <id> "CN=Soft Signer token" SHA1WithRSA /tmp/certreq.pem

Then upload the signing certificate  to the worker using the command:

bin/signserver.sh uploadsignercertificatechain <id> GLOB /tmp/cert.pem

After the certificate chain has been uploaded to the server, the configuration must be reloaded and the SoftCryptoToken will be active and ready to use.

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 Worker

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. The MailSigner although have a timed service that checks if a Mail Processor have an expiring certificate and sends e-mail notifications about this to the administrators.

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. (Not used for the MailSigner)

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)

13.1 CertificateExpireTimedService (MailSigner only)

13.1.1 Overview

The CertificateExpireTimedService  is a timed service specific for the MailSigner. It checks all available mail processors if they have a certificate about to expire. In that case a notification about this is sent to the administrators. By default is this done 30 days before expiration. If the Mail Processor isn't updated a reminder message is sent.

The CertificateExpireTimedService have the class path: org.signserver.mailsigner.module.common. CertificateExpireTimedService and is compiled into a the dist-server/mailsigner-module-common.jar that can be included in MAR files that needs the service.

13.1.2 Available Properties

EXPIRETIMEDAYS =   Number of remaining days of the certificate before a notification is sent.(Optional, default 30 days).

REMINDERTIMEDAYS = Number of remaining days of the certificate before a reminder notification is sent.(Optional, default 10 days).

ADMINEMAIL = The email address of were the notifications is sent. (Optional, default is the configured postmaster address.)

FROMEMAIL =   The from email used in the notifications is sent.  (Optional, default is certexpire@<postmaster-domain>)

MESSAGESUBJECT  =   The subject used in the first notification message.  (Optional, default is "WARNING: Mail Processor with id : ${WORKERID} is about to expire.")

REMINDERSUBJECT  =   The subject used in the reminder notification message.  (Optional, default is "REMINDER: Mail Processor with id : ${WORKERID} is about to expire.")

EXPIREMESSAGE  =   The message body in the notifications is sent.  (Optional, default is "A mail processor at host ${HOSTNAME} have a certificate about to expire.${NL}${NL}The Mail Processor have id ${WORKERID} and a certificate with DN '${cert.CERTSUBJECTDN}' and will expire the ${cert.EXPIREDATE}. ${NL}")

REMINDERMESSAGE =   The message body in the remainder notifications is sent.  (Optional, default is "This is a reminder that a mail processor at host ${HOSTNAME} have a certificate about to expire.${NL}${NL}The Mail Processor have id ${WORKERID} and a certificate with DN '${cert.CERTSUBJECTDN}' and will expire the ${cert.EXPIREDATE}. ${NL}")

13.1.3 Available Substitution Variables

The following substitution variables can be used in notification subject and message bodys.

${NL}  = New line

${DATE}  = The current date

${HOSTNAME}  = Name of the host running the application.

${WORKERID}  = Id of the worker.

${WORKERNAME}  = Name of the worker.

${cert.CERTSERIAL}  = The serial number of the certificate about to expire.

${cert.EXPIREDATE}  = The certificates expiration date.

${cert.CERTSUBJECTDN}  = The certificate subject DN.

${cert.CERTISSUERDN}  = The certificate issuer DN.

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 The Cluster Class Loader

Important, this feature is very new in version 3.1 and should still be considered experimental.

New to SignServer 3.1.x is the Cluster Class Loader.  Simplifying the management of code in clusters. Instead of manually having to synchronize all the required JAR files to all nodes, it is possible to upload the code once and it will be accessible to all nodes in the cluster directly without having to restart the cluster. This is archived by storing the JAR resource data (such as class files) in database instead of in the application server class path.

Each worker will have their own Cluster Class Loader instance that will be reinitialized upon reload.

It is also possible to run multiple code versions of a worker simultaneously in a cluster, something that haven't been possible until now since only one version of class can exists in one JVM. This is a great feature for migration purposes where you have an old worker that is known to be stable, then it is possible to upload a new module beside the old one, with newer code, and migrate calling clients one by one.  Under the hood is actually a version prefix appended on the fly to the class name by the Cluster Class Loader when converting the byte code into a class. For example a class called somepkg.SomeWorker with version 3 will be called v3.somepkg.SomeWorker internally in the JVM. A developer should have to thing about this when developing his module but it might cause problems when remotely debugging the SignServer since the IDE won't find the source class to the modified code. If remote debugging is going to be used should class versioning be turned off.

To improve the security of the code stored in database it is possible to enforce signature verification of all the uploaded code. This is a good feature if the database is in a different security zone or managed by different administrator than the SignServer nodes itself. If verification is turned on will the Cluster Class Loader check that the class is signed with a certificate issued by issuers stored in a specific trust key store for this purpose. Important, make sure the v the code signing certificate and it's issuers have a validity long enough to avoid production stop since the signature will not verify after the certificate have expired. The code is signed by a separate JKS key store when the module is uploaded to a cluster. The code signing certificate must have the extended key usage 'code signing' in order for the Cluster Class Loader to verify it.

Before code can be uploaded to the Cluster Class Loader must it's JAR files be packaged in something called a Module Archive (MAR). See section 15.2 for details about generating a MAR file.

15.1 How to configure your worker to use the Cluster Class Loader

To enable the use of the Cluster Class Loader in a worker must the module name (and optionally version) be specified in the worker properties. If the version isn't specified will the latest be used.

Note: These two settings is set automatically if the workers is configured using property files included in a MAR file.

Cluster Class Loader Related Properties

15.2 Building Module Archives

A 'Module Archive' is a package containing all the jars required by the module along with a descriptor with information about the name of the module and it's version. A module archive is uploaded once and is then accessible for all the nodes in the cluster. A module archive can also have multiple parts indicating where in the system the code should be uploaded. In 3.1.x is only one part called 'server' supported, but in the future will other parts such as 'admin' exist. In that case will the code that should be executed on the server, such as worker code, be sent to the cluster, while the administrative part of the code is only sent to the node with an administrative web interface.

A 'Module Archive' have the postfix '.mar' and is managed with the CLI interface using the 'module' commands.

15.2.1 The MAR Descriptor

Every Module archive should have a descriptor file in it's META-INF directory. It follows the JAVA Properties notation and is used to specify general information about the module such as version and name of the module. This file is generated automatically when using the ANT tasks.

The MAR descriptor supports the following properties:

MAR descriptor Properties

15.2.2 Including Worker Configurations

It is also possible to include a set of worker configurations in the 'server' part of the module archive, these settings is configured directly after all the JAR files have been uploaded. These worker configurations should be property files that follows the same notation as if they where used with the 'setproperties' CLI command.

By default it should be named 'part-config.properties' and be in the 'server' part directory. It is also possible to have multiple configurations that is used depending on the environment the SignServer cluster is used. For instance it is possible to have one configuration file for test, another for production and a third for development. This makes it easy to manage the module since exactly the same file will be used in all environments. In case of multiple configurations should every property file be named '<environment>-part-config.properties', for instance test-part-config.properties. Later when the module is uploaded and the environment 'test' is specified will the test configuration be used.

Important, if a part-config.properties file is included in the MAR file will the worker properties MODULENAME and MODULEVERION automatically the be set to all workers defined in the  configuration file and there is no need to manually define these settings.

15.2.3 Using ANT

The simplest way to build a Module Archive is by using ANT. The SignServer have provided two ant tasks to do this.

All that is required to use these tasks is to add the following two lines in your target:

    <taskdef name="mar" classname="org.signserver.anttasks.MarAntTask"    

       classpathref="signserver.test.compile.classpath"/>

    <taskdef name="part" classname="org.signserver.anttasks.PartAntTask"

       classpathref="signserver.test.compile.classpath"/>

With these two lines included you will have access the the 'mar' and 'part' tasks. The tasks have the following properties.

MAR Task Properties

PART Task Properties

Here is an example of a simple ANT task building a MAR file, it will have the module name of SOME, version of 3 and have a 'server' part with all the JARs in 'somejarlocation' and all the worker properties in the directory 'someworkerpropertieslocation' :

    <target name="gensomemar" depends=”signserver.ear”>

    <taskdef name="mar" classname="org.signserver.anttasks.MarAntTask"    

       classpathref="signserver.test.compile.classpath"/>

    <taskdef name="part" classname="org.signserver.anttasks.PartAntTask"

       classpathref="signserver.test.compile.classpath"/>

    <mar version="3" destfile="dist/some.mar" verbose="true" >

    <part>

            <fileset dir="${somelibrarylocation}">

              <include name="*.jar"/>

            </fileset>

            <fileset dir="${somejarlocation}">

              <include name="*.jar"/>

            </fileset>

            <fileset dir="${someworkerproperiteslocation}">

              <include name="*.properties"/>

            </fileset>

    </part>

    </mar>

    </target>

15.2.4 Building Manually

A Module Archive is just like a JAR or EAR file basically a ZIP with a certain file structure. And it is quite easy to create one manually if the ANT task cannot be used. The following rules should be followed when creating a MAR file:

• ●.The module descriptor file should be in META-INF/mar-descriptor.properties. If other than  just the 'server' part is used, then it is important that the 'parts' property is set correctly. 

• ●.Every part should have a directory with the same name as the part containing all the JAR files and worker configuration files. In 3.1.x is only one part supported and it should be named 'server'. No subdirectories should exists in the parts directory. 

15.2.5 Managing Module Archives

Managing of MAR files is done using the CLI command 'signserver.sh/.cmd module' it have three subcommands: add, remove and list. See chapter 17.2.5 for more details.

Here is an example usage of adding a module to a SignServer:

'bin/signserver.sh module add dist-server/tsa.mar demo'

This will load the Time-Stamp Authority module with the demo environment, this requires that the mar file have a file called demo-part-config.properties in the server directory.

15.2.6 Changing the default configuration of the Cluster Class Loader

When enabled, the default configuration of the Cluster Class Loader is to support multiple versions but not requiring signature verification. This behaviour can be changed in the signserver_build.properties file under the 'Cluster Class Loader Configurations' section.

The following properties can be set:

SignServer Build Properties

Remember to do an 'ant clean' when changing settings in the signserver_build.properties

16  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.

17  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.

17.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.

See the directory 'sample-configs' for examples.

Remove Property Command:

Removes a configured property

Dump Properties

This tool will dump all configured properties for one or all workers in the system into a property file. If the configuration for one worker is dumped it can be used to transfer the configuration from one installation to another. If all configurations is dumped, it can be used as a backup tool.

Upload Certificate Command:

Used to upload the certificate when the worker only needs the actual signing certificate and not the entire chain.

Upload Certificate Chain Command:

Used when uploading a complete certificate chain to the worker. Which command that is supposed to be used is depending on the worker and crypto token used.

Generate Certificate Request Command

Used to generate a certificate request for a worker to be signed by a certificate authority. It takes

distinguished name and signature algorithm as parameters and writes the request in PEM format to

file.

Activate Cryptographic Token Command:

Used to activate hard crypto tokens. Authentication code is usually the PIN used to unlock the keys  on the HSM. Not used if the token is set to auto-activation.

Deactivate Cryptographic Token Command:

Brings a crypto token off-line. Not used if token is set to auto-activation.

17.2 SignServer Specific Commands

17.2.1 Authorization Related

These commands are used to configure the internal client certificate authorization when it is turned on. It controls which clients that is authorized to request a processable worker.

Add Authorized Client Command:

Adds a client certificate to a processable workers list of acceptable clients using this worker. Specify

certificate serial number in hex and the Issuer DN of the client certificate.

Removes Authorized Certificate Command:

Removes added client certificate entries.

List Authorized Clients Commands:

Displays the current list of acceptable clients.

17.2.2 Database Related

Resynchronize Database Command:

The 'resync' command is used after a SignServer had a complete database failure. When this happens  will the Global Configuration become in 'Off-line' mode and it's not possible for the nodes to communicate internally and the Global Configurations will not be in sync any more. After the database is up again can this command be sent to the node that have the most valid Global Configuration and write it to the database. After this will the Global Configuration be in 'On-line' mode again.

17.2.3 Archive Related

This commands can be used for processable workers that have archiving turned on. They are used to find specific archived responses. It's up to the implementation of the worker if it supports archiving or not.

Archive Find from Archive Id Command:

Command used to extract archived data from database identified by the archive Id.

The Id depends on the worker, in case of the TSA is the TimeStampInfo serial number used.

The data is stored with the same file name as the archive id in the specified path.

Archive Find from Request IP Command:

Used to extract all archived data requested from a specified IP address.

All data is stored as separate files with the archive id as file name in the specified path.

Archive Find from Request Certificate Command:

Used to extract all archived data requested from a client by specified it's certificates serial number and  issuer DN.

All data is stored as separate files with the archive id as file name in the specified path.

17.2.4 Group Key Service Related

These commands only applies for group key services.

Pregenerate Group Keys Command:

Command used to pregenerate a given number of group keys for a given group key service and stores them unassigned encrypted in the database. This commands can be used to let the cluster work on CPU insensitive key generation during low business hours.

Remove Group Keys Command:

Command used to remove group keys not used any more. A time range of when created, first used and last fetched can be used as criteria.

Switch Encryption Key Commands:

Command used manually switch the encryption key used to secure the group keys in database. Usually is the encryption key switched automatically but this command can be used to override this default behaviour.

17.2.5 Module Archive Related

There exists three commands for managing module archives in a cluster, they are quite straightforward. Use the command 'signserver.sh/cmd module' command for more details.

Add Module:

The 'add' command uploads a '.mar' file to the cluster. It is possible to define in which environment the module should be used, for instance 'production' or 'test' but this is all depending on which environments the module supports.

If signature verification is required by the server it is also possible to specify a path to a JKS key store along with an alias and password to the key used.

Remove Module:

Command used to remove a specified version of a module.

List Modules:

Command to list all uploaded modules, it is also possible to see all JAR files that is included in the  modules.

17.3 MailSigner Specific Commands

Add Authorized User Command:

Command to add a SMTP authorized user to a MailSigner, it applies for all configured MailProcessors.

Remove Authorized User Command:

Removes an authorized SMTP user.

List Authorized Users Command:

List currently authorized STMP users.

18  Making the SignServer highly-available

Here are some tips on configuration used to make the SignServer redundant. Usually is the SignServer set-up with three nodes (required minimum for MySQL cluster) where one node is a management node from were all deployment and administration is done and the other two services are service nodes processing the actual requests.

18.1 HTTP access requires a load balancer

HTTP based workers like the TSA can be clustered using a load balancer accessing a health check servlet returning the state of the SignServer. The basic settings of the health check servlet can be configured in the build configuration file but more advanced settings are done in 'src/web/healthcheck/WEB-INF/web.xml'. With the default settings will the servlet return the text 'ALLOK' when accessing the URL http://localhost:8080/signserver/healthcheck/signserverhealth. If something is wrong with the sign server will an error message be sent back instead.

The health check servlet can also be used to monitor the SignServer by creating a script that monitors the URL periodically for error messages.

Tip, heartbeat with ldirectord is a good solution for a load balancer and works well with the SignServer. KeepAlived is another open source solution.

The Main WebService using the Java client API manages the HA parts itself and then isn't a load balancer necessary.

18.2 Setting up a MySQL Cluster

The database backed of the SignServer can be made redundant using MySQL Cluster. Details on how to set-up the MySQL cluster can be found in the document SignServer_3_Installation_Guide.pdf that can be downloaded from http://www.signserver.org.

More information about the MySQL Cluster can be found at

http://www.mysql.com/products/database/cluster/

18.3 MailSigner

The MailSigner have no built in support for high-availability instead are the standard SMTP approach used where multiple server can be set up with different priority in the DNS MX records.

19 Installation Packages

From version 3.1 and upwards will there be binary installation packages released alongside the regular source packages. The packages includes all software necessary except for Java, were JDK 1.5+ is required (JRE will do for the MailSigner) before installing.

At the current moment are the platforms Linux (mainly Debian distribution is tested but it should work for other distributions as well) and Windows XP/2003 supported. The SignServer have two packages, one server part that should be installed in every node in the cluster and one management package containing the CLI. The same goes for the MailSigner which is also separated into two parts, one containing the SMTP server and the other containing the management CLI.

19.1Using the Installation Packages

The installation package can be used either by using a GUI or on the command line by specifying the argument '–mode text'

For an advanced set-up, for instance if many nodes should be installed with similar configuration, it is possible to preconfigure the installation by specifying a properties file containing some or all the properties asked during the installation. The properties will be used directly during installation and there will be no questions about it. See each package section for details about supported properties.

The configuration file should be in the following locations:

Unix SignServer Installation : /etc/signserver/signserver.conf

            Unix MailSigner Installation : /etc/mailsigner/mailsigner.conf

            Windows SignServer Installation: %SYSTEMROOT%\signserver.conf

(i.e C:\WINDOWS\signserver.conf)

Windows MailSigner Installation: %SYSTEMROOT%\mailsigner.conf

After installation will all the settings be saved to the configuration file by the installation program to simplify re-installation.

If all necessary properties is given in the property file, it's possible to install the package silently by specifying '--mode unattended' on the command line.

19.1.1 SignServer Node

The server part of the SignServer package contains everything (except Java) that is needed to set-up a node in a cluster. It contains a preconfigured version of JBoss that is ready to use.

The steps performed during the installation process are:

Unix:

• ●.By default is everything unpacked in /opt/signserver-<version> . 

• ●.If a /etc/signserver/signserver.conf file exists, it's read and used during installation. 

• ●.The user and group 'signserver' is created 

• ●.JBoss init.d script is configured to run at runlevel 3,4,5 

• ●.Directory /etc/signserver/ is created to contain all configuration files 

• ●.Database configuration file /etc/signserver/database-conf.xml is populated. 

• ●.Log configuration file /etc/signserver/log-conf.xml is populated and configured to log to the directory /var/log/signserver 

• ●.If no HTTP SSL certificate is specified in the configuration file will dummy key stores be generated to /etc/signserver. 

• ●.Tomcat is configured for HTTPS and it's configuration file is placed in /etc/signserver/webserver-conf.xml 

• ●.Finally is Jboss started and ready to be used. 

Windows:

• ●.By default is everything unpacked in C:\Program\SignServer\SignServer-<version> . 

• ●.If a c:\WINDOWS\signserver.conf file exists it's read and used during installation. 

• ●.JBoss is configured to be run as a service that is started automatically. 

• ●.Database configuration file <INSTALLDIR>\database-conf.xml is populated. 

• ●.Log configuration file <INSTALLDIR>\log-conf.xml is populated and configured to log to the default directory <INSTALLDIR>\jboss\server\default\log 

• ●.If no HTTP SSL certificate is specified will dummy key stores be generated to <INSTALLDIR> 

• ●.Tomcat is configured for HTTPS and it's configuration file is placed in <INSTALLDIR>\webserver-conf.xml 

• ●.Finally is Jboss started and ready to be used. 

The supported properties in the configuration file /etc/signserver/signserver.conf (or %SYSTEMROOT%\signerserver.conf for windows) are:

19.1.2 SignServer Management

This package installs the CLI interface on the management station (which can be the same as a node). The following steps are performed during installation:

Unix:

• ●.By default is everything unpacked in /opt/signserver-<version> . 

• ●.If a /etc/signserver/signserver.conf file exists it's read and used during installation. 

• ●.The user and group 'signserver' is created 

• ●.A link from /opt/signserver-<version>/bin/signserver.sh is done to /usr/local/bin. 

Windows:

• ●.Everything is unpacked in C:\Program\SignServer\SignServer-<version> by default. 

• ●.If a c:\WINDOWS\signserver.conf file exists it's read and used during installation. 

   

The signserver.conf supports the following settings:

19.1.3 MailSigner Server

The MailSigner package works much in the same way as the SignServer package with the difference that James SMTP server is included instead of Jboss.

The steps performed during the installation process are:

Unix:

• ●.By default is everything is unpacked in /opt/mailsigner-<version> . 

• ●.If a /etc/mailsigner/mailsigner.conf file exists it's read and used during installation. 

• ●.The user and group 'mailsigner' is created 

• ●.James init.d script is configured to run at runlevel 3,4,5 

• ●.Directory /etc/mailsigner/ is created to contain all configuration files 

• ●.James configuration file /etc/mailsigner/mailsigner_conf.xml is populated. 

• ●.Log configuration file /etc/mailsigner/log-conf.xml is populated and configured to log to the directory /var/log/mailsigner 

• ●.Finally is James started and ready to be used. 

Windows:

• ●.By default is everything is unpacked in C:\Program\MailSigner\MailSigner-<version> . 

• ●.If a c:\WINDOWS\mailsigner.conf file exists it's read and used during installation. 

• ●.James is configured to be run as a service that is started automatically. 

• ●.James configuration file <INSTALLDIR>\mailsigner_conf.xml is populated. 

• ●.Log configuration file <INSTALLDIR>\log-conf.xml is populated and configured to log to the default directory <INSTALLDIR>\james\logs 

• ●.Finally is James started and ready to be used. 

The supported properties in the configuration file /etc/mailsigner/mailsigner.conf (or %SYSTEMROOT%\mailsigner.conf for windows) are:

19.1.4 MailSigner Management

This package installs the CLI interface on the management station (which can be the same as the SMTP server). The following steps are performed during installation:

Unix:

• ●.By default is everything is unpacked in /opt/mailsigner-<version> . 

• ●.If a /etc/mailsigner/mailsigner.conf file exists it's read and used during installation. 

• ●.The user and group 'mailsigner' is created 

• ●.A link from /opt/mailsigner-<version>/bin/mailsigner.sh is done to /usr/local/bin. 

Windows:

• ●.Everything is unpacked in C:\Program\MailSigner\MailSigner-<version> by default. 

• ●.If a c:\WINDOWS\mailsigner.conf file exists it's read and used during installation. 

The mailsigner.conf supports the following settings but it is important that 'hostname.masternode' and 'hostname.allnodes' must point to the same host:

19.2 Generating Installation Packages

Before generating a installation package must Bitrock InstallBuilder be installed on a Linux workstation. Then set the build mode in signserver_build.properties and go to src/install/bitrock. If a SignServer package should be generated must the environment variable JBOSS_PREP point the a prepared JBoss installation that will be included in the package.

Then execute the script './buildsignserverpkgs.sh <version>' to start the generation process. The packages will be generated in BitRocks default output directory. For MailSigner use the script 'buildmailsignerpkgs.sh'.

20  For Developers

This section describes the details of how to develop your own plug-ins for the SignServer API. It goes through most of the necessary interfaces to get going.

20.1 Building with Customized Code

It is possible to have your own code in a separate code tree to avoid a mix of custom code with SignServer project code. This makes it easier to maintain and update the code for future versions. This is done by configuring one or more of the 'custom.' parameters in the build configuration file. The are each described here:

custom.src.java = Should point to an external directory containing the package base of the Java code. These are then included in the compilation at build time.

custom.src.web = Should point to the base of a WAR source tree with WEB-INF/web.xml included. This will replace the default WAR deployed during the build.

custom.build.xml = This can point to a custom build.xml that will be imported from the main build.xml and lets the developer include his own ant tasks if necessary.

custom.commandfactory = Should point to a custom implementation of the interface org.signserver.cli.ISignServerCommandFactory. This gives to ability to extend (or replace) the default CLI with another one. The best way of extending the CLI is to look at  how the DefaultSignServerCommandFactory  is structured.

20.2 Implementing Workers

The main component in the SignServer is the Worker from which most other components inherits. To get a better overview of how the different component types relate to one and another see illustration 1 in the Overview section.

Most workers work in the same way but with different interfaces to implement but for all of them should the following steps be performed.

• ●.Create a custom  class implementing the specified interface. There usually exists a base class implementing the most basic function to simply the implementation even further. If it exists it's recommended to inherit it. 

• ●.You can define your own properties that the worker can use for its configuration. 

• ●.Make sure the custom class is available to the application server 

• ●.Redeploy the SignServer. 

• ●.Register the worker in the application by setting a property WORKER<id>.CLASSPATH with a global scope in the global configuration. (Also make sure to set it's crypto tokens class-path, see separate section). 

• ●.Reload the service with the CLI reload command. 

20.2.1 The ISigner Interface

A Signer is a component used to perform some form of cryptographic processing of requested data and to create a custom signer class it should  implement the org.signserver.server.signers.ISigner interface. There exists a BaseSigner that can be inherited taking care of some of the functionality. If the BaseSigner is inherited the only method that needs to be implemented is 'processData() '.

• ●. 

There exists a DummySigner implementation that is used for demonstration purposes.

20.2.2 The ITimedService Interface

There are two kinds of timed services, singleton or non-singleton. A singleton service is only run at one of the nodes at the time while non-singleton services are run at all nodes simultaneously. If a singleton service fails to run on one of the nodes will one of the other nodes take over the service

automatically.

If a service should be singleton or not is determined by a standard property SINGLETON defined

in the ServiceConfig class.

Other basic properties used to configure all services are:

ACTIVE when set to “TRUE” means that the service is active and should be run.

INTERVAL defining the interval in seconds of how often the service should be run.

CRON used as a complement to INTERVAL to specify on a calendar basis.

• ●.To create a custom timed service class it should implement the org.signserver.server.timedservices.ITimedService interface. There exists a BaseTimedService that can be inherited taking care of most of the basic functionality. If the BaseTimedService is inherited the the only method that needs to be implemented is the 'work()' method.
   

The work method that needs to be implemented is described here:

/**

* Method that should do the actual work and should

* be implemented by all services. The method is run

* at a periodical interval defined in getNextInterval.

*

* @throws ServiceExecutionFailedException if execution of a service failed

*/

public void work() throws ServiceExecutionFailedException;

There exists a DummyTimedService implementation that is used for demonstration purposes.

Just as the other worker plug-ins have the validator service a base class taking care of most of the common methods and the only method that needs to be implemented is the 'validate' method below. But for most applications should the DefaultValidationService work. What is probably more interesting is to develop a custom IValidator used to integrate the default validation service against different certificate status repositories. See section called 'Other Customizations' for details of how to implement a Validator.

/**

* Method used to check the validation of a certificate

*

* @param validationRequest

* @return a ValidateResponse

* @throws IllegalRequestException if data in the request didn't conform with the  

 specification.

* @throws CryptoTokenOfflineException if the crypto token isn't online.

* @throws SignServerException for general failure exception during validation

* @see org.signserver.validationservice.common.ValidateRequest

* @see org.signserver.validationservice.common.ValidateResponse

*/

ValidateResponse validate(ValidateRequest validationRequest) throws IllegalRequestException, CryptoTokenOfflineException, SignServerException;

20.2.4 IGroupKeyService Interface

To customize a group key service is slightly more work. Then need five methods be implemented: 'fetchGroupKey', 'pregenerateGroupKeys', 'swithEncryptionKey', 'removeGroupKeys' and 'getStatus'. The default implementation stores the group keys in database with a reference to the encryption key used, the encryption key is stored in the extended key store. See the JavaDoc and the code for the default group key service for more details of implementing a customized one.

/**

* Main method of a Group Key Service responsible for fetching keys from

* the database.

*

* @param fetchKeyRequest

* @return a FetchKeyReponse

* @throws IllegalRequestException if data in the request didn't conform with the specification.

* @throws CryptoTokenOfflineException if the crypto token isn't online.

* @throws SignServerException for general failure exception during key generation.

* @see org.signserver.groupkeyservice.common.FetchKeyRequest

* @see org.signserver.groupkeyservice.common.FetchKeyResponse

*/

FetchKeyResponse fetchGroupKey(FetchKeyRequest fetchKeyRequest) throws IllegalRequestException, CryptoTokenOfflineException, SignServerException;

/**

* Method that instructs the group key service to pregenerate keys.

* This method is called at periods when the server is having

* a low load. This option is optional to implement, if the

* service doesn't support this method it should return null.

*

*

* @param pregenerateKeysRequest request data

* @return a response containing number of keys generated, etc

* @throws IllegalRequestException if requests contain unsupported data.

* @throws CryptoTokenOfflineException if the crypto token isn't online.

* @throws SignServerException for general failure exception during key generation.

* @see org.signserver.groupkeyservice.common.PregenerateKeysRequest

* @see org.signserver.groupkeyservice.common.PregenerateKeysResponse

*/

PregenerateKeysResponse pregenerateGroupKeys(PregenerateKeysRequest pregenerateKeysRequest) throws IllegalRequestException, CryptoTokenOfflineException, SignServerException;

/**

* Method instructing the key service to switch the encryption key for

* storing the group keys in the database. This to ensure that one encryption

* key isn't exposed through to much data.

*

* This method is optional for the implementing service to implement, if

* it's not implemented it should return null.

*

* @param switchEncKeyRequest request data.

* @return a response containing the result of the operation such as new key index.

* @throws IllegalRequestException if requests contain unsupported data.

* @throws CryptoTokenOfflineException if the crypto token isn't online.

* @throws SignServerException  for general failure exception during key generation.

* @see org.signserver.groupkeyservice.common.SwitchEncKeyRequest

* @see org.signserver.groupkeyservice.common.SwitchEncKeyResponse

*/

SwitchEncKeyResponse switchEncryptionKey(SwitchEncKeyRequest switchEncKeyRequest) throws IllegalRequestException, CryptoTokenOfflineException, SignServerException;

/**

* Method instructing the key service to remove old group keys not used anymore

* it up to the caller to check that the implementing service supports the type

* of IRemoveGroupKeyRequest used. The request should contain data specifying which

* keys that should be removed.

*

* This method is optional for the implementing service to implement, if

* it's not implemented it should return null.

*

* @param removeGroupKeyRequests request data.

* @return a response containing the result of the operation such as number of keys actually removed.

* @throws IllegalRequestException if requests contain unsupported data.

* @throws CryptoTokenOfflineException if the crypto token isn't online.

* @throws SignServerException  for general failure exception during key generation.

* @see org.signserver.groupkeyservice.common.RemoveGroupKeyResponse

* @see org.signserver.groupkeyservice.common.IRemoveGroupKeyRequest

*/

RemoveGroupKeyResponse removeGroupKeys(IRemoveGroupKeyRequest removeGroupKeyRequests) throws IllegalRequestException, CryptoTokenOfflineException, SignServerException;

/**

* Should return the actual status of the worker, status could be if

* the signer is activated or not, or equivalent for a service.

* @return a WorkerStatus object.

*/

public WorkerStatus getStatus();

20.2.5 IMailProcessor Interface

Implementing a MailProcessor for the MailSigner is almost exactly the same as for the other components but here it's the 'service' method that needs to be implemented. There also exists a utility class called SMIMEHelper that contains methods for securing emails.

/**

* Main method used when processing mails

* @param mail the mail sent through the SMTP server

* @throws MessagingException if error occurred during processing of mail.

* @throws CryptoTokenOfflineException if the signing token not available at the time of the process.

*/

void service(Mail mail) throws MessagingException, CryptoTokenOfflineException;

20.3 Implementing Crypto Tokens

20.3.1 The ICryptoToken Interface

• ●.A custom crypto token needs to implement the interface org.signserver.server.cryptotokens.ICryptoToken.  See P12CryptoToken for an example implementation. 

• ●.You can define own properties for a crypto token in the same way as for workers. The properties are sent to the crypto token upon initialization. 

• ●.Make sure the custom class is available to the application server 

• ●.Redeploy the SignServer. 

• ●.Register the crypto token to a worker in the application by setting a property WORKER<id>.CRYPTOTOKEN.CLASSPATH with a global scope in the global configuration. (Also make sure to set it's crypto tokens class-path, see next section). 

• ●.Reload the service with the CLI reload command. 

The ICryptoToken interface have the following methods that needs to be implemented:

public interface ICryptoToken {

public static final int PURPOSE_SIGN = 1;

public static final int PURPOSE_DECRYPT = 2;

public static final int PROVIDERUSAGE_SIGN    = 1;

public static final int PROVIDERUSAGE_DECRYPT = 2;

   /**

    * Method called after creation of instance.

    *

    */

public abstract void init(Properties props) throws CryptoTokenInitializationFailureException;

/**

*  Method that returns the current status of the crypto token.

*

*  Should return one of the SignerStatus.STATUS_.. values

*/

public abstract int getCryptoTokenStatus();

    /**

     * Method used to activate SignTokens when connected after being off-line.

     *

     * @param authenticationcode used to unlock crypto token, i.e PIN for smartcard HSMs

     * @throws CryptoTokenOfflineException if SignToken is not available or connected.

     * @throws CryptoTokenAuthenticationFailureException with error message if authentication to crypto token fail.

     */

    public abstract void activate(String authenticationcode) throws CryptoTokenAuthenticationFailureException, CryptoTokenOfflineException;    

    /**

     * Method used to deactivate crypto tokens.

     * Used to set a crypto token too off-line status and to reset the HSMs authorization code.

     *

     * @return true if deactivation was successful.

     */

    public abstract boolean deactivate();    

    /** Returns the private key (if possible) of token.

    *

    * @param purpose should one of the PURPOSE_... constants

    * @throws CryptoTokenOfflineException if CryptoToken is not available or connected.

    * @return PrivateKey object

    */

    public abstract PrivateKey getPrivateKey(int purpose) throws CryptoTokenOfflineException;

    /** Returns the public key (if possible) of token.

    *

    * @param purpose should one of the PURPOSE_... constants    

    * @throws CryptoTokenOfflineException if CryptoToken is not available or connected.

    * @return PublicKey object

    */

    public abstract PublicKey getPublicKey(int purpose) throws CryptoTokenOfflineException;

    /** Returns the signature Provider that should be used to sign things with

     *  the PrivateKey object returned by this crypto device implementation.

     *  @param providerUsage should be one if the ICryptoToken.PROVIDERUSAGE_ constants

     *  specifying the usage of the private key.

     * @return String the name of the Provider

     */

    public abstract String getProvider(int providerUsage);

    /**

     * Method returning the crypto tokens certificate if it's included in the token.

     * This method should only be implemented by soft crypto tokens which have the certificate

     * included in the key store.

     *

     * All other crypto tokens should return 'null' and let the signer fetch the certificate from database.

     *

     */

    public abstract Certificate getCertificate(int purpose) throws CryptoTokenOfflineException;

    /**

     * Method returning the crypto tokens certificate chain if it's included in the token.

     * This method should only be implemented by soft crypto tokens which have the certificates

     * included in the key store.

     *

     * All other crypto tokens should return 'null' and let the signer fetch the certificate from database.

     *

     */

    public abstract Collection<Certificate> getCertificateChain(int purpose) throws CryptoTokenOfflineException;

/**

* Method used to tell the crypto token to create a certificate request using its crypto token.

*/

public ICertReqData genCertificateRequest(ISignerCertReqInfo info) throws CryptoTokenOfflineException;

/**

* Method used to remove a key in the signer that shouldn't be used any more

* @param purpose on of ICryptoToken.PURPOSE_ constants

* @return true if removal was successful.

*/

public boolean destroyKey(int purpose);

}

20.3.2 The Extended Crypto Token Interface

The default group key service need support for symmetric keys in addition the the functionality provided in the basic crypto token which mainly focuses on asymmetric key functionality.

The extended crypto token adds four more methods that need implementation used to generate exportable keys (symmetric or asymmetric) and to encrypt/decrypt data using symmetric keys.

public interface IExtendedCryptoToken extends ICryptoToken {

/**

* Method instructing the crypto token to generate a key that is returned

*

* @param keyAlg the key algorithm to generate, it's up to the caller to check that the crypto token

* used supports the given value.

* @param keySpec specification of the key, it's up to the caller to check that the crypto token

* used supports the given value.

* @return either a java.security.Key or a java.security.KeyPair depending on type of keyAlg sent to the the crypto token.

* @throws IllegalRequestException if the token doesn't support the given key alg or key spec.

* @throws CryptoTokenOfflineException if the token isn't online.

*/

Serializable genExportableKey(String keyAlg, String keySpec) throws IllegalRequestException, CryptoTokenOfflineException;

/**

* Instructs the crypto token to generate a key stored in the device returning only

* a alias reference to the key.

*

* @param keyAlg the key algorithm to generate, it's up to the caller to check that the crypto token

* @param keySpec keySpec specification of the key, it's up to the caller to check that the crypto token

* used supports the given value.

* @return a reference to the key in that can be used later for encryption/decryption.

*

* @throws IllegalRequestException if the token doesn't support the given key alg or key spec.

* @throws CryptoTokenOfflineException if the token isn't online.

*/

String genNonExportableKey(String keyAlg, String keySpec) throws IllegalRequestException,  CryptoTokenOfflineException;

/**

* Method used to encrypt data using a key stored in the crypto token. This

* method should mainly be used for symmetric encryption.

* @param keyRef a alias reference to the key that should be used.

* @param data the data to encrypt.

* @return the encrypted data.

* @throws CryptoTokenOfflineException if the token isn't online.

*/

byte[] encryptData(String keyRef, byte[] data) throws CryptoTokenOfflineException;

/**

* Method used to decrypt data using a key stored in the crypto token. This

* method should mainly be used for symmetric encryption.

* @param keyRef a alias reference to the key that should be used.

* @param data the data to decrypt.

* @return the encrypted data.

* @throws CryptoTokenOfflineException if the token isn't online.

*/

byte[] decryptData(String keyRef, byte[] data) throws CryptoTokenOfflineException;

}

20.4 Other Customizations

20.4.1 The IValidator Interface

A Validator is used in the DefaultValidationService to connect to different kinds of certificate status repositories, such as CRL, OCSP, XKMS, database etc. It contains two methods 'validate' used for the actual certificate validation and 'testConnection' used by health check related functionality to check that the connection to the underlying validator resource is alright.

/**

* Main method of a Validation Service responsible for validating certificates.

*

* Important a validator also have to support to check the revocation status of the

         * involved CA certificates and should only return Validation object with status REVOKED or VALID

* If the validator doesn't support the given issuer it must return null.

*

*

* @param cert the certificate to validate.

* @return a Validation object or null if the certificate couldn't be looked up in this validator.

* @throws IllegalRequestException if data in the request didn't conform with the specification.

* @throws CryptoTokenOfflineException if the crypto token isn't online.

* @throws SignServerException for general failure exception during validation.

*/

Validation validate(ICertificate cert) throws IllegalRequestException, CryptoTokenOfflineException, SignServerException;

/**

* Optional method used to test the connection to a specific underlying validator implementation.

*

* @throws ConnectException if connection to underlying validator implementation failed.

* @throws SignServerException for general failure exception during validation.

*/

void testConnection() throws ConnectException, SignServerException;

20.4.2 The IAuthorizer Interface

It's possible to integrate the authorization of processable requests with external authorizations applications. All that is needed is a class implementing the IAuthorizer interface containing two methods, 'init' and 'isAuthorized'.

To register that the customized authorizer should be used by a worker, all that's needed to be done is to set the property AUTHTYPE to the class path of the authorizer implementation.

public interface IAuthorizer {

/**

* Method called by the worker upon first call to the authenticator after instantiation.

*

* @param workerId id of worker.

* @param config active worker configuration of worker

* @param em the SignServer EntityManager

* @throws SignServerException if unexpected error occurred during initialization.

*/

void init(int workerId, WorkerConfig config, EntityManager em) throws SignServerException;

/**

*

* Main method determining if the requester is authorized to process the data in the request.

*

* @param request the request data sent to the worker to process.

* @param requestContext containing the optional clientCert client certificate or remote IP of the user, may also contain customly defined data.

* @throws SignServerException if unexpected error occurred during authorization.

* @throws IllegalRequestException if the requester isn't authorized or couldn't be authenticated for some other reason.

*/

void isAuthorized(ProcessRequest request, RequestContext requestContext) throws IllegalRequestException, SignServerException;

}

20.5 Using the Global Configuration Store

The global configuration store is a memory bank that workers can use to store data used

in ongoing operations. The data can be either node (i.e. only read by the current node) or global

scoped.

To access the global configuration store use the getGlobalConfigurationSession() method

from the BaseWorker (inherited by most of the base component implementations). The returned

GlobalConfigurationSession have the following methods that can be used (the other ones should be

avoided)

/**

* Method setting a global configuration property. For node. prefix will the

node id be appended.

* @param scope, one of the GlobalConfiguration.SCOPE_ constants

* @param key of the property should not have any scope prefix, never null

* @param value the value, never null.

*/

public void setProperty( java.lang.String scope,java.lang.String

key,java.lang.String value ) ;

/**

* Method used to remove a property from the global configuration.

* @param scope, one of the GlobalConfiguration.SCOPE_ constants

* @param key of the property should start with either glob. or node., never

null

* @return true if removal was successful, othervise false.

*/

public boolean removeProperty( java.lang.String scope,java.lang.String key )

;

/**

* Method that returns all the global properties with Global Scope and Node

scopes properties for this node.

* @return A GlobalConfiguration Object, nevel null

*/

public org.signserver.common.GlobalConfiguration getGlobalConfiguration( ) ;

The getGlobalConfiguration returns a GlobalConfiguration and have a method

String getProperty(String scope, String property) that can be used.

The value of the property can be user-defined as long as it is guaranteed to be unique over the entire

application.

Reserved values are all property keys starting with “WORKER”.

21  Testing

There exists some test scripts used to test that the SignServer functions correctly. They are described here.

21.1 Automatic Junit Tests

Automatic Junit tests lies in the directory 'src/tests'. There are two different test suites, one for the SignServer build and the other for the MailSigner. The same command applies for both.

Important: For the SignServer test suite to run successful through all the tests must both the Main WebService and validation service WebService API be enabled in the build configuration.

To run the test suite do the following:

• •.Set the environment variable SIGNSERVER_HOME 

• •.Make sure the sign server is deployed and JBoss is running 

• •.do 'ant test:run'  

• •.A protocol is generated in the directory 'tmp/bin/junit'
   

21.2Testing the TimeStamp Authority

21.2.1 The TSA Test Client

There exists a Time Stamp Authority test client that is built with the main distribution. For other workers it's recommended to test it with the WS CLI client described in the 'Main WebService' section.

It only works without client authentication requirements and through HTTP.

To run the client do

ant

cd dist-client

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

It will continuously make one request per second.

21.2.2 Manual Tests

The time stamp signer have been tested with the OpenTSA client with both HTTP and HTTPS.

22  References

Java  (http://java.sun.com)

Jboss  (http://www.jboss.org)

Apache James mail server  (http://james.apache.org/)

Apache Ant (http://ant.apache.org)

Bouncycastle (http://www.bouncycastle.org)

RFC3161, Time-Stamp Protocol (TSP) (http://www.ietf.org)