2.5. Command Line Interfaces

This section discusses command-line utilities.

2.5.1. "pki" CLI

The pki command-line interface (CLI) provides access to various services on the server using the REST interface (see the REST Interface section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition)). The CLI can be invoked as follows: 
$ pki [CLI options] <command> [command parameters]
Note that the CLI options must be placed before the command, and the command parameters after the command.

2.5.1.1. pki CLI Initialization

To use the command line interface for the first time, specify a new password and use the following command: 
$ pki -c <password> client-init
This will create a new client NSS database in the ~/.dogtag/nssdb directory. The password must be specified in all CLI operations that uses the client NSS database. Alternatively, if the password is stored in a file, you can specify the file using the -C option. For example: 
$ pki -C password_file client-init
To import the CA certificate into the client NSS database refer to Section 11.2, “Importing a Root Certificate”.
Some commands may require client certificate authentication. To import an existing client certificate and its key into the client NSS database, specify the PKCS #12 file and the password, and execute the following command:
Execute the following command to extract the admin client certificate from the .p12 file: 
$ openssl pkcs12 -in file -clcerts -nodes -nokeys -out file.crt
Validate and import the admin client certificate as described in Chapter 11, Managing Certificate/Key Crypto Token: 
$ PKICertImport -d ~/.dogtag/nssdb -n "nickname" -t ",," -a -i file.crt -u C

Important

Make sure all intermediate certificates and the root CA certificate have been imported before importing the CA admin client certificate.
To import an existing client certificate and its key into the client NSS database, specify the PKCS #12 file and the password, and execute the following command: 
$ pki -c <password> pkcs12-import --pkcs12-file <file> --pkcs12-password <password>
Verify the client certificate with the following command: 
certutil -V -u C -n "nickname" -d ~/.dogtag/nssdb

2.5.1.2. Using "pki" CLI

The command line interface supports a number of commands organized in a hierarchical structure. To list the top-level commands, execute the pki command without any additional commands or parameters: 
$ pki
Some commands have subcommands. To list them, execute pki with the command name and no additional options. For example: 
$ pki ca
$ pki ca-cert
To view command usage information, use the --help option: 
$ pki --help
$ pki ca-cert-find --help
To view manual pages, specify the command line help command: 
$ pki help
$ pki help ca-cert-find
To execute a command that does not require authentication, specify the command and its parameters (if required), for example: 
$ pki ca-cert-find
To execute a command that requires client certificate authentication, specify the certificate nickname, the client NSS database password, and optionally the server URL: 
$ pki -U <server URL> -n <nickname> -c <password> <command> [command parameters]
For example: 
$ pki -n jsmith -c password ca-user-find ...
By default, the CLI communicates with the server at http://local_host_name:8080. To communicate with a server at a different location, specify the URL with the -U option, for example: 
$ pki -U https://server.example.com:8443 -n jsmith -c password ca-user-find

2.5.2. AtoB

The AtoB utility decodes the Base64-encoded certificates to their binary equivalents. For example: 
$ AtoB input.ascii output.bin
For further details, more options, and additional examples, see the AtoB(1) man page.

2.5.3. AuditVerify

The AuditVerify utility verifies integrity of the audit logs by validating the signature on log entries.
Example: 
$ AuditVerify -d ~jsmith/auditVerifyDir -n Log Signing Certificate -a ~jsmith/auditVerifyDir/logListFile -P "" -v
The example verifies the audit logs using the Log Signing Certificate (-n) in the ~jsmith/auditVerifyDir NSS database (-d). The list of logs to verify (-a) are in the ~jsmith/auditVerifyDir/logListFile file, comma-separated and ordered chronologically. The prefix (-P) to prepend to the certificate and key database file names is empty. The output is verbose (-v).
For further details, more options, and additional examples, see the AuditVerify(1) man page or 14.2.2. Using Signed Audit Logs in the Red Hat Certificate System Administration Guide.

2.5.4. BtoA

The BtoA utility encodes binary data in Base64. For example: 
$ BtoA input.bin output.ascii
For further details, more options, and additional examples, see the BtoA(1) man page.

2.5.5. CMCRequest

The CMCRequest utility creates a certificate issuance or revocation request. For example: 
$ CMCRequest example.cfg

Note

All options to the CMCRequest utility are specified as part of the configuration filed passed to the utility. See the CMCRequest(1) man page for configuration file options and further information. Also see 4.3. Requesting and Receiving Certificates Using CMC and 6.2.1. Revoking a Certificate Using CMCRequest in Red Hat Certificate System Administration Guide.

2.5.6. CMCRevoke

Legacy. Do not use.

2.5.7. CMCSharedToken

The CMCSharedToken utility encrypts a user passphrase for shared-secred CMC requests. For example: 
$ CMCSharedToken -d . -p myNSSPassword -s "shared_passphrase" -o cmcSharedTok2.b64 -n "subsystemCert cert-pki-tomcat"
The shared passphrase (-s) is encrypted and stored in the cmcSharedtok2.b64 file (-o) using the certificate named subsystemCert cert-pki-tomcat (-n) found in the NSS database in the current directory (-d). The default security token internal is used (as -h is not specified) and the token password of myNSSPassword is used for accessing the token.
For further details, more options, and additional examples, see the CMCSharedtoken(1) man page and also 8.1.3.1. Creating a Shared Secret Token in Red Hat Certificate System Administration Guide.

2.5.8. CRMFPopClient

The CRMFPopClient utility is Certificate Request Message Format (CRMF) client using NSS databases and supplying Proof of Possession.
Example: 
$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -t false -v -o /user_or_entity_database_directory/example.csr
This example creates a new CSR with the cn=subject_name subject DN (-n), NSS database in the current directory (-d), certificate to use for transport kra.transport (-b), the AES/CBC/PKCS5Padding key wrap algorithm verbose output is specified (-v) and the resulting CSR is written to the /user_or_entity_database_directory/example.csr file (-o).
For further details, more options, and additional examples, see the output of the CRMFPopClient --help command and also 4.2.4. Creating a CSR Using CRMFPopClient in Red Hat Certificate System Administration Guide.

2.5.9. HttpClient

The HttpClient utility is an NSS-aware HTTP client for submitting CMC requests.
Example: 
$ HttpClient request.cfg

Note

All parameters to the HttpClient utility are stored in the request.cfg file. For further information, see the output of the HttpClient --help command.

2.5.10. OCSPClient

An Online Certificate Status Protocol (OCSP) client for checking the certificate revocation status.
Example: 
$ OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2
This example queries the server.example.com OCSP server (-h) on port 8080 (-p) to check whether the certificate signed by caSigningcet cert-pki-ca (-c) with serial number 2 (--serial) is valid. The NSS database in the /etc/pki/pki-tomcat/alias directory is used.
For further details, more options, and additional examples, see the output of the OCSPClient --help command.

2.5.11. PKCS10Client

The PKCS10Client utility creates a CSR in PKCS10 format for RSA and EC keys, optionally on an HSM.
Example: 
$ PKCS10Client -d /etc/dirsrv/slapd-instance_name/ -p password -a rsa -l 2048 -o ~/ds.csr -n "CN=$HOSTNAME"
This example creates a new RSA (-a) key with 2048 bits (-l) in the /etc/dirsrv/slapd-instance_name/ directory (-d with database password password (-p). The output CSR is stored in the ~/ds.cfg file (-o) and the certificate DN is CN=$HOSTNAME (-n).
For further details, more options, and additional examples, see the PKCS10Client(1) man page.

2.5.12. PrettyPrintCert

The PrettyPrintCert utility displays the contents of a certificate in a human-readable format.
Example: 
$ PrettyPrintCert ascii_data.cert
This command parses the output of the ascii_data.cert file and displays its contents in human readable format. The output includes information like signature algorithm, exponent, modulus, and certificate extensions.
For further details, more options, and additional examples, see the PrettyPrintCert(1) man page.

2.5.13. PrettyPrintCrl

The PrettyPrintCrl utility displays the content of a CRL file in a human readable format.
Example: 
$ PrettyPrintCrl ascii_data.crl
This command parses the output of the ascii_data.crl and displays its contents in human readable format. The output includes information, such as revocation signature algorithm, the issuer of the revocation, and a list of revoked certificates and their reason.
For further details, more options, and additional examples, see the PrettyPrintCrl(1) man page.

2.5.14. TokenInfo

The TokenInfo utility lists all tokens in an NSS database.
Example: 
$ TokenInfo ./nssdb/
This command lists all tokens (HSMs, soft tokens, and so on) registered in the specified database directory.
For further details, more options, and additional examples, see the output of the TokenInfo command

2.5.15. tkstool

The tkstool utility is interacting with the token Key Service (TKS) subsystem.
Example: 
$ tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h token_name
This command creates a new master key (-M) named new_master (-n) in the /var/lib/pki/pki-tomcat/alias NSS database on the HSM token_name
For further details, more options, and additional examples, see the output of the tkstool -H command.