Provided by: pki-tools_10.6.0-1ubuntu2_amd64 bug


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


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


       The  pki  command  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.


       -c <NSS database password>
              Specifies the NSS database password (mutually exclusive to the '-C' option).

       -C <NSS database password file>
              Specifies  the file which contains the NSS database password (mutually exclusive to
              the '-c' option).

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

       -h <hostname>
              Specifies the hostname (default: hostname of the local machine).

       --help Prints additional help information.

       --ignore-cert-status <list>
              Comma-separated list of ignored certificate validity statuses.

       --message-format <format>
              Message format: xml (default), json.

       -n <client certificate nickname>
              Specifies the nickname for client certificate authentication (mutually exclusive to
              the '-u' option). This authentication requires a security database password.

       --output <folder>
              Folder to store HTTP messages.

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

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

       --reject-cert-status <list>
              Comma-separated list of rejected certificate validity statuses.  PKI subsystem type
              - [CA, KRA, OCSP, TKS, or TPS] (non-case-sensitive).

       -t <type>
              Subsystem type.

              Security token name

       -U <URL>
              Specifies the server URL.

       -u <username>
              Specifies the username for basic authentication (mutually  exclusive  to  the  '-n'
              option). This authentication requires a user password.

       -v, --verbose
              Displays verbose information.

              Displays CLI version information.

       -w <password>
              Specifies the user password (mutually exclusive to the '-W' option).

       -W <client-side password file>
              Specifies the file which contains the user password (mutually exclusive to the '-w'


       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.

       An NSS database is needed to execute commands  that  require  crypto  operations  such  as
       establishing SSL connection.  See pki-client(1) for more information.

       By  default,  the CLI connects to a server running on the local machine 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 URI:

       pki -U <URI> <command>

       where the URI is of the format <protocol>://<hostname>:<port>.

       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 execute a command using basic authentication (i. e. - username/password), see the Basic
       Authentication section of this man page.

       To execute a command using client authentication (i. e. -  client  certificate),  see  the
       Client Authentication section of this man page.

   Basic Authentication
       To authenticate with a username and password:

       pki -u <username> -w <password> <command>

       Rather  than  being exposed in plaintext on the command-line, user passwords may be stored
       in a file instead.  See Client-side Password Files for detailed information.

       To authenticate with a username by obtaining the user password from a client-side password

       pki -u <username> -W <client-side password file> <command>

       Finally,  if  a  username  has  been  specified  on  the command-line, and neither the '-W
       <client-side password file>' nor the '-w  <password>'  options  have  been  utilized,  the
       password will be prompted for.

       To authenticate with a username by interactively prompting for a password:

       pki -u <username> <command>

       Note: Prompting for a user password is not suitable for automated batch processing.

   Client Authentication Setup
       A  client  certificate  associated  with  the  desired  PKI server must be used for client
       authentication. This can be done by importing the client certificate into an NSS  security
       database and passing the values to the relevant options provided by the pki CLI framework.

       To  achieve  this, execute the following commands to set up an NSS database for use by the
       pki client, import the client certificate into the  NSS  database,  and  list  information
       (including the nickname of the client certificate) stored in the NSS database:

       - certutil -N -d <CERT_DB_DIR_PATH>

       - pk12util -i <Agent_Cert_P12_FILE_PATH> -d <CERT_DB_DIR_PATH>

       - certutil -L -d <CERT_DB_DIR_PATH>

       The  first  command  creates an NSS database, and asks the client user to enter a password
       for this NSS database.

       The second command imports a client certificate stored in a PKCS12 format  into  this  NSS
       database;  it  prompts  for  the  passwords  of the PKCS12 file and the NSS database.  The
       simplest example of such a client certificate is to obtain the  administrator  certificate
       created  during  the configuration portion of the basic PKI installation of the associated
       PKI server (e. g. -  located  at  /root/.dogtag/pki-tomcat/ca_admin_cert.p12  on  the  PKI
       server machine).

       The  third  command shows the information about the imported client certificate (including
       its nickname).

       Note: When issuing the first  pki  command  using  the  authentication  parameters  (after
       completion of the setup of the NSS database), a user may be greeted with a warning message
       which indicates that an untrusted issuer was encountered.  Simply reply 'Y' to import  the
       CA  certificate,  and,  presuming  that  the  displayed  CA server URL is valid, press the
       carriage return.

   Client Authentication
       To authenticate with a client certificate:

       pki -d <NSS database location> -c <NSS database password> -n <client certificate nickname>

       Alternatively,  to  prevent exposure via the command-line, an NSS database may store their
       password in a file instead. See Client-side Password Files for detailed information.

       To authenticate with a client certificate by using the NSS database password stored  in  a

       pki  -d  <NSS  database  location> -C <NSS password file> -n <client certificate nickname>

       Finally, if a client certificate has been specified on the command-line, and  neither  the
       '-C  <NSS  database password file>' nor the '-c <NSS database password>' options have been
       utilized, the NSS database password will be prompted for.

       To authenticate with a client certificate by interactively prompting for an  NSS  database

       pki -d <NSS database location> -n <client certificate nickname> <command>

       Note:  Prompting  for  an  NSS  database  password  is  not  suitable  for automated batch

   Client-side Password Files
       Both the '-C' (client authentication) and the '-W' (basic authentication) options  require
       the use of a client-side password file.

       For  security  purposes,  client-side  password  files  should be, at a minimum, operating
       system protected non-world readable files.

       Client-side  password  files  generally  store  a  password  in  an  equals-sign-delimited
       plaintext  format  'token=password'  (e.  g.  -  'internal=foobar' where 'internal' is the
       token, '=' is the delimiter, and 'foobar' is the  actual  password).   The  token  keyword
       'internal'  is  the  default  specification  for  a token, and refers to the "Internal Key
       Storage Token".  If a client-side password file is being used for the sole purposes of the
       pki  command-line  tool,  a client-side password file also supports the format that merely
       consists of the plaintext password on a single line (read the Caveats which follow).


              · Since client-side password files are allowed to use the 'token=password'  format,
              the  first '=' character can only be used as a delimiter (i. e. - it cannot be used
              as a valid character within the 'token' name) as escaping the '=' character  within
              a token is not supported.

              ·  When  specifying  a  password which contains an '=' character, always specify an
              initial '=' prior to specifying the actual password (mandatory when  no  token  has
              been specified) as escaping the '=' character within a password is not supported.

              ·  Tokens  do not support leading or trailing whitespace since these characters are
              stripped prior to  their  use;  however,  all  whitespace  inside  tokens  will  be

              · Passwords preserve all leading, trailing, and internal whitespace since passwords
              are not trimmed prior to their use.

              · TBD: Supply code to handle the case of a non-internal token (e. g.  -  'hardware-
              nethsm'  utilized  in  the  following  examples) since the current code ignores the
              specified token (i. e. - it always utilizes the default 'internal' token no  matter
              what is currently specified).

              ·  TBD: Allow numerous 'token=password' lines in a single client-side password file
              to support the ability to authenticate against specified tokens as well as multiple

       Valid examples include:

          where:  token="internal", password="foobar"

          where:  token="hardware-nethsm" (ignored - TBD), password="foobar"

          where:  token="internal", password="ack=bar"

          where:  token="hardware-nethsm" (ignored - TBD), password="ack=bar"

          where:  token="internal" (default), password="foobar"

          where:  token="internal" (default), password="foo=bar"
                  (Since the password contains an '=' character,
                   an initial '=' character must be specified!)

          where:  token="internal" (default), password="foobar"

   Results Paging
       Some  commands  (e.g.  cert-find) may return multiple results. Since the number of results
       may be large, the results are split into multiple  pages.  By  default  the  command  will
       return  only  the first page (e.g. the first 20 results). To retrieve results from another
       page, additional paging parameters can be specified:

       * start: index of the first result to return (default: 0)
       * size: number of results to return (default: 20)

       For example, to retrieve the first page (index #0-#19):

       pki cert-find --start 0 --size 20

       To retrieve the second page (index #20-#39):

       pki cert-find --start 20 --size 20

       To retrieve the third page (index #40-#59):

       pki cert-find --start 40 --size 20




           Certificate management commands

           NSS database management commands

           Group management commands

           Group member management commands

           Key management commands

           Security domain management commands

           User management commands

           User certificate management commands

           User membership management commands

           Profile management commands


       Ade  Lee  <>,  Endi  Dewata  <>,  and   Matthew   Harmsen


       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