Usage Guide
- Usage Guide
Usage Guide
Quick Start Guides
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.
*** Required Software ***
- Sun JDK 6 Update 10 or later (http://java.sun.com)
- JBoss-4.2.3.GA (http://www.jboss.org)
- Apache ant version 1.7 (http://ant.apache.org)
- SignServer-3.1 (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
*** Installation Steps ***
-
First make sure that ant, Java and JBoss is installed properly.
-
Set the JAVA_HOME, JBOSS_HOME and SIGNSERVER_HOME environment variables.
-
Set the SIGNSERVER_NODEID environment variable, it should be a server unique string identifying the node in a cluster. (optional for one node installations).
-
Unzip the SignServer package and go to it's home directory.
-
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
-
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".
-
Do 'ant deploy' and then start JBoss (JBOSS_HOME\bin\run.sh) in another console.
-
Edit the signserver_cli.properties and set all properties starting with 'hostname.'
-
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 demoThis 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 1And double check the configuration. (Important, the properties are case sensitive).
Finally run
bin/signserver.sh reload 1To activate the configuration.
-
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.
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.
*** Required Software ***
- Sun JDK 6 Update 10 or later (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.
*** Installation Steps ***
- First make sure that Ant and Java is installed properly.
- Set the JAVA_HOME and SIGNSERVER_HOME environment variables.
- Set the SIGNSERVER_NODEID environment variable, it should be a server unique string identifying the node in a cluster. (optional for one node installations).
- Unzip the SignServer package and go to it's home directory.
- 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.
- Then build the mail signer with the command 'ant' in the SIGNSERVER_HOME directory.
- 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.
- Start the mail signer application with the command: ant run
- 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.propertiesThen run
bin/signserver.sh getconfig 1Finally run
bin/signserver.sh reload 1 To activate the configuration. -
Finally add an authorized SMTP user with the command:
bin/signserver.sh addauthorizeduser <username> <password> - 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.
Building and deploying
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 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.
Configuration/Administration
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.
Command Line Interface
*** 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.
| Rule | Comment |
|---|---|
| Properties starting with id<num>. | Will set the property to the value of the given id to the worker with the given id. |
| Properties starting with name<name>. | Will set the property to a worker with the given name. (If the name doesn't exists a unique id will be generated and assigned). |
| Property keys containing GENID<NUM>, example WORKERGENID1 or GLOB. WORKERGENID1 | The SignServer will find a free unique id and assign substitute all GENID<num> with this id. |
| Properties starting with glob. | Will set a global property with global scope. |
| Properties starting with node. | Will set a global property with node scope. |
| Properties starting with -<other prefix><value> | Will remove the property, either worker or global. |
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.
*** SignServer Specific Commands ***
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.
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.
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.
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.
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.
*** 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.
Setup Workers
In SignServer operations are performed by workers. There can be many workers and each worker has its own configuration. Each worker is identified by an unique ID. A worker can also be configured with a name by setting the property NAME. After the configuration has been activated (by issuing reload with the worker ID) that name can also be used to address the worker.
Workers are configured slitly differently depending on if the cluster class loader is used and the plugin is a separate module or if the plugin is built-in to SignServer.
*** Configuring using a built-in plugin ***
A worker is configured by setting properties for it. Specifically if the plugin is built-in it is specified by setting the property CLASSPATH to the fully qualified name of the class implementing the plugin.
The properties can be set manually using the setproperty command or by loading them all at once from a configuration file using the setproperties command. Sample configuration files are available in SIGNSERVER_HOME/sample-configs.
To setup a PDFSigner using the quick start configuration file issue the following command:
bin/signserver.sh setproperties sample-configs/qs_pdfsigner_configuration.properties
Notice the created workerId and use it when applying the configuration using the reload command:
bin/signserver.sh reload WORKER-ID
*** Configuring using a module ***
To configure the worker using a module the cluster class loader must be activated (see Changing the default configuration of the Cluster Class Loader) and the code for the plugin available as .MAR-file. To setup a worker using a module archive issue the following command:
bin/signserver.sh module add dist-server/MODULE.MAR ENVIRONMENT
Replace "MODULE.MAR" with the name of the module file and "ENVIRONMENT" with the name of the built-in configuration to load. For example to load the TSA module using the demo configuration issue the following command:
bin/signserver.sh module add dist-server/tsa.mar demo
Notice the created workerId and use it when applying the configuration using the reload command:
bin/signserver.sh reload WORKER-ID
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.
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.
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_0_Installation_Guide.pdf that can be downloaded from www.signserver.org. More information about the MySQL Cluster can be found at http://www.mysql.com/products/database/cluster/.