CSPConfig.exe configuration utility reference

Synopsis

CSPConfig [command] [--options]

Commands

checkgrant
Checks the current grant status
getcertificate
Retrieves a certificate
getgrant
Obtains a new grant or refreshes a grant
getpublickey
Retrieves the public key of a certificate
grant
All grant commands
jwtsign
Sign a token for use with JWT
listobjects
Lists all available objects
option
General configuration management
proxy
Sets HTTP proxy options
reset
Resets the client configuration
revokegrant
Revokes a grant
setgrant
Sets a grant by providing an authentication token
seturl
Sets the virtual HSM and authentication server URLs
sign
Create a signature for a file
storekey
Uploads a certificate, key pair, or both to a per-user environment
sync
Synchronizes local data with the server backend
trace
Trace settings for troubleshooting
trust
Manages trust for virtual HSM and authentication server access
unsync
Removes local data
update
Updates a CodeSign Protect client
verify
Verify a file signature
version
Displays the version number and build timestamp

To get command help, run CSPConfig [command] --h.

Options

checkgrant options

Checks if the system has a valid grant and displays grant information.

--days:<d>
Grant is not considered valid if it expires within <d> days.
--machine
Checks the local machine store rather than the current user store.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

Return code 0 indicates a grant has been configured

Return code 1 indicates a missing or expired grant

This command is designed to allow automated systems, such as a builder or monitoring system, to programmatically check if the grant is still valid in preflight checks.

getcertificate options

Retrieves a certificate and/or certificate chain. Use the ListCertificates command to obtain list of available certificates.

If the --chainfile and --file argument specify the same filename, the certificate will be stored first in the file, followed by the chain and PEM format will be used, ignoring any --format setting.

This command is useful when using signing applications that require the certificate in a file on the signing server. See also getpublickey.

--chainfile:<file>
Output file for the certificate chain (PEM format only).
--file:<file>
Output file for the certificate.
--format:<PEM|DER>
Output file format (Default: PEM).
--label:<label>
Label of the certificate to retrieve.
--rootfirst
Writes the root first when writing the chain. The default is to write the intermediate first.
--split
Splits the chain into separate files, one certificate per file. Inserts a number before the extension, if one is provided.
--verbose
Outputs subject and issuer before the PEM block.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

getgrant options

Obtains a new grant if no refresh token exists. If one exists, the existing grant will be renewed. To always obtain a new grant, use --force. If --force is used while having an existing refresh token, the existing grant will first be revoked.

By using the --authurl and --hsmurl switches with this option, initial setup can be done by just using getgrant. See the following example:

CSPConfig getgrant --force --username=sample-user --password=Passw0rd --hsmurl=https://TPP_Server_URL/vedhsm/ --authurl=https://TPP_Server_URL/vedauth/
--authurl:<url>
Sets the authentication server URL. This can also be set using the seturl option.
--autologon
Requests a new grant using credentials that were used to log on to the local system. Client and server must be in the same domain.
--force
Forces getting a new get grant; never refreshes.
--hsmurl:<url>
HSM backend URL. This can also be set using the seturl option.
--password:<pw>
Authentication password.
--proxymode:<mode>
Enables or disables using a proxy server for communication. Available modes: auto, disable, url.
--proxyurl:<url>
URL of the proxy server to use. Implies --proxymode:<url>.
--username:<user>
Authentication username.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

getpublickey options

Retrieves the public key of a certificate. Use the listcertificates command to obtain list of available certificates. This command is useful when using signing applications that require the public key in a file on the signing server. See also getcertificate.

--file:<file>
Output file for the public key.
--format:<PEM|DER>
Output file format (Default: PEM).
--label:<label>
Label of the public key to retrieve.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD for GnuPG configuration store.
--csp
Use CSP configuration store (Windows only).

grant options

Grant-related functions. Use -h with the options to get option-specific help. The getgrant, revokegrant, and checkgrant commands are shortcuts for this command.

--check
Checks if the system has a valid grant.
--get
Obtains a new grant.
--machine
Stores the configuration values to the machine configuration store rather than the user configuration store.
--revoke
Revokes an existing grant.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

jwtsign options

Sign a token for use with JWT.

--label:<label>
Label of the key to use for signing
--header:<header>
File containing Header for JSON Web Token
--output:<file>
Filename to store the signature in
--payload:<payload>
File containing Payload for JSON Web Token
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

listobjects options

Queries the HSM backend server and returns a list of certificates and public keys from all available environments.

This command is useful in conjunction with getpublickey and getcertificate. It can be used to obtain the --label name they require.

NOTE  If listobjects has a filter applied, only the objects that match the filter will be returned. A notice will appear at the bottom of the results if a filter is applied. Filters are created using the option .

--env:<env-list>
Show only Environments of types specified in <env-list>. Available types are all, apple, cert, gpg, net, keypair, and key.
--grouped
Group related objects
--table
Output in table format.
--type:<type-list>
Show only objects of types specified in <type-list>. Available types are all, priv, pub, cert, and key.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

option options

Manages configuration options. Provides direct management of all configuration options, including options set through other commands, such as seturl.

Creates filters to apply when using listobjects. Example filter:

CSPConfig option --name:"Filter Name" --value:"<environment-label>"

--clear
Clears the value for <name>.
--name:<name>
Name to set, show, or clear.
--show
Displays the value for <name> or all if no -name specified.
--value:<value>
Value to set.
--Silent:<value>
Enables or disables dialogs in the UI. Set to 1 to disable the dialogs.
--machine
Stores the configuration values to the machine configuration store rather than the user configuration store.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

proxy options

--mode:<mode>
Enables or disables using a proxy server for communication. Available modes:
auto: Uses the system proxy settings. This is the default.
disable: Disables the proxy for CSPConfig. Will bypass any system proxy settings.
url: Uses a specified URL. Use --url:<url> to set the proxy URL.
--url:<url>
URL of the proxy server to use. Implies --mode:url.
--show
Displays current mode and, if applicable, the proxy URL.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

reset options

Resets the client configuration.

--all
Reset the configuration for all CodeSign Protect client stores on this system.
--current
Reset only the configuration for the current client (default)
--preserve
Preserves the configured URLs
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

revokegrant options

Revokes any configured grants.

--clear
Deletes a configuration file (or registry entry on Windows) created by a LIBHSMINSTANCE environment variable. For an example, see Using libhsm with multiple grants concurrently.
--force
Forces the grant to be revoked.
--machine
Revokes the local machine grant rather than the current user grant.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

setgrant options

--force
Forces getting a new grant. Never refreshes.
--host:<hostname>
Automatically detect URLs using the specified hostname.
--proxymode:<mode>
Enables or disables using a proxy server for communication. Available modes are auto, disable, and url.
--refresh:<token>
Refresh token
--token:<token>
Authentication token

seturl options

Configures the virtual HSM and authentication server URLs. This command is useful to change existing server URLs if the authentication server or virtual HSM URLs change.

--authurl:<url>
URL of the Trust Protection Platform authentication server.
--hsmurl:<url>
URL of the Trust Protection Platform virtual HSM server.
--machine
Stores the configuration values to the machine configuration store rather than the user configuration store.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

sign options

Creates a signature for a file.

--file:<file>
File to sign.
--label:<label>
Label of the key to use for signing.
--output:<file>
Filename to store the signature in.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.
--csp
Modify the CSP configuration store (Windows only).

storekey options

--contex:<ctx>
The context of the key to store, if the environment holds multiple keys.
--force
Accept all warning prompts.
--label:<label>
The label of the target environment.
--password:<pw>
The password needed to decrypt the private key file.
--private:<file>
The file containing the private key (PFX/P12 or PEM format). If uploading a PEM, the Private Key and Certificate must be in separate files.
--public:<file>
The file containing the public key or certificate (PEM format). If uploading a PEM, the Private Key and Certificate must be in separate files.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

sync options

Synchronizes the certificate store with the certificates available for the user. No additional options.

trace options

Manages settings for diagnostics and troubleshooting.

--console
Enable/disable applies to console.
--disable
Disables console or file tracing.
--enable
Enables console or file tracing.
--file:<file>
Sets the trace file path and filename prefix.
--log
Enable/disable applies to trace log.
--output:<out>
Sets the console output target. Can be stderr or stdout.
--show
Shows existing trace settings.
--pkcs11:<file>
Sets the PKCS#11 API trace file path and filename prefix.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.
--csp
Modify the CSP configuration store (Windows only).

trust options

Manages certificate trust store. Trust is required to be able to communicate with the authentication server and HSM backend. When trust is established, the certificates are stored in the in the user configuration store by default.

When trust is established on Windows, the certificates are stored in CAPI. Trust on Windows only needs to be established if the virtual HSM or authentication server are using a private certificate the Windows system doesn’t already trust (such as through corporate certificate management). When trust is established on non-Windows systems, the certificates by default are stored in ~/.libhsmtrust, unless the user has changed the location via the “CA Trust” configuration value.

--authurl:<url>
Authentication server URL to retrieve certificates from.
--check
Checks if configured HSM backend is trusted.
--delete:<name>
Delete certificate with subject containing <name>.
--file:<file>
PEM certificate file to import certificates from.
--force
Forces import without confirmation.
--hsmurl:<url>
HSM backend URL to retrieve certificates from.
--show
Shows existing certificates in trust store.
--machine
Stores the configuration values to the machine configuration store rather than the user configuration store.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.

unsync options

Removes synchronized local data from the Windows Certificate Store. No additional options.

update options

Updates CodeSign Protect clients. Requires the Code Signing Client Distribution component be installed on the Trust Protection Platform server.

--arch:<arch>
Override the detected architecture. Available values: x86_64, x86_32, arm64.
--latest
Download and install the latest available version, unless it is already installed.
--our:<path>
Store the package in the specified output directory and do not install it.
--type:<type>
Override the detected package type. Available types: msi, rpm, deb, dmg.
--updateurl:<url>
Client update server URL.
--version:<ver>
Download and install the specified version.

verify options

Verifies a file signature.

--file:<file>
File to verify.
--input:<file>
Filename that holds the signature.
--label:<label>
Label of the key to use for verification.
--default
Modify the PKCS#11 configuration store.
--gpg
Use VenafiSCD to modify the GnuPG configuration store.
--csp
Modify the CSP configuration store (Windows only).

version options

Displays the version of the CSPConfig utility and the build timestamp. No additional options.