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. 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 the Importing a certificate into an NSS Database section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
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 the Managing Certificate/Key Crypto Token section in the Red Hat Certificate System Planning, Installation, and Deployment Guide:
$ 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 Section 15.3.2, “Using Signed Audit Logs”.
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 Section 7.2.1, “Revoking a Certificate Using CMCRequest”.
2.5.6. CMCRevoke
Legacy. Do not use.
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 Section 7.2.1, “Revoking a Certificate Using CMCRequest”.
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.
