Rest PKI Client Tool
The Rest PKI client tool is a command line application to perform signatures, among other operations, in desktop applications using Rest PKI Core. For instance, to sign a PDF file:
rpkitool document.pdf --cert-cpf 11111111111 --overwrite
The client tool is a single executable file that can be downloaded below:
For other platforms, click here.
Configuration
To use the client tool, you must configure the endpoint of the Rest PKI Core instance and also the API Key. This can either be done with environment variables or with command parameters.
With the environment variables RestPki__Endpoint and RestPki__ApiKey:
RestPki__Endpoint=https://restpki.yourcompany.com/
RestPki__ApiKey=YOUR_API_KEY
With the command parameters --endpoint and --api-key:
rpkitool ... --endpoint https://restpki.yourcompany.com/ --api-key YOUR_API_KEY
Note
API keys for Rest PKI Core usually have a pipe character (|), for instance yourapp|12345678 (but longer). If this creates problems
for your environment, you can use only the part after the pipe character, for instance only 12345678 in the previous example.
Optional configurations
By default, the timeout when making API calls to the Rest PKI Core instance is 5 minutes. It may be necessary to increase this value if you're signing
very large files or under slow internet connection scenarios. You can customize this with the environment variable RestPki__TimeoutSeconds:
RestPki__TimeoutSeconds=600
Or with the command paramerer --timeout:
rpkitool ... --timeout 600
The above examples would set the timeout to 10 minutes (600 seconds).
Commands
Each operation that can be performed with the client tool is a command. The following commands are available:
- sign - Signs a document
- list-certs - Lists the certificates on the current user's certficate store
- allocate-keys - Allocates document keys
Output / exit codes
If the command is executed successfully, the exit code will be 0 and any eventual output will be written to stdout.
If an error occurs, the exit code will be >= 1 and information about the error will be written to stderr. See below the list of exit codes.
| Exit code | Description |
|---|---|
| 0 | Success |
| 1 | Unspecified error |
| 2 | Bad syntax |
| 3 | Missing API parameters |
| 4 | File not found |
| 5 | Unacceptable filename |
| 6 | File rejected |
| 7 | Certificate not specified |
| 8 | Certificate not found |
| 9 | Certificate rejected |
| 10 | Bad --count argument |
| 12 | Rest PKI API exception |
Logging
By default, log files are written to:
- On Windows:
%LOCALAPPDATA%\Lacuna Software\Rest PKI Tool\Logs(e.g. C:\Users\USERNAME\AppData\Local\Lacuna Software\Rest PKI Tool\Logs) - On Linux:
~/.local/share/rpkitool/logs(e.g. /home/USERNAME/.local/share/rpkitool/logs)
You can override this behavior by setting the log directory on the environment variable Serilog__WriteToPath.
By default, only logs with severity Warning or higher are written. You can override this behavior by setting the environment variable
Serilog__MinimumLevel__Default. The log levels, from least to most severe, are:
VerboseDebugInformationWarningErrorFatal