PKI Client CLI - dogtagpki/pki GitHub Wiki
The pki client-* commands provide a way to manage client environment.
A client NSS database is needed for client certificate authentication and various other operations.
A new NSS database can be initialized with the following command:
$ pki -c Secret.123 client-init ------------------ Client initialized ------------------
By default it will create a database in ~/.dogtag/nssdb with the specified password.
This operation is optional for the admin. When the admin creates a new subsystem, an NSS database will automatically be created (e.g. ~/.dogtag/pki-tomcat/ca/alias). The database can be used directly as follows:
$ pki -d ~/.dogtag/pki-tomcat/ca/alias -c Secret.123 -n caadmin ca-user-find
The certificates in the NSS database can be listed using the following command:
$ pki -c Secret.123 client-cert-find ---------------------- 2 certificate(s) found ---------------------- Serial Number: 0x1 Nickname: CA Signing Certificate - EXAMPLE Subject DN: CN=CA Signing Certificate,OU=pki-tomcat,O=EXAMPLE Issuer DN: CN=CA Signing Certificate,OU=pki-tomcat,O=EXAMPLE Serial Number: 0xa Nickname: testuser Subject DN: UID=testuser Issuer DN: CN=CA Signing Certificate,OU=pki-tomcat,O=EXAMPLE ---------------------------- Number of entries returned 2 ----------------------------
The pki client-cert-request can be used to request a certificate from the CA.
Note: This command has been deprecated since PKI 11.9. Use pki nss-cert-request instead.
If key archival is not needed, use a PKCS #10 request. If key archival is needed, use a CRMF request.
To generate and submit a PKCS #10 request:
$ pki -c Secret.123 client-cert-request uid=testuser ----------------------------- Submitted certificate request ----------------------------- Request ID: 7 Type: enrollment Request Status: pending Operation Result: success
Use a profile that supports key archival, e.g. caSigningUserCert. Prior to PKI 10.3 use caDualCert profile.
To generate and submit a CRMF request:
$ pki -c Secret.123 client-cert-request uid=testuser --profile caSigningUserCert --type crmf ----------------------------- Submitted certificate request ----------------------------- Request ID: 28 Type: enrollment Request Status: pending Operation Result: success
By default it will download the transport certificate from the CA. To use a transport certificate stored in a local file, specify --transport <filename>. Either way, the transport certificate will be imported into the NSS database.
This operation is optional. When the CLI connects to the server via SSL it will check if the CA certificate already exists in the NSS database. If it does not exist, the CLI will ask the user whether to download and import the CA certificate from the CA server.
$ pki ... user-find WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,O=EXAMPLE' indicates a non-trusted CA cert 'CN=CA Signing Certificate,O=EXAMPLE' Import CA certificate (Y/n)? CA server URI [http://pki.example.com:8080/ca]:
Alternatively, the server certificate chain can be imported manually. To download and import CA certificate from the CA server:
$ pki client-cert-import "CA Certificate" --ca-server ------------------------------------- Imported certificate "CA Certificate" -------------------------------------
To import CA certificate from a file:
$ pki client-cert-import "CA Certificate" --ca-cert ca.pem ------------------------------------- Imported certificate "CA Certificate" -------------------------------------
To import user certificate directly from CA:
$ pki client-cert-import testuser --serial 0x8
To import user certificate from file:
$ pki client-cert-import testuser --cert testuser.crt
This operation is also optional for the admin. When the admin creates a new subsystem the admin certificate (e.g. caadmin) and the private key will automatically be stored in the client security database. The admin certificate can be used directly as follows:
$ pki ... -n caadmin ...
Otherwise, the user certificate and the private key can be imported from a PKCS #12 file using the following command:
$ pk12util -i client_cert.p12 -d ~/.dogtag/nssdb -K Secret.123 -W Secret.123 pk12util: PKCS12 IMPORT SUCCESSFUL
$ pki -c Secret.123 client-cert-import --pkcs12 ca_admin_cert.p12 --pkcs12-password Secret.123 ---------------------------------------- Imported certificates from PKCS #12 file ----------------------------------------
To display certificate usage:
$ pki client-cert-validate testuser Cert has the following usages: SSLClient,UserCertImport,VerifyCA,ProtectedObjectSigner,AnyCA
To validate client certificate usage:
$ pki client-cert-validate testuser --certusage SSLClient Valid certificate: testuser
Note: The --certusage option has been deprecated since PKI 11.9. Use pki nss-cert-verify instead.
Client certificates can be removed with the following command:
$ pki client-cert-del testuser ------------------------------ Removed certificate "testuser" ------------------------------
Note: This command has been deprecated since PKI 11.5. Use pki nss-cert-del instead.