tkdriverconfig configuration utility reference

Synopsis

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

jwtsign

Sign a token for use with JWT.

jwtverify

Verify a JWT.

Common commands

Command

Description

sync

Synchronizes local data with the service backend.

unsync

Removes local data.

getcertificate

Retrieves a certificate.

getpublickey

Retrieves the public key of a certificate.

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

getcertificate options

Retrieves a certificate and/or certificate chain. Use the list 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.

  • Run tkdriverconfig getcertificate with no options to invoke interactive mode.

Option

Description

--filename:<file>

Output file for the certificate.

--chainfile:<file>

Output file for the certificate chain (PEM format only).

--format:<format>

Output file format (default is PEM). Options: PEM, DER.

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

--force

Overwrite the output files if they already exist.

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 tkdriverconfig getgrant with no options to invoke interactive mode.

  • 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:

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

getpublickey options

Retrieves the public key of a certificate. Use the list 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.

Run tkdriverconfig getpublickey with no options to invoke interactive mode.

Option

Description

--filename:<file>

Output file for the public key.

--format:<PEM|DER>

Output file format (Default: PEM).

--label:<label>

Label of the public key to retrieve.

--force

Overwrite the output files if they already exist.

jwtsign options

Sign a token for use with JWT.

Run tkdriverconfig jwtsign with no options to invoke interactive mode.

Option

Description
--header:<header> File containing Header for JSON Web Token.
--payload:<payload> File containing Payload for JSON Web Token.
--output:<file> Filename to store the signature in.
--label:<label> Label of the key to use for signing.

jwtverify options

Verifies a signed JWT Token signed by the jwtsign command.

Run tkdriverconfig jwtverify with no options to invoke interactive mode.

NOTE  This command cannot verify a signature created with external tools

Option

Description
--filename=<file> File to verify.
--label=<label> Label of the key to use for verification.
--keysize=<size> The size of the key that was used to sign the JWT (Options: 256, 384, 512).

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 .

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:

tkdriverconfig 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 tkdriverconfig proxy with no options to invoke interactive mode.

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 tkdriverconfig. 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 tkdriverconfig setgrant with no options to invoke interactive mode.

  • 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 tkdriverconfig seturls with no options to invoke interactive mode.

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 tkdriverconfig sign with no options to invoke interactive mode.

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.

--force

Overwrite the output file if it already exists.

storekey options

Moves a private key and certificate from the macOS keychain to the server and associates it with the environment specified with -label.

Option

Description

--label:<label>

The label of the target environment.

--context:<ctx>

The context of the key to store, if the environment holds multiple keys.

--identity:<cn>

The CN of the source certificate in the macOS keychain.

--force

Accept all warning prompts.

sync options

Synchronizes the macOS keychain with the Venafi CodeSign Protect server.

Option

Description

--clear

Completely removes any stored configuration.

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 macOS local keychain data.

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 tkdriverconfig verify with no options to invoke interactive mode.

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.

version options

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