gpgconfig configuration utility reference

Synopsis

gpgconfig [command] [--options]

Configuration commands

Command

Description

checkgrant

Checks the current grant status.

getgrant

Obtains a new grant or refreshes a grant.

setgrant

Sets a grant by providing an authentication token.

revokegrant

Revokes a grant.

trust

Manages trust for virtual HSM and authentication server access.

seturls

Sets the virtual HSM and authentication server URLs.

option

General configuration management.

proxy

Sets HTTP proxy options.

reset

Resets the client configuration.

update

Updates the CodeSign Protect client.

Signing and verification commands

Command

Description

list

Lists all available objects.

sign

Create a signature for a file.

verify

Verify a file signature.

Common commands

Command

Description

sync

Synchronizes local data with the service backend.

unsync

Removes local data.

storekey

Uploads a certificate, key pair, or both to a per-user environment.

trace

Trace settings for troubleshooting

health

Checks client configuration health. No additional options.

version

Displays the version number and build timestamp. No additional options.

help

Displays general usage information.

To get specific command help, run gpgconfig [command] -h.

Options

checkgrant options

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

Option

Description

--days:<d>

Grant is not considered valid if it expires within <d> days.

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.

getgrant options

Obtains a code signing grant from the authentication server.

  • If a refresh token is stored, it will be used to renew the grant, ignoring any other provided credentials, unless -force is used.

  • Run gpgconfig getgrant with no options to invoke interactive mode.

    NOTE  Interactive mode is disabled when run as part of a script.

  • Credentials may be specified with -username and -password arguments, or with the -jwtfile argument.

  • If URL arguments are specified, the given URL(s) will be configured and used to obtain the grant.

TIP  Use the following command for a quick start on getting a grant:

gpgconfig getgrant -hostname:<codesign-protect-hostname> -username:<user> -password:<pw>

Option

Description

Authentication options

--username:<user>

Authentication username.

--password:<pw>

Authentication password.

--jwtfile:<jwt>

Name of the file that contains a signed JWT (replaces username and password). A JWT Mapping must first be created in Trust Protection Platform.

Proxy options

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

--noproxy=<list>

A list of host names that should not use the proxy.

URL options

--hostname:<hostname>

Automatically detects and sets URLs using the specified Venafi CodeSign Protect host name.

--authurl:<url>

Sets the authentication server URL (example: https://<tpp-server-url>/vedauth). This can also be set using the seturls option.

--hsmurl:<url>

Sets the virtual HSM backend URL (example: https://<tpp-server-url/vedhsm). This can also be set using the seturls option.

--updateurl:<url>

Sets the client update server URL (example: https://<tpp-server-url>/csc). This can also be set using the seturls option.

Advanced options

--force

Forces getting a new grant; never refreshes.

health options

Performs health checks to detect common configuration issues.

Run gpgconfig health with no options to run a health check with all options.

Option

Description

--drivers

Checks for a valid grant and valid client configuration.

--grants

Checks for a valid grant only.

--updates

Checks to see if an updated version of the client is available.

--urls

Checks the URLs to the CodeSign Protect server.

list options

Displays a list of all available objects. Defaults to listing certificates and public keys from all available environments.

This command can be used to obtain the --label name that other commands require.

NOTE  If list 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 .

If no grant exists, interactive prompts will be given for the user to obtain a grant.

NOTE  Interactive mode is disabled when run as part of a script.

Option

Description

--env:<env-list>

Only show environments of types specified (options: all, apple, certificate, gpg, csp, net, keypair)

--type:<type-list>

Only show objects of types specified (options: all, private, public, certificate)

--sort=<column>

Sort on the specified column (options: label, environment, object, keytype, detail, context, keyid, handle)

--grouped

Group related objects

--table

Output in table format.

--number

Display a number for each item.

--reverse

Reverse the sort order.

--force

Do not wait and reload if objects are pending creation.

option options

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

Creates filters to apply when using list. Example filter:

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

Option

Description

--clear

Clears the value for <name>.

--show

Displays the value for <name> or all if no -name specified.

--name:<name>

Name to set, show, or clear.

--value:<value>

Value to set.

proxy options

Configures proxy settings to use when communicating with backend APIs.

Run gpgconfig proxy with no options to invoke interactive mode.

NOTE  Interactive mode is disabled when run as part of a script.

Option

Description

--proxymode:<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 gpgconfig. Will bypass any system proxy settings.

  • url: Uses a specified URL. Use --url:<url> to set the proxy URL.

--proxyurl:<url>

URL of the proxy server to use. Implies --proxymode:url.

--noproxy:<url>

A list of host names that should not use the proxy.

--show

Displays current proxy settings.

reset options

Resets the client configuration.

Option

Description

--all

Reset the configuration for all CodeSign Protect client stores on this system.

--current

Reset only the configuration for the current client (default).

--preserve

Preserve the configured URLs.

revokegrant options

Revokes any configured grants.

Option

Description

--clear

Completely removes any stored configuration after revoking the grant.

--force

Forces grant revocation without confirmation.

setgrant options

Sets the grant using an authentication token that has already been obtained from the authentication server.

  • If a refresh token is provided, it will be used to renew the grant, ignoring any other provided credentials, unless -force is used.

  • Run gpgconfig setgrant with no options to invoke interactive mode.

    NOTE  Interactive mode is disabled when run as part of a script.

  • If URL arguments are specified then the given URL(s) will be configured and used to verify and refresh the grant.

Option

Description

Authentication token options

--refresh:<token>

Refresh token

--token:<token>

Authentication token

Proxy options

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

--noproxy=<list>

A list of host names that should not use the proxy.

URL options

--hostname:<hostname>

Automatically detects and sets URLs using the specified Venafi CodeSign Protect host name.

--authurl:<url>

Sets the authentication server URL (example: https://<tpp-server-url>/vedauth). This can also be set using the seturls option.

--hsmurl:<url>

Sets the virtual HSM backend URL (example: https://<tpp-server-url/vedhsm). This can also be set using the seturls option.

--updateurl:<url>

Sets the client update server URL (example: https://<tpp-server-url>/csc). This can also be set using the seturls option.

Advanced options

--force

Forces getting a new grant; never refreshes.

seturls options

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

Run gpgconfig seturls with no options to invoke interactive mode.

NOTE  Interactive mode is disabled when run as part of a script.

Option

Description

URL options

--hostname:<hostname>

Automatically detects and sets URLs using the specified Venafi CodeSign Protect host name.

Advanced options

--authurl:<url>

Sets the authentication server URL (example: https://<tpp-server-url>/vedauth). This can also be set using the seturls option.

--hsmurl:<url>

Sets the virtual HSM backend URL (example: https://<tpp-server-url/vedhsm). This can also be set using the seturls option.

--updateurl:<url>

Sets the client update server URL (example: https://<tpp-server-url>/csc). This can also be set using the seturls option.

sign options

Creates a signature for a file using the CodeSign Protect server directly.

Run gpgconfig sign with no options to invoke interactive mode.

NOTE  Interactive mode is disabled when run as part of a script.

NOTE  This command will hash the specified file, sign the hash and store the raw resulting signature. The format of the signature is intended to test key access only and is not compatible with most other tools.

Option

Description

--file:<file>

File to sign.

--label:<label>

Label of the key to use for signing.

--output:<file>

Filename to store the signature in.
--hashalg

Hash algorithm to use for post quantum. Default is SHA2_256).

Available options: SHA2_256, SHA2_384, SHA2_512, SHA3_256, SHA3_384, SHA3_512, SHAKE_128, SHAKE_256, PURE)

NOTE  PURE is a signing mode where the data is not hashed before signing. Instead, the original data is passed directly to the CodeSign Protect server. The size limit is 15MB.

--force

Overwrite the output file if it already exists.

storekey options

Moves a GPG secret key from the local gpg keychain to the server and associates it with the environment specified with -label.

Option

Description

--label:<label>

The label of the target environment.

--uid:<user id>

The uid of the source secret key in the local GPG keychain.

sync options

Synchronizes the GPG keychain with the Venafi CodeSign Protect server.

If no grant exists, interactive prompts will be given for the user to obtain a grant.

NOTE  Interactive mode is disabled when run as part of a script.

Option

Description

--bindir:<file>

Specifies the directory that contains the GnuPG executables. Autodetected if not specified.

--scdpath:<file>

Specifies the directory that contains the VenafiSCD executable. Autodetected if not specified.

trace options

Manages settings for diagnostics and troubleshooting.

Option

Description

--console

Enable/disable applies to console.

--log

Enable/disable applies to trace log.

--disable

Disables console or file tracing.

--enable

Enables console or file tracing.

--filename:<file>

Sets the trace file path and filename prefix.

--output:<out>

Sets the console output target. Can be stderr or stdout.

--show

Shows existing trace settings.

trust options

Manages certificate trust store. Trust is required to communicate with the CodeSign Protect server.

Option

Description

--check

Checks if the configured CodeSign Protect is trusted.

--delete:<name>

Delete certificate with subject containing <name>.

--filename:<file>

PEM certificate file to import certificates from.

--force

Forces import without confirmation.

--hostname:<url>

Host name or URL to retrieve certificates from.

--show

Shows existing certificates in trust store.

unsync options

Removes previously synchronized local GPG keychain data.

If no grant exists, interactive prompts will be given for the user to obtain a grant.

NOTE  Interactive mode is disabled when run as part of a script.

Option

Description

--bindir:<file>

Specifies the directory that contains the GnuPG executables. Autodetected if not specified.

--scdpath:<file>

Specifies the directory that contains the VenafiSCD executable. Autodetected if not specified.

update options

Updates CodeSign Protect clients. Requires the Code Signing Client Distribution component be active.

Option

Description

--latest

Download and install the latest available version, unless it is already installed.

--architecture:<arch>

Override the detected architecture. Available values: x86_64, x86_32, arm64.

--type:<type>

Override the detected package type. Available types: msi, rpm, deb, dmg.

--out:<file>

Store the package in the specified output directory and do not install it.

--updateurl:<url>

Client update server URL.

verify options

Verifies a signature created by the sign command.

Run gpgconfig verify with no options to invoke interactive mode.

NOTE  Interactive mode is disabled when run as part of a script.

NOTE  This command cannot verify a signature created with external tools

Option

Description

--filename:<file>

File to verify.

--input:<file>

File name that holds the signature.

--label:<label>

Label of the key to use for verification.
--hashalg

Hash algorithm to use for post quantum. Default is SHA2_256).

Available options: SHA2_256, SHA2_384, SHA2_512, SHA3_256, SHA3_384, SHA3_512, SHAKE_128, SHAKE_256, PURE)

version options

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