Usage Guide
Usage Guide
Configuration/Administration
The SignServer administration command line interface (Admin CLI) is started using bin/signserver.sh (or bin/signserver.cmd).
Every worker is identified by an ID and an optional 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.
Administration CLI
*** General Commands ***
getstatus: 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.
getconfig: 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.
setproperty: Sets a custom property used by the worker or crypto token, see reference for the given Worker and CryptoToken for available properties.
setproperties: 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.
removeproperty: Removes a configured property
dumpproperties: 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.
uploadsignercertificate: Used to upload the certificate when the worker only needs the actual signing certificate and not the entire chain.
uploadsignercertificatechain: 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.
generatecertreq: 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.
activatecryptotoken: Used to activate 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.
deactivatecryptotoken: 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.
addauthorizedclient: 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.
removeauthorizedclient: Removes added client certificate entries.
listauthorizedclients: Displays the current list of acceptable clients.
Database Related
resync:
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 and it is up to the choosen Archiver if it archives the data in way that it can be queried using this commands. For Archivers other than the default "OldDatabaseArchiver" quering might have to be done directly in the database or by some custom application.
archive findfromarchiveid: 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 findfromrequestip: 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 findfromrequestcert: 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.
groupkeyservice pregeneratekeys: 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.
groupkeyservice removegroupkeys: 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.
groupkeyservice switchenckey: 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.
module add: 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.
module remove: Command used to remove a specified version of a module.
module list: Command to list all uploaded modules, it is also possible to see all JAR files that is included in the modules.
Administrators Related
wsadmins -list:
Lists administrator certificates (certificate serial number and issuer DN) for administrators authorized to use the Admin Web Service interface to administrate SignServer.
wsadmins -add:
Authorizes an administrator to use the Admin Web Service interface by certificate serialnumber and issuer DN.
wsadmins -remove:
Removes an administrator from the list of authorized administrators.
Administration GUI
As a complement to the command line interface there is also a graphical user interface for managing some of the most basic administrative tasks.
The SignServer AdminGUI can be build by running "ant admingui" and then started using the script bin/admingui.sh. By default it tries to connect to a locally running SignServer instance using EJB calls. If that fails or if the command line option "-ws" is specified a connection dialog for connecting using web services is displayed instead.
*** Connect to SignServer dialog ***
Specify URL to SignServer server as well as keystore and truststore for setting up the HTTPS connection and then click the button Connect. By clicking the button Load defaults the settings from the file default_connect.properties is loaded. If the connection is successful the current settings are stored to connect.properties and displayed the next time the dialog is openned.
Web Service URL: Base URL to the SignServer server. Default: https://localhost:8443/signserver
Truststore Type: Type of the truststore. Should match the choosen truststore file (if any). Options are: "Use keystore", JKS, PKCS12 or PEM. If "Use keystore" is choosen the trusted certificates are instead taken from the keystore and no truststore is used.
Truststore file path: Path to the truststore file (if any).
Truststore password: Password of the truststore file (if any).
Keystore Type: Type of the keystore. Should match the choosen keystore file path. Options are: JKS, PKCS12 or PKCS11. If PKCS11 is choosen the keystore file path should be the patch to the PKCS#11 shared library file.
*** Main window ***
The SignServer Administration GUI main window consists of a menu bar, a toolbar, the working area and at the bottom a status bar. The working area constists of a left and right part where the left is a list of all configured workers and the right shows details for the selected workers (if any).
*** Main window: Menu bar ***
File -> Exit: Exits the SignServer Administration GUI
Edit -> Activate: Activates the selected worker(s).
Edit -> deactivate: Deactivates the selected worker(s).
Edit -> Renew key...: Opens the Renew key dialog for the selected worker(s).
Edit -> Test key...: Opens the Test key dialog for the selected worker(s).
Edit -> Generate CSR...: Opens the Generate CSR dialog for the selected worker(s).
Edit -> Install certificates...: Opens the Install certificates dialog for the selected worker(s).
Edit -> Renew signer...: Opens the Renew signer dialog for the selected worker(s).
Edit -> Global configuration...: Opens the Global configuration window.
Edit -> Administrators...: Opens the Administrators window.
View -> Refresh: Refreshes the information about all workers.
View -> Status Summary...: Switches to the Status Summary tab for the selected worker.
View -> Status Properties...: Switches to the Status Properties tab for the selected worker.
View -> Configuration...: Switches to the Configuration tab for the selected worker.
View -> Authorization...: Switches to the Authorization tab for the selected worker.
Help -> About...: Opens the about box doc.
*** Main window: Tool bar ***
Refresh: Refreshes the information about all workers.
Activate: Activates the selected worker(s).
Deactivate: Deactivates the selected worker(s).
Renew key...: Opens the Renew key dialog for the selected worker(s).
Test key...: Opens the Test key dialog for the selected worker(s).
Generate CSR...: Opens the Generate CSR dialog for the selected worker(s).
Install certificates...: Opens the Install certificates dialog for the selected worker(s).
Renew signer...: Opens the Renew signer dialog for the selected worker(s).
*** Main window: Status Summary Tab ***
Displays the status summary for the selected worker in the same format as the CLI command "signserver getstatus complete".
*** Main window: Status Properties Tab ***
Displays the status in properties format with the option of viewing details for some properties such as for the certificates.
Details...: Selecting an property and clicking this button opens a dialog box with more information for the property (if supported). Currently for certificates this openns the Certificate details dialog.
*** Main window: Configuration Tab ***
Lists all the selected worker's configuration properties and gives the ability to add, remove or edit properties.
Add...: Adds a new property to the selected worker.
Edit: Edit the selected property.
Remove: Removes the selected property.
*** Main window: Authorization Tab ***
Lists all the authorized client certificates for the selected worker. Notice that this only applies if the worker has the AUTHTYPE set to CLIENTCERT otherwise information about authorized clients might be taken from other sources.
Add...: Adds a new authorized client. If the option "Apply changes to all selected workers" is checked the client is added to all the currently selected workers.
Edit...: Edits the selected authorized client. If the option "Apply changes to all selected workers" is checked the client is modified in all the currently selected workers.
Remove: Removes the selected client. If the option "Apply changes to all selected workers" is checked the client is modified in all the currently selected workers.
*** Renew key dialog ***
Generates new keys for all the listed workers. For this to work all workers should have the same password. Key algorithm, Key specification and New key alias must be specified if it is not taken from the worker's configuration.
*** Test key dialog ***
Test keys for all the listed workers. It is optional to either test the current key or the next key (if any) or all the keys in the keystore. For this to work all workers should have the same password. The results shows for each key the key alias, SUCCESS and the public key hash if the test signing succeded.
*** Generate CSR dialog ***
Generates certificate signing requests (CSR:s) in PKCS#10 format for all listed signers and either for the current key (Default key) or the next key. Signature algorithm, subject distingueshed name (DN) and Filename must be specified if not already taken from the worker's configuration. The format of the request could either be a Standard CSR file or a CSR wrapped in PKCS#7/CMS signed object created by a RequestSigner. The with the last option is that at the CA the signature of the request can be verified.
*** Install certificates ***
Installs signer certificate and certificate chains for the listed workers and if next key is choosen that key becomes the new default key.
Signer certificate: Browse for the signer certificate file in PEM format.
Certificate chain: Browse for the signer certificate chain file in PEM format. The signer certificate is added to the chain if it is not already included so normally this could just be the CA certificate.
*** Renew signer dialog ***
Requests a Renewal worker to renew all the choosen and selected workers. The Renewal worker will generate a new key if there isn't already a next key available and then contact EJBCA using its web service interface to request a new certificate. After recieving the new certificate it is installed and the next key becomes the current default key. Notice how the "Not valid after" date and possibly also the Signings column changes and the Renewal checkbox gets unchecked after a successfull renewal.
Working with 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 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
*** Configuring using a built-in plugin ***
Configuring using a build-in plugin only works if you have set the option includemodulesinbuild=true in signserver_build.properties.
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
*** Remove Workers ***
You can list which workers you have with the command:
bin/signserver.sh getstatus brief all
If will display for example:
===========================================
Executing Command on host : localhost
===========================================
Current version of server is : SignServer 3.2-svn
Status of Signer with Id 1 is :
SignToken Status : Offline
Signings: 0
You can remove the worker with Id 1 with the command:
bin/signserver.sh removeworker 1
bin/signserver.sh reload all
Working with Modules
*** Remove modules ***
If you have made changes to the module, and you are using the cluser classloader (i.e. not built in modules) you have to remove the module before deploying a new one.
bin/signserver.sh modules list
===========================================
Executing Command on host : localhost
===========================================
Using cluster class loader.
Listing all available modules :
Module : MRTDSODSIGNER, version 3200
Parts :
server
bin/signserver.sh module remove MRTDSODSIGNER 3200
===========================================
Executing Command on host : localhost
===========================================
Using cluster class loader.
Removing module MRTDSODSIGNER version 3200 ...
Removal of module successful.
*** Add updated modules ***
After rebuilding the modules you can add updated modules.
bin/signserver.sh module add dist-server/pdfsigner.mar soft bin/signserver.sh reload all bin/signserver.sh getstatus complete all
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/.