signdocument

Request signing of a document using HTTP(s), REST, Client WS or Web Services.

The data to send to SignServer can be supplied using one of the following methods (see Sample usages below):

• Provided directly on the command line as a string using the -data flag. Useful for text input.
• As a path to the file containing the data using the -infile flag.
• As a path to folder containing files with the input data using the -indir flag and combined with -outdir for the response files. This is the so called Batch Signing Mode.

usage: signdocument <-workername WORKERNAME | -workerid WORKERID>
                    [options] Request a document to be signed by SignServer
 -accesstoken <arg>       Access token to use for JWT authentication. Can
                          not be specified at the same time as -username.
                          Can only be used with protocol HTTP or REST.
  -baseurlpath <arg>      URLPath to call. Default is /signserver.
  -clientside             Hash the file(s) locally, sign the hash
                          server-side, and assemble the resulting file(s)
                          locally. Note: this option is only available in
                          the enterprise edition.
 -data <arg>              Data to send to the worker.
 -digestalgorithm <arg>   Digest algorithm to use for client-side hashing
                          and construction (using the -clientside option).
                          Note: this option is only available in the
                          enterprise edition.
 -extraoption <arg>       Additional options for the command needed for
                          some file-types. The parameters should be given
                          in the form KEY=VALUE. This option can be given
                          multiple times.
 -filetype <arg>          Overrides automatic file-type detection for
                          client-side hashing and construction (possible
                          values PE, MSI, ZIP), default: try to guess
                          based on input. Note: this option is only
                          available in the enterprise edition.
 -host <arg>              Server name or IP address. Default: localhost
 -hosts <arg>             List of server names or IP addresses to try in
                          order.
 -indir <arg>             Directory to read input files from. Required if
                          outdir specified. Can not be combined with
                          infile or outfile.
 -infile <arg>            File to read data to send to the worker from.
 -keyalias <arg>          Alias of the key in the keystore to use for
                          authentication.
 -keyaliasprompt          Ask for which key alias to use in the keystore
                          to use for authentication.
 -keystore <arg>          Keystore with private key and certificate for
                          client certificate authentication.
 -keystorepwd <arg>       Password for reading the keystore.  If keystore
                          is specified but not this keystore password
                          option, the CLI will instead prompt for the
                          password.
 -keystoretype <arg>      Type of keystore. Examples: JKS, PKCS11 and
                          PKCS11_CONFIG.
 -loadbalancing <arg>     Specify if the load balancing feature using
                          round robin should be used. ROUND_ROBIN or NONE.
                          Default: NONE. NONE means no load balancing.
 -metadata <arg>          Additional meta data to send to the signer. The
                          parameters should be given in the form
                          KEY=VALUE. This option can be given multiple
                          times.
 -nohttps                 Do not use HTTPS even if keystore and/or
                          truststore are provided on the command line.
 -onefirst                In batch mode, don't send all requests until the
                          first succeeds. This is primary to prevent too
                          many incorrect password attempts. Default if
                          username is provided and -startall not provided.
 -outdir <arg>            Directory to write output files to. Required if
                          indir specified. Can not be combined with infile
                          or outfile.
 -outfile <arg>           File to write the result to. If not specified
                          result is written to stdout. Must specify
                          -outfile or -outdir when using -clientside.
 -password <arg>          Password for authentication. If username is
                          specified but not this password option, the CLI
                          will instead prompt for the password.
 -passwordfromstdin       Read password from standard input. Useful for
                          scripting. Might also be needed for some
                          terminals which don't support reading from a
                          ConsoleReader. NOTE: when running interactively,
                          this will echo back the password.
 -pdfpassword <arg>       Password for changing the PDF (if required).
 -port <arg>              Server port. Default: 8080 (for HTTP), 8442 for
                          HTTPS and 8443 for HTTPS with client
                          authentication.
 -protocol <arg>          Method of interacting with SignServer. HTTP, REST
                          CLIENTWS or WEBSERVICES. Default: HTTP.
 -removefromindir         Specify this flag to have the successfully
                          processed input files removed from indir.  
 -servlet <arg>           Servlet to call.
 -signkeyalias <arg>      Alias of the key in the keystore to use for
                          signing the requests.
 -signkeyaliasprompt      Ask for which key alias to use in the keystore
                          to use for signing the request(s).
 -signrequest             Sign the request using the specified key from
                          the keystore. Used with the
                          SignedRequestAuthorizer server-side. Requires
                          specifying keystore. Note: this option is only
                          available in the enterprise edition.
 -startall                In batch mode, send all requests at once,
                          without waiting for the first to succeed.
                          Default unless username is provided or -onefirst
                          provided.
 -threads <arg>           Number of threads for sending the requests. Only
                          allowed in batch mode, ie when indir and outdir
                          are specified. Default: 1.
 -timeout <arg>           Timeout limit in milliseconds for connecting to
                          SignServer. If the connection is not established
                          within this time interval it will be considered
                          as a connection failure. Default timeout is
                          system dependent. Specifying as 0 means no
                          timeout.
 -truststore <arg>        Keystore with trusted certificates to use with
                          HTTPS.
 -truststorepwd <arg>     Password for the keystore with trusted
                          certificates. If truststore is specified but not
                          this truststore password option, the CLI will
                          instead prompt for the password.
 -username <arg>          Username for authentication.
 -workerid <arg>          ID of worker which should perform the operation.
 -workername <arg>        Name of worker which should perform the
                          operation.

Sample usages:
a) signdocument -workername XMLSigner -data "<root/>"
b) signdocument -workername XMLSigner -infile /tmp/document.xml
c) signdocument -workerid 2 -data "<root/>" -truststore truststore.jks
-truststorepwd changeit
d) signdocument -workerid 2 -data "<root/>" -keystore superadmin.jks
-keystorepwd foo123
e) signdocument -workerid 2 -data "<root/>" -metadata param1=value1
-metadata param2=value2
f) signdocument -workerid 3 -indir ./input/ -removefromindir -outdir
./output/ -threads 5
g) signdocument -workerid 3 -indir ./input/ -outdir ./output/ -threads 5
-hosts primaryhost,secondaryhost
h) signdocument -workerid 3 -indir ./input/ -outdir ./output/ -threads 5
-hosts primaryhost,secondaryhost,otherhost -timeout 5000
i) signdocument -workerid 3 -indir ./input/ -outdir ./output/ -threads 5
-hosts host1,host2,host3 -loadbalancing ROUND_ROBIN -timeout 5000
j) signdocument -workerid 2 -data "<root/>" -keystoretype PKCS11 -keystore
libcryptoki.so
k) signdocument -workerid 2 -data "<root/>" -keystoretype PKCS11 -keystore
libcryptoki.so -keyaliasprompt
l) signdocument -workerid 2 -data "<root/>" -keystoretype PKCS11 -keystore
libcryptoki.so -keyalias admin3
m) signdocument -workerid 2 -data "<root/>" -keystoretype PKCS11_CONFIG
-keystore sunpkcs11.cfg
n) signdocument -data "<root/>" -servlet /signserver/worker/XMLSigner
o) signdocument -protocol REST -workername XMLSigner -data "<root/>"
p) signdocument -protocol REST -workername XMLSigner -infile /tmp/document.xml

As of SignServer 6.0, the signature algorithm used to sign the request when using the -signrequest option with an ECDSA key has been changed. Now the algorithm uses a digest algorithm matching the key size (e.g. SHA256withECDSA for secp256r1 keys, SHA384 for secp384r1 keys). The change is a result of changes in the underlying JJWT library.

Batch Signing Mode

Instead of specifying the input data using the -data flag or specifying one file using -infile, you can use the -indir and -outdir options to process multiple files in one run. This however will not recursively go into subdirectories but will instead skip them. A warning will be printed for each subdirectory but it will not affect the exit code of the command. Before SignServer version 5.9, an error was instead printed and the command would exit with an error code after processing all files. 

Failover and Load Balancing Modes

SignClient can be used instead of having a load balancer as it is capable of failing over to another host if the current one fails and also has the option to spread the load between multiple servers. These features are configured by specifying additional SignServer hosts, setting the connection timeout value and the optional loadbalancing option.

The failover and load balancing features are limited to the signdocument command and is only supported using the default -protocol HTTP or -protocol REST.

You can use the -hosts flag to specify multiple SignServer hosts to send the requests to. If the connection to one host fails, either directly or because of a timeout, the next host in the list is tried instead. To specify a timeout value, use the -timeout flag.

Connection failures include cases where the host is not reachable, SignServer is not available (i.e. not started and/or deployed), or the worker is not available (for example due to that the HSM is not activated or the worker is misconfigured). Failures caused by issues with the request, like incorrect input data or wrong credentials etc., are generally not considered connection failures.

Load balancing is by default not used and the default behavior is to use the first host in the list and only if that fails, try the next host in the list, and so on until the request(s) are processed or there are no more hosts to try.

To enable load balancing, specify the -loadbalancing ROUND_ROBIN option. The first host to use is then randomly selected from the list of hosts. If the command is running in Batch Signing Mode (i.e. -indir is specified) so there is more than one request to process, the next request will use the next host in the list (the list will wrap-around at the end, continuing with the first host).

Smartcard Authentication

In addition to using a software keystore for client certificate authentication it is also possible to use a PKCS#11 device like a smart card or a token.