Plugins

Configuring a plug-in

A worker component is configured by entering its class path (and optionally its crypto token class path) in a memory bank called the global configuration and then issuing the reload command. There exists sample configurations for most of the plug-ins in the 'doc/sample-configs' directory.

SignServer Signers

There exists multiple signers. One is the time stamp signer generating RFC 3161 compliant timestamps using the Bouncycastle library. An MRTD signer creating "Machine Reader Travel Document" signatures using the RSA algorithm from pre-padded data and another is the MRTD SOD Signer which creates the complete Security Object (SOd) by signing the datagroups for the passport. There are also signers for automatically signing of specific document-types such as PDF, XML, ODF and OOXML and there is a general purpose signer that can sign any document-type and produces the output in Cryptographic Message Syntax (CMS).

Common Properties

Properties that have common use among most signers:

INCLUDE_CERTIFICATE_LEVELS = Number of certificate levels to include. This property is supported for all signers except MRTDSODSigner, MRTDSigner, and MSAuthCodeTimeStampSigner. The property is optional and defaults to include all certificates in the chain, except for XAdESSigner, where the default is to only include one certificate (the signing certificate). Setting this to 0 (include no certificates) is not supported for TimeStampSigner. To include all certificates specify at least the same value as number of certificates in the certificate chain.

REQUESTDN = Subject DN to be included in a certificate signing request (CSR) by default. Used by interfaces such as the Admin GUI to have a default value already filled in.

Time-stamp Signer

The time-stamp signer has the class name: org.signserver.server.signers.TimeStampSigner

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:

org.signserver.server.LocalComputerTimeSource
This is the default TimeSource and uses the time from the local computer and always returns the time.
org.signserver.server.StatusReadingLocalComputerTimeSource

This TimeSource returns the time from the local computer but only if the status property TIMESOURCE0_INSYNC is not expired and returned as true from the Status Repository.

Worker properties:

  • LEAPSECOND_HANDLING: NONE, PAUSE or STOP. Default is NONE.

    NONE: Leap seconds are not considered and time-stamp tokens are issued as usual.

    PAUSE: The TimeSource will query the status property LEAPSECOND from the Status Repository. If this property is not expired, and has the value POSITIVE or NEGATIVE and current time is in the interval surrounding a potential leap second (23:59:58,989 - 00:00:01,010) (at month shifts, in UTC time), the TimeSource will make a pause to ensure the time value is not fetch on the leap second. The value NONE is interpreted as there is no leap second and the time value will be returned immediately as usual. If the value has expired, no valid time will be returned.

    STOP The TimeSource will query the status property in the same way as for the PAUSE strategy. During the interval surrounding a potential leap second no time will be returned. This will cause the response to the clients to be timeSourceNotAvailable. If the LEAPSECOND status property value has expired, no valid time will be returned.

This time source will add an additional worker status item indicating the currently used leap second strategy.

The following additional log fields will be included for a logger implementation to use:

  • LEAP_UPCOMING This field will have the value true if a leap second is known to be coming soon, false if there is no leap second known to be coming, or unknown if it was unable to read the status.

    LEAP_PERIOD This field will be included when LEAP_UPCOMING is true and has the value true or false depending on whether the request was made during the time interval surrounding a leap second.

    LEAP_ACTION This field will include the value of the currently used leap second strategy.

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. Note that only policies listed in this property are allowed to be requested. If the property does not contain any policies then no policy can be requested. Requests not including any policy would use the default policy regardless of this property but requests explicitly requesting the default policy would still not be allowed unless it is listed in this property. If this property is used, ACCEPTANYPOLICY can not be set to true. (OPTIONAL, Recommended)

ACCEPTANYPOLICY = If set to true, allow any policy. If set to true, ACCEPTEDPOLICIES can not be set. Optionally this can be set to false or left empty when setting ACCEPTEDPOLICIES.

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.

INCLUDEORDERING = If set to true, always include the ordering attribute, even when ORDERING is set to false. It is not allowed to set this to false when ORDERING is set to true. (OPTIONAL), default false.

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

TSA_FROM_CERT = Setting this property to true sets the general name of the Time Stamp Authority to the subject DN of the signing certificate. This can not be set to true if the TSA property is set. (OPTIONAL) (the default is to not set the general name)

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.

INCLUDESIGNINGTIMEATTRIBUTE = Specifies if the signingTime signed CMS attribute should be included in the response. (OPTIONAL), default true.

CERTIFICATE_DIGEST_ALGORITHM = Specifies the digest algorithm used for calculating the digest of the signing certificate.
Supported values:

  • SHA1

  • SHA224

  • SHA256

  • SHA384

  • SHA512


When using an algorithm other than SHA1, RFC 5816-compliant time stamps will be issued.
To get the old behaviour (with the ESSCertID attribute instead of ESSCertIDv2), SHA1 must be set explicitly.
Default: SHA256.

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.

MS Authenticode Time Stamp Signer

The class name is: org.signserver.server.signers.tsa.MSAuthCodeTimeStampSigner

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)

INCLUDE_SIGNING_CERTIFICATE_ATTRIBUTE = Specifies if the signing certificate attribute (id-aa-signingCertificate) [RFC2634] should be included in the response (OPTIONAL, default: false).

Howto

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

Extended Time Stamp Signer

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

The extended time stamp signer has the class name: org.signserver.module.tsa.ExtendedTimeStampSigner

Overview

The extended time stamp signer, in addition to all features provided by the regular time stamp signer, also supports including the qualified time stamp extension, as required by EU regulation 910/2014 specification.

Available Properties

INCLUDE_QC_EXTENSION = Set this to true to enable including the qualified time stamping extension (default: false)

MRTD Signer

The MRTD signer has the class name: org.signserver.module.mrtdsigner.MRTDSigner

Overview

The MRTD Signer performs a RSA signing operation on incoming data. The data should already be padded. This signer could be used to sign 'Machine Readable Travel Documents' i.e. electronic passports.

Available Properties

No configuration properties exists.

MRTD SOD Signer

The MRTD SOD signer has the class name: org.signserver.module.mrtdsodsigner.MRTDSODSigner

Overview

The MRTD SOD Signer creates the complete security object (SOd) for a MRTD (Machine Readable Travel Document, i.e. electronic passports, residence permit etc) by signing the provided data groups (DGs).

Note 1: The Document Signer (DS) certificate is included in the SOd.
Note 2: The SOd is verified (including certificate path) before it is returned so the certificate chain must contain the Country Signing CA (CSCA) certificate.
Note 3: See also the integration guide for SODProcessServlet or the ClientWS interface.

Available Properties

DODATAGROUPHASHING = True if this signer first should hash the DG values. Otherwise the values are assumed to be hashes already. (Optional, default is false)
DIGESTALGORITHM = Message digest algorithm that is applied or should be applied to the values. (Optional, default is SHA256)
SIGNATUREALGORITHM = Signature algorithm for signing the SO(d). (Optional, default is SHA256withRSA all though SHA256withRSAandMGF1 is recommended by Doc9303)
LDSVERSION = Version of Logical Data Structure (LDS). For LDS version 1.7 enter "0107" and for version 1.8 "0108". (Optional, default is 0107)
UNICODEVERSION = Version of Unicode used in the datagroups. Required if LDS 1.8 is used. Example: "040000" for Unicode version 4.0.0.

PDF Signer

The PDF signer has the class name: org.signserver.module.PDFSigner

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.

If a document is protected by an owner password it has to be supplied with the request for SignServer to sign the document. If the document is protected by a user password, either the user password or the owner password has to be supplied with the request for SignServer to sign the document.

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:

REASON

The reason included in the PDF signature and displayed by the PDF reader.

Default: "Signed by SignServer".

LOCATION

The location included in the PDF signature and displayed by the PDF reader.

Default: "SignServer".

ADD_VISIBLE_SIGNATURE

Setting that control whether signature to be added should be visible or invisible.

Possible values: True or False.

Default: "False"

VISIBLE_SIGNATURE_PAGE

Specifies the page on which the visible signature will be drawn. This property is ignored if ADD_VISIBLE_SIGNATURE is set to False.

Possible values:
"First" : signature drawn on first page of the document,
"Last" : signature drawn on last page of the document,
page_number : signature is drawn on a page specified by numeric argument. If specified page number exceeds page count of the document ,signature is drawn on last page. If page_number specified is not numeric (or negative number) the signature will be drawn on first page

Default: "First".

VISIBLE_SIGNATURE_RECTANGLE

Specifies the rectangle signature is going to be drawn in.

This property is ignored if ADD_VISIBLE_SIGNATURE is set to False. Format is : (llx,lly,urx,ury).
Here :
llx =left lower x coordinate,
lly=left lower y coordinate,
urx =upper right x coordinate,
ury = upper right y coordinate

Default: "400,700,500,800".

VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 & VISIBLE_SIGNATURE_CUSTOM_IMAGE_PATH

If we want the visible signature to contain custom image, specify image as base64 encoded byte array. Alternatively custom image can be specified by giving a path to image on file system.

Note: if specifying a path to an image "\" should be escaped (thus C:\photo.jpg => "C:\\photo.jpg")

Note: if specifying image as base64 encoded byte array "=" should be escaped (this "BBCXMI==" => "BBCXMI\=\=")

If both of these properties are set then VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 will take priority.

If we do not want this feature then do not set these properties.

Default: not set (no custom image).

These properties are ignored if ADD_VISIBLE_SIGNATURE is set to False.

NOTE: in clustered environment it is more manageable and advised to specify image as base64 string, since image data will be stored in central database. Otherwise each node should contain copy of the image, and each image managed separately (e.g. on image updates, or insertion of new image for different worker)

VISIBLE_SIGNATURE_CUSTOM_IMAGE_SCALE_TO_RECTANGLE

If we want our custom image to be resized to specified rectangle (set by VISIBLE_SIGNATURE_RECTANGLE) then set to True. If set to True image might look different that original (as an effect of resizing). If set to False the rectangle drawn will be resized to specified image's sizes.

If set to False llx and lly coordinates specified by VISIBLE_SIGNATURE_RECTANGLE property will be used for drawing rectangle (urx and ury will be calculated from specified image's size).

This property is ignored if ADD_VISIBLE_SIGNATURE is set to False or if custom image to use is not specified.

Possible values: True, False.

Default: "True".

CERTIFICATION_LEVEL

Set this property to have the document certified with a certifying signature.

Possible values:
NOT_CERTIFIED: The document is not certified.
FORM_FILLING: The document is certified but the form can be filled in without invalidating the signature.
FORM_FILLING_AND_ANNOTATIONS: The document is certified but the form can be filled in and annotations added without invalidating the signature.
NO_CHANGES_ALLOWED: The document is certified and no changes can be made.

Default: "NOT_CERTIFIED".

TSA_URL

If we want to timestamp document signature, specify timestamp authority URL.

This will cause time stamp requests to be issued via HTTP requests. Under high load this can lead to thread deadlocks in the application server if using a localhost URL (using a time stamp signer running in the same server). In this case, use the internal mechanism described below).

If we do not want to timestamp document signature, do not set property.

Note: if path contains characters "\" or "=" , these characters should be escaped (thus "\" = "\\", "=" =>"\=")

Note: this property can not be set at the same time as TSA_WORKER (see below).

Default: not set (no timestamping).

TSA_WORKER

Specify a worker ID or worker name for a time stamp signer

This will use internal calls and can only be used for a time stamp authority running in the same SignServer instance.

Note: use this option instead of TSA_URL when using a time stamp signer running in the same SignServer instance to avoid thread deadlocks under high load.

Note: this property can not be set at the same time as TSA_URL (see above).

Default: not set (no timestamping).

TSA_USERNAME & TSA_PASSWORD

If the TSA requires authentication for timestamping, specify username and password. If the TSA does not require authentication, do not set these properties. These properties are ignored if TSA_URL is not set (no timestamping).

Default: not set (tsa does not require authentication).

EMBED_CRL If we want to embed the CRL for signer certificate inside the signature package set to True, otherwise set to False.

Default: "False".

EMBED_OCSP_RESPONSE

If we want to embed the OCSP response for the signer certificate inside the signature package set to True, otherwise set to False.

Note: issuer certificate (of signing certificate) should be in certificate chain.

Note: OCSP responses must contain a nextUpdate field in order for off-line validation to work with Adobe Reader. For EJBCA OCSP Responder see configuration of ocsp.untilNextUpdate in ocsp.properties.

Default: "False".

ARCHIVETODISK

If we want the produced signed document to be stored in the local file system set this property to true and add the ARCHIVETODISK_PATH_BASE property explained below.

Default: "False".

ARCHIVETODISK_PATH_BASE

The file path to the folder to store the signed documents in.

Required if ARCHIVETODISK is True.

ARCHIVETODISK_PATH_PATTERN

Pattern used for creating sub-folders under the ARCHIVETODISK_PATH_BASE folder.

Current date can be put in by adding ${DATE:yyyy} where yyyy can be replaced be the same syntax as defined in the class java.text.SimpleDateFormat. Other fields are:

  • ${WORKERID}
  • ${WORKERNAME}
  • ${REMOTEIP}
  • ${REQUESTID}
  • ${TRANSACTIONID}
  • ${USERNAME}

Default: "${DATE:yyyy/MM/dd}".

ARCHIVETODISK_FILENAME_PATTERN

Pattern used for creating the filename. The same fields and syntax as for the ARCHIVETODISK_PATH_PATTERN property can be used.

Default: "${WORKERID}-${REQUESTID}-${DATE:HHmmssSSS}.pdf".

REFUSE_DOUBLE_INDIRECT_OBJECTS

True if PDF documents containing multiple indirect objects with the same name should be refused. Used to mitigate a collision signature vulnerability described in http://pdfsig-collision.florz.de/.

REJECT_PERMISSIONS

Reject signing of the document if any of the permissions in the comma separated list would be in the document.

Available permissions (from the PDF reference, version 1.6, page 99, TABLE 3.20):

ALLOW_PRINTING Print the document to a representation from which a faithful digital copy of the PDF content could be generated. When this is not set (and ALLOW_DEGRADED_PRINTING is set), printing is limited to a low-level representation of the appearance, possibly of degraded quality.
ALLOW_MODIFY_CONTENTS Modify the contents of the document by operations other than those controlled by ALLOW_MODIFY_ANNOTATIONS, ALLOW_FILL_IN, and ALLOW_SCREENREADERS.
ALLOW_COPY Copy or otherwise extract text and graphics from the document, including extracting text and graphics (in support of accessibility to users with disabilities or for other purposes).
ALLOW_MODIFY_ANNOTATIONS Add or modify text annotations, fill in interactive form fields, and, if ALLOW_MODIFY_CONTENTS is also set, create or modify interactive form fields (including signature fields).
ALLOW_FILL_IN Fill in existing interactive form fields (including signature fields), even if ALLOW_MODIFY_ANNOTATIONS is not set.
ALLOW_SCREENREADERS Extract text and graphics (in support of accessibility to users with disabilities or for other purposes).
ALLOW_ASSEMBLY Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if ALLOW_MODIFY_CONTENTS is not set.
ALLOW_DEGRADED_PRINTING Print the document (possibly not at the high-est quality level, depending on whether ALLOW_PRINTING is also set).

Default: unset/empty (no permissions are rejected)

SET_PERMISSIONS

Replace the current permissions (if any) with the permissions specified in this comma separated list of permissions.

Available permissions: The same permission names as for the property REJECT_PERMISSIONS.

This property can not be specified if REMOVE_PERMISSIONS is used.

Notice 1: This property and the REMOVE_PERMISSIONS property only sets the permissions setting in the document. All permissions might not be enforced by the PDF reader and some permissions even though specified by this property to be allowed might not be allowed when opening the final document (i.e. if that would invalidate the signature and/or certification).

Notice 2: If the document is not already protected by an owner password and the SET_OWNERPASSWORD is not specified a random password will be used as owner password.

Default: unset (permissions are not set by this property)

REMOVE_PERMISSIONS

Remove all permissions specified in this comma separated list from the document.

Available permissions: The same permission names as for the property REJECT_PERMISSIONS.

This property can not be specified if SET_PERMISSIONS is used.

Notice: This property only removes the permissions listed even if some permissions (i.e. ALLOW_PRINTING) by the standard gives more permissions (i.e. also ALLOW_DEGRADED_PRINTING). To remove all permissions to print remove both ALLOW_PRINTING and ALLOW_DEGRADED_PRINTING. To still have ALLOW_DEGRADED_PRINTING it is possible to specify to only remove ALLOW_PRINTING.

See also Notice 1 and Notice 2 for REMOVE_PERMISSIONS which also applies to this setting.

Removing only ALLOW_DEGRADED_PRINTING has no effect as degraded printing is implicitly allowed if printing is allowed.

Default: unset/empty (no permissions are removed)

SET_OWNERPASSWORD

Sets the specified password as owner password in the document.

The same permissions as before will be used (unless other properties will change them). The same encryption algorithm as the original document will be used. If the original document did not use any encryption then the default encryption algorithm will be used.

Default: unset (if the permissions are changed, the existing owner password will be used or if no such password is used in the document a semi-random password will be created)

DIGESTALGORITHM

Sets the hash algorithm used for the message digest and signature hash.

Setting this property will also imply a minimum PDF version depending on the hash used. The resulting PDF will be upgraded to this version if it's higher than the version used in the original PDF. Since upgrading the version requires re-creating the file (i.e. not appending the new signature) this is not supported on already signed document (i.e. using a hash algorithm requiring a higher version than the original document). Attempting to sign such a document will result in a failure.

Supported hash algorithms.

Algorithm PDF version
SHA1 1.3
SHA256 1.6
SHA384 1.7
SHA512 1.7
RIPEMD160 1.7

Default SHA1.

ODF Signer

Fully qualified class name: org.signserver.module.odfsigner.ODFSigner

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.

XML Signer

Fully qualified class name: org.signserver.module.xmlsigner.XMLSigner

Overview

The XML Signer creates enveloped XML signatures using XMLDSig.

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

Available Properties

SIGNATUREALGORITHM = property specifying the algorithm used to sign the data (default: depending on the signer's private key: SHA1withDSA for DSA keys, SHA1withRSA for RSA keys, and SHA1withECDSA for ECDSA keys.)

Supported Signature Algorithms

  • SHA1withDSA
  • SHA1withRSA
  • SHA256withRSA
  • SHA384withRSA
  • SHA512withRSA
  • SHA1withECDSA
  • SHA256withECDSA
  • SHA384withECDSA
  • SHA512withECDSA

XAdES Signer

Fully qualified class name: org.signserver.module.xades.signer.XAdESSigner

Overview

The XAdES Signer creates XML signatures according to the specified profile of XAdES.

Available Properties

XADESFORM = Which profile of XAdES to use. Currently BES and T is supported. Default: BES
COMMITMENT_TYPES = List of commitment types to be indicated in the signature. Multiple values can be given separated by ",". See list below for valid values. Optionally the constant NONE can be used to explicitly state that no commitment types should be included (this constant can only be used alone). Optional. Default: no commitment types are included.
SIGNATUREALGORITHM = The algorithm used to sign the data. The same set of algorithms as for the same property in XMLSigner is supported. Optional. Default: depending on the signer's private key: SHA1withDSA for DSA keys, SHA256withRSA for RSA keys, and SHA1withECDSA for EC keys.
CLAIMED_ROLE = Claimed role to include in the signature. If the CLAIMED_ROLE_FROM_USERNAME property is also set, this value is used as a fallback when there is no user name provided in the request. Optional. Default: no default claimed role defined.
CLAIMED_ROLE_FROM_USERNAME = If this is set to true, use the user name from the request (provided by an authorizer) as the value for claimed role. If there is no user name provided fall back to the value set by CLAIMED_USER. If this is set to true and CLAIMED_ROLE is not set and the request doesn't contain a user name, the request will result in an error. Optional. Default: false.
INCLUDE_CERTIFICATE_LEVELS = Number of certificate levels to include in the document's KeyInfo (also see the common properties above). Minimum and default value is 1 which includes only the signer certificate. The value 2 includes the signer certificate and its issuer. To include all certificates specify at least the same value as number of certificates in the certificate chain. TSA_URL = URL of timestamp authority. Required if XADESFORM=T and TSA_WORKER not specified.
Note: this property can not be set at the same time as TSA_WORKER (see below).
TSA_WORKER = Specify a worker ID or worker name for a time stamp signer. Required if XADESFORM=T and TSA_URL not specified.
This will use internal calls and can only be used for a time stamp authority running in the same SignServer instance.
Note: Use this option instead of TSA_URL when using a time stamp signer running in the same SignServer instance to avoid thread deadlocks under high load.
Note: This property can not be set at the same time as TSA_URL (see above).
TSA_USERNAME = Login username used if the TSA uses HTTP Basic Auth.
TSA_PASSWORD = Login password used if the TSA uses HTTP Basic Auth.

Commitment Types

Value Description
NONE Don't include any commitment type. This can not be used in conjunction with the other constants below
PROOF_OF_APPROVAL Indicates that the signer has approved the content of the signed data object
PROOF_OF_CREATION Indicates that the signer has created the signed data object (but not necessarily approved, nor sent it)
PROOF_OF_DELIVERY Indicates that the TSP providing that indication has delivered a signed data object in a local store accessible to the recipient of the signed data object
PROOF_OF_ORIGIN Indicates that the signer recognizes to have created, approved and sent the signed data object
PROOF_OF_RECEIPT Indicates that signer recognizes to have received the content of the signed data object
PROOF_OF_SENDER Indicates that the entity providing that indication has sent the signed data object (but not necessarily created it)

OOXML Signer

Fully qualified class name: org.signserver.module.ooxmlsigner.OOXMLSigner

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.

CMS Signer

The CMS signer has the fully qualified class name: org.signserver.module.cmssigner.CMSSigner

Overview

The CMS signer can sign arbitrary data and produces a CMS (RFC 3852) SignedData structure in binary format with or without the content encapsulated.

Currently the signer certificate is always included.

Available Properties

SIGNATUREALGORITHM = property specifying the algorithm used to sign the data (default: depending on the signing key: SHA1withDSA for DSA keys, SHA1withECDSA for ECDSA keys, otherwise SHA1withRSA)

DETACHEDSIGNATURE = property specifying if a detached signature (a.k.a. "external signature") should be used. That is a signature where the content is not included/encapsulated. Default is false.

ALLOW_DETACHEDSIGNATURE_OVERRIDE = property specifying if the requestor can request an other value for DETACHEDIGSNATURE than what is configured. Default is false.
If set to true a request could include a metadata property with an other value for DETACHEDSIGNATURE.

MS Authenticode Signer

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

The signer has the fully qualified class name: org.signserver.module.msauthcode.signer.MSAuthCodeSigner

Overview

The signer signs portable executable files such as Windows executables and shared libraries (.exe, .dll and .ocx etc) according to the Windows Authenticode Portable Executable Signature Format. The signature can optionally include a timestamp response from a TSA using the Authenticode format.

Available Properties

PROGRAM_NAME = Program name to embed in the signature (Optional, default: none)

ALLOW_PROGRAM_NAME_OVERRIDE = If the requestor should be able to override the program name by supplying it as a request metadata property (Optional, default: false)

PROGRAM_URL = Program URL to embed in the signature (Optional, default: none)

ALLOW_PROGRAM_URL_OVERRIDE = If the requestor should be able to override the program URL by supplying it as a request metadata property (Optional, default: false)

SIGNATUREALGORITHM = Signature algorithm (Optional, default: depending on the signing key, SHA1withRSA, SHA1withDSA or SHA1withECDSA)

DIGESTALGORITHM = Algorithm for the digest of the binary (Optional, default: SHA-1)

TSA_WORKER = Worker ID or name of internal (authenticode) timestamp signer in the same SignServer (Optional, default: none). This property can not be combined with TSA_URL.

TSA_URL = URL of external (authenticode) timestamp authority (Optional, default: none). This property can not be combined with TSA_WORKER.

TSA_USERNAME = Login username used if the TSA uses HTTP Basic Auth (Optional, default: none).

TSA_PASSWORD = Login password used if the TSA uses HTTP Basic Auth (Required if TSA_USERNAME specified, default: none).

DO_LOGREQUEST_DIGEST = If a digest of the request should be computed and logged (Optional, default: true).

LOGREQUEST_DIGESTALGORITHM = Algorithm used to create the message digest (hash) of the request document to put in the log (default: SHA256).

DO_LOGRESPONSE_DIGEST = If a digest of the response should be computed and logged (Optional, default: true).

LOGRESPONSE_DIGESTALGORITHM = Algorithm used to create the message digest (hash) of the response document to put in the log (default: SHA256).

Request Properties

This worker can accept the following request metdata properties, given that they are configured to be allowed:

PROGRAM_NAME = Program name text to use instead of the configured one (if any). Specifying an empty value removes the configured program name. Without ALLOW_PROGRAM_NAME_OVERRIDE configured in the worker request including this request property will not be allowed.

PROGRAM_URL = Program URL to use instead of the configured one (if any). Specifying an empty value removes the configured program URL. Without ALLOW_PROGRAM_URL_OVERRIDE configured in the worker request including this request property will not be allowed.

Worker Log Fields

REQUEST_DIGEST = A message digest (hash) for the request document in hex encoding.

REQUEST_DIGEST_ALGORITHM = The name of the message digest (hash) algorithm used for the request digest in the log.

RESPONSE_DIGEST = A message digest (hash) for the response document in hex encoding.

RESPONSE_DIGEST_ALGORITHM = The name of the message digest (hash) algorithm used for the response digest in the log.

JArchive Signer

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

The signer has the fully qualified class name: org.signserver.module.jarchive.signer.JArchiveSigner

Overview

The signer signs Java Archives or ZIP files (.jar, .war, .ear, .apk and .zip etc) according to the JAR File Specification. The signature can optionally include a timestamp response from a TSA using the RFC#3161 format.

Available Properties

SIGNATUREALGORITHM = Algorithm for signing (Optional, default: "SHA256withRSA")

DIGESTALGORITHM = Algorithm for message digests (Optional, default: "SHA-256")

ZIPALIGN = True if the offset at which each file entry's data starts should be aligned to 4 bytes. (Optional, default: False)

KEEPSIGNATURE = True if existing signature files should be kept. If this is false no previous META-INF/*.SF,.RSA,.DS or .EC files are kept. (Optional, default: True)

REPLACESIGNATURE = True if an existing signature with the same name should be overwritten and not fail with an error. (Optional, default: True)

SIGNATURE_NAME_TYPE = What type of signature name to use. With the type VALUE, the name is taken from the SIGNATURE_NAME_VALUE property. With the type KEYALIAS, the name is taken from the key alias of the key used to sign the response after converting it according to the signature name rules (see the SIGNATURE_NAME_VALUE property). (Optional, default: KEYALIAS)

SIGNATURE_NAME_VALUE = The value for the signature name if the SIGNAURE_NAME_TYPE requires a value. With the type VALUE, the name is taken directly from this property but must follow the signature name rules:

  • Only characters from A-Z0-9_.-
  • Minimum 1 character
  • Maximum 8 characters

(Optional or required depending on SIGNATURE_NAME_TYPE)

TSA_WORKER = Worker ID or name of internal (RFC#3161) timestamp signer in the same SignServer (Optional, default: none). This property can not be combined with TSA_URL.

TSA_URL = URL of external (authenticode) timestamp authority (Optional, default: none). This property can not be combined with TSA_WORKER.

TSA_USERNAME = Login username used if the TSA uses HTTP Basic Auth (Optional, default: none).

TSA_PASSWORD = Login password used if the TSA uses HTTP Basic Auth (Required if TSA_USERNAME specified, default: none).

TSA_POLICYOID = Time-stamping policy OID to request from the TSA (Optional, default: none).

DO_LOGREQUEST_DIGEST = If a digest of the request should be computed and logged (Optional, default: true).

LOGREQUEST_DIGESTALGORITHM = Algorithm used to create the message digest (hash) of the request document to put in the log (default: SHA256).

DO_LOGRESPONSE_DIGEST = If a digest of the response should be computed and logged (Optional, default: true).

LOGRESPONSE_DIGESTALGORITHM = Algorithm used to create the message digest (hash) of the response document to put in the log (default: SHA256).

Worker Log Fields

REQUEST_DIGEST = A message digest (hash) for the request document in hex encoding.

REQUEST_DIGEST_ALGORITHM = The name of the message digest (hash) algorithm used for the request digest in the log.

RESPONSE_DIGEST = A message digest (hash) for the response document in hex encoding.

RESPONSE_DIGEST_ALGORITHM = The name of the message digest (hash) algorithm used for the response digest in the log.

Master List Signer

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

The Master List signer has the fully qualified class name: org.signserver.module.masterlist.signer.MasterListSigner

Overview

Produces a signed list of CSCA certificates according to the ICAO specification MRTD TR CSCA countersigning and Master List issuance, version 1.0.

As mandated by the specification, both the signer certificate and the CSCA certificates are included in the signature. The INCLUDE_CERTIFICATE_LEVELS property is thus not allowed.

Available Properties

SIGNATUREALGORITHM = property specifying the algorithm used to sign the data (default: depending on the signing key: SHA1withDSA for DSA keys, SHA1withECDSA for ECDSA keys, otherwise SHA1withRSA)

Plain Signer

The Plain signer has the fully qualified class name: org.signserver.module.cmssigner.PlainSigner

Overview

The Plain signer can sign arbitrary data and simply produces a signature in the format determined by the configured signature algorithm.

Available Properties

SIGNATUREALGORITHM = property specifying the algorithm used to sign the data (default: depending on the signing key: SHA1withDSA for DSA keys, SHA1withECDSA for ECDSA keys, otherwise SHA1withRSA)

LOGREQUEST_DIGESTALGORITHM = property specifying the algorithm used to create the message digest (hash) of the request document to put in the log (default: SHA256).

Worker Log Fields

REQUEST_DIGEST = A message digest (hash) for the request document in hex encoding.

REQUEST_DIGEST_ALGORITHM = The name of the message digest (hash) algorithm used for the request digest in the log.

RESPONSE_ENCODED = The response document (plain signature) in base64 encoding.

SignServer Document Validators

Document Validators checks the signature and the certificate(s) in documents.

XML Validator

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

XAdES Validator

Overview

The XAdES validator validates the signature of XAdES documents and validatates the certificate chain. The validator will also validate embedded timestamp tokens in XAdES form T-signed documents.

Available Properties

TRUSTANCHORS = Trusted certificates. In PEM format. When validating a XAdES form T-signed document, must include the trusted certificate for the time stamp authory as well. Required.

CERTIFICATES = Intermediate CA certificates that might be needed to build a trust path from the signer certificates to any of the trusted certifivcates. In PEM format.

REVOCATION_CHECKING = True if revocation checking should be performed. The intermediate CA certificates (if any) and the signer certificate needs to have an Authority Information Access URL to an online OCSP responder or an CRL Distribution Point from where a CRL can be downloaded. If both are available the OCSP responder will be consulted first and then the CRL if the reseponder were unavailable. Default: true

SignServer Dispatchers

Dispatchers are workers that forwards the request to other workers.

FirstActiveDispatcher

Fully qualified class name: org.signserver.server.dispatchers.FirstActiveDispatcher

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.

RequestedPolicyDispatcher

Fully qualified class name: org.signserver.module.tsa.RequestedPolicyDispatcher

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.

UserMappedDispatcher

Fully qualified class name: org.signserver.server.dispatchers.UserMappedDispatcher

Overview

Dispatches the request to a worker based on a mapping from username and workername.

Available Properties

USERNAME_MAPPING = Comma separated list of mappings from user name to worker name.
The property is of the form:
username1:workername1, username2:workername2

SignServer Validation Service Framework

The validation service framework is used to validate certificates from one or more issuers. It can be used to have one central point of performing revokation statuses to simplify the integration of external PKIs within an enterprise.

The validation service framework also provides a validation cache that can be used to increase performance for those cases an application does multiple lookups of the same certificate within a short period of time.

Out-of-the-Box there exists a DefaultValidationService that should satisfy most use cases but it's possible to develop a custom ValidationService if necessary. See the developer section for more details.

All Validation Services is configured by specifying the org.signserver.validationservice.server.ValidationServiceWorker in the global configuration, then is the actual ValidationService configured in the worker configuration setting the class path in the property TYPE (Not necessary for the DefaultValidationService).

The validation service framework is mostly used with X509v3 certificates but other kinds of certificates is supported as well by design.

Another concept in the Validation Service Framework is that the client also can ask the service to check the type of certificate that the certificate might be used for. A certificate type could be IDENTIFICATION or ELECTRONIC SIGNATURE.

DefaultValidationService

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 and/or Digital Signature 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 = Fully qualified class name of 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
WORKER1.IMPLEMENTATION_CLASS=org.signserver.validationservice .server.ValidationServiceWorker
#Uncomment and set class path to custom validation service, otherwise 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.....

Certificate Validators

CRLValidator

Class name: org.signserver.validationservice.server.CRLValidator

OCSPValidator

Class name: org.signserver.validationservice.server.OCSPValidator

OCSPCRLValidator

Class name: org.signserver.validationservice.server.OCSPCRLValidator

NoRevocationCheckingValidator

Class name: org.signserver.validationservice.server.NoRevocationCheckingValidator

Certificate Validator that validates the certificate chain but does not perform any revocation checking. This can be useful for demonstation purposes or when revocation checking should not be performed.

DummyValidator

Class name: org.signserver.validationservice.server.DummyValidator

Certificate Validator that only works for specific issuers and certificates and is only available for testing and demonstration purposes as no real certificate validation is performed. The keystores under res/test/dss10/ with certificates issued by "DSS Root CA 10" can for instance be used together with this validator.

The Validation CLI interface.

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

When compiling, make sure that setting validationclient.enabled is set to "true" in the build properties. The client is lib/SignServer-Client-ValidationCLI.jar.

Use the client with 'java -jar lib/SignServer-Client-ValidationCLI.jar <options>'.

Here is a list of available options:

-cert <cert-file> 			: Path to certificate file (DER or PEM) (Required).
-certpurposes <certpurposes>  	: A ',' separated string containing requested certificate purposes.
-der                           			: Certificate is in DER format.
-help                          			: Display this info
-hosts <hosts>                 		: A ',' separated string containing the hostnames of the validation service nodes. Ex 'host1.someorg.org,host2.someorg.org' (Required)
-pem                    	       		: Certificate is in PEM format (Default).
-port <port>                   		: Remote port of service (Default is 8080 or 8442 for SSL).
-service <service-name>        	: The name or ID of the validation service to process request. (Required)
-silent                        			: Don't produce any output, only return value.
-truststore <jks-file>         		: Path to JKS truststore containing trusted CA for SSL Server certificates.(for HTTPS connections)
-truststorepwd <password>      	: Password to unlock the truststore.


The following return values is used:

-2   : Error happened during execution
-1   : Bad arguments
0   : Certificate is valid
1   : Certificate is revoked
2   : Certificate is not yet valid
3   : Certificate have expired
4   : Certificate doesn't verify
5   : CA Certificate have been revoked
6   : CA Certificate is not yet valid
7   : CA Certificate have expired
8   : Certificate have no valid certificate purpose

Timed Services

A Timed Service (formerly called just service) is a task that is run on a timely basis, performing maintenance tasks like changing active key, or it could generate a report.

A Timed Service framework supports a couple basic properties that is used to calculate when and how a timed service should run. These properties are:

ACTIVE = "TRUE" if the service should be run, otherwise it is disabled.

SINGLETON = "TRUE" if the service only should be run on one of the nodes in the cluster at the time. If it's not set or set to FALSE is the service run simultaneously on all nodes in the cluster. If the node running a singleton service fails will another node sense this and start up the service.

INTERVAL = Property defining the interval in seconds the service should run.

INTERVALMS = Property defining the interval in milliseconds the service should run. Notice that the platform and application server might put a lower bound on the value. The lower limit for GlassFish is by default 7000 milliseconds but can be changed by editing minimum-delivery-interval-in-millis in domain.xml.

CRON = Property that should define a CRON expression of how often the service should run. It should conform to Unix CRON standard. (One and only one of INTERVAL, INTERVALMS or CRON is required)

WORK_LOG_TYPES = Property specifying a comma-separated list of log types that should be used for logging invocations of the service.
The following values can be used:

INFO_LOGGING Use Log4J info logging
SECURE_AUDITLOGGING Use CESeCore secure audit logging

By default, if this property is not set, INFO_LOGGING is used. It is possible to turn off logging by setting this property to an empty value. Errors during service invocations will always be logged at error level using Log4J. If the property contains SECURE_AUDITLOGGING, the error will additionally be logged to the audit log.

SignerStatusReportTimedService

Fully qualified class name: org.signserver.module.signerstatusreport.SignerStatusReportTimedService

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.

HSMKeepAliveTimedService

Fully qualified class name: org.signserver.server.timedservices.hsmkeepalive.HSMKeepAliveTimedService

Overview

The HSMKeepAliveTimedService is a timed service that can be used to periodically run the test key operation on selected crypto workers. This is intended as a measure to prevent HSM connections timing out. The service will use the key alias TESTKEY for the workers when set, otherwise it will fall back on DEFAULTKEY. Notice that the service will not fallback on DEFAULTKEY if TESTKEY is set, but didn't succeed when testing the key.

Available Properties

CRYPTOTOKENS = Comma-separated list of worker names or worker IDs of workers whos keys should be tested. This would typically be crypto workers i.e. corresponding to different slots in an HSM, but could also be regular workers with crypto tokens configured directly). This property is required, but can be set to an empty value if only audit logging is needed (see below).

NOTE: if secure audit logging is used and a separate crypto token is used for logging, the service logging described above using the WORK_LOG_TYPES property and the SECURE_AUDITLOGGING value can be used to write to the audit log at the same time as testing crypto worker keys, to keep the auditlog crypto token from timing-out.

RenewalTimedService

Note
The RenewalTimedService is an Enterprise Edition feature.

Fully qualified class name: org.signserver.module.renewal.service.RenewalTimedService

Overview

The RenewalTimedService is a timed service that can be used to periodically check the signing validity of workers and invoking the renewal worker if needed.

Setup

A typical setup with automatic renewal contains of at least 4 workers:

  1. The Crypto Worker:

    The worker holding the crypto token.

    Configured just as before but it is required to be a separate worker from the one that will be renewed in order for it to not get deactivated when the worker's configuration changes during the renewal.

  2. The renewee(s):

    One or more workers which should be automatically renewed.

    Each renewee needs the RENEWWORKER property and can have additional properties:

    • Required property RENEWWORKER: Points out which Renewal worker to use.
    • Optional property RENEW_FORDEFAULTKEY: If set to true the certificate request is sent for the current DEFAULTKEY and no key generation is performed. Default: false.
    • Optional property RENEW_MINREMAININGSIGNINGVALIDITY: The minimum signing validity that must remain for the worker without it to be up for renewal. This value is expressed as a number of days, hours, minutes and milliseconds on the form "*d *h *m *s *ms". Default: "0d".
  3. The Renewal worker:

    The worker performing the renewal.

    See the RenewalWorker for its configuration.

  4. The Renewal Timed service:

    The worker which runs periodically and checks if a worker needs renewal.

    Needs a property listing each worker to check and renew if needed.

Available Properties

WORKERS = Comma-separated list of workers to check the validity time for and request renewal for if needed.

Execution

  • As all timed services the Renewal Timed Service is executed periodically.
  • The service checks the configurations and certificates for all the configured workers and creates a list with renewal statuses for each worker.
  • Then each worker in the list that is configured correctly and is up for renewal is renewed by sending a request for it to the Renewal worker.

A note about crypto token activation:

The workers that should be renewed most have their crypto tokens previously activated. Only activated workers configured with a certificate will be scheduled for renewal. This means that the worker needs to be renewed manually the first time to get its initial key and certificate. For the renewal service to work automatically the worker that is going to be renewad must use a separate worker (i.e. a CryptoWorker) for its crypto token. If the worker would have its own crypto token configuration the token would be deactivated during the renewal process.

Troubleshooting

The list of renewal statuses can be seen by looking at the services' complete status information:

$ bin/signserver getstatus complete RenewalTimedService1
...
Workers Renewal Prognose:
    - TimeStampSigner (102): Renewal after: 2016-03-02 16:14:07,000, with key generation, using renewal worker "RenewalWorker1".
    - CMSSigner (3): Renewal after: 2016-02-22 16:01:00,000 (on next run), without key generation, using renewal worker "RenewalWorker1".

What we can see from the above example:

  • The service is configured to manage two workers and their names and worker ID are displayed.
  • Both workers have certificates configured and was active so the service will be able to determine after which date they need to be renewed.
  • For the CMSSigner the renewal date has already passed and this is indicated by the text "on next run" showing that the renewal will take place as soon as the service runs.
  • We can assume that the CMSSigner is configured with the worker property "RENEW_FORDEFAULTKEY=true" as the status says "without key generation".
  • Finally we can see that both workers are configured with "RENEWWORKER=RenewalWorker1".

Installing a service

To install a service you use the same commands as for installing a worker:

$ bin/signserver setproperties configuration.properties

Example:

$ bin/signserver setproperties doc/sample-configs/signerstatusreport.properties
===========================================
  Executing Command on host : localhost
===========================================
Configuring properties as defined in the file : doc/sample-configs/signerstatusreport.properties
Setting the property ACTIVE to TRUE for worker 2
Setting the property INTERVAL to 10 for worker 2
Setting the global property WORKER2.CLASSPATH to org.signserver.server.timedservices.SignerStatusReportTimedService with scope GLOB.
Setting the property WORKERS to PDFSigner1 for worker 2
Setting the property NAME to SignerStatusReporter for worker 2
Setting the property OUTPUTFILE to /tmp/statusreport for worker 2

$ bin/signserver reload 2
===========================================
Executing Command on host : localhost
===========================================
SignServer reloaded successfully
Current configuration is now activated.

Other workers

CryptoWorker

The Crypto Worker is a worker not performing any operations on its own and instead only hosts a Crypto Token that can be referenced by other workers.

Fully qualified class name: org.signserver.server.signers.CryptoWorker

Worker properties

See the Available CryptoTokens for the required properties of the configured crypto token.

RenewalWorker

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/signclient signdocument -workername MyRenewalWorker -data "WORKER=MySigner
AUTHCODE=foo123"

(Notice that the command is on two lines)

The renewal can also be initiated from the Admin CLI:

bin/signserver renewsigner MySigner -renewalworker MyRenewalWorker -authcode foo123

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. Must be specified. Example: https://ca-server:8443/ejbca

TRUSTSTOREPATH = Path to the keystore containing the CA's SSL server certificate as a trusted entry. Used instead of TRUSTSTOREVALUE. If this property is not specified, TRUSTSTOREVALUE must be set.

TRUSTSTOREVALUE = Keystore containing the CA's SSL server certificate as a trusted entry. Used instead of TRUSTSTOREPATH. If this property is not specified, TRUSTSTOREPATH must be set. If TRUSTSTORETYPE is not PEM the keystore is stored in the property in base64 encoding.

TRUSTSTORETYPE = Type of keystore. JKS and PEM is supported. This property must be set.

TRUSTSTOREPASSWORD = Password protecting the truststore keystore. This property must be set if TRUSTSTORETYPE is not PEM.

KEYSTOREPASSWORD = The password that locks the key-store. Required for JKS.

DEFAULTKEY = Key alias to use from the crypto token. This property must be set.

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 (Required when using a RenewalTimedService otherwise 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

Renewee Request Result
DEFAULTKEY NEXTCERTSIGNKEY FORDEFAULTKEY DEFAULTKEY NEXTCERTSIGNKEY
- - - New key and alias Removed
present - - New key and alias Removed
- present - Alias from nextcertsignkey Removed
present present - Alias from nextcertsignkey Removed
present - TRUE Same alias Same alias
present present TRUE Same alias Same alias

StatusPropertiesWorker

Fully qualified class name: org.signserver.module.statusproperties.StatusPropertiesWorker

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

TimeMonitorManager

Note
The TimeMonitorManager is an Enterprise Edition feature.

Fully qualified class name: org.signserver.module.timemonitormanager.TimeMonitorManager

Overview

Similar to the StatusPropertiesWorker, the TimeMonitorManager also supports setting status properties in the status repository. In addition the TimeMonitorManager also supports dynamic configuration of the TimeMonitor as well as gives a complete view of the state of the TimeMonitor.

Worker Properties

All worker properties starting with either "TIMEMONITOR." or "TIMESERVER." are sent to the TimeMonitor if it asks for it.

See the SignServer TimeMonitor manual for the list of available properties.

Request Properties

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)

Response Properties

x.UPDATE = The time when the property was written

Status output

Much information about the state of the TimeMonitor is available in the getstatus output of the TimeMonitorManager:

  • Time monitor: Indicates if the application is detected to be 'Running', 'Disabled', 'Not running?' or 'Unavailabe'. The state is determined by if the manager has seen an update from the TimeMonitor before the status properties are starting to expire.
  • Last update: The last time the TimeMonitor contacted the manager.
  • Current time: Current time of the server.
  • Time state: The last time state from the TimeMonitor.
  • Report state: The last report state from the TimeMonitor.
  • Leap state: The last leap state from the TimeMonitor.
  • Configuration: Either 'out of sync' or 'up to date' depending on if the current configuration has been read by the TimeMonitor or not. After changing a property in the TimeMonitorManager it is normal that the cofiguration is marked as 'out of sync' until the TimeMonitor fetches it.
  • Status properties values: Prints the current value and possibly the expiration time for the TIMESOURCE0_INSYNC and LEAPSECOND status properties.
  • Timings: Prints the current time values from the TimeMonitor.
  • Configuration: Prints the configuration values in the manager (not necessarily read by the TimeMonitor yet).
  • Last TimeMonitor log entries: Prints the last log entries obtained from the last update from the TimeMonitor.

Sample output:

Status of Worker with ID 300 (TimeMonitorManager) is:
   Worker status : Active
   Time monitor  : Running
   Last update   : 2014-08-26 11:43:39,176
   Current time  : 2014-08-26 11:43:39,580
   Time state    : INSYNC
   Report state  : REPORTED
   Leap state    : NONE
   Configuration : Up to date

   Status Repository values:
      TIMESOURCE0_INSYNC:        true
      LEAPSECOND:                NONE

   Timings:
      NTP server time offset:           0 ms
      NTP server query time:          507 ms
      NTP leap status query time:       8 ms
      Report time:                      7 ms
      Total required run time:        522 ms

   Configuration:
      NTP server hosts:            192.168.30.25
      NTP query samples:                2
      NTP query timeout:              200 ms
      Max accepted offset:            997 ms
      Warn offset:                    500 ms
      Status expire time:             900 ms
      Leap status expire time:      60000 ms
      Warn run time:                  800 ms
      Minimum run time:               550 ms

   Last TimeMonitor log entries:
      2014-08-26 11:36:29,253 INFO  Started
      2014-08-26 11:36:29,287 INFO  State changed to: UNKNOWN,REPORTED,UNKNOWN
      2014-08-26 11:36:44,255 INFO  Config changed to: 1ccdf46b
      2014-08-26 11:36:44,782 INFO  Time back in calibration: offset abs(0)  max accepted offset 997
      2014-08-26 11:36:44,793 INFO  State changed to: INSYNC,REPORTED,NONE

TimeMonitorStatusReportWorker

Note
The TimeMonitorStatusReportWorker is an Enterprise Edition feature.

Fully qualified class name: org.signserver.module.timemonitormanager.TimeMonitorStatusReportWorker

Overview

Worker that outputs the TimeMonitor state line as described in the SignServer TimeMonitor manual.

Response

Sample output:

1409055102120,INSYNC,REPORTED,NONE,1ccdf46b,0,507,7,6

SignerStatusReportWorker

Fully qualified class name: org.signserver.module.signerstatusreport.SignerStatusReportWorker

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.

Available CryptoTokens

There exists four types of crypto tokens (Formerly known as sign tokens), two for storing the keys in software, one general for communicating with cryptographic hardware through the PKCS11 interface and one for SmartCards. See the developer section for information about developing support for other HSMs.

Which CryptoToken a worker is using is determined by the its SIGNERTOKEN.CLASSPATH property which should contain the fully qualified class name of the CryptoToken implementation. In addition to that property one must also make sure that the other properties needed by the particular crypto token are available.

General properties

SIGNERTOKEN.CLASSPATH: Global configuration property for the fully qualified class name of the crypto token implementation to use. See below for available crypto tokens.

KEYALG: Key algorithm to use when generating new keys (Only for cryptotokens supporting key generation).

KEYSPEC: Key specification to use when generating new keys (Only for cryptotokens supporting key generation).

KEYGENERATIONLIMIT: Limit for the maximum number of keys allowed to be generated. If set and set to 0 or a positive value, key generation is not allowed if the current number of keys equals to or is larger than this value (Default: "" = no limit).

SELFSIGNED_DN: Distinguished Name (DN) to use as issuer and subject DN in the self-signed certificate instead of the default one. Note: This property can be set on the worker that is going to use the key so that different options can be used for different workers.

SELFSIGNED_SIGNATUREALGORITHM: Signature algorithm to use in the self-signed certificate instead of the default "SHA1withRSA". Note: This property can be set on the worker that is going to use the key so that different options can be used for different workers.

SELFSIGNED_VALIDITY: Validity time (in seconds) to use in the self-signed certificate instead of the default of about 30 years. Note: This property can be set on the worker that is going to use the key so that different options can be used for different workers.

P12CryptoToken

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

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 a key is not derived from each signing request (using an implementation of the AliasSelector interface), this needs to be defined. (optional)

JKSCryptoToken

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

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 a key is not derived from each signing request (using an implementation of the AliasSelector interface), this needs to be defined. (optional)

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

KeystoreInConfigCryptoToken

Overview

A CryptoToken using a PKCS#12 keystore stored in the configuration (in the database).

The content of the keystore is not part of the regular worker properties. Thus, it is not included when running the

dumpproperties
command. It is also removed when removing the crypto worker (or regular worker when using the legacy method to set-up crypto tokens). To backup the content of the crypto token, a database backup should be made.

The password supplied when activating the token the first time will be used as the keystore password.

SIGNERTOKEN.CLASSPATH

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

Available Properties

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)

PKCS11CryptoToken

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)

SHAREDLIBRARYNAME = Name of pre-defined PKCS11 library to be used. The available libraries can be configured in signserver_deploy.properties. If the legacy SHAREDLIBRARY property is also defined, it must point to the same library on the file system. (Required, unless the old SHAREDLIBRARY is set)

SHAREDLIBRARY = Full path to the library containing the PKCS11 interface. From version 3.7.0 this must point to a file declared in signserver_deploy.properties (or using the built-in values). If this property is defined at the same time as SHAREDLIBRARYNAME they must point to the same library on the file system. NOTE: This property is deprecated.

SLOTLABELTYPE = Indicates how the slot should be identified. Supported values are SLOT_NUMBER, SLOT_INDEX or SLOT_LABEL. (Required)

SLOTLABELVALUE = The slot to use, identified with the type specified in SLOTLABELTYPE: (Required)

  • SLOT_NUMBER is the number (ID) of the slot
  • SLOT_INDEX is the zero-base index of the slot in the list of available slots as returned by the PKCS#11 provider
  • SLOT_LABEL this is the label of the slot

This properites are not allowed if the legacy properties below are specified.

SLOT or SLOTLISTINDEX = Legacy properties for indicating which slot to use. Only available for backwards compatibility. Instead use the SLOTLABELTYPE and SLOTLABELVALUE properties.

ATTRIBUTESFILE = Path to file with PKCS#11 attributes used for key generation. (Optional, not allowed if ATTRIBUTES specified)

ATTRIBUTES = PKCS#11 attributes used for key generation specified directly in the property value. (Optional, not allowed if ATTRIBUTESFILE specified)

Sample p11attributes.cfg:

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

# Work-around for performance issue in the Apache XMLSec library
disabledMechanisms = {
    CKM_SHA1_RSA_PKCS
    CKM_SHA256_RSA_PKCS
    CKM_SHA384_RSA_PKCS
    CKM_SHA512_RSA_PKCS
    CKM_MD2_RSA_PKCS
    CKM_MD5_RSA_PKCS
    CKM_DSA_SHA1
    CKM_ECDSA_SHA1
}

Notice: The PKCS#11 attributes configuration is global per shared library. If specified in multiple workers only the configuration from the first worker loaded will be used. Changing the property might not take effect without restarting the application server.

Notice: For a Thales nCipher 'module protected' slot (slot index 0), CKA_PRIVATE must be false for the CKO_PRIVATEKEY so the key can be used without a login otherwise the key generation will fail with a CKR_USER_NOT_LOGGED_IN PKCS#11 error.

CACHE_PRIVATEKEY = If set to true the private key and certificate is cached in the worker so that they are not queried for each signature. This could potentially improve performance in some environments, typically where network HSMs or HSM slots with many keys are used. (Default: false)

Notice: This worker property is to be specified in the worker where the key to be used is specified by the DEFAULTKEY property. It is that key that will be cached locally in the worker. It is important to remember this if the crypto token is configured in a separate worker in which case this property should be specified in the worker that will be using the crypto token and not necessarily in the one having the crypto token configuration.

Notice: When this option is used, the signer certificate is also cached if it is taken from the token and not overridden by specifying it in the configuration. This means that if the certificate in the token is changed the old certificate will still be used until the worker is reloaded which will clear the cache.

Default global properties

Some worker properties can instead by specified as default values in the global configuration so they does not have to be repeated in every worker. Individual workers can override the default global values (if any) by specifying the property as usual.

Global default values are specified as global values in the global configuration with the name prefixed with "DEFAULT.". The following properties can currently be specified in the global configuration:

  • SHAREDLIBRARYNAME
  • SHAREDLIBRARY
  • SLOTLABELTYPE
  • SLOTLABELVALUE
  • SLOT
  • SLOTLISTINDEX
  • ATTRIBUTES
  • ATTRIBUTESFILE
  • PIN

Example usage

Edit (preferably a copy of) pkcs11-crypto.properties to match your PKCS#11 token. Run the following command to set up the token:

bin/signserver setproperties pkcs11-crypto-configuragtion.properties

Reload the configuration using the ID that was printed (in this example 8):

bin/signserver reload 8

Activate the crypto token by specifying the PIN code:

bin/signserver activatecryptotoken 8

Unless your DEFAULTKEY worker property points to an existing key in the HSM the activation will look like it failed. Don't worry and instead continue creating a key that can be used for testing slot activation:

Generate a keypair in the token to be used as test key:

bin/signserver generatekey 8 -alias testkey1 -keyalg RSA -keyspec 2048

Set the key as test key:

bin/signserver setproperty 8 DEFAULTKEY testkey1
bin/signserver reload 8
bin/signserver activatecryptotoken 8

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

The signer certificate should then be uploaded to the worker wich should use it. Upload the signing certificate chain to the signer using the command: bin/signserver uploadsignercertificatechain 9 GLOB /tmp/certchain.pem bin/signserver reload 9

Alias Selectors

By using an alias selector it is possible to control how the key used for signing are selected at run-time based the signing request. For example it is possible to have keys selected based on the authenticated user for a signing request.

The default, if no alias selector is explicitly configured is to use a default selector behaving in a backwards-compatible way, using the DEFAULTKEY property of the crypto worker being used.

To configure an alternative alias selector, set the ALIASSELECTOR worker property of the worker pointing to the class name of an implementation for an alias selector to use.

Available implementations

DefaultAliasSelector

The fully qualified class name is: org.signserver.server.aliasselectors.DefaultAliasSelector

This alias selector chooses DEFAULTKEY or NEXTCERTSIGNKEY as specified for the crypto worker depending on the purpose of the request. This alias selector would be used if none has been explicitly set.

AuthorizedUsernameAliasSelector

The fully qualified class name is: org.signserver.server.aliasselectors.AuthorizedUsernameAliasSelector

This alias selector chooses keys based on the authorized username in the request.

An optional prefix can be specified using the

ALIAS_PREFIX
worker property. If this is not specified, the plain username will be used as the key alias.

Archivers

See also the section about the ARCHIVERS worker property that can be set to one or more of the available Archiver implementations described below.

OldDatabaseArchiver

The default archiver used if the the property ARCHIVE=true is set. Or if the ARCHIVERS property contains its class name. This Archiver archives to the database table "ArchiveData" using the same datasource as SignServer uses for accessing the database for its configuration etc.

The data is stored in an XML encoded Base64PutHashMap. In the "dataEncoding" column this format is indicated as DATA_ENCODING_XML.

The fully qualified class name is: org.signserver.server.archive.olddbarchiver.OldDatabaseArchiver

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", IP addresses 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, by default the last forwarded address is used. 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".

ARCHIVERx.MAX_FORWARDED_ADDRESSES = Where "x" is the index of the archiver in the ARCHIVERS property. Sets the maximum number of forwarded addresses to add the remote IP in the archive, counted from the end. The addresses is listed in the order they appear in the header. The default value is 1 (only include the last address). This property is only used when USE_FORWARDED_ADDRESS is set to "true".

ARCHIVERx.INCLUDE_DIRECT_ADDRESS = Where "x" is the index of the archiver in the ARCHIVERS property. If this property is set to "true", and USE_FORWARDED_ADDRESS is also set to "true", the host IP address (direct address) is added to the end of the list of forwarded addresses. This address is not taken into account for the number of forwarded addresses by MAX_FORWARDED_ADDRESSES above. The default is "false" (not included). This property is only used when USE_FORWARDED_ADDRESS is set to "true".

ArchiveData table

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

uniqueId Primary key of the archive row.
archiveData The actual data encoded in an Base64PutHashMap.
archiveId Some identifier for the produced item.
For the TimeStampSigner this would be the Time stamp token serial number (in hex encoding). Other signers might use a hash of the request document and the transaction ID.
requestCertSerialnumber Serial number (in hex encoding) of the client certificate (if any) used by the client.
Notice: This only indicates that the client certificate where used when establishing the connection to the web server and not wither the worker required a client certificate or not or if it did any additional checks if the authenticated client was authorized.
requestIP By default IP address of the host connecting. When USE_FORWARDED_ADDRESS is set to "true" this contains a list of forwarded IP addresses from X-Forwarded-For optionally ending with the host address (when setting INCLUDE_DIRECT_ADDRESS to "true").
requestIssuerDN Issuer DN (in string representation) of the issuer of the client certificate (if any) used by the client.
See also note about requestCertSerialnumber.
signerId ID of the worker handling the request.
time Timestamp (number of milliseconds since January 1 1970 00:00:00) on the SignServer host when the item where archived.
type The type of archivable item. Currently this could be:
  • 0 - TYPE_RESPONSE
  • 1 - TYPE_REQUEST
dataEncoding Type of encoding used for the archiveData. Currently this could be:
  • NULL - DATA_ENCODING_XML
  • 0 - DATA_ENCODING_XML
  • 1 - DATA_ENCODING_BASE64
Where DATA_ENCODING_XML uses the Base64PutHashMap and DATA_ENCODING_BASE64 uses a plain Base64 encoding of the binary data.

Base64DatabaseArchiver

This Archiver archives to the database table "ArchiveData" using the same datasource as SignServer uses for accessing the database for its configuration etc. It is similar to the OldDatabaseArchiver but does not use an XML structure for storing the data. Instead the data is simply base64 encoded.

In the "dataEncoding" column this format is indicated as DATA_ENCODING_BASE64.

The fully qualified class name is: org.signserver.server.archive.base64dbarchiver.Base64DatabaseArchiver

Worker Properties

ARCHIVERx.ARCHIVE_OF_TYPE = Same as for OldDatabaseArchiver above.

Accounters

See also the section about the ACCOUNTER worker property that can be set to one of the available Accounter implementations described below.

NoAccounter

The fully qualified class name is: org.signserver.server.NoAccounter

Accounter not doing anything. Sets purchased to true.

GlobalConfigSampleAccounter

The fully qualified class name is: org.signserver.server.GlobalConfigSampleAccounter

Accounter holding the clients balances internally in the global configuration.
Note: This Accounter is only for demonstration purposes and will not work under load. A production Accounter should use an implementation using a proper database.

Global Configuration Properties

GLOBALCONFIGSAMPLEACCOUNTER_USERS = Mapping from credential to account name
GLOBALCONFIGSAMPLEACCOUNTER_ACCOUNTS = Mapping from account name to a balance

Example:

GLOBALCONFIGSAMPLEACCOUNTER_USERS = user1,password:account1; user2,password2:account2
GLOBALCONFIGSAMPLEACCOUNTER_ACCOUNTS = account1:14375; account2:12