Usage Guide

Configuration/Administration

The SignServer administration command line interface (Admin CLI) is started using bin/signserver (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.

getproperty: List the value of a worker or global property.

Usage:

signserver getproperty <signerid | signerName | global | node> <propertykey>

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.

importcertificatechain: Used to import a certificate chain into a crypto token. It takes a worker ID of the crypto worker (or a worker ID of a worker with the crypto token configured in the legacy way) and a path pointing to a file containing the certificate chain and a key alias to import to. This is currently supported by the PKCS11 and keystore crypto token implementations.

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. An optional key alias can be specified to generate a request given a specific key alias from the crypto token.

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. If DN components contains commas, these needs to be escaped with backslashes. Alternatively a certificate file (PEM or DER format) can be specified, from which the serial number and issuer DN is fetched.

Usage:

Example 1: signserver addauthorizedclient 1 EF34242D2324 "CN=Test Root CA"
Example 2: signserver addauthorizedclient 1 EF3456789ABC "CN=Client,O=Test Organization,C=SE"
Example 3: signserver addauthorizedclient 1 client.pem

removeauthorizedclient: Removes added client certificate entries.

listauthorizedclients: Displays the current list of acceptable clients.

renewsigner: Sends a request for renewal of the specified worker to the specified renewal worker. If the authcode parameter is omitted the command will renew the certificate without an authcode, assuming the crypto token is auto-activated or the worker is using a separate crypto worker (recommended). To get the old behaviour of prompting for the authcode, specify the -authprompt option. When the authcode is not passed as a parameter or prompted for, an explicit activation of the token will not be performed. See also the section about the RenewalWorker.

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 chosen Archiver if it archives the data in way that it can be queried using this commands. For Archivers other than the default "OldDatabaseArchiver" and Base64DatabaseArchiver querying might have to be done directly in a database, filesystem 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 title as the archive ID and with the file extension depending on the type of item, for instance ".request" or ".response".

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 title and the file extension depending on the type of item.

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 title and the file extension depending on the type of item.

archive query: Used to query contents of the archive. Actual archived data is not fetched by this command.

Usage:

signserver archive query -limit <number> [-criteria  "<field> <op> <value>" [-criteria...]] [-from <index>] [-header] [-request|-response]
   <field> is a field name from the archive: archiveId, requestCertSerialNumber, requestIP, requestIssuerDN, signerid, time, type
   <op> is a relational operator: GT, GE, LT, LE, EQ, NEQ, LIKE, NULL, NOTNULL
   -request shows only entries for requests
   -response shows only entries for responses
   Example: signserver archive query -limit 10 -criteria "signerid EQ 1"
   Example: signserver archive query -limit 10 -criteria "signerid EQ 1" -request
   Example: signserver archive query -limit 10 -criteria "time GT 1359623137000" -criteria "requestIP EQ 127.0.0.1
   Example: signserver archive query -limit 10 -criteria "signerid EQ 1" -outpath /tmp/out\n\n"

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 (in hexadecimal) and issuer DN with space after each comma separating DN components. If DN components contains commas, these needs to be escaped with backslashes.

An example on how to enter the issuer DN when using a certificate issued from EJBCA with the default (as specified by EJBCA) LDAP DN order:

C=SE, O=TestOrganization, CN=IssuingCA

An example using escaped DN components

C=SE, O=TestOrganization\, The, CN=IssuingCA\, The

This is the reversed order compared to how the issuer DN is stored in the certificate.

An example on how to enter the issuer DN when using a certificate issued from EJBCA with the Use LDAP DN order option disabled:

CN=ReverseIssuingCA, O=TestOrganization, C=SE

Alternatively a certificate file can be specified, from which the serial number and issuer DN will be taken.

Samples:

Example 1: signserver wsadmins -add -certserialno 123ABCDEF -issuerdn "CN=Neo Morpheus, C=SE"
Example 2: signserver wsadmins -add -cert wsadmin.pem

wsadmins -remove:

Removes an administrator from the list of authorized administrators.

wsadmins -allowany:

Sets whether any administrator with a certificate accepted by the web server/proxy is authorized or not. When set (true) it overrides the WSADMINS global property. Takes an optional boolean parameter, if left out sets to true (allow all). This can be used for initial setup.

Auditors Related

wsauditors -list:

Lists auditor certificates (certificate serial number and issuer DN) for administrators authorized to use the Admin Web Service interface to query the audit log of SignServer.

wsauditors -add:

Authorizes an auditor to use the Admin Web Service interface by certificate serialnumber (given in hexadecimal) and issuer DN.

wsauditors -remove:

Removes an auditor from the list of authorized administrators.

Archive Auditors Related

wsarchiveauditors -list:

Lists archive auditor certificates (certificate serial number and issuer DN) for auditors authorized to use the Admin Web Service interface to query the archive of SignServer.

wsarchiveauditors -add:

Authorizes an auditor, by specifying a certificate serial number (in hexadecimal) and issuer DN, to use the Admin Web Service interface for querying the archive.

wsarchiveauditors -remove:

Removes an auditor from the list of authorized archive auditors.

auditlog -query:

Query the CESeCore audit log.

Usage:

signserver auditlog -query -limit <number> [-criteria  "<field> <op> <value>" [-criteria...]] [-from <index>] [-header]

-limit sets the maximum number of rows matched, this option is required to avoid putting too much load on the server.

<field> is a field name from the audit log: additionalDetails, authToken, customId, eventStatus, eventType, module, nodeId, searchDetail1, searchDetail2, sequenceNumber, service, timeStamp.

<op> is a relational operator: GT, GE, LT, LE, EQ, NEQ, LIKE, NULL, NOTNULL

When given the -header option, a column header is outputted before the results.

If databaseprotection.enableverify is enabled at the server side the signature of each row displayed are verified. If the verification fails for any of the rows matching the search criteria, an error message is displayed. The error message contains information about the first row that failed.

querytokenentries:

Queries the entries (key alias, certificates etc) in a CryptoToken. If no limit is given all entries are queried and printed (10 at a time). You can specify to start query from an index in the result. Search conditions can be added to only search for entries with certain key aliases.

Usage:

signserver querytokenentries -token <id or name> -limit <number> [-criteria  "<field> <op> <value>" [-criteria...]] [-from <index>] [-v]

-limit sets the maximum number of rows matched, this option is required to avoid putting too much load on the server.

<field> is a field name from the token: alias

<op> is a relational operator: EQ, NEQ or LIKE

-v means verbose and if given outputs also entry type as well as any certificates or additional information available in each entry

Database CLI

Note
This is a SignServer Enterprise Edition (EE) feature.

The SignServer Database CLI uses Java Persistence API (JPA) to connect to the SignServer database. The CLI is configured by the dbcli.* properties in signserver_cli.properties.

The CLI needs to have the JDBC driver of the selected database available on the classpath. This can be achieved by setting the OPTIONAL_CLASSPATH environment variable when calling the bin/signserver-db script or by putting the JAR under lib/ext/jdbc/ and calling it jdbc.jar. The last method is required to be able to run the JUnit tests.

Sample usage:

bin/signserver-db audit

Verify Auditlog Command

Usage: verifylog -all
       verifylog [-node NODENAME[:OFFSET] ...]

Verifies logs from all nodes starting at sequence number 0 or only from the specified nodes and optional sequence number offsets specified.
If the nodename is suffixed with a colon and an number then the verification for that node is started from that sequence number.
The JDBC connector of the database might have to be put on the classpath. See the example below.

Example: a) signserver-db audit verifylog -all
Example: b) signserver-db audit verifylog -node server1 -node server2:708
Example: c) OPTIONAL_CLASSPATH=/usr/share/java/mysql-connector-java.jar signserver-db audit verifylog -all

The command can be run to verify the signature of every entry in the auditlog as well as checking the sequence number in order to make sure that it does not contain any gaps.

The keys used to verify the log are configured in conf/databaseprotection.properties.

Sample output:

2013-07-04 15:29:10,073 INFO  [VerifyLogCommand] The following nodes exists: [server1, server2]
2013-07-04 15:29:10,074 INFO  [VerifyLogCommand] Start sequences: {server1=0, server2=0}
2013-07-04 15:29:10,635 INFO  [SoftCryptoToken] Invalid authentication code. Token id=400.
2013-07-04 15:29:10,716 INFO  [SoftCryptoToken] Activated Crypto Token with ID 400.
2013-07-04 15:29:10,722 INFO  [VerifyLogCommand] Progress: node=server1 rowCount=3
2013-07-04 15:29:10,722 INFO  [VerifyLogCommand] Last sequence number: 2
2013-07-04 15:29:10,745 INFO  [VerifyLogCommand] Progress: node=server2 rowCount=11
2013-07-04 15:29:10,745 INFO  [VerifyLogCommand] Last sequence number: 7
2013-07-04 15:29:10,747 INFO  [VerifyLogCommand] Audit log validation completed in 0 seconds. 11 rows found. Errors: 0 Warnings: 0
2013-07-04 15:29:10,747 INFO  [VerifyLogCommand] Verification finished with success
2013-07-04 15:29:10,747 INFO  [VerifyLogCommand] Last sequences: {server1=2, server2=7}

Archiving of the audit log

As the Database CLI audit verifylog command checks for gabs in the sequence numbering entries from the audit log can not be archived/moved to other storage without special care. However since the command now supports the option to specify from which sequence number to start the verification the following scheme for archiving is proposed:

  1. Run the command to verify the complete log audit log:
    audit verifylog -all
    Note down the last sequence number for each node. Ie:
    Last sequences: {server1=2, server2=7}
  2. All entries from 0 up to the entry before the last can now be archived and removed from the database. In our example that would be entry 0 and 1 for node server1 and entries from 0 to 6 for node server2.
  3. The next time the log should be verified start the verification from the last sequence numbers:
    audit verifylog -node server1:2 -node server2:7
    Again note down the last sequence number for each node and all entries up to the sequence number before the last for each node can now be archived.
Note
It is important to not remove the row with the last sequence number for any node as if the application is restarted the sequence numbering would than start again from 0 for that node.

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 is built by default (unless the property admingui.enabled is set to the value "false" in signserver_deploy.properties), and can be started using the script bin/signserver-gui.

On startup, the connect to SignServer dialog offers the possibility to either connect to a locally running SignServer instance or a remote one over web services. If the "-ws" command line option is specified the later option is already selected when the dialog opens.

See also the Admin GUI troubleshooting section.

Connect to SignServer dialog

First select either to connect to a local or remote instance. If a remote one is selected then also specify URL to SignServer server as well as keystore and truststore for setting up the HTTPS connection. Then click the button Connect. By clicking the button Load defaults the settings from the file default_connect.properties is loaded. The current settings are stored to connect.properties and displayed the next time the dialog is openned.

Connect to: Select to either connect to a "Local SignServer" using the EJB interface or a "Remote SignServer" using web services on the specified URL.

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 path 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 consists 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 -> Add Worker/Load Configuration…: Opens the dialog to import a configuration or set-up a worker manually by specifying worker parameters. When selecting "Load from file" it is possible to load a configuration file. This is equivalent of the "setproperties" Admin CLI command. Selecting "Add worker" enables setting up a worker from scratch by manually specifying a worker ID (the default selected will generate an ID dynamically), worker name, fully qualified class name for the implementation, and (optionally) a signer token implementation. Additional properties can be added using the table below. When the required parameters are given, the "Next" button will enable moving to the next step where additional manual editing of the resulting configuration can be made (the format is the same as the worker properties files). Clicking the "Apply" button from this stage will load the current configuration. The dialog can be dismissed in both states using the "Cancel" button.

File -> Export...: Opens the Export configuration dialog. This is the equivalent of the "dumpproperties" Admin CLI command. The dialog gives the option to export all workers, the selected workers or none. In addition it also gives the option to include all global configurations not related to any worker (always enabled if no workers choosen for export).

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 -> Destroy key...: Opens the Remove key dialog for the selected worker and asks for a key to remove from the crypto token.

Edit -> Remove worker...: Removes the selected workers from the SignServer configuration.

Edit -> Reload from database...: Reloads the global configuration or the selected workers from the database. This is only needed if the configuration was changed from an other node and the nodes uses a shared database.

Edit -> Global configuration...: Opens the Global configuration window.

Edit -> Administrators...: Opens the Administrators window.

Allows adding webservice administrators, auditors, and archive auditors. The administrators can be added by explicitly entering the client certificate's serial number in hexadecimal (leading zeroes and letter case is not significant) and the issuer DN with space after each comma separating DN components. If DN components contains commas, these needs to be escaped with backslashes.

An example using a certificate issued from EJBCA with the default (as specified by EJBCA) LDAP DN order:

C=SE, O=TestOrganization, CN=IssuingCA

This is the reversed order compared to how the issuer DN is stored in the certificate. An example using a certificate issued from EJBCA with the Use LDAP DN order option disabled:

CN=ReverseIssuingCA, O=TestOrganization, C=SE

Alternatively a certificate file can be loaded, from which the serial number and issuer DN will be taken.

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.

Specify certificate serial number in hex and the Issuer DN of the client certificate. If DN components contains commas, these needs to be escaped with backslashes. Alternatively a certificate file (PEM or DER format) can be loaded, from which the serial number and issuer DN is fetched.

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 opens 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. If the checkbox "Allow any administrator with a valid certificate..." is selected, any user with a valid certificate will be authorized. Having this enabled will override the administrators added in the list above. This is meant primarily for allowing a temporary certificate for setting up initial configuration.

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. The "..." button can be used to read the values for serial number and issuer DN from a certificate file in PEM or DER format.

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.

Main window: CryptoToken Tab

The CryptoToken tab is only visible when selecting a worker that either is a CryptoWorker or is a worker that has crypto token configuration. The tab allows quering of entries inside the crypto token as well as generating keys, certificate requests and importing certificates etc.

First: Go to the first search results page.

Previous: Go to the previous search results page.

Reload: Reloads the search result according the the current index and the selected number of entries per page.

Next: Go to the next search results page.

Displaying results: Displays the first row index and the last in the current result.

Entries per page:: The maximum number of rows to display in one page.

Generate key...: Opens the key generation dialog. Fill in the alias of the new key that should be generated as well as the key type (i.e. RSA, DSA or ECDSA) as well as the the key specification (i.e. key length such as "2048" for RSA and DSA or curve name such as "secp256r1" for ECDSA). For RSA keys, a custom public exponent can be expressed as part of the key specification by entering a value such as "2048 exp 5" or "2048 exp 0x10001", expressing the exponent value in decimal or hexadecimal form. After filling in a key alias a new row will automatically added which allows for generating more keys.

Note that this dialog is different from the Renew key dialog as in this case the worker's next key property (NEXTCERTSIGNKEY) is not updated.

Test: Opens the Test key dialog for the selected entry.

Generate CSR...: Opens the Generate CSR dialog with the key aliases of the selected entries filled in.

Import certificates...: Opens the Install certificates dialog for importing ceritificates to the selected token entries.

Note that installing certificates this way it is only possible to store the certificates in the token and the worker's current key (DEFAULTKEY) and next key (NEXTCERTSIGNKEY) properties are not updated.

Remove: Opens the Remove key dialog with the selected key aliases already filled in.

Details...: Opens the details window displaying more information about the token entry:

  • Alias: The key alias
  • Type: The type of entry, i.e. private key, secret key or trusted certificate
  • Creation date: If available the time and date the entry was created
  • Certificate: If available, the subject DN of the end entity certificate. The View button opens a window where the certificates can be inspected.
  • Key specification: If available, the key length or curve used
  • Key algorithm: If available, the algorithm used for the key, i.e. RSA, DSA, ECDSA or AES etc.
  • Additional information might be available depending on the crypto token implementation.

Double clicking or pressing the Enter key on a selected row opens the details window as well.

Main window: Audit log

In the "Audit log" tab controls for querying and filter the audit log exists.

  • Current conditions: Lists query conditions used to filter the search results.
  • Add: Opens a dialog box for adding query conditions.
  • Remove: Removes the selected query condition.
  • First: Go to the first search results page.
  • Previous: Go to the previous search results page.
  • Reload: Loads or reloads the search result according the the current search condition(s), index and the selected number of entries per page.
  • Next: Go to the next search results page.
  • Displaying results: Displays the first row index and the last in the current result.
  • Entries per page:: The maximum number of rows to display in one page.

Double clicking or pressing the Enter key on a selected row opens a window showing details for the row.

If databaseprotection.enableverify is enabled at the server side the signature of each row displayed are verified. If the verification fails for any of the rows in a page, an error message is displayed. The error message contains information about the first row that failed.

Main window: Archive

In the "Archive" tab controls for querying and filter the archive.

  • Current conditions: Lists query conditions used to filter the search results.
  • Add: Opens a dialog box for adding query conditions.
  • Remove: Removes the selected query condition.
  • First: Go to the first search results page.
  • Previous: Go to the previous search results page.
  • Reload: Loads or reloads the search result according the the current search condition(s), index and the selected number of entries per page.
  • Next: Go to the next search results page.
  • Displaying results: Displays the first row index and the last in the current result.
  • Entries per page:: The maximum number of rows to display in one page.

When selection one or more rows from the search result, the "Fetch selected archive data items" button is enabled. Clicking this button opens a dialog allowing to select a download directory and downloading the archived data of the selected rows.

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. In the key dropdown menu either the current key (Default key) or the next key can be selected. It is also possible to manually enter a value in the field to generate a CSR for a specific key alias in the crypto token. 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.

At least one of "Signer certificate" and "Signer certificate chain" columns needs to be filled in. If a file is chosen for "Signer certificate" then the first certificate from that file will be used as signer certificate. It will also be added to the beginning of the certificate chain (if it is not already there). If a file is chosen for "Signer certificate chain" then all of the certificates from that file will be included in the certificate chain. The first certificate will be used as signer certificate (if a "Signer certificate" was not chosen).

If the "Install in token" check box is selected, the certificate chain will be imported to the worker's crypto token (if the crypto token supports this operation). When this is selected, the key alias to import the chain to in the token can be manually entered in the key column. This is currently only supported for keystore and PKCS11 crypto tokens.

Signer certificate: Browse for the signer certificate file in PEM format.

Certificate chain: Browse for the signer certificate chain file (or CA certificate(s)) in PEM format.

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.

Remove key dialog

Enter the key alias of the key to remove from the crypto token. Note that multiple workers might be using the key. If the crypto token supports key removal the key will be deleted and it might not be possible to restore it.

Global configuration dialog

Lists all the global configuration properties and gives the ability to add, remove or edit properties.

Administrators dialog

Lists all the authorized WS administrators, auditors, and archive auditors and gives the ability to add, remove or edit them. It is also possible to get the serial number and issuer DN from a certificate file in PEM or DER format by using the "From file" button.

If already connected over WS, it is possible to click the "Load current" button to fill in the values from the currently used administrator certificate.

If the "Allow any aministrator with a valid certificate" is checked all administrators are given access even if they are not present in the list. This is for instance useful when first setting up the system. After adding your administrators the checkbox can be unchecked. It is recommended to add your self using the "Load current" button to be sure the correct information is filled in before disabling access for admins not in the list.

Admin GUI troubleshooting

  • AdminGUI login using smartcard fails on 64-bit (x86_64) version of Windows:
    The 64-bit version of Oracle Java does not support PKCS#11. A 32-bit version of Java and the PKCS#11 shared library should be used instead on that platform.

  • AdminGUI login using smartcard fails if path to DLL contains parenthesis:
    For instance the following path would cause problem: c:\program files (x86)\middleware\pkcs11.dll
    The problem is Java bug 7196009.
    Until this has been fixed you will need to install the middleware (PKCS#11/smartcard library) to a path without parenthesis.

  • IPv6 dualstack can give permission denied when trying to connect from AdminGUI:
    Trying to connect to SignServer over web services using the AdminGUI on Windows where both IPv4 and IPv6 is available can give "permission denied".
    One workaround is to edit signserver-gui.cmd and adding the following to the command:
    -Djava.net.preferIPv4Stack=true

  • AdminGUI login using smartcard fails most of the time with some cards:

    The card prompts for the PIN but then doesn't ask for which certificate to login with. Instead an error message with the text "Received fatal alert: bad_certificate" is displayed. This error message indicates that the server did not accept the provided certificate (ie, the issuer was not in the server's truststore). However, in this case the error could be because no certificate was possible to read from the card. This has been observed with some type of smart cards.

    A workaround that has been working in those cases are:

    1. Start the GUI without the card inserted
    2. Press Connect (without the card inserted)
    3. There will be an error message saying that "slotListIndex is 0 but token has 0 slots". Just ignore it.
    4. Now insert the card and press Connect again
    5. This time after the PIN prompt you are asked for which certificate to login with

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.

Configuring

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 setproperties sample-configs/pdfsigner.properties

Notice the created workerId and use it when applying the configuration using the reload command:

bin/signserver reload WORKER-ID

Remove Workers

You can list which workers you have with the command:

bin/signserver getstatus brief all

If will display for example:

===========================================
Executing Command on host : localhost
===========================================


Current version of server is : SignServer 3.3.0alpha0


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 removeworker 1
bin/signserver reload all

Making the SignServer highly-available

Here are some tips on configuration used to make the SignServer redundant.

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 SignServer, an error message will 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.

Healthcheck

Setting up the Health check servlet

In SignServer there exists a health check service that can be used for health monitoring. It is also useful for cluster, as it can be checked by load balancers to determine if a node should be active in the cluster (healthy) or taken out of the cluster (unhealthy).

The servlet is located at the URL: http://localhost:8080/signserver/healthcheck/signserverhealth and configured in signserver_deploy.properties.

The following configuration parameters may be set to configure authorization and what the service checks:

healthcheck.authorizedips
- A semicolon-delimited list of IP addresses authorized to access the healthcheck servlet, if the list contains the keyword "ANY", any IP address is authorized access (defaults to 127.0.0.1).

healthcheck.minimumfreememory
- Number of megabytes of memory that must be free before removing the node out of the cluster (defaults to 1).

healthcheck.checkdbstring
- The string that should be used to do a minimal check that the database is working. May differ between databases. (defaults to Select count(*) from signerconfigdata, the property is not used when running without database).

healthcheck.maintenancefile
- The path to a file containing the maintenance state, this file is a standard Java property file and should have a property (by default named DOWN_FOR_MAINTENANCE"). If this property has the value true, none of the standard health checks will be performed, and instead the result will be a string of the form MAINT: DOWN_FOR_MAINTENANCE. If this property is not set (or an invalid file is given), the maintenance functionallity is disabled.

healthcheck.maintenancepropertyname
- The property name to be used in the maintenance file. This will also affect the error message returned when in maintenance mode (the part of the string after MAINT: (defaults to DOWN_FOR_MAINTENANCE).

Available tests and responses

  • No errors
    If all tests passed the HTTP result code is "200 OK" and page contains only the text "ALLOK".

  • Down for maintenance
    If the down for maintenance file indicates that the server is down for maintenance an HTTP response code in 5xx range is returned with an error page containing "MAINT: " followed of the name of the maintenance property as configured. No further checks are performed.

  • Database test
    A test is performed that SignServer is able to query the database. When running without database a check is made that the configured directory is initialized correctly and is not empty. If anything failed one or more error messages are included in an error page returned with the HTTP response code in the 5xx range.

  • Memory test
    Checks the available free memory. If anything failed an error message is included in an error page returned with the HTTP response code in the 5xx range.

  • Workers test
    Each (non-disabled) worker is checked for a number of things. If anything failed one or more error messages are included in an error page returned with the HTTP response code in the 5xx range.

    • Token offline: Workers having a crypto token can be reported as offline
    • Worker status and errors: Each worker implementation can put different requirements on when it is status is considered to be offline.
    • Signer certificate: Signers requiring a certificate are checked that they have a certificate matching the configured key-pair and that the certificate is valid according the certificate validity time and the configured minimum remaining validity time.
    • TimeStampSigner certificate missing EKU: If a TimeStampSigner certificate does not include the required EKU its status is set to offline.
    • TimeStampSigner certificate not included in certificate chain If a TimeStampSigner certificate chain property does not include the signer certificate its status is set to offline.
  • Disabled workers
    Workers that are disabled by having the worker property DISABLED=true are not considered in the Health check report.