gpgconfig configuration utility reference
Synopsis
gpgconfig [command] [--options]
Commands
- checkgrant
- Checks the current grant status
- getgrant
- Obtains a new grant or refreshes a grant
- 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
- revokegrant
- Revokes a grant
- setgrant
- Sets a grant by providing an authentication token
- seturl
- Sets the virtual HSM and authentication server URLs
- 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
- update
- Updates a CodeSign Protect client
- version
- Displays the version number and build timestamp
To get command help, run gpgconfig [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.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
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 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:
gpgconfig 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.
- --csp
- Modify the 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.
- --revoke
- Revokes an existing grant.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
jwtsign
options
Sign a token for use with JWT.
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.
- --csp
- Modify the CSP configuration store (Windows only).
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:
gpgconfig 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.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
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 gpgconfig. 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.
- --csp
- Modify the CSP configuration store (Windows only).
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.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
setgrant
options
auto
, disable
, and url
.
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.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
storekey
options
- --label:<label>
- The label of the target environment.
- --uid:<user id>
- The uid of the source secret key in the local gpg keychain.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
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.
- --default
- Modify the PKCS#11 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.
- --default
- Modify the PKCS#11 configuration store.
- --csp
- Modify the CSP configuration store (Windows only).
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.