13.18 winpki and pkid Command Reference

Use winpki (on Windows) or pkid (on UNIX systems) to configure, start, and stop the PKI Services Manager service, and to check certificate validity and allowed identities.

Synopsis

Windows: winpki [command [command args]] [options...]

UNIX: pkid [command [command args]] [options...]

command = start | stop | restart | reload | ping | validate <cert>

options = [-b path] [-c cert] [-d level] [-f file] [-h] [-i] [-k][-m path] [-p] [-o key=value] [-t host] [-u user] [-V] [-w]

Commands

start

Starts the service.

stop

Stops the service.

restart

Stops and restarts the service.

reload

Reloads the configuration without stopping the service. Reloading the configuration also clears the internal in-memory caches used for downloading certificates and CRLs. Although certificate and CRL lifetimes are honored by the cache, it might be necessary to clear these manually if a certificate or CRL has been updated at its source before it has expired. Note: Most settings become available when you reload; however some settings require a restart.

ping

Displays service status and the port used by the service.

validate certificate

Validates a certificate and optionally provides information about allowed identities. The service must be running. For example, to determine if sample.crt is valid (UNIX syntax):

pkid validate sample.crt

Use -u, -t, or -w after the certificate name to get information about allowed identities for the specified certificate. For example, to determine if the user joe can authenticate using sample.cer (Windows syntax):

winpki validate sample.cer -u joe

Options

Both short (-b path) and long (--baseDir path) options are shown.

-b path --baseDir path

Specifies the data directory used for PKI Services Manager configuration.

-c cert--cert cert

Validates the specified certificate. This option is available when the service is not running. Use the validate command to validate certificates when the service is running.

-d level--debug level

Specifies the amount of information sent to the log. Allowed values are: 'error', 'warn', 'info', 'debug', and 'trace'. The default is 'error'.

-f file--config_file file

Launches using a non-default configuration file.

-h --help

Displays a brief summary of command options.

-i --init

This option is rarely needed. It initializes PKI Services Manager, which creates a key pair for the server, and creates user data directories and files. Initialization happens automatically during installation on UNIX systems and on first run on Windows systems. Using this option has no effect if your system is already initialized. Note: You can create new keys by deleting the existing keys (pki_key and pki_key.pub), and then using this option. Existing configuration files are not affected.

-k --check-config

Checks for errors in your configuration and map files and then quits.

-m path--migrate path

Migrates certificate authentication settings from Reflection and F-Secure configuration files. If path specifies a directory, PKI Services Manager looks for server (sshd2_config) and client (ssh2_config) configuration files in that directory and migrates settings from those files. If path specifies a file, PKI Services Manager migrates the settings in the specified file. Full path information is required for both files and directories. Note: If the pki_config file in the destination folder already has a trust anchor configured, no migration occurs. This helps ensure that the migration won't overwrite modifications you have already configured.

Settings are migrated to the pki_config and pki_map files used by PKI Services Manager. If you use the -b switch, files with your migrated settings are created in the specified directory. If you omit this switch, the files are created in the default PKI Services Manager configuration directory.

A migration log is created in the logs directory located in the PKI Services Manager data directory. By default, this log records at a level of 'info' which shows if errors or warnings occurred. The level can be elevated using -d.

-o key=value--option key=value

Sets any option that can be configured using a configuration file keyword. Options configured this way override configuration file settings. For a list of keywords and their meanings, see pki_config. Syntax alternatives are shown below. Use quotation marks to contain expressions that include spaces.

-o key1=value
-o key1="sample value"
-o "key1 value"
-o key=value1,value2
-o key="value1, value2"

To configure multiple options, use multiple -o switches.

-o key1=value -o key2=value
-p --showkey

Displays the public fingerprint and shows the full path and key name.

Use this option after the certificate name following a validate command. PKI Services Manager reads the map file(s) and reports whether the specified host is an allowed identity for the host certificate being validated.

-t host--hostName host

Use this option after the certificate name following a validate command. PKI Services Manager reads the map file(s) and reports whether the specified host is an allowed identity for the host certificate being validated.

-u user--userID user

Use this option after the certificate name following a validate command. PKI Services Manager reads the map file(s) and reports whether the specified user is an allowed identity for the user certificate being validated. If you include a server name (in the form user@server), PKI Services Manager reports on whether the user is allowed to authenticate to the specified server. If you specify only a user name, PKI Services Manager tests whether the user is allowed to authenticate with this certificate without checking for host-specific conditions.

-V --version

Displays the product name and version.

-w [host] --whoAmI [host]

Use this option after the certificate name following a validate command. PKI Services Manager reads the identity map file(s) and returns a list of all allowed identities for the certificate being authenticated. If you specify a server name after this option, the list is limited to allowed users for connections to that server. If no server name is specified, PKI Services Manager doesn't check for server-specific conditions.