signdocument | Keyfactor Docs

Use the SignClient signdocument command to request document signing using HTTP(S), REST, or Client Web.

The data to send to SignServer can be supplied using one of the following methods:

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 standard input, using the -stdin flag.
As a path to folder containing files with the input data, using the -indir flag combined with -outdir for the response files. This is Batch Signing Mode.

Command Options

Option	Description
`-accesstoken <arg>`	Access token to use for JWT authentication. Can only be used with protocol HTTP or REST. Cannot be specified at the same time as `-username`.
`-baseurlpath <arg>`	URL path to call. Default: `/signserver`
`-clientside`	Enterprise Hash the file locally, sign the hash server-side, and assemble the resulting file locally. See Client-side Hashing.
`-data <arg>`	Data to send to the Worker.
`-digestalgorithm <arg>`	Enterprise Digest algorithm to use for client-side hashing and construction using the `-clientside` option.
`-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 provided multiple times.
`-filetype <arg>`	Enterprise Overrides automatic file type detection for client-side hashing and construction. By default, SignClient tries to guess based on input. Possible values: `PE`, `MSI`, `ZIP`
`-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. Cannot be combined with `infile` or `outfile`.
`-infile <arg>`	File from where data is read to send to the Worker.
`-stdin`	Read request data for the Worker from standard input. Large file handling is only supported with HTTP protocol.
`-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 `-keystorepwd`, the CLI instead prompts for the password.
`-keystoretype <arg>`	Type of keystore. Examples: `JKS`, `PKCS11`, and, `PKCS11_CONFIG`. Defaults to `JKS` when a `.jks` file is used.
`-loadbalancing <arg>`	Specify if the load balancing feature using round robin should be used. Values: `ROUND_ROBIN` or `NONE`. Default: `NONE` (no load balancing)
`-metadata <arg>`	Additional metadata to send to the Signer. The parameters should be given in the format `KEY=VALUE`. This option can be provided multiple times.
`-nohttps`	Do not use HTTPS, even if `keystore` or `truststore` are provided on the command line.
`-onefirst`	In batch mode, do not send all requests until the first succeeds. This is primarily to prevent too many incorrect password attempts. Default if `-username` is provided and `-startall` is not provided.
`-outdir <arg>`	Directory to write output files to. Required if `indir` specified. Cannot be combined with `infile` or `outfile`.
`-outfile <arg>`	File to write the result to. If not specified, the result is written to `stdout`. When using `-clientside`, `-outfile` or `-outdir` is required.
`-password <arg>`	Password for authentication. If `-username` is specified but not `-password`, the CLI instead prompts for the password.
`-passwordfromstdin`	Read password from standard input. Use for scripting and for terminals which do not support reading from a ConsoleReader. 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`.
`-publickey <arg>`	Base64 encoded public key to be used for specific actions such as ML-DSA External Mu calculation. When signing using ML-DSA External Mu, the public key must match the ML-DSA key pair that performs the signing action. See Signing with ML DSA External μ.
`-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`	Enterprise Sign the request using the specified key from the keystore. Used with the Signed Request Authorizer server-side. Requires specifying `keystore`. As of SignServer 6.0, when using the `-signrequest` option with an ECDSA key, the signature algorithm uses a digest size matching the key size, for example, `SHA256withECDSA` for secp256r1 keys and `SHA384withECDSA` for secp384r1 keys. This change is a result of updates to the underlying JJWT library.
`-startall`	In batch signing mode, send all requests at once, without waiting for the first to succeed. Default unless `-username` or `-onefirst` is provided.
`-threads <arg>`	Number of threads for sending the requests. Only allowed in batch signing mode 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 `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 `-truststorepwd`, the CLI instead prompts for the password.
`-username <arg>`	Username for authentication.
`-workerid <arg>`	ID of Worker performing the operation.
`-workername <arg>`	Name of Worker performing the operation.

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. Batch mode does not recurse into subdirectories. Subdirectories are skipped and a warning is printed, but this does not affect the exit code of the command.

Before SignServer 5.9, encountering a subdirectory would print an error 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. It can fail over to another host if the current one fails, and optionally distributes requests across multiple servers.

These features apply only to the signdocument command and are only supported with -protocol HTTP (the default) or -protocol REST.

Hosts and Failover

Use -hosts to specify multiple SignServer hosts as a comma-separated list. If the connection to one host fails, either directly or because of a timeout, SignClient tries the next host in the list. Connection failures include cases such as the host is unreachable, SignServer is not running, or the Worker is unavailable.

Use -timeout to set a connection timeout in milliseconds. If a host does not respond within this time, it is treated as a connection failure and the next host is tried.

Failures caused by request issues, such as incorrect input data or wrong credentials, are not treated as connection failures and will not trigger failover.

Load Balancing

By default, load balancing is disabled. SignClient uses the first host in the list and only moves to the next if that host fails.

To enable round-robin load balancing, specify -loadbalancing ROUND_ROBIN. The first host is selected randomly from the list. In batch mode (when -indir is specified), each subsequent request is sent to the next host in the list, wrapping around when the end of the list is reached.

Example Use Cases

Basic Signing

Sign a small XML string passed directly on the command line:

signdocument -workername XMLSigner -data "<root/>"

Sign a file by providing its path, and the result is written to standard output:

 signdocument -workername XMLSigner -infile /tmp/document.xml

HTTPS with Server Certificate Validation

Connect over HTTPS and validate the server certificate using a truststore. Worker is identified by ID rather than name:

signdocument -workerid 2 -data "<root/>" -truststore truststore.jks -truststorepwd changeit

Connect over HTTPS and authenticate the client using a keystore containing a private key and certificate:

signdocument -workerid 2 -data "<root/>" -keystore superadmin.jks -keystorepwd foo123

This is mutual TLS so both sides present certificates.

Sending Additional Metadata

Pass extra key-value metadata to the signer alongside the data. Metadata is used when the worker is configured to require or accept additional input parameters.

signdocument -workerid 2 -data "<root/>" -metadata param1=value1 -metadata param2=value2

Batch Signing with File Removal

Sign all files in an input directory, writing results to an output directory using 5 parallel threads. Successfully processed input files are removed from the input directory after signing:

signdocument -workerid 3 -indir ./input/ -removefromindir -outdir./output/ -threads 5

Batch Signing with Failover

Sign all files in an input directory using two hosts. If the primary host is unavailable, SignClient automatically fails over to the secondary host.

signdocument -workerid 3 -indir ./input/ -outdir ./output/ -threads 5 -hosts primaryhost,secondaryhost

Signing Using the REST Protocol

Use the REST interface instead of the default HTTP interface:

signdocument -protocol REST -workername XMLSigner -data "<root/>"

Use the REST interface to sign a file specified by path:

signdocument -protocol REST -workername XMLSigner -infile /tmp/document.xml

Signing from Standard Input (stdin)

Pipe binary or text data into signdocument via stdin. Useful for scripting or when the data is generated by another process.

cat data.bin | signclient signdocument -workername XMLSigner -stdin

Large file handling via stdin is only supported with -protocol HTTP (the default).

Batch Signing with Round-robin Load Balancing

Distribute signing requests across three hosts using round-robin load balancing with a 5-second timeout. The first host is chosen randomly, and subsequent requests cycle through the list.

signdocument -workerid 3 -indir ./input/ -outdir ./output/ -threads 5 -hosts host1,host2,host3 -loadbalancing ROUND_ROBIN -timeout 5000

Client Authentication using a PKCS#11 Hardware Token

Authenticate using a key stored on a hardware security module (HSM) or smart card via a PKCS#11 library. The -keystore flag points to the PKCS#11 shared library (.so file). The first available key alias in the token is used.

signdocument -workerid 2 -data "<root/>" -keystoretype PKCS11 -keystore libcryptoki.so

PKCS#11 Authentication

Same as above, but prompt the user to select a key alias from the PKCS#11 token interactively. Useful when multiple keys are present on the token.

signdocument -workerid 2 -data "<root/>" -keystoretype PKCS11 -keystore libcryptoki.so -keyaliasprompt

Targeting a Worker by Servlet Path

Address a Worker directly using its servlet URL path instead of specifying -workername or -workerid. Useful in non-standard deployments or when constructing URLs programmatically.

signdocument -data "<root/>" -servlet /signserver/worker/XMLSigner