pki(1)

NAME
pki - Command-Line Interface for accessing Certificate System services.

SYNOPSIS
pki [CLI options] <command> [command arguments]

DESCRIPTION

pki provides a command-line interface allowing clients to access various services on the Certificate System server. These services include certificates, groups, keys, security domains, and users.

OPTIONS

-c <security database password>
    Specifies the security database password.

-d <security database location>
    Specifies the security database location (default: ~/.dogtag/nssdb).

-h <hostname>
    Specifies the hostname (default: localhost).

--help
    Prints additional help information.

-n <nickname>
    Specifies the certificate nickname.

-P <protocol>
    Specifies the protocol (default: http).

-p <port>
    Specifies the port (default: 8080).

-U <URL>
    Specifies the server URL.

-u <username>
    Specifies the username.

-v  Displays verbose information.

--version
    Displays 'pki' CLI version information.

-w <password>
    Specifies the user password.

OPERATIONS
To view available commands and options, simply type pki. Some commands have sub-commands. To view the sub-commands, type pki <command>. To view each command's usage, type pki <command> --help.

  Security Database
The CLI uses a security database to store keys and certificates on the client side. To create a new database execute the following command: pki -d <security database location> -c <security database password> client-init To view certificates in the security database: pki -d <security database location> -c <security database password> client-cert-find To import a certificate into the security database: pki -d <security database location> -c <security database password> -n <certificate nickname> client-cert-import --cert <certificate file> To delete a certificate from the security database: pki -d <security database location> -c <security database password> client-cert-del <certificate nickname>

  Connection
By default, the CLI connects to a server running on the localhost via the non-secure HTTP port 8080. To specify a different server location, use the appropriate arguments to give a different host (-h), port (-p), or connection protocol (-P). pki -P <protocol> -h <hostname> -p <port> <command> Alternatively, the connection parameters can be specified as a URL: pki -U <URL> <command> where the URL is of the format <protocol>://<hostname>:<port>.

  Authentication
Some commands require authentication. These are commands that are restricted to particular sets of users (such as agents or admins) or those operations involving certificate profiles that require authentication. To execute a command without authentication: pki <command> To authenticate with a username and password: pki -u <username> -w <password> <command> To authenticate with a client certificate: pki -d <security database location> -c <security database password> -n <certificate nickname> <command>

  Viewing Certificates
Certificates can be viewed anonymously. To list all certificates in the CA: pki ca-cert-find It is also possible to search for and list specific certificates by adding a search filter. Use pki ca-cert-find --help to see options. For example, to search based on issuance date: pki ca-cert-find --issuedOnFrom 2012-06-15 To view a particular certificate: pki ca-cert-show <certificate ID>

  Revoking Certificates
Revoking, holding, or releasing a certificate must be executed as an agent user. To revoke a certificate: pki <agent authentication> ca-cert-revoke <certificate ID> To place a certificate on hold temporarily: pki <agent authentication> ca-cert-hold <certificate ID> To release a certificate that has been placed on hold: pki <agent authentication> ca-cert-release-hold <certificate ID>

  Certificate Requests
To request a certificate, first generate a certificate request in PKCS #10 or CRMF, and store this request in the XML template file, of the profile type the request relates to. The list of profiles can be viewed using the CLI command: pki ca-cert-request-profile-find The XML template file for a profile type can be created by calling the ca-cert-request-profile-show CLI command. For example: pki ca-cert-request-profile-show <profileID> --output <file to store the XML template> will store the XML template of the request in the specified output file. Then, fill in the values in the XML file and submit the request for review. This can be done without authentication. pki ca-cert-request-submit <request file> Then, an agent needs to review the request by running the following command: pki <agent authentication> ca-cert-request-review <request ID> --file <file to store the certificate request> The certificate request, as well as the defaults and constraints of the enrollment profile, will be stored in the output file provided by the --file option. The agent can examine the file and override any values if necessary. To process the request, enter the appropriate action when prompted: Action (approve/reject/cancel/update/validate/assign/unassign): Alternatively, the agent can process the request in a single step with the following command: pki <agent authentication> ca-cert-request-review <request ID> --action <action>

  Group Management Commands
All group commands must be executed as the subsystem administrator. Type pki <subsystem>-group to view all group management commands for the subsystem. To list groups in CA, use pki ca-group-find. It is possible to select the page size to limit the number of entries returned. To list all groups: pki <admin authentication> ca-group-find To view a particular group: pki <admin authentication> ca-group-show <group ID> To add a group: pki <admin authentication> ca-group-add <group ID> --description description To delete a group: pki <admin authentication> ca-group-del <group ID> To add a user to a group: pki <admin authentication> ca-group-member-add <group ID> <Member ID> To delete a user from a group: pki <admin authentication> ca-group-member-del <group ID> <Member ID>

  Security Domain Commands
pki can be used to access certain information from the security domain. To get an installation token (used when installing a new subsystem within a security domain): pki <security domain admin authentication> securitydomain-get-install-token --hostname <hostname> --subsystem <subsystem> To show the contents of the security domain: pki <security domain admin authentication> securitydomain-show

  User Management Commands
All user commands must be executed as the subsystem administrator. Type pki <subsystem>-user to view all user management commands for the subsystem. To list users in CA, use pki ca-user-find. It is possible to select the page size to limit the size of the results. To list all users: pki <admin authentication> ca-user-find To view a particular user: pki <admin authentication> ca-user-show <user ID> To add a user: pki <admin authentication> ca-user-add <user ID> --fullName <full name> To delete a user: pki <admin authentication> ca-user-del <user ID>

FILES
/usr/bin/pki

AUTHORS
Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, and Matthew Harmsen <mharmsen@redhat.com>. pki was written by the Dogtag project.

COPYRIGHT
Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.