pkcs11config configuration utility reference

Synopsis

pkcs11config [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

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

--machine

Uses the machine grant rather than the user grant.

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

--machine

Uses the machine grant rather than the user grant.

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

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

--machine

Requests a grant for the machine rather than a user. Before using this option, review Local machine grant.

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

--machine

Uses the machine grant rather than the user grant.

jwtsign options

Sign a token for use with JWT.

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

--machine

Uses the machine grant rather than the user grant.

jwtverify options

Verifies a signed JWT Token signed by the jwtsign command.

Run pkcs11config 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).

--machine

Uses the machine grant rather than the user grant.

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.

--machine

Lists objects available to the machine, not a specific user.

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:

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

--machine

Performs configuration options for the machine rather than the user.

proxy options

Configures proxy settings to use when communicating with backend APIs.

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

--machine

Modifies the machine configuration rather than the user configuration.

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.

--machine

Resets the machine configuration.

revokegrant options

Revokes any configured grants.

Option

Description

--clear

Completely removes any stored configuration after revoking the grant.

--force

Forces grant revocation without confirmation.

--machine

Revokes the local machine grant rather than the current user grant.

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

--machine

Sets the grant for the machine rather than the user. Before using this option, review Local machine grant.

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

--machine

Sets URLs for the machine configuration rather than the user configuration.

sign options

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

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

--machine

Uses the machine grant rather than the user grant.

storekey options

Stores the private key along with the matching public key or certificate on 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.

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

--force

Accept all warning prompts.

--machine

Uses the machine grant rather than the user grant.

trace options

Manages settings for diagnostics and troubleshooting. For example usage of this command, see Enabling and disabling PKCS#11 trace logging.

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.

--module:<file>

Sets the location of the PKCS#11 library.

--pkcs11:<file>

Sets the PKCS#11 API trace file path and filename prefix.

--machine

Sets the trace options for the machine.

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.

--machine

Manages trust for the machine.

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 pkcs11config 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 pkcs11config utility and the build timestamp. No additional options.