2.4. Overview of the Supported pki Commands

PDF

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:

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>

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:

Generate a CSR:

$ certutil -R -d security database directory -s subject DN -a

Use the following command to obtain a profile template:

$ pki cert-request-profile-show profile --output file

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>

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:

Generate a file with the specified certificate request:

$ pki agent authentication cert-request-review request_ID --output filename

Review the generated output file manually and edit it if required.
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

2.4. Overview of the Supported pki Commands

2.4.1. Client Management with `pki client`

Client Initialization

Listing Local Certificates

Importing Certificates and Private Keys

Removing Local Certificates

2.4.2. Certificate Management with `pki cert`

Listing Certificates

Displaying a Certificate

Creating a Certificate Request

Checking Certificate Request Status

Managing Certificate Requests

Revoking Certificates

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

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

2.4.5. Security Domain Management with `pki securitydomain`

2.4.6. Key Management with `pki key-*`

Templates

Key Requests

Keys

2.4.7. KRA Connector Management with `pki ca-kraconnector`

2.4.8. CA Management with `pki ca`

Listing Profiles

Displaying Profiles

2.4.9. TPS Management with `pki tps`

Activities

Audit

Users

Profiles

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4. Overview of the Supported pki Commands

2.4.1. Client Management with pki client

Client Initialization

Listing Local Certificates

Importing Certificates and Private Keys

Removing Local Certificates

2.4.2. Certificate Management with pki cert

Listing Certificates

Displaying a Certificate

Creating a Certificate Request

Checking Certificate Request Status

Managing Certificate Requests

Revoking Certificates

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

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

2.4.5. Security Domain Management with pki securitydomain

2.4.6. Key Management with pki key-*

Templates

Key Requests

Keys

2.4.7. KRA Connector Management with pki ca-kraconnector

2.4.8. CA Management with pki ca

Listing Profiles

Displaying Profiles

2.4.9. TPS Management with pki tps

Activities

Audit

Users

Profiles

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4.1. Client Management with `pki client`

2.4.2. Certificate Management with `pki cert`

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

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

2.4.5. Security Domain Management with `pki securitydomain`

2.4.6. Key Management with `pki key-*`

2.4.7. KRA Connector Management with `pki ca-kraconnector`

2.4.8. CA Management with `pki ca`

2.4.9. TPS Management with `pki tps`