*** APPSRV_HOME ***

Set APPSRV_HOME to point to your application server installation (/opt/jboss could be a symbolic link).

export APPSRV_HOME=/opt/jboss
                        

*** ANT_OPTS ***

Set ANT_OPTS to give Ant more memory for building SignServer.

export ANT_OPTS="-Xmx512m -XX:MaxPermSize=128m"
                        

*** SIGNSERVER_HOME ***

Set SIGNSERVER_HOME to point to your SignServer installation.

export SIGNSERVER_HOME=/opt/signserver
                        

*** SIGNSERVER_NODEID ***

Set SIGNSERVER_NODEID to an unique ID for the server.

export SIGNSERVER_NODEID=node1
                        

*** Fix web service problem in JBoss ***

Edit jboss-beans.xml to force the endpoint URL to be generated based on the WSDL request by commenting out the line:

    <property name="webServiceHost">${jboss.bind.address}</property>

For JBoss 5.1.0.GA the file is available under: server/default/deployers/jbossws.deployer/META-INF/

*** Fix JBoss 5 bug with Oracle JDK ***

If you are using Oracle's JDK and JBoss 5.1.x you need to copy SIGNSERVER_HOME/lib/ext/1.6/bc*.jar to JBOSS_HOME/server/default/lib/. Remember this when it's time for upgrades! This is a bug tracked by JBoss as JBAS-7882.

*** Application server configuration ***

Set appserver.type to the application server (jboss or glassfish).

appserver.type=jboss
                        

*** Web GUI configuration ***

Uncomment j2ee.web-nohttps=true if SignServer should be used to configure the keystore in JBoss.

#j2ee.web-nohttps=true
                        

For GlassFish change httpserver.privhttps to a port configured with HTTPS and client authentication.

httpserver.privhttps=8181
                        

*** Database configuration ***

For GlassFish make sure the datasource.jndi-name and datasource.jndi-name-prefix matches the resource configured in the admin console.

datasource.jndi-name=SignServerDS
datasource.jndi-name-prefix=jdbc/
                        

Select database management system

database.name=mysql
                        

For JBoss set the database connection URL, database driver and username and password.

database.url=jdbc:mysql://127.0.0.1:3306/signserver
database.driver=com.mysql.jdbc.Driver
database.username=signserver
database.password=signserver
                        

*** Web Service Configuration ***

Enable or disable the web services.

signserverws.enabled=true
genericws.enabled=true
validationws.enabled=true
adminws.enabled=true
clientws.enabled=true
                        

*** Modules Configuration ***

Enable all modules that should be built and choose if they should be included in the SignServer enterprise application archive (EAR). By setting includemodulesinbuild=true (default) all modules are built in. Otherwise for each module specify that it should be enabled and included:

module.xmlsigner.enabled=true
module.xmlsigner.include=true
...
                        

For GlassFish to enable debug logging include the Log4j module.

module.log4j.enabled=true
module.log4j.include=true
                        

*** Command Line Interface ***

bin/signserver getstatus brief all
Assuming JBoss JNDI provider...
===========================================
Executing Command on host : localhost
===========================================


Current version of server is : SignServer 3.3.0alpha0
                    

*** Graphical User Interface ***

bin/signserver-gui	
						

*** Web Interface ***

Point your web browser to http://localhost:8080/signserver for demo web pages and local documentation.

*** setproperties ***

The "setproperties" command loads all the properties from a property file that can define one or many signers. The code for the signers needs to be deployed to the application server together with SignServer either by setting includemodulesinbuild=true to include all modules or by setting individual module.MODULENAME.include=true properties in signserver_build.properties.

bin/signserver setproperties doc/sample-configs/CONFIGURATION.PROPERTIES
                        

*** Production configuration with HSM ***

To install a production signer using an HSM instead of the demo signer you can edit doc/sample-config/qs_mrtdsodsigner_configuration.properties and change from SoftCryptoToken to PKCS11CryptoToken and comment all properties under SoftCryptoToken properties and instead fill in all properties under PKCS11CryptoToken properties and then run:
(note after changing properties in the file it needs to be loaded again with setproperties)

Before starting with an HSM installation you should read the about the PKCS11CryptoToken in the plugins section of the manual.

bin/signserver setproperties doc/sample-config/qs_mrtdsodsigner_configuration.properties
bin/signserver getconfig 9
bin/signserver reload 9
bin/signserver generatecertreq 9 "C=SE,CN=MRTD SOD Signer" SHA256WithRSA mrtdsodsigner.req

Where 9 is the signerId that you got when running the 'setproperties' command.
This will create a certificate request that you can get signed by your CA. When you have received the response you can import it and the CA certficate. If you have the returned signer certificate as cert.pem and the CA certificate as cacert.pem, then:

cat cert.pem cacert.pem > certchain.pem
bin/signserver uploadsignercertificate 9 glob cert.pem
bin/signserver uploadsignercertificatechain 9 glob certchain.pem
bin/signserver reload 9

Hint: you can use EJBCA to create keys on a PKCS#11 HSM using clientToolBox.
ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/ETcpsdk/lib/linux-x86_64/libcryptoki.so 2048 DSSignKey 5

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

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

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.

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.

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 and issuer DN.

wsauditors -remove:

Removes an auditor from the list of authorized administrators.

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.

*** Verify Auditlog Command ***

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-02-08 21:26:13,067 INFO  [PKCS11CryptoToken] Activated Crypto Token with id 300.
2013-02-08 21:26:13,203 INFO  [VerifyLogCommand] Progress: node=0 rowCount=63
2013-02-08 21:26:13,685 INFO  [VerifyLogCommand] Progress: node=1 rowCount=701
2013-02-08 21:26:13,690 INFO  [VerifyLogCommand] Audit log validation completed in 1 seconds. 701 rows found. Errors: 0 Warnings: 0
2013-02-08 21:26:13,690 INFO  [VerifyLogCommand] Verification finished with success
                        

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

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

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

*** 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 and auditors and gives the ability to add, remove or edit them.

*** 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/qs_pdfsigner_configuration.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                    
                    

*** 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_build.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 (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.

*** Signing and validating an XML document ***

try {
    System.setProperty("javax.net.ssl.trustStore", "p12/truststore.jks");
    System.setProperty("javax.net.ssl.trustStorePassword", "changeit");
  
    ISigningAndValidation signserver = new SigningAndValidationWS("localhost", 8442, true);

    // Document to sign
    byte[] unsigned = "<document><name>Some content</name></document>".getBytes();
    byte[] signed;

    // Signing
    GenericSignResponse signResp = signserver.sign("DemoXMLSigner", unsigned);
    signed = signResp.getProcessedData();
    System.out.println("Signed: " + new String(signed));

    // Validating
    GenericValidationResponse validateResp = signserver.validate("DemoXMLValidator", signed);
    System.out.println("Valid: " + validateResp.isValid());

    if(validateResp.getSignerCertificate() != null) {
        if(validateResp.getSignerCertificate() instanceof X509Certificate) {
            X509Certificate signerCert = (X509Certificate) validateResp.getSignerCertificate();
            System.out.println("Signed by: " + signerCert.getSubjectDN().getName());
        }
    }
} catch (Exception ex) {
    ex.printStackTrace();
}                                   

*** Samples ***

• HTTP GET:
  http://localhost:8080/signserver/process?workerName=DemoXMLSigner&data=%3Croot%3Ehej2%3C/root%3E
  http://localhost:8080/signserver/process?workerName=DemoXMLSigner&encoding=base64&data=PGhlajI%2Bb2s8L2hlajI%2BCg%3D%3D
  
  
• HTTP POST with multipart/form-data or x-www-form-urlencoded:
  For example see /signserver/demo/xmlsign.jsp (multipart/form-data) and /signserver/demo/genericsign.jsp (x-www-form-urlencoded).
  
  
• HTTP POST with other content-type:
  See the TimeStampClient.
  
  

*** Samples ***

• HTTP GET:
  http://localhost:8080/signserver/worker/DemoXMLSigner?data=%3Croot%3Ehej2%3C/root%3E
  http://localhost:8080/signserver/worker/DemoXMLSigner?encoding=base64&data=PGhlajI%2Bb2s8L2hlajI%2BCg%3D%3D
  
  

*** Samples ***

• See /signserver/demo/mrtdsodsign.jsp.
  
  

*** No authentication ***

AUTHTYPE = NOAUTH

Sets the server to not require any authentication.

*** Client certificate authentication ***

AUTHTYPE = CLIENTCERT

(default) requires a certificate of all the clients. The certificates must be in the application server's truststore. Authorized clients is configured manually using the CLI interface.

*** Username/password-based authentication ***

AUTHTYPE = org.signserver.server.UsernamePasswordAuthorizer

USER.[NAME] = [PASSWORD]
USER.[NAME] = [HASHED_PASSWORD]:[HASH_ALGORITHM]
USER.[NAME] = [HASHED_PASSWORD]:[HASH_ALGORITHM]:[SALT]

This authorizer requires a valid username and password. User accounts are configured by setting properties of the form shown above, where [NAME] is the username and [PASSWORD] is the clear-text password. In the second form [HASHED_PASSWORD] should be replaced with the output of the digest algorithm specified in [HASH_ALGORITHM]. The third form uses a hash value that is appended to the password before hashing it.

If a valid username and password is not supplied the worker throws an AuthorizationRequiredException which in case of the HTTP interfaces causes a HTTP Basic Authentication (RFC 2617).

*** Username-based authentication ***

AUTHTYPE = org.signserver.server.UsernameAuthorizer

Form 1: ACCEPT_ALL_USERNAMES = false (default) and usernames are specified:
ACCEPT_ALL_USERNAMES = false
ACCEPT_USERNAMES = user1;user2;user3

Form 2, ACCEPT_ALL_USERNAMES = true and no usernames are specified:
ACCEPT_ALL_USERNAMES = true

An Authorizer that can be used for instance if SignServer sits behind an Apache front-end which uses HTTP basic authentication. With this Authorizer the username is logged but the password is not checked as it is assumed to be checked by the front-end.

The Authorizer can be configured to either accept all usernames or only accept those usernames listed in one of its properties.

*** Remote address authentication ***

AUTHTYPE = org.signserver.server.RemoteAddressAuthorizer

ALLOW_FROM = Comma separated list of IP addresses to allow requests from. By default all other addresses are denied access.

If a worker is invoked directly using an EJB call and no REMOTE_IP is specified in the RequestContext the IP-address is set to the String "null". In that case, to allow requests using EJB calls, null can be added to the list of allowed addresses.

Note: When adding "null" to ALLOW_FROM not only locally running clients like the ClientCLI and AdminGUI is allowed access but also from workers that invoke the other worker directly using an EJB call. This is for instance the case for the XMLValidator which delegates the validation of the certificate to a CertValidator. If the CertValidator had a RemoteAddressAuthorizer allowing access from "null" then the XMLValidator would be able to use it. To restrict users from using the CertValidator (indirectly through the XMLValidator) an Autorizer could be configured for the XMLValidator.

Logging: This authorizer will add the remote IP address to the log field AUTHORIZED_ADDRESS.

*** List-based Address Authorizer ***

AUTHTYPE = org.signserver.server.ListBasedAddressAuthorizer

An authorizer that supports white- and blacklisting direct and forwarded addresses (coming via a proxy).

WHITELISTED_DIRECT_ADDRESSES = A comma-separated list of IP addresses allowed direct access.

BLACKLISTED_DIRECT_ADDRESSES = A comma-separated list of IP addresses denied direct access.

WHITELISTED_FORWARDED_ADDRESSES = A comma-separated list of IP addresses allowed access as a forwarded address.

BLACKLISTED_FORWARDED_ADDRESSES = A comma-separated list of IP addresses denied access as a forwarded address.

It is not possible to specify both a whitelist and a black list at the same time for each of direct and forwarded addresses. One of each list (direct and forwarded) must be specified. When specifying a whitelist for forwarded addresses, requests without an X-Forwarded-For header will always be denied. Only the last address in the X-Forwarded-For header is considered (in the case of using multiple proxies).

Examples:

1. To accept requests from all direct addresses except for 10.0.0.5 and for all forwarded addresses except 13.170.18.12 and 13.170.18.13 use:
BLACKLISTED_DIRECT_ADDRESSES=10.0.0.5
BLACKLISTED_FORWARDED_ADDRESSES=13.170.18.12, 13.170.18.13

2. To only accept direct requests from 10.0.0.1 and 10.0.0.2 and from the forwarded address 216.34.181.97 use:
WHITELISTED_DIRECT_ADDRESSES=10.0.0.1, 10.0.0.2
WHITELISTED_FORWARDED_ADDRESS=216.34.181.97

3. To only allow direct access from the proxy servers 10.0.0.1 and 10.0.0.2 but allow them to forward from all address except the to banned addresses 13.170.18.12 and 13.170.18.13 use:
WHITELISTED_DIRECT_ADDRESSES=10.0.0.1, 10.0.0.2
BLACKLISTED_FORWARDED_ADDRESSES=13.170.18.12, 13.170.18.13

4. To accept direct requests from all addresses except 10.0.0.5 but only forwarded from 216.34.181.97 use:
BLACKLISTED_DIRECT_ADDRESSES=10.0.0.5
WHITELISTED_FORWARDED_ADDRESS=216.34.181.97

Logging: This authorizer will add the remote IP address to the log field AUTHORIZED_ADDRESS and the proxied address (if it's available in the request) in the log field AUTHORIZED_FORWARDED_ADDRESS.

*** DispatchedAuthorizer ***

AUTHTYPE = org.signserver.server.DispatchedAuthorizer

AUTHORIZEALLDISPATCHERS = True, if any Dispatcher should be authorized. (Default: true, currently only true is supported)

Only accepts requests that has gone through a Dispatcher. This Authorizer only checks the present of the DISPATCHER_AUTHORIZED_CLIENT field in the request context to know that the request has passed a Dispatcher.

*** Custom ***

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.

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

*** Available Properties ***

The following properties can be configured with the signer:

TIMESOURCE = property containing the fully qualified name of the class implementing the ITimeSource that should be used (OPTIONAL). Below are the built-in TimeSourceS available:

SIGNATUREALGORITHM = property specifying the algorithm used to sign the timestamp (default: SHA1withRSA)

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. Only false is supported.

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

REQUIREVALIDCHAIN = Set to true to perform an extra check that the SIGNERCERTCHAIN only contains certificates in the chain of the signer certificate. (OPTIONAL), default false.

MAXSERIALNUMBERLENGTH = The maximum size (in bytes) used when generating serial numbers, must be between 8 and 20 (64 - 160 bits) (Default: 8) The generated serial number will always be positive (so the sign bit is always a zero).

WORKERLOGGER = As for other workers this property can be used to specify which worker logger to use. By default the DefaultTimeStampLogger is used.

INCLUDESTATUSSTRING = Specifies if the status string is to be included in the response. Setting this to true triggers a bug in some versions of OpenJDK's jarsigner utility. (OPTIONAL), default true.

*** TimeStampSigner Certificates ***

Specifying a signer certificate is required as information from that certificate will be used to indicate which signer signed the time-stamp token.

The signer certificate chain contains all certificates included in the token if the client requests the certificates. The signer certificate MUST be included in the configured certificate chain. Other certificates might also be included in the chain (typically intermediate CA certificates). However, if REQUIREVALIDCHAIN=true is specified only the signer certificate directly followed by its issuer and then the issuer's issuer and so on is allowed. All certificates will be verified if there is a certificate coming after it. No check is made that the last certificate is a root certificate as that certificate is usually not included.

*** Overview ***

This time stamp signer is compatible with the Microsoft Authenticode time-stamping code signing.

*** Available Properties ***

TIMESOURCE = property containing the fully qualified name of the class implementing the ITimeSource that should be used (OPTIONAL). This property has the same values as for TimeStampSigner above.

SIGNATUREALGORITHM = property specifying the algorithm used to sign the timestamp (default: SHA1withRSA)

*** Howto ***

There is a howto about testing Authenticode signing available in doc/howtos/test_ms_authcode.txt

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

*** Available Properties ***

No configuration properties exists.

*** Overview ***

The main purpose of the PDF signer is to add digital signatures to PDF documents.

The signer supports the addition of visible or invisible signatures. Both visible and invisible signatures serve the same purpose of signing document, and technically are equivalent in that sense. The difference is that when visible signature is applied to a document, signature image (in shape of rectangle) is placed at the specified place in the document, clicking on which will allow seeing properties of the signature (Adobe Acrobat Reader). On the other hand when invisible signature is applied, signature properties are accessed through menu items. For visible signatures properties such as : custom signature image, signature rectangle, page at which signature rectangle to be drawn and others can be specified (see Available Properties below)

PDF Signer can also apply timestamp to a signature. If the signature is timestamped, it can be viewable through signature properties in Adobe Acrobat Reader. Timestamping is used to prove that document was signed before the time specified by timestamp token. If the signature is not timestamped then the signature time specified in the signature properties is not considered to be trusted. It is strongly advised to apply timestamp to a signature, and the TSA module can be used for this purpose.

Also CRL or OCSP Response of the signer's certificate can be embedded inside the signature package. Embedding CRL or OCSP response with the package will help validate signature even after the signer's certificate is expired. (Though it will not totally guarantee the long term signature preservation. Topic of long term signature preservation for archival purposes is a large one and is discussed to be implemented in future versions of SignServer).

The PDF Signer can also be configured to enforce that certain PDF permissions are not available in the signed document and/or that certain permissions should be removed.

*** PDF passwords ***

PDF documents can optionally be protected by a password.

There are two different types of passwords:

• User password:
  Also sometimes referred to as "open password" or "document password". It can be used for reading an encrypted document.
• Owner password:
  Also sometimes referred to as "permission password" or "security restriction password". It can be used for reading an encrypted document and making changes to a document that has permissions.

*** PDFSigner Requests ***

PDF signing requests can be served using either web services or the web server interface (HTTP). See Integration for general information about the different interfaces.

For the web server interface the GenericProcessServlet can be used. The PDFSigner supports the extra request field "pdfPassword" letting the client supply a PDF password to be used for opening the PDF for signing (not required unless the PDF is already password protected).

For the old web services interface the request should contain an encoded GenericProcessesRequest and the response will be an GenericProcessResponse. It is possible to supply a PDF password by including it in the requestMetaData with the key "pdfPassword".

*** Worker Properties ***

The following properties can be configured with the signer:

*** Overview ***

ODF Signer, which stands for Open Document Format Signer is a plug-in to SignServer that applies server side signature to documents in ODF format. It has been tested with OpenOffice.org 3.1.

ODF Signer supports only "invisible" signatures, that is unlike PDF signer there's no pictorial representation of the digital signature. When you open signed document in OpenOffice.org you can verify signature using toolbars, or the notifier in status bar (red mark), which notifies user that the document is digitally signed.

*** Available Properties ***

Other than standard worker properties, ODF Signer does not have any other custom ODF signer specific properties.

*** Overview ***

The XML Signer creates enveloped XML signatures using XMLDSig.

The signed XML document can be validated using the XML Validator.

*** Available Properties ***

This signer has no extra properties above the standard worker properties.

*** Overview ***

OOXML Signer, which stands for Office Open XML Signer is a plug-in to SignServer that applies server side signature to documents in OOXML format. It has been tested with MS Office 2007.

Currently OOXML Signer supports only "invisible" signatures , that is unlike PDF signer there's no pictorial representation of the digital signature. When you open signed document in MS Office you can verify signature using toolbars, or the notifier in status bar (red mark), which notifies user that the document is digitally signed.

*** Available Properties ***

Other than standard worker properties, OOXML Signer does not have any other custom OOXML signer specific properties.

NOTE : In later versions of OOXML Signer it is planned to add support for visible signatures and custom signature image.

*** Overview ***

The CMS signer can sign arbitrary data and produces a CMS (RFC 3852) SignedData structure in binary format.

Currently the signed content is always embedded as well as the signer certificate.

*** Overview ***

The XML validator validates the signature of XML documents. The certificate is checked by the configured certificate validation service.

*** Available Properties ***

VALIDATIONSERVICEWORKER = Name or id of validation service worker for handling certificate validation

RETURNDOCUMENT = True if the response should contain the validated document

STRIPSIGNATURE = True if the signature should be removed from the document if it is returned

*** Overview ***

Dispatches the request to the first of the configured workers that has an active cryptotoken. This dispatcher can be useful if you want to have one worker to call that forwards the request to any of the configured workers that has a valid certificate etc.

*** Available Properties ***

WORKERS = Comma separated list of workerNameS to try to forward requests to.

*** Overview ***

Dispatches the Time-stamp request to an other signer based on the requested TSA Policy according to an configured mapping table. This dispatcher can be useful if you want to have multiple signers (Time Stamp Units) signing with different TSA policies but don't want the client to have to call different workers.

See also the DispatchedAuthorizer which if configured by a signer can allow all requests that has gone through a Dispatcher.

*** Available Properties ***

DEFAULTWORKER = Worker name or ID to dispatch to in case no policy was requested.

USEDEFAULTIFMISMATCH = If true dispatches to DEFAULTWORKER in case no mapping existed for the requested policy OID (default: false)

MAPPINGS = Mapping from requested policy OID to a worker name.
The property is of the form:
POLICYOID1:WORKERNAMEORID1; POLICYOID2:WORKERNAMEORID2; POLICYOID3:WORKERNAMEORID3;

INCLUDESTATUSSTRING = Specifies if the status string is to be included in the response. This setting only affects the behavior when USEDEFAULTIFMISMATCH is false, and there is no mapping for the requested policy. In case there is a mapping (or no mapping and USEDEFAULTIFMISMATCH is true, the state of INCLUDESTATUSSTRING of the used signer is used to determine if the status string is included. Setting this to true triggers a bug in some versions of OpenJDK's jarsigner utility. (OPTIONAL), default true.

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

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

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

*** 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)

*** Overview ***

The SignerStatusReportTimedService is a timed service that outputs status for a set of workers to a file. The information includes each workers crypto token status ACTIVE/OFFLINE and if available also the numbers of signatures that has been performed with the key currently associated with the worker. If the worker has a configured limit of number of signatures, this value is also included. See also the SignerStatusReportWorker which is an alternative way of offering this reports.

Format:

workerName=WORKERNAME1, status=STATUS1, KEY3=VALUE3, KEY4=VALUE4, ...
workerName=WORKERNAME2, status=STATUS2, KEY3=VALUE3, KEY4=VALUE4, ...
workerName=WORKERNAME3, status=STATUS3, KEY3=VALUE3, KEY4=VALUE4, ...
...
                        

Rules:

• Each line contains a set of properties for one worker.
• Lines are separated by a system dependent newline character (CR, LF or CRLF).
• Properties are of form KEY=VALUE and are separated by a comma and a space (", ").
• The properties "workerName" and "status" are the only ones that must be present.
• The property "workerName" is always the first property.

Properties:

• workerName: name of the worker. Example: "sod71" or "sod72"
• status: status of the worker's crypto token and key. Either "ACTIVE" or "OFFLINE".
• validityNotBefore: the first date the signer is allowed to sign. Format is java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss z").
• validityNotAfter: the last date the signer is allowed to sign.
• signings: the number of signatures that has been performed with the key used by this worker.
• signLimit: the maximum number of signatures this worker is allowed to perfom or -1 if there is no limit.

Examples:

workerName=Sod71, status=ACTIVE, validityNotBefore=2010-07-05 17:32:36 CEST, validityNotAfter=2010-09-08 17:32:36 EEST, signings=132, signLimit=100000,
workerName=Sod72, status=OFFLINE, validityNotBefore=2010-07-05 17:32:33 CEST, validityNotAfter=2010-09-08 17:32:33 EEST, signings=100000, signLimit=100000,
workerName=Sod73, status=OFFLINE, validityNotBefore=2010-07-05 17:32:33 CEST, validityNotAfter=2010-09-08 17:32:33 EEST, signings=0, signLimit=100000,
workerName=Sod74, status=OFFLINE,
                        

Examples explained:

Sod71 has done 132 signings and is ACTIVE and validityNotAfter indicates that it can continue to sign until 8th September if not the sign limit is reached before

Sod72 has performed all of its 100000 signings and can not sign until it gets a new key and certificate.

Sod73 has not reached its limit and is still in validity time but is OFFLINE for some other reason.

Sod74 is OFFLINE and has no certificate configured.

*** Available Properties ***

WORKERS = Comma separated list of worker names (signers) that should be monitored.

OUTPUTFILE = File that the information will be written to. If the file exists the content will be overwritten. The application server needs to have write access to this file when the service is executed.

*** Overview ***

The RenewalWorker can be used for generation a new key-pair and renewing a worker's certificate from EJBCA using web services (WS). The RenewalWorker should be configured with its own CryptoToken and an SSL client authentication certificate with permissions set up in EJBCA to issue certificates. Some properties are configured for the RenewalWorker such as the EJBCA WS endpoint URL and truststore details, other properties should be set on the worker that should be renewed (the renewee) and some arguments are provided when the worker is invoked.

Known limitation: It might not be possible to have multiple renewal workers using different crypto tokens because the keys and certificates used by the TLS connection for the web service is setup globally.

Fully qualified class name: org.signserver.module.renewal.worker.RenewalWorker

*** Requesting the worker ***

After setting up an RenewalWorker and installing its certificate signers (and other workers), can easily be renewed using the SignServer AdminGUI. See Renew Signer dialog. As the RenewalWorker is a worker it can also be invoked using the normal client APIs. Using the demo web pages: Generic Signing Demo:

Sign by Direct Input
Worker name: MyRenewalWorker
Data:

WORKER=MySigner
AUTHCODE=foo123

Using the Client CLI:

bin/client.sh signdocument -workername MyRenewalWorker -data "WORKER=MySigner
AUTHCODE=foo123"

(Notice that the command is on two lines)

*** RenewalWorker operations ***

The RenewalWorker starts by generating a new key-pair (unless an NEXTCERTSIGNKEY is already set for the renewee or the request property FORDEFAULTKEY=true is set in the request). The HSM/keystore password needs to be submitted as part of the request (AUTHCODE request property) to generate a new key-pair. After the key-pair has been generated and tested successfully the key alias is set as the NEXTCERTSIGNKEY property. A certificate signing request is created for the key and the worker sends the request to EJBCA to issue a certificate for the configured end entity. After receiving the certificate and certificate chain they are installed for the worker and the DEFAULTKEY property is updated with the value from NEXTCERTSIGNKEY and that property is removed.

*** Worker Properties ***

EJBCAWSURL = URL to the EJBCA. Example: https://ca-server:8443/ejbca

TRUSTSTOREPATH = Path to the keystore containing the CA's SSL server certificate as a trusted entry.

TRUSTSTORETYPE = Type of keystore. JKS and PEM is supported.

TRUSTSTOREPASSWORD = Password protecting the truststore keystore.

*** Properties of renewee ***

RENEWENDENTITY = Name of the existing end entity in EJBCA

REQUESTDN = Subject DN to set in the certificate signing request (PKCS#10).

SIGNATUREALGORITHM = Signature algorithm to use when signing the certificate signing request (PKCS#10)

KEYALG = Algorithm for the key generation. Examples: RSA, DSA or ECDSA

KEYSPEC = Key length (for RSA or DSA) or curve name (for ECDSA). Examples: 2048, 4096, secp256r1

EXPLICITECC = True if explicit domain parameters should be used instead of NamedCurves. Default: false

RENEWWORKER = Name of the default RenewalWorker to use (Optional). Specify this to have the current RenewalWorker already selected in the AdminGUI when renewing signers.

DEFAULTKEY = Key alias for the current existing key. The worker will update this property.

NEXTCERTSIGNKEY = Key alias for the next existing key. If this property exists a new key-pair will not be generated. The worker will update/remove this property.

*** Request Properties ***

WORKER = Name of the worker that should be renewed.

AUTHCODE = HSM/keystore password for activation.

FORDEFAULTKEY = If the current key should be used instead of the next key or a new key. (Optional, default: false)

*** Response Properties ***

RESULT = "OK" if the renewal succeeded otherwise "FAILURE".

MESSAGE = Error message if any.

*** Renewal modes ***

*** Overview ***

The StatusPropertiesWorker can be used to query and setting status properties in the status repository.

*** Worker Properties ***

(none)

*** Request Properties ***

GET - Comma-separated list of status properties to query

x.VALUE - Where x is a status property: Sets the value of the property

x.EXPIRATION - Where x is a status property: Sets the expiration time for x (x.VALUE must also be specified)

If no property is specified all valid status properties are returned

*** Response Properties ***

x.VALUE = See Request Properties

x.EXPIRATION = See Request Properties

*** Overview ***

The SignerStatusReportWorker is a worker that returns a status report for a configured set of workers. The information includes each workers crypto token status ACTIVE/OFFLINE and if available also the numbers of signatures that has been performed with the key currently associated with the worker. If the worker has a configured limit of number of signatures, this value is also included. This worker returns the report in the same format as defined for the SignerStatusReportTimedService.

*** Worker Properties ***

WORKERS = Comma separated list of worker names (signers) that should be monitored.

*** Overview ***

A CryptoToken using a PKCS#12 (.p12/.pfx) key-store in the local file-system.

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

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

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.JKSCryptoToken

*** Available Properties ***

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

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

DEFAULTKEY: The key to use. If not specified the first found key is used. (optional)

*** Overview ***

A CryptoToken using a Java Key Store (.jks) in the file-system.

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

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

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.P12CryptoToken

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

DEFAULTKEY: The key to use. If not specified the first found key is used. (optional)

NEXTCERTSIGNKEY: The next key to use. See PKCS11CryptoToken. (optional)

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

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.PrimeCardHSMCryptoToken

*** Available Properties ***

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

NEXTCERTSIGNKEY: The next key to use. See PKCS11CryptoToken. (optional)

AUTHCODE = Authentication code for automatic activation (Optional).

*** Overview ***

Using PKCS11 it's possible to use a HSM that has a PKCS11 module, such as Utimaco, nCipher, SafeNet or AEP KeyPer. SignServer uses the same underlying implementation of PKCS11 crypto tokens as EJBCA. To find out more about supported devices and get information how to configure them you can visit the HSM documentation at EJBCA.org. The only thing that differs are the token labels strings, which you should use from below for SignServer. A very useful tool from EJBCA is the ClientToolBox. If you can generate anbd test PKCS11 keys using the clientToolBox, you can use them with SignServer.

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.PKCS11CryptoToken

*** Available Properties ***

DEFAULTKEY = The key alias. (Required)

NEXTCERTSIGNKEY = The next key to use. This property can be used to hold the name of the next key to use. Certificate signing requests (CSR) can be made for this key can while to the current key (DEFAULTKEY) is still in production. After uploading the new certificate the value of NEXTCERTSIGNKEY can be moved to DEFAULTKEY. (optional)

PIN = Authentication code for activation. (Only required for auth-activation, otherwise the activatecryptotoken CLI command can be used)

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

SLOT or SLOTLISTINDEX = Slot number or the index of the slot to use. (Required and only one of them can be used.)

ATTRIBUTESFILE = Path to file with PKCS#11 attributes used for key generation.

Sample p11attributes.cfg working with SafeNet Luna:

attributes(generate,*,*) = {
  CKA_TOKEN = true
}
attributes(generate,CKO_PUBLIC_KEY,*) = {
  CKA_ENCRYPT = true
  CKA_VERIFY = true
  CKA_WRAP = true
}
attributes(generate, CKO_PRIVATE_KEY,*) = {
  CKA_EXTRACTABLE = false
  CKA_DECRYPT = true
  CKA_SIGN = true
  CKA_UNWRAP = true
}
                        

*** 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 setproperties qs_pdfsigner_configuration.properties

Generate a keypair for the signer: bin/signserver generatekey 8 -alias defaultKey -keyalg RSA -keyspec 2048

Test the keypair: bin/signserver testkey 8

You also need a certificate for the signer. Generate a certificate request with the command: bin/signserver 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 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.

*** Overview ***

The SoftCryptoToken is a simple token managing it's own soft keys instead of using a PKCS12 file. 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.

There is also a tool available for constructing the properties from a PKCS12 file in CryptoTokenUtils.java. To run the tool outside the IDE first build SignServer by running "ant". After that the tool can be executed with something similar to:

java -cp lib/signserver-ejb.jar:lib/ext/1.6/bcprov-jdk.jar:lib/SignServer-Common.jar:lib/ext/ejbca-util.jar org.signserver.server.cryptotokens.CryptoTokenUtils createsoft src/test/dss10/dss10_signer1.p12 "signer 1" foo123
                        

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.SoftCryptoToken

*** 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")

*** 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 generatecertreq <id> "CN=Soft Signer token" SHA1WithRSA /tmp/certreq.pem
                        

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

bin/signserver 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.

*** Worker Properties ***

ARCHIVERx.ARCHIVE_OF_TYPE = Where "x" is the index of the Archiver in the ARCHIVERS property. Determines what this Archiver should archive. Alternatives are: "REQUEST", "RESPONSE" or "REQUEST_AND_RESPONSE". Default is "RESPONSE".
Example: ARCHIVER0.ARCHIVE_OF_TYPE=REQUEST_AND_RESPONSE

Currently archiving of requests is only supported by TimeStampSigner and MSAuthCodeTimeStampSigner.

ARCHIVERx.USE_FORWARDED_ADDRESS = Where "x" is the index of the Archiver in the ARCHIVERS property. If this property is set to "true", the last IP address in the comma-separated list given in the X-Forwarded-For header is used as the remote IP stored in the archive in case this header is set. If the header is not included, the IP address the request comes from is used (the same behavior as when this property isn't set, or set to "false"). This is useful when running a proxy in front of SignServer, to record the orginal IP address of the client, instead of the proxy's IP address. Defaults to "false".

*** ArchiveData table ***

The exact database table structure is described in the SQL scripts available under doc/sql-scripts/.

*** Worker Properties ***

ARCHIVERx.ARCHIVE_OF_TYPE = Same as for OldDatabaseArchiver above.

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

*** 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. INTERVALMS defining the interval in milliseconds of how often the service should be run. CRON used instead of INTERVAL or INTERVALMS 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.

*** IValidationService Interface ***

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;
                        

*** 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();
                        

*** 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);
}
                        

*** 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;


}
                        

*** System tests with HSM ***

To run system tests with an HSM create an properties file in SIGNSERVER_HOME called test-config.properties containing the PKCS#11 configuration including the key alias for an existing RSA key-pair:

test.p11.sharedlibrary=/opt/ETcpsdk/lib/linux-x86_64/libcryptoki.so
test.p11.slot=1
test.p11.pin=foo123
test.p11.existingkey1=mykey001
                        

The tests can be run with:

ant test:p11:run test:report
                        

*** Building and running ***

Build from modules/SignServer-Test-Random/ using:

ant jar

It can then be run from SIGNSERVER_HOME using:

bin/randomtest

*** Usage ***

usage: randomtest <options>
Random testing tool
 -randomseed <arg>     Optional. Seed to initialize the pseudo random
                       generator with.
 -testsuite <arg>      Test suite to run. Any of [signWhileUpdatingConfig,
                       signAndCountSignings, signWhileRenewing].
 -threadgroup1 <arg>   Number of threads in group 1.
 -threadgroup2 <arg>   Number of threads in group 2.
 -timelimit <arg>      Optional. Only run for the specified time (in
                       milliseconds).
 -workergroup1 <arg>   First group of workers. Comma separated list of
                       workerId/workerType.
 -workergroup2 <arg>   Second group of workers. Comma separated list of
                       workerId/workerType
 -workergroup3 <arg>   Third group of workers. Comma separated list of
                       workerId/workerType

Sample usages:
a) randomtest -testsuite signWhileUpdatingConfig -workergroup1
5678/xml,5679/tsa,5680/xml -threadgroup1 4 -workergroup2
5677/xml,5678/xml,5679/tsa -threadgroup2 3 -timelimit 30000

b) randomtest -testsuite signAndCountSignings -workergroup1
5678/xml,5679/tsa,5680/xml -threadgroup1 10 -timelimit 30000

c) randomtest -testsuite signWhileRenewing -workergroup1 300/xml
-workergroup2 301/xml,302/xml -threadgroup1 5 -workergroup3 309/renew
-timelimit 20000

Available worker types:
- workerType can be any of [xml, tsa, renew]

Test suite: signAndCountSignings
- Signs documents with the workers from group 1 with the number of threads
defined for group 1
- Pauses signings and counts performed signings a compares to the key
usage counter value
- Notice that it is assumed that all workers use the same key-pair

Test suite: signWhileUpdatingConfig
- Signs documents with the workers from group 1 with the number of threads
defined for group 1
- Increases a counter in the configuration of group 2
- Notice that the size of thread group 2 must be equal to the number of
workers in group 2

Test suite: signWhileRenewing
- Signs documents with the workers from group 1 with the number of threads
defined for group 1
- Renews signers from group 2 using the one renewal worker in group 3
- Notice that group 3 should only include one renewal worker
                        

*** Building and running ***

Build from modules/SignServer-Test-Performance/ using:

ant jar

It can then be run from SIGNSERVER_HOME using:

bin/stresstest

*** Usage ***

usage: stresstest <options>
Performance testing tool
 -maxwaittime <arg>     Maximum number of milliseconds for a thread to
                        wait until issuing the next time stamp.
                        Default=100
 -statoutputdir <arg>   Optional. Directory to output statistics to. If
                        set, each threads creates a file in this directory
                        to output its response times to. The directory
                        must exist.
 -testsuite<arg>       Test suite to run. Any of [TimeStamp1].
 -threads <arg>         Number of threads requesting time stamps.
 -timelimit <arg>       Optional. Only run for the specified time (in
                        milliseconds).
 -tsaurl <arg>          URL to timestamp worker to use.
 -warmuptime <arg>      Don't count number of signings and response times
                        until after this time (in milliseconds). Default=0
                        (no warmup time).

Sample usages:
a) stresstest -testsuite TimeStamp1 -threads 4 -tsaurl
http://localhost:8080/signserver/tsa?workerId=1
b) stresstest -testsuite TimeStamp1 -threads 4 -maxwaittime 100
-statoutputdir ./statistics/ -tsaurl
http://localhost:8080/signserver/tsa?workerId=1
              			

When finished (after time limit expires, or process is stopped using control+c) a statistic overview is printed containing number of signings, and statistics (average, minimum, and maximum) for response times.

*** AllFieldsWorkerLogger ***

The default worker logger for most workers. Can be used during testing to find which fields a worker logs and then changed to the PatternWorkerLogger with only does fields that are of interest chosen.
LOGLEVEL_DEFAULT sets the level at which the logger will do log output. These are specified as standard Log4J levels (FATAL, ERROR, WARNING, INFO, DEBUG, and TRACE), if not set, it defaults to INFO.

WORKERLOGGER=org.signserver.server.log.AllFieldsWorkerLogger
LOGLEVEL_DEFAULT=INFO
                        

*** SecurityEventsWorkerLogger ***

Worker logger using the CESeCore security events logger. This logger included all fields in the additionalDetails fields in the audit log, except the worker ID, which is mapped to searchDetail2.

The properties LOGINCLUDEFIELDS and LOGEXCLUDEFIELDS can be used to restrict the fields included in additionalDetails by explicitly setting a comma-separated list of field names. Only one of these options can be set at a time.

WORKERLOGGER=org.signserver.server.log.SecurityEventsWorkerLogger
                        

*** PatternWorkerLogger ***

The LOGLEVEL_DEFAULT property has the same behavior as for the AllFieldsWorkerLogger.

WORKERLOGGER=org.signserver.server.log.PatternWorkerLogger
LOGTIMEZONE=GMT
LOGDATEFORMAT=yyyy-MM-dd:HH:mm:ss:z
LOGPATTERN=\$\{(.+?)\}
LOGORDER=AUDIT; LOG_ID: ${LOG_ID}; CLIENT_IP: ${CLIENT_IP}; REQUEST_FULLURL: ${REQUEST_FULLURL}; RequestTime: ${LOG_TIME}; ResponseTime: ${REPLY_TIME}; EXCEPTION: ${EXCEPTION};
LOGLEVEL_DEFAULT=INFO
                        

*** DefaultTimeStampLogger ***

Pattern logger with a default log order suitable for logging time-stamp requests. This logger is the default logger used by the TimeStampSigner.

WORKERLOGGER=org.signserver.module.tsa.DefaultTimeStampLogger
                        

*** NullWorkerLogger ***

Worker logger that does not log anything.

WORKERLOGGER=org.signserver.server.log.NullWorkerLogger                            
                        

*** CustomTimeStampLogger1 ***

WORKERLOGGER=org.signserver.module.tsa.CustomTimeStampLogger1
                        

*** FileWorkerLogger ***

Worker logger that writes the log values to a worker-specific log file (the logger logs all fields, similar to AllFieldsWorkerLogger.
This logger is mainly intended for use by unit tests, and is not thread safe.

WORKERLOGGER=org.signserver.server.log.FileWorkerLogger
LOG_FILE_PATH=/path/to/logfile
						

*** Available log events ***

EVENT: SIGNSERVER_STARTUP; MODULE: SERVICE; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; VERSION: SignServer 3.3.0alpha12; REPLY_TIME:1350562045545

EVENT: SIGNSERVER_SHUTDOWN; MODULE: SERVICE; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; VERSION: SignServer 3.3.0alpha12; REPLY_TIME:1350562045545

EVENT: SET_GLOBAL_PROPERTY; MODULE: GLOBAL_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; GLOBALCONFIG_VALUE: TESTVALUE47; GLOBALCONFIG_PROPERTY: GLOB.TESTPROPERTY47; REPLY_TIME:1350657202153

EVENT: REMOVE_GLOBAL_PROPERTY; MODULE: GLOBAL_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; GLOBALCONFIG_PROPERTY: GLOB.TESTPROPERTY47; REPLY_TIME:1350657202444

EVENT: GLOBAL_CONFIG_RELOAD; MODULE: GLOBAL_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; REPLY_TIME:1350657202593

EVENT: GLOBAL_CONFIG_RESYNC; MODULE: GLOBAL_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; REPLY_TIME:1350894343902

EVENT: SET_WORKER_CONFIG; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; added:FOO: bar; REPLY_TIME:1350657202773

EVENT: SET_WORKER_CONFIG; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; changed:FOO: newvalue; REPLY_TIME:1350657202873

EVENT: SET_WORKER_CONFIG; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; removed:FOO: newvalue; REPLY_TIME:1350657202873

EVENT: SET_WORKER_CONFIG; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; added:FOO: bar; changed:BAR: newvalue; REPLY_TIME:1350657202873

EVENT: SET_WORKER_CONFIG; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; added:authorized_client: SN: 1234567890, issuer DN: CN=Test; REPLY_TIME:1350657202873

EVENT: CERTINSTALLED; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; CERTIFICATE: Subject: CN=Anyone
Issuer: CN=Anyone
-----BEGIN CERTIFICATE-----
MIIBnTCCAQagAwIBAgIIWWNYSOeuN+swDQYJKoZIhvcNAQEFBQAwETEPMA0GA1UE
AwwGQW55b25lMB4XDTEyMTAxOTE0MzMyM1oXDTEzMTAxOTE0MzMyM1owETEPMA0G
A1UEAwwGQW55b25lMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCDE9GElbJd
e74WmIpPSsIF9r5vv0oH6WWo7n31goR1zMIHJPC9V1mpwQZ6C0uCHCV2ZvqQIIAE
ZQM7mgbPfxjCF74RqKzScZlOSaHnvdf7zCWpYraVrIDt9Wg3HMxye0/L3cCImmkY
FkFtabtoa5UuPZObdIt154Yg+GpGB8aPBwIDAQABMA0GCSqGSIb3DQEBBQUAA4GB
AHm3oAUHwM0KwMcEUwWouE0f4+UK6ZvYvxLAgiCVZQnPImcqX1oBl+iFV59FlsXj
rqoQYJROxIeV0ByGeyBYXqvgTw1YtdqoR+wKmiymjn/lynmTh1fQMcFoUouGfubX
EK4rfPBXEl33gKbsO5aeMHd5iF2jtx7RfYMsOuHKoDSe
-----END CERTIFICATE-----
; SCOPE: GLOBAL; REPLY_TIME:1350657204367

EVENT: CERTCHAININSTALLED; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; CERTIFICATECHAIN: Subject: CN=Signer,C=SE
Issuer: CN=Issuer,C=SE
-----BEGIN CERTIFICATE-----
MIIBdjCCASCgAwIBAgIIE+fXOs/SAwMwDQYJKoZIhvcNAQEFBQAwHjEPMA0GA1UE
AwwGSXNzdWVyMQswCQYDVQQGEwJTRTAeFw0xMjEwMjIwNzQ1MDZaFw0xMzEwMjIw
NzQ1MDZaMB4xDzANBgNVBAMMBlNpZ25lcjELMAkGA1UEBhMCU0UwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBAKpX5psdaL5CHAKSxoOvB12Ie8iUb/mX6ikF8jfu
zrbwVgf6bX0RCUnD+v+t9vY7byz+nN32KnmGluNGdBFdM1Ug9Oc+64ZNBbgZi9mi
cHnKMDLLSECBY2Nux62PZejp5SwtzpjFymt3TMCtRr4UHGu3zkuqLLCHFlGRdvdo
MPQ9AgMBAAEwDQYJKoZIhvcNAQEFBQADQQADlInGm9AujZfL+1kM7ehaKyKKencF
fp6YGElOpGEplxxIwgmVc0iYKv4rCkfUAysYL6l3AC+VLK1asxkpEJc1
-----END CERTIFICATE-----
Subject: CN=Issuer,C=SE
Issuer: CN=Issuer,C=SE
-----BEGIN CERTIFICATE-----
MIIBMTCB3KADAgECAggbfKZHs8ttKDANBgkqhkiG9w0BAQUFADAeMQ8wDQYDVQQD
DAZJc3N1ZXIxCzAJBgNVBAYTAlNFMB4XDTEyMTAyMjA3NDUwNloXDTEzMTAyMjA3
NDUwNlowHjEPMA0GA1UEAwwGSXNzdWVyMQswCQYDVQQGEwJTRTBcMA0GCSqGSIb3
DQEBAQUAA0sAMEgCQQCpgzxJ6r6D1cP8v1AB88pJsCwi0SJdeRSGYydYYBOafJk0
fpqxJCwaiFS3tt9OkWUAXzcixv5+sItkEuEOpmp7AgMBAAEwDQYJKoZIhvcNAQEF
BQADQQCC5NG3eWx/mXXKZmePOvZEIwyqWHOwzsBB174gkzlyhOdiOr3YwVihyebI
VAfkEktRrO04Hi5eLR+AxW7EVz6l
-----END CERTIFICATE-----
; SCOPE: GLOBAL; REPLY_TIME:1350891906417

EVENT: KEYSELECTED; MODULE: WORKER_CONFIG; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 100; KEYALIAS: ts_key00002; SCOPE: GLOBAL; REPLY_TIME:1350891907048

EVENT: KEYGEN; MODULE: KEY_MANAGEMENT; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 5676; KEYALIAS: ts_key00004; KEYSPEC: 2048; KEYALG: RSA; REPLY_TIME:135089190791

EVENT: KEYTEST; MODULE: KEY_MANAGEMENT; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 47; KEYALIAS: all; TESTRESULTS: KeyTestResult{alias=tsu47_key00005, success=true, status=, publicKeyHash=979359e5261112b11fac341962bec1e7e6052d9e}
KeyTestResult{alias=key5, success=true, status=, publicKeyHash=46b264e4892ef2e4fd9616e4927534ca3597fd9c}
KeyTestResult{alias=key3, success=true, status=, publicKeyHash=ae64792f1f50e23eb54bf79d46d819bc07db2d79}
KeyTestResult{alias=key2, success=true, status=, publicKeyHash=b1317f363e6124a8e15bba8c1adb9f20b2f4ef59}
KeyTestResult{alias=TS Signer 1, success=true, status=, publicKeyHash=8f6dfccdcea931d4deee9466f43c0eb0e7f4d8b1}
; REPLY_TIME:1350564289165

EVENT: GENCSR; MODULE: KEY_MANAGEMENT; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: 5676; CSR: MIIBYDCBygIBADAjMRQwEgYDVQQDDAtUUyBTaWduZXIgMTELMAkGA1UEBhMCU0Uw
gZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJt8F51wD+QcX+WLyIxjWu3at3q+
IiJrL5jIenmggUhjOLHGHOStoNOiYEQAaiiTZ623m9y7O3zhqFdAdWZg+JrfsHQJ
pjKV9RgvJznl6yk/K54BWOBgqjvbloAUGtn8y8Hf+5DYJUJNFqrzvRLcmCQ9JU0H
mgSmEIqgOIwBL3oBAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAer5hr/cUYx4jy0XO
N4U8sP/2gSFppytx9dn5BamVBLjDkcML8B3c9u9omDPebd+LEsCU+HCmYN9xHkSS
Ei8lcAqyVv+SDLEmvE8gnrPFR/J7uADCRayLVQumW6/YpVO/sFEGuM6rgnn8ZJmW
X2lhvJ4V1UhlkEAeyIQ861U3IgE=; REPLY_TIME:1350891907981

EVENT: SET_STATUS_PROPERTY; MODULE: STATUS_REPOSITORY; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; STATUSREPO_EXPIRATION: 1350891909366; STATUSREPO_PROPERTY: TEST_PROPERTY1; STATUSREPO_VALUE: TESTVALUE47; REPLY_TIME:1350891908372

EVENT: PROCESS; MODULE: WORKER; ADMINISTRATOR: null; ISSUER: null; SERIAL_NUMBER: null; WORKER_ID: null; LOG_ID: db517726-ff0d-40dd-8f2b-2297925cb4d3; CLIENT_IP: 127.0.0.1; PROCESS_SUCCESS: false; REQUEST_LENGTH: 0; XFORWARDEDFOR: null; FILENAME: noname.dat; 
REQUEST_FULLURL: http://localhost:8080/signserver/process?null; LOG_TIME: 1350628977410; WORKER_ID: 0; EXCEPTION: No such worker: 0; REPLY_TIME:1350628977411

*** Signed log ***

To enable signed audit logs configure conf/databaseprotection.properties (see conf/databaseprotection.properties.sample). And set the following which enables signing of the AuditRecordData table as well as verification of the log entries queried using for instance the CLI or GUI:

databaseprotection.enablesign.AuditRecordData = true
databaseprotection.enableverify.AuditRecordData = true
                        

Configure a key-pair to use for signing and verification of the log with something similar to this:

databaseprotection.keyid = 400
databaseprotection.keyid.0 = 400
databaseprotection.keylabel.0 = dbProtKey
databaseprotection.classname.0 = org.cesecore.keys.token.PKCS11CryptoToken
databaseprotection.properties.0 = sharedLibrary=/opt/utimaco/Software/PKCS11/lib/Linux-x86-64/libcs2_pkcs11.so, slot=1
databaseprotection.data.0 =
databaseprotection.tokenpin.0 = userpin1
databaseprotection.version.0 = 2
                        

Note: each SignServer node writing to the audit log needs to use different node IDs. By default the hostname is used. If multiple instances are running from the same host set the node id manually in conf/cesecore.properties as cluster.nodeid.

If enableverify is set to true, all individual log entries that are displayed using CLI, GUI or over web services are verified at the server side and in case of inconsistent signatures an error message is displayed. This verification will not discover missing log entries. To verify the complete log for all nodes as well as detect gaps in the sequence numbering, run the Database CLI.

*** AuditRecordData table ***

The exact database table structure is described in the SQL scripts available under doc/sql-scripts/.

1359550503607

C=SE, O=My Organization, CN=Admin 1

CLI User

StartServicesServlet.init

Client User

4a3442e98e3ce428

C=SE, O=My Organization, CN=AdminCA1

71

dsstsa1.example.com

<?xml version="1.0" encoding="UTF-8"?>
<java version="1.6.0_24" class="java.beans.XMLDecoder">
 <object class="org.cesecore.util.Base64PutHashMap">
  <void method="put">
   <string>GLOBALCONFIG_PROPERTY</string>
   <string>GLOB.WORKER1.CLASSPATH</string>
  </void>
  <void method="put">
   <string>GLOBALCONFIG_VALUE</string>
   <string>org.signserver.module.xmlsigner.XMLSigner</string>
  </void>
 </object>
</java>
                                    

1:2:400:079b6c2d89671702077b1802ff221cd7c6d71804ea3771b7d5f7cd1...