Client CLI signdocument Command
Request signing of a document using HTTP(s) 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. -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. -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, CLIENTWS or WEBSERVICES. Default: HTTP. -removefromindir Specify this flag to have the successfully processed input files removed from indir. -servlet <arg> Servlet to call. Default /signserver/process -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
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.
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.
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).
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.
|-keystoretype PKCS11||With this keystore type the -keystore option should point to the PKCS#11 (cryptoki) shared library file.|
|-keystoretype PKCS11_CONFIG||With this keystore type the -keystore options should point to a SunPKCS11 configuration file.|
|-keyaliasprompt||Instead of providing the key alias with -keyalias, this option can be used to have SignClient prompt for which of the matching key alias to use.|
|-keystorepwd||Smartcard PIN can either be provided on the command line or if this option is not provided instead SignClient will prompt for the PIN.|