pki-client Command Line Utility

pki-client provides access to certificate validation services using Reflection PKI Services Manager.

Synopsis

java ‑jar pki-client.jar validate [--service pki‑host[:port]] ‑‑key public‑key‑file [‑‑whoAmI] [‑‑hostName host‑identity] [‑‑userID user‑identity] certificate‑file

java -jar pki-client.jar ping [--service pki‑host[:port]]

java -jar pki-client.jar pubkey [--service pki‑host[:port]]

java -jar pki-client.jar anchors [--service pki‑host[:port]]

Description

pki-client is a Java-based command line utility that you can use to query PKI Services Manager for information. You can query for information using the following keywords:

validate

Returns whether a certificate is valid, and (optionally) which servers or client users are allowed to authenticate using the certificate. Note: The certificate validation test applies only to end-entity certificates, not CA certificates. Valid CA-signed root and intermediate certificates will not pass the validation test.

ping

Returns whether the specified Reflection PKI Services Manager server is available and running.

pubkey

Returns the fingerprint of the specified Reflection PKI Services Manager server's public key in SHA1 and MD5 format.

anchors

Returns the subject line of each of the trust anchors configured for the specified Reflection PKI Services Manager server.

How to run the client

To run the utility, you need a computer running Java 1.5 or newer and the pki-client.jar file, which is installed with Reflection PKI Services Manager. The default install location of the jar file is:

Windows:
64-bit systems: C:\Program Files (x86)\Attachmate\ReflectionPKI
32-bit systems: C:\Program Files\Attachmate\ReflectionPKI\

UNIX: /opt/attachmate/pkid/lib/

You can run pki-client on the PKI Services Manager host, or run it from a remote computer.

To configure a computer to run pki-client:

  1. Confirm that a supported version of Java is running on the system. For example, from a command line, run the following:

    java -version

  2. Copy pki-client.jar to any convenient location on the computer. (If you're running on the PKI Services Manager host, you can use this file in the default install location, and/or copy it to a new location.)
  3. Copy the PKI Services Manager public key to the computer. (If you're running on the PKI Services Manager host, you can use the installed key file.) See the description for --key below for information about where to find this key.

Options

The service option is available for

--service pki-host[:port]

(Optional for ping, pubkey, and anchors) Specifies the host name or IP address of the computer running Reflection PKI Services Manager. The default is localhost:18081. You can omit this option if you're running from the PKI Services Manager host and it is configured to use the default listening address.

--key public-key-file

(Required for validate) Specifies the name and location of the public key used to confirm the identity of Reflection PKI Services Manager. Use quotation marks if the key name or path includes spaces. The default location on the PKI Services Manager host is:

Windows: common application data folder\Attachmate\ReflectionPKI\config\pki_key.pub

UNIX: /opt/attachmate/pkid/config/pki_key.pub

If you're running pki-client on a different computer than PKI Services Manager, copy the public key to the computer running pki-client.

--whoAmI

(Optional for validate) PKI Services Manager reads the identity map file(s) and returns a list of all allowed identities for the certificate being authenticated.

‑‑hostName host‑identity

(Optional for validate) PKI Services Manager reads the map file(s) and reports whether the specified host is an allowed identity for the host certificate being validated.

‑‑userID user‑identity

(Optional for validate) PKI Services Manager reads the map file(s) and reports whether the specified user is an allowed identity for the user certificate being validated.

certificate‑file

(Required for validate) Identifies the certificate to validate. If path information is omitted, pki-client looks for the certificate in the current working directory. Use quotation marks if the certificate name or path includes spaces.

Examples

In all of these examples, the command line shown is executed from the same folder that contains the pki-client.jar file.

In the first example, pki-client runs on the same computer that runs the PKI Services Manager service, so no service host needs to be specified. The response indicates that the certificate is valid and that no identity checking was requested.

C:\Program Files\Attachmate\ReflectionPKI>java -jar pki-client.jar validate --key
"C:\ProgramData\Attachmate\ReflectionPKI\config\pki_key.pub" c:\test\user1_sample.cer

Certificate is valid. Identity was not checked.

In the following example, pki-client runs on a different computer than the PKI Services Manager service, so the service host (mypkihost) must be specified. The public key and certificate are in the same folder as pki-client.jar, so no paths are required. The--whoAmI option is included to request a list of users who can validate with the certificate. The response indicates that only one user (joe) can authenticate using the specified certificate (user_joe.cer).

C:\Test>java -jar pki-client.jar validate --service mypkihost --key pki_key.pub
--whoAmI user_joe.cer

Certificate is valid. Allowed Identities: joe

The following example shows a sample response to the same command when the specified certificate failed to pass one of the required validation tests.

C:\Test>java -jar pki-client.jar validate --service mypkihost --key pki_key.pub
--whoAmI user_joe.cer

Certificate is not valid (error 22): Intermediate cert not found: CN=ABC Authority