SupportConsoleDevelopersStart a trialContact

2.4. Overview of the Supported pki Commands

This section lists some of the pki commands and their subcommands, as well as their functions. For more detailed information on how to use a particular pki subcommand, execute it with the --help option added. For example: 
$ pki cert-find --help
usage: cert-find [OPTIONS...]
--certTypeSecureEmail <on|off>         Certifiate Type: Secure Email
--certTypeSSLClient <on|off>           Certifiate Type: SSL Client
--certTypeSSLServer <on|off>           Certifiate Type: SSL Server
...
Some of the subcommands are also described in the pki(1) man page.

2.4.1. Client Management with pki client

The pki client-* commands enable you to manage the Certificate System client environment. For more information on these commands, see the pki-client(1) man page.

Client Initialization

pki client-init
Initializes a new client environment; the command creates a security database in the default certificate database directory ~/.dogtag/nssdb/. The password for the new security database must be specified with the -c or -C option. For example: 
$ pki -c Secret123 client-init
------------------
Client initialized
------------------

Note

This operation is optional for the administrator. When the administrator creates a new subsystem, a client security database is created automatically.

Listing Local Certificates

pki client-cert-find
Lists all the certificates in the client security database

Importing Certificates and Private Keys

pki client-cert-import
Imports the CA certificate or the client certificate from a PKCS #12 file

Example 2.1. Importing the CA Certificate from the CA Server

To download and import the CA certificate from the CA server: 
$ pki -c Secret123 -n "CA Signing Certificate - EXAMPLE" client-cert-import --ca-server
-------------------------------------------------------
Imported certificate "CA Signing Certificate - EXAMPLE"
-------------------------------------------------------

Example 2.2. Importing the CA Certificate from a File

To import the CA certificate from a file: 
$ pki -c Secret123 -n "CA Signing Certificate - EXAMPLE" client-cert-import --ca-cert ca.pem
-------------------------------------------------------
Imported certificate "CA Signing Certificate - EXAMPLE"
-------------------------------------------------------

Note

Importing the CA certificate is optional. If the CA certificate is not present in the client security database when connecting to the server through SSL from the command line, the user is asked whether to download and import the CA certificate from the CA server.

Example 2.3. Importing the Client Certificate and Private Key

To import the private key from a PKCS #12: 
$ pki -c Secret123 client-cert-import --pkcs12 ca_admin_cert.p12 --pkcs12-password Secret123
----------------------------------------
Imported certificates from PKCS #12 file
----------------------------------------

Note

Importing the certificate and the private key is optional for the administrator. When the administrator creates a new subsystem, the administrator certificate and the private key are automatically stored in the client security database.

Removing Local Certificates

pki client-cert-del
Removes a local certificate

2.4.2. Certificate Management with pki cert

The pki cert-* commands enable you to manage certificates and certificate requests on the CA. For more information on these commands, see the pki-cert(1) man page.

Listing Certificates

pki cert-find
Lists all certificates

Example 2.4. Listing Only Valid Certificates

To list only certificates that are valid: 
$ pki cert-find --status VALID

Example 2.5. Listing Certificates Based on a File with Search Constraints

To list certificates with search constraints defined in a file:
  1. Prepare an XML file defining the search constraints. The file must follow this format: 
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CertSearchRequest>

    <serialNumberRangeInUse>true</serialNumberRangeInUse>
    <serialFrom></serialFrom>
    <serialTo></serialTo>
    
    <subjectInUse>false</subjectInUse>
    <eMail></eMail>
    <commonName></commonName>
    <userID></userID>
    <orgUnit></orgUnit>
    <org></org>
    <locality></locality>
    <state></state>
    <country></country>
    
    <matchExactly>false</matchExactly>
    
    <status></status>
    
    <revokedByInUse>false</revokedByInUse>
    <revokedBy></revokedBy>
    
    <revokedOnFrom>false</revokedOnFrom>
    <revokedOnTo></revokedOnTo>
    
    <revocationReasonInUse>false</revocationReasonInUse>
    <revocationReason></revocationReason>
    
    <issuedByInUse>false</issuedByInUse>
    <issuedBy></issuedBy>
    
    <issuedOnInUse>false</issuedOnInUse>
    <issuedOnFrom></issuedOnFrom>
    <issuedOnTo></issuedOnTo>
    
    <validNotBeforeInUse>false</validNotBeforeInUse>
    <validNotBeforeFrom></validNotBeforeFrom>
    <validNotBeforeTo></validNotBeforeTo>
    
    <validNotAfterInUse>false</validNotAfterInUse>
    <validNotAfterFrom></validNotAfterFrom>
    <validNotAfterTo></validNotAfterTo>
    
    <validityLengthInUse>false</validityLengthInUse>
    <validityOperation></validityOperation>
    <validityCount></validityCount>
    <validityUnit></validityUnit>
    
    <certTypeInUse>false</certTypeInUse>
    <certTypeSubEmailCA></certTypeSubEmailCA>
    <certTypeSubSSLCA></certTypeSubSSLCA>
    <certTypeSecureEmail></certTypeSecureEmail>
    
</CertSearchRequest>
  2. Run the pki cert-find command, adding the file path to the command: 
    $ pki cert-find --input filename

Displaying a Certificate

pki cert-show
Displays or retrieves a specified certificate

Example 2.6. Downloading a Certificate

To use pki cert-show to download a certificate: 
$ pki cert-show certificate ID --encoded --output filename

Creating a Certificate Request

pki cert-request-profile-show and pki cert-request-submit
These commands can be used to create and submit a certificate request

Example 2.7. Creating and Submitting a Certificate Request

To create and submit a certificate request using pki cert-request-profile-show and pki cert-request-submit:
  1. Generate a CSR: 
    $ certutil -R -d security database directory -s subject DN -a
  2. Use the following command to obtain a profile template: 
    $ pki cert-request-profile-show profile --output file
  3. Edit the output file and insert the CSR into the cert_request attribute. For example: 
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CertEnrollmentRequest>

...

    <Input id="i1">
	
...

      <Attribute name="cert_request_type">
        <Value>pkcs10</Value>

...

      </Attribute>
      <Attribute name="cert_request">
        <Value>
MIIBZTCBzwIBADAmMRAwDgYDVQQKEwdFWEFNUExFMRIwEAYDVQQDEwlUZXN0IFVz
ZXIwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAL7hYQp/g4FblKRd3Cjyfh8e
MFGZLbTDZcY+YBxOk43JeqIDLkGZRHpr/84hK4lgISuyXpvz8owKel2jw6q7bP9Z
0D8AGrrJfEvAuMQrAJiMd/O3U6CKF9+U/z8RjzHPXjzAKl/cIVpqnPuAQOMWQGmx
HkxmLYZww0hKcc9nl5KPAgMBAAGgADANBgkqhkiG9w0BAQUFAAOBgQCtpV2ts1Hp
w+s7ev90d2gRpmPBtNGfOz4OsOpNYbDX3fGabkLFIJAWQ8arjQqToGawIh0nZpND
UJ9hSa1gIfI+4uxYKjk6cFQAPnZeVgLg1KgELVIzYZ0Qem5NXHmRsR/Vwxh5abzX
XeuHTCnFT0Elpva9mnR+tqe1agZwHghDwQ==
        </Value>

...

      </Attribute>
    </Input>

...

</CertEnrollmentRequest>
  4. Use the pki cert-request-submit command to submit the request: 
    $ pki cert-request-submit filename

Checking Certificate Request Status

pki cert-request-show
Displays the status of the certificate request

Managing Certificate Requests

Important

Viewing or processing certificate requests must be executed with agent credentials. For information on how to authenticate when using the pki commands, see Section 2.2, “Authentication”.
pki cert-request-find
Displays all certificate requests
pki cert-request-review
Reviews a certificate request and performs an action, such as approve or reject

Example 2.8. Reviewing a Certificate with pki cert-request

To use pki cert-request-review to review a certificate:
  1. Generate a file with the specified certificate request: 
    $ pki agent authentication cert-request-review request_ID --output filename
  2. Review the generated output file manually and edit it if required.
  3. Enter one of the following actions into the command line to complete the review:
    • approve
    • reject
    • cancel
    • update
    • validate
    • assign
    • unassign

Note

You can perform the approval process in a single step by passing the required review action directly to the command using the --action. For example: 
$ pki agent authentication cert-request-review request_ID --action approve

Revoking Certificates

Important

Revoking, holding, or releasing certificates must be executed with agent credentials. For information on how to authenticate when using the pki commands, see Section 2.2, “Authentication”.
pki cert-revoke
Revokes the certificate
pki cert-hold
Holds the certificate temporarily
pki cert-release-hold
Releases a certificate that has been held

2.4.3. User and Group Management with pki user and pki group

The pki user-* and pki group-* commands enable you to manage users and groups. These commands require you to specify the subsystem to which the operation is to be applied. For more information on these commands, see the pki-user(1) and pki-group(1) man pages.

Important

All of these commands must be executed with administrator credentials. For information on how to authenticate when using the pki commands, see Section 2.2, “Authentication”.
pki subsystem-user-find
Lists users
pki subsystem-group-find
Lists groups
pki subsystem-user-show
Displays details for a specified user
pki subsystem-group-show
Displays details for a specified group
pki subsystem-user-add
Adds a new user
pki subsystem-group-add
Adds a new group
pki subsystem-user-mod
Modifies an existing user entry
pki subsystem-group-mod
Modifies an existing group entry
pki subsystem-user-del
Deletes the user
pki subsystem-group-del
Deletes the group

2.4.4. Group Member and User Membership Management with pki group-member and pki user-membership

pki group-member-* commands
Commands for group member management
pki user-membership-* commands
Commands for user membership management
For a complete list of the available group member and user membership management commands, run pki group-member or pki user-membership. For more information about the commands, see the pki-group-member(1) and pki-user-membership(1) man pages.

2.4.5. Security Domain Management with pki securitydomain

pki securitydomain-show
Displays the security domain information; for more information on this command, see the pki-securitydomain(1) man page.

2.4.6. Key Management with pki key-*

The pki key-* commands enable you to manage keys in KRA. For more information on these commands, see the pki-key(1) man page.

Templates

pki key-template-find
Lists all available key templates
pki key-template-show
Displays a key template or stores the key template into a file

Example 2.9. Storing a Key Template Into a File

To store a key template into a file: 
$ pki key-template-show retrieveKey --output retrieveKey.xml

Key Requests

Important

All key requests must be executed with KRA agent credentials. For information on how to authenticate when using the pki commands, see Section 2.2, “Authentication”.
pki key-request-find
Lists all submitted key requests
pki key-request-show
Displays a specified key request
pki key-request-review
Reviews a key request; the review process follows the same rules as reviewing a certificate request, as described in Example 2.8, “Reviewing a Certificate with pki cert-request”.

Keys

Important

All key operations must be executed with KRA agent credentials. For information on how to authenticate when using the pki commands, see Section 2.2, “Authentication”.
pki key-find
Lists all archived keys
pki key-generate
Generates a new key on the server
pki key-archive
Archives a secret specified in the command line
To archive a secret already encrypted in a template: 
$ pki -d ~/.dogtag/pki-tomcat/ca/alias/ -c Secret123 -n caadmin key-archive --input archiveKey.xml
pki key-retrieve
Retrieves a key

Example 2.10. Retrieving a Key with Random Security Parameters

To retrieve a key with randomly generated security parameters: 
$ pki -d ~/.dogtag/pki-tomcat/ca/alias/ -c Secret123 -n caadmin key-retrieve --keyID 0x1

Retrieve Key Information
------------------------
  Key Algorithm: RSA
  Key Size: 1024
  Nonce data: rYkeh4Rb+MI=

  Actual archived data: MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBALTyleypbSGRnb8+
P/BItA74mTdLX4eFY+fKE4hraeOV4ts+4M9qfry/FJkbMq3dpIpsxuMmGclbHEUQ
J/MfLAHgaxwVLGK8qCGb0IeY0Z7qIbGucSCLcDVpODlsTvqftK/SJZm56ODu7xXh
...

Example 2.11. Retrieving a Key with Custom Security Parameters

To retrieve a key with custom security parameters specified in a template: 
$ pki -d ~/.dogtag/pki-tomcat/ca/alias/ -c Secret123 -n caadmin key-retrieve --input retrieveKey.xml
pki key-recover
Recovers a key
pki key-show
Displays details for a specified key

Example 2.12. Displaying a Key When Specifying the Key ID

To display a key when specifying the key ID: 
$ pki -d ~/.dogtag/pki-tomcat/ca/alias/ -c Secret123 -n caadmin key-show 0x1
  Key ID: 0x1
  Client Key ID: test
  Status: active
  Algorithm: RSA
  Size: 1024
  Owner: kraadmin
  Public Key: 

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC08pXsqW0hkZ2/Pj/wSLQO+Jk3
S1+HhWPnyhOIa2njleLbPuDPan68vxSZGzKt3aSKbMbjJhnJWxxFECfzHywB4Gsc
FSxivKghm9CHmNGe6iGxrnEgi3A1aTg5bE76n7Sv0iWZuejg7u8V4QmU+jBc79O4
ydfTGLzZvtTVrYbgdQIDAQAB

Example 2.13. Displaying a Key When Specifying the Client Key ID

To display a key when specifying the client key ID: 
$ pki -d ~/.dogtag/pki-tomcat/ca/alias/ -c Secret123 -n caadmin key-show --clientKeyID test
  Key ID: 0x1
  Client Key ID: test
  Status: active
  Algorithm: RSA
  Size: 1024
  Owner: kraadmin
  Public Key: 

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC08pXsqW0hkZ2/Pj/wSLQO+Jk3
S1+HhWPnyhOIa2njleLbPuDPan68vxSZGzKt3aSKbMbjJhnJWxxFECfzHywB4Gsc
FSxivKghm9CHmNGe6iGxrnEgi3A1aTg5bE76n7Sv0iWZuejg7u8V4QmU+jBc79O4
ydfTGLzZvtTVrYbgdQIDAQAB
pki key-mod --status active
Activates a key. Setting the --status option to inactive deactivates the key.

2.4.7. KRA Connector Management with pki ca-kraconnector

The pki ca-kraconnector-* commands enable you to manage KRA connectors.

Important

It is required that all pki ca-kraconnector-* commands are directed to CA and executed as the administrator. For information on how to authenticate when using the pki commands, see Section 2.2, “Authentication”.
pki ca-kraconnector-show
Displays a KRA connector
pki ca-kraconnector-add
Adds a new KRA connector
pki ca-kraconnector-del
Removes a KRA connector

2.4.8. CA Management with pki ca

The pki ca-* commands enable you to access various CA services.

Listing Profiles

pki ca-profile-find
Lists all CA profiles in the specified database

Displaying Profiles

pki ca-profile-show
Displays a specified profile in the database

2.4.9. TPS Management with pki tps

The pki tps-* commands enable you to access various TPS services.

Activities

tps-activity-find
Displays all TPS activities
tps-activity-show
Displays a specified activity

Audit

tps-audit-mod
Modifies the audit configuration
tps-audit-show
Displays the audit configuration into a file

Users

pki tps-user-find
Displays all TPS users
pki tps-user-show
Displays a specified TPS user
pki tps-user-add
Adds a new TPS user
pki tps-user-mod
Modifies an existing TPS user
pki tps-user-del
Deletes a TPS user

Profiles

pki tps-profile-find
Displays all TPS profiles
pki tps-profile-show
Displays a specified TPS user
pki tps-profile-add
Adds a new TPS profile
pki tps-profile-mod
Modifies an existing TPS profile
pki tps-profile-del
Deletes a TPS profile
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.