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