PKI CLI Authentication - dogtagpki/pki GitHub Wiki
Certain PKI CLI commands can be executed anonymously, while some others may require authentication, either with username/password or client certificate. See PKI Server Authentication.
To execute a command without authentication:
$ pki <command>
For example:
$ pki ca-cert-find
To authenticate with username and password:
$ pki -u <username> -w <password> <command>
The following additional new options are available in PKI 10.2.x:
$ pki -u <username> -W <password file> <command>
Use of the -W (uppercase W) option is preferred for batch deployments as greater safeguards may be placed upon a file (e.g. system permissions, system ACLs, SELinux, etc.) rather than the -w (lowercase w) option of a simple plaintext designation which may be seen in shell history when invoked directly from the command-line, are far more likely to show up accidentally in cut/pastes of command-lines, and inside shell scripts which are seldom safeguarded from being world readable.
$ pki -u <username> -y <command>
Prompt for password which is preferred for individual command-line invocations as it masks the actual password from being displayed, but is generally not suitable for batch-oriented deployments.
To authenticate using client certificate, the certificate and the private key must be stored in the client NSS database.
To request a new certificate, see the following pages:
See also Adding System User.
To import the default CA admin certificate, see Default CA Admin.
Once the certificate and the private key is created/imported, the client certificate authentication can be done by specifying the NSS database password and the certificate nickname:
In PKI 10.0 or later the authentication can be done as follows:
$ pki -n <certificate nickname> -w <password> <command>
The default certificate database directory is $HOME/.pki/nssdb.
In PKI 10.1 or later the authentication can be done as follows:
$ pki -n <certificate nickname> -c <assword> <command>
The NSS database password now should be specified with a -c parameter. This option should only be used in a test environment where plain-text password visible in shell history or in shell scripts would not cause a security problem.
In PKI 10.2 or later the authentication can be done as follows:
$ pki -n <certificate nickname> -c <password> <command> $ pki -n <certificate nickname> -C <password file> <command>
The first option is identical to the option available in the previous version.
The second option using -C parameter can be used to provide the NSS database password via a file. This option might be preferrable for batch execution as greater safeguards may be placed upon a file (e.g. system permissions, system ACLs, SELinux).
In PKI 10.4.1 or later the authentication can be done as follows:
$ pki -n <certificate nickname> -c <password> <command> $ pki -n <certificate nickname> -C <password file> <command> $ pki -n <certificate nickname> <command>
The first and second options are identical to the options available in the previous version.
The third option without any password parameter can be used if there is no NSS database, or if the NSS database is not protected with a password. If the NSS database has a password the CLI will prompt for the password on the console. This option might be preferred for manual execution.
In PKI 10.6.0 or later the authentication can be done as follows:
$ pki -n <certificate nickname> -c <password> <command> $ pki -n <certificate nickname> -C <password file> <command> $ pki -n <certificate nickname> <command> $ pki -n <certificate nickname> -f <password config> <command>
The first, second, and the third options are identical to the options available in the previous version.
The fourth option with -f provides a way to specify multiple passwords for NSS database that has multiple tokens.
The passwords can be specified in a configuration file. The internal token password should be specified
as follows:
internal=<password>
HSM password should be specified as follows:
hardware-<token>=<password>
Anything else will be ignored.
This option can be used to access PKI server’s NSS database:
$ pki \
-d /var/lib/pki/pki-tomcat/conf/alias \
-f /var/lib/pki/pki-tomcat/conf/password.conf \
client-cert-find