Chapter 2. User interfaces

The Java console is used by four subsystems: the CA, OCSP, KRA, and TKS. The console is accessed using a locally-installed pkiconsole utility. It can access any subsystem because the command requires the host name, the subsystem’s administrative TLS port, and the specific subsystem type.

pkiconsole -d nssdb -n 'optional client cert nickname' https://server.example.com:admin_port/subsystem_type

# pkiconsole -d nssdb -n 'optional client cert nickname' https://server.example.com:admin_port/subsystem_type

If DNS is not configured, you can use an IPv4 or IPv6 address to connect to the console. For example:

https://192.0.2.1:8443/ca
https://[2001:DB8::1111]:8443/ca

https://192.0.2.1:8443/ca
https://[2001:DB8::1111]:8443/ca

This opens a console, as in the below figure:

Figure 2.1. Certificate System console

View larger image

The Configuration tab controls all of the setup for the subsystem, as the name implies. The choices available in this tab are different depending on which subsystem type the instance is; the CA has the most options since it has additional configuration for jobs, notifications, and certificate enrollment authentication.

All subsystems have four basic options:

The Status tab shows the logs maintained by the subsystem.

This section explains browser initialization for Firefox to access PKI services.

Importing a CA certificate

Importing a client certificate

Accessing the web console

You can access the PKI services by opening https://host_name:port in your browser.

All subsystems use a HTML-based administrative interface. It is accessed by entering the host name and secure port as the URL, authenticating with the administrator’s certificate, and clicking the appropriate Administrators link.

The HTML admin interface is much more limited than the Java console; the primary administrative function is managing the subsystem users.

The TPS only allows operations to manage users for the TPS subsystem. However, the TPS admin page can also list tokens and display all activities (including normally-hidden administrative actions) performed on the TPS.

Figure 2.2. TPS admin page

View larger image

The agent services pages are where almost all of the certificate and token management tasks are performed. These services are HTML-based, and agents authenticate to the site using a special agent certificate.

Figure 2.3. Certificate Manager’s agent services page

View larger image

The operations vary depending on the subsystem:

The TKS is the only subsystem without an agent services page.

The CA and TPS both process direct user requests in some way. That means that end users have to have a way to connect with those subsystems. The CA has end-user, or end-entities, HTML services. The TPS uses the Enterprise Security Client.

The end-user services are accessed over standard HTTP using the server’s host name and the standard port number; they can also be accessed over HTTPS using the server’s host name and the specific end-entities TLS port.

For CAs, each type of TLS certificate is processed through a specific online submission form, called a profile. There are about two dozen certificate profiles for the CA, covering all sorts of certificates - user TLS certificates, server TLS certificates, log and file signing certificates, email certificates, and every kind of subsystem certificate. There can also be custom profiles.

Figure 2.4. Certificate Manager’s end-entities page

View larger image

End users retrieve their certificates through the CA pages when the certificates are issued. They can also download CA chains and CRLs and can revoke or renew their certificates through those pages.

The pki command-line interface (CLI) provides access to various services on the server using the REST interface (see 2.3.4 REST Interface in the Planning, Installation and Deployment Guide (Common Criteria Edition). You can invoke the CLI as follows:

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

$ pki [CLI options] <command> [command parameters]

Note that the CLI options must be placed before the command, and the command parameters after the command.

The AtoB utility decodes the Base64-encoded certificates to their binary equivalents. For example:

AtoB input.ascii output.bin

$ AtoB input.ascii output.bin

For further details, more options, and additional examples, see the AtoB(1) man page.

The AuditVerify utility verifies integrity of the audit logs by validating the signature on log entries.

For example:

AuditVerify -d ~jsmith/auditVerifyDir -n Log Signing Certificate -a ~jsmith/auditVerifyDir/logListFile -P "" -v

$ 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 12.2.1, “Displaying and verifying signed audit logs”.

The BtoA utility encodes binary data in Base64. For example:

BtoA input.bin output.ascii

$ BtoA input.bin output.ascii

For further details, more options, and additional examples, see the BtoA(1) man page.

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

CMCRequest example.cfg

$ CMCRequest example.cfg

The CMCResponse utility is used to parse CMC responses returned from CMC issuance or revocation requests. For example:

*CMCResponse -d /home/agentSmith/certdb_dir -i /home/agentSmith/certdb_dir/cmc.dirsrv_pkcs10.resp -o /home/agentSmith/certdb_dir/Server-Cert.crt*

$ *CMCResponse -d /home/agentSmith/certdb_dir -i /home/agentSmith/certdb_dir/cmc.dirsrv_pkcs10.resp -o /home/agentSmith/certdb_dir/Server-Cert.crt*

For further details, more options, additional examples, see the CMCResponse(1) man page.

Legacy. Do not use.

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"

$ 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 Section 8.4.1, “Creating a Shared Secret token”.

The CRMFPopClient utility is Certificate Request Message Format (CRMF) client using NSS databases and supplying Proof of Possession.

For 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

$ 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 5.2.3, “Creating a CSR using CRMFPopClient”.

The HttpClient utility is an NSS-aware HTTP client for submitting CMC requests.

For example:

HttpClient request.cfg

$ HttpClient request.cfg

OCSPClient is an Online Certificate Status Protocol (OCSP) client for checking the certificate revocation status.

For example:

OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2

$ 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.

The PKCS10Client utility creates a CSR in PKCS10 format for RSA and EC keys, optionally on an HSM.

For example:

PKCS10Client -d /etc/dirsrv/slapd-instance_name/ -p password -a rsa -l 2048 -o ~/ds.csr -n "CN=$HOSTNAME"

$ 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.

The PrettyPrintCert utility displays the contents of a certificate in a human-readable format.

For example:

PrettyPrintCert ascii_data.cert

$ 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.

The PrettyPrintCrl utility displays the content of a CRL file in a human readable format.

For example:

PrettyPrintCrl ascii_data.crl

$ 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.

The TokenInfo utility lists all tokens in an NSS database.

For example:

TokenInfo ./nssdb/

$ 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.

The tkstool utility is interacting with the token Key Service (TKS) subsystem.

For example:

tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h token_name

$ 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.