Common Configuration

Introduction

Configuring workers are done by setting properties in the worker configuration. There is one set of configuration options that are handled by the framework, and that applies to all workers, then there are worker specific properties handled by the worker implementation.

Properties are usually defined in the module configuration file used to install a module, or configured manually using one of the bin/signserver setproperty variant.

Generic Worker Properties

NAME = The name of the worker.

TYPE = The type of the worker. Currently can be one of:

  • UNKNOWN: Indicating that the type is not yet known/set.
  • PROCESSABLE: Processable worker that can be invoked to process (for instance sign) data.
  • TIMED_SERVICE: Worker scheduled to be run at some interval.
  • SPECIAL: Not a callable or schedulable worker. Reserved for future use.
  • CRYPTO_WORKER: A special worker only holding a crypto token mainly to be used by other workers.

Setting Authorization Type

SignServer

By default (if the property is not set) is client-certificate authentication required for a signature request to be processed. This can be changed with the AUTHTYPE property.

No authentication

AUTHTYPE = NOAUTH

Sets the server to not require any authentication.

Client certificate authentication

AUTHTYPE = CLIENTCERT

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

Username/password-based authentication

AUTHTYPE = org.signserver.server.UsernamePasswordAuthorizer

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

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

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

Username-based authentication

AUTHTYPE = org.signserver.server.UsernameAuthorizer

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

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

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

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

Remote address authentication

AUTHTYPE = org.signserver.server.RemoteAddressAuthorizer

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

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

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

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

List-based Address Authorizer

AUTHTYPE = org.signserver.server.ListBasedAddressAuthorizer

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

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

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

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

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

MAX_FORWARDED_ADDRESSES = Number of IP addresses to inspect in the list of forwarded addresses. (Default: 1).

It is not possible to specify both a whitelist and a black list at the same time for each of direct and forwarded addresses. One of each list (direct and forwarded) must be specified. When specifying a whitelist for forwarded addresses, requests without an X-Forwarded-For header will always be denied. When there are multiple addresses in the X-Forwarded-For header (in the case of using multiple proxies) the number of addresses specified in MAX_FORWARDED_ADDRESSES counting from the end of the list (or the entire list if it is shorter than this) is considered for white- and blacklisting. If specified, MAX_FORWARDED_ADDRESSES must have a value >= 1. It is not allowed to set it 0 to disable checking forwarded addresses. RemoteAddressAuthorizer should be used in this case.

Examples:

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

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

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

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

5. To accept direct request from a proxy server 10.0.1.1 allowing forwarding from another proxy 10.0.2.2 in turn proxying the request from the client with address 192.0.43.10 use:
WHITELISTED_DIRECT_ADDRESSES=10.0.1.1
WHITELISTED_FORWARDED_ADDRESSES=10.0.2.2,192.0.43.10
MAX_FORWARDED_ADDRESSES=2

6. To blacklist a set of IP addresses, set the MAX_FORWARDED_ADDRESSES value to a value gauranteed to be larger than the number of proxies you have control over, like in the following example: BLACKLISTED_FORWARDED_ADDRESSES=10.0.1.1,10.0.2.2,10.0.3.3 MAX_FORWARDED_ADDRESSES=10

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

DispatchedAuthorizer

AUTHTYPE = org.signserver.server.DispatchedAuthorizer

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

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

Custom

This authorization functionality doesn't work for all use cases. Then it's possible to create a customized authorizer and specify it's class path as value in the AUTHTYPE property. The Processable will then automatically instantiate and use it. How to develop such a plug-in is explained in the developers section.

Archiving Responses

The archiving feature can be used to save all generated responses.

For the OldDatabaseArchiver and Base64DatabaseArchiver, in some extent, the Admin CLI can be used to query the archive. See the CLI section for more information.

When a request has been process each Archiver is called one at the time to archive any results.

ARCHIVERS: Used instead of the old ARCHIVE property to enable archiving by listing the class names of all the Archivers that should be used. Multiple Archivers can be specified separated by a "," (comma character). Exempel:

ARCHIVERS=org.signserver.server.archive.olddbarchiver.OldDatabaseArchiver,org.signserver.server.archive.otherarchiver.OtherArchiver123

ARCHIVE: Previously the archiving was enabled by setting the property to "TRUE". This is the same as to set

ARCHIVERS=org.signserver.server.archive.olddbarchiver.OldDatabaseArchiver

Default: FALSE.

See also the section about all available Archivers.

Accounter

An Accounter is responsible for somehow charging a client for a successful request or to deny the request if the client has insufficient funds.

When a request has been processed, and if the worker marked the request as successfully fulfilled, the configured Accounter (if any) is called. The Accounter implementation could potentially query an external database and make a purchase for the service.

The Accounter to use is configured using the ACCOUNTER worker property. By default no Accounter is used. Example:

ACCOUNTER=org.signserver.server.GlobalConfigSampleAccounter

See also the section about all available Accounters.

Checking validity of signer certificates

By default the SignServer checks if the signer certificate of a signer is valid before letting the signer process a request. If the signers certificate is not valid an error message is returned. There are two properties that can be set to disable this check:

CHECKCERTVALIDITY: default value is true, meaning that the validity period of the certificate will be verified before processing. Set to false to ignore if the certificate is expired or not yet valid.

CHECKCERTPRIVATEKEYVALIDITY: default value is true, meaning that the validity period in the PrivateKeyUsagePeriod of the certificate will be verified before processing. This is only done if this extension exists (it is optional in a certificate). Set to false to ignore the PrivateKeyUsagePeriod.

MINREMAININGCERTVALIDITY: default value is 0. This property defines a minimum remaining validity time required of the signing certificate. If the signing certificate expires within the number of days specified an error occurs. Set to 0 (default) to disable this check.

Limiting the number of signatures

By default SignServer keeps track of the number of signings performed with each key by holding counters in the database that are updated for each signing. The following worker properties controls the key usage counter:

KEYUSAGELIMIT = Sets how many signatures that are allowed to be created with the same key by this worker (default is -1 = no limit). After the limit has been reached the worker is considered offline. Note that the counter is per key and not per worker so if multiple workers share the same key they will all increment the counter. This also means that the worker is active again after it has gotten a new certificate/key.

DISABLEKEYUSAGECOUNTER = By default all key usages are counted but by specifying this as "TRUE" key usages performed by this worker will not be counted. Disabling the key usage counter can be a gain in performance as it will be less database transactions. However, if you have requirements on the number of allowed signings for one worker make sure to not use the same key with another worker for which the counter is disabled as those uses will then be missed.

The key usage counter can not be disabled for a worker if KEYUSAGELIMIT is also specified.

Other properties

DISABLED = Setting this to true disables a worker. A disabled worker can not perform any operations and any requests to it will fail. However, disabled workers are not included in the Health check report.

EXPLICITECC = Setting this to true uses explicit domain parameters instead of NamedCurves when generating a certificate request using the RenewalWorker or through to admin GUI. (default: false)

NOCERTIFICATES = Setting this to true tells SignServer to not warn if no signer certificate is configured for this worker. This could be useful for special types of workers not performing any signing operations.