Using the iclview utility

Purpose

The iclview program displays the entries contained in an issued certificate list (ICL). Depending on how you have configured PKI Services, the ICL can be in a VSAM data set or in a DB2® table. Each ICL record consists of a fixed header followed by a variable-length section containing the BER-encoded certificate. For each entry iclview displays the header information and optionally calls a user-provided program to process the BER-encoded certificate.

Path setup

Update your PATH, LIBPATH, and NLSPATH environment variables with the appropriate pkiserv directory before you run iclview. (Note that you are updating the environment variables for the user running the utility, not updating values in the PKI Services environment variables file, pkiserv.envars.) Once you have updated these variables, you can run iclview from the UNIX command line.

Variable name	You must add …
PATH	`/install-dir/pkiserv/bin`
LIBPATH	`/install-dir/pkiserv/lib`
NLSPATH	`/install-dir/pkiserv/lib/nls/msg/%L/%N`

The default directory for install-dir is /usr/lpp.

Format

iclview {-d vsam-dataset-name [-r] | -b db2-subsystem-name -k db2-package-name  
        | -c [-p path]}
        [-D CA-domain-name] [-s decode-command-string]

Parameters

You can display usage information about the iclview command format and parameters when you issue the iclview utility command with no parameters.

-d vsam-dataset-name

Specifies the MVS™ data set name of the VSAM issued certificate list (ICL).

If you specify -d, do not specify -b, -k or -c. If you do, the utility issues an error message and the command fails.

Note: If the data set name has no quotes, the program uses the invoker of the command as the first qualifier. If you specify the fully-qualified data set name, use quotes, and make sure to include the escape character, which is a backslash (\), before the quotation marks enclosing the data set name. For example, see \'pkisrvd.vsam.ost\' in Examples.

-r

Indicates to open in VSAM record-level sharing (RLS) mode the VSAM data set specified with the -d option.

-r is ignored and the utility issues a warning message if -b and -k are specified, or if -c is specified.

-b db2-subsystem-name

Specifies the name of the DB2 subsystem or group attachment where the ICL is located.

If you specify -b and you do not specify -k, or you specify -d or -c, the utility issues an error message and the command fails.

-k db2-package-name

Specifies the DB2 package name of the ICL.

If you specify -k and do not specify -b, or you specify -d or -c, the utility issues an error message and the command fails.

-c

Indicates to retrieve the location of the ICL from the pkiserv.conf configuration file. Either the VSAM data set name is retrieved, or the DB2 subsystem name and package name are retrieved, depending which you are using. For VSAM, the SharedPlex value determines whether the VSAM data set is opened in record-level sharing (RLS) mode. (For DB2, the SharedPlex value has no effect on this utility.)

If you specify -c, and you also specify -d, -b, or -k, the utility issues an error message and the command fails.

Note: When you also specify the -D option, you must use the -p option to specify the CA domain configuration directory if it is not /etc/pkiserv.

-p path

Specifies the directory where the pkiserv.conf configuration file resides. If not specified, the directory defaults to /etc/pkiserv. This option is only valid when specified with the -c option. If specified with the -b, -k, or -d options, the utility issues a warning message, and the -p option is ignored.

-D CA-domain-name

Specifies the CA domain name where this utility command is directed.

Notes:

The -D option is required only if PKI Services is running in multiple-CA mode.
The CA-domain-name value can be entered using uppercase or lowercase letters.
When you also specify the -c option, you must use the -p option to specify the CA domain configuration directory if not /etc/pkiserv.

-s decode-command-string

Specifies an optional command to call for decoding the ASN.1-encoded data. The command must be able to read and decode binary (BER) data from STDIN.

Examples

To view the records in the ICL in the VSAM data set 'PKISRVD.VSAM.ICL', passing the certificate to a utility called dumpasn1, use the following command:

iclview -d \'pkisrvd.vsam.icl\' -s 'dumpasn1 -'

To view the records in the ICL for the CA domain MasterCA using the information from the pkiserv.conf file located in the directory /etc/pkiserv/MasterCA, use the following command:

iclview -c -p /etc/pkiserv/MasterCA -D MasterCA

To view the records in the ICL in the DB2 subsystem DSN9 with a package name of MasterCA, passing the certificate to a utility called dumpasn1 and directing the output to the file icl.out, use the following command:

iclview -b DSN9 -k MASTERCA -s 'dumpasn1 -' >icl.out

Note: A dumpasn1 utility is not shipped with PKI Services.

Output

The fixed header data that is displayed for each record is similar to the following sample:

Cert 8: John Q. Public@someWebProvider.com                                                   
     ISSUED (Issued certificate)                                          
     Issued at 2001-12-19 17:27:41                                        
     Last changed 2001-12-19 17:42:30                                     
     Subject: CN=John Smith,OU=Class 1 Internet Certificate CA,O=The Firm 
     Issuer: OU=PKI Services CA,O=IBM,C=US                                
     Requester: John Smith                                                
     ApplData: 1YBSSL                                                     
     Serial Number: CCD                                                   
     Email flag: Off                                                      
     AutoRenew flag: Enabled                                              
     Additional flags Set: NotRenewable                                   
     KeyID: 12FD68977EE1F987DC9CA1440B62CCCD1CD0A9BB 
     Validity: 2012/07/19 00:00:00 – 2013/07/18 23:59:59
     Revocation information location: Distribution Point 151

The first line of the output specifies the certificate's sequential position within the ICL, relative to the other certificates, and the requestor's name.

The second line specifies the certificate state, which is one of the following states, and a comment (if any):

ISSUED
REVOKED, not posted
REVOKED, awaiting CRL post
REVOKED, on posted CRL

Issued at

Indicates when the certificate was issued.

Last changed

Indicates when the administrator last changed the certificate.

Subject

Indicates the name of the person who owns the certificate.

Issuer

Indicates the name of the certificate authority that issued the certificate.

Requestor

Indicates the requestor's name.

Appldata

Indicates the 8-character string identifying to the application the short name or nickname of the certificate template. (PKI Services provides sample certificate templates but it is RACF®, or an equivalent security product, rather than PKI Services, that handles the SAF templates.) Table 1 shows the nicknames for each certificate template. (These nicknames are supplied in the pkiserv.tmpl certificate templates file as defaults but your installation might have changed them or added others during customization. See TEMPLATE sections for more information.)

Serial Number

Indicates the serial number of the certificate as a hexadecimal number.

Email flag

Indicates whether or not to send an expiration warning message. The possible values are On or Off.

AutoRenew flag

Indicates whether a certificate is AutoRenew enabled, disabled, or not set up for automatic renewal.

Revoked at

Indicates the date and time the certificate was revoked or suspended.

Revocation Reason

Indicates one of the following reasons:

No reason.
User key was compromised.
Original use no longer valid.
CA key was compromised.
User changed affiliation.
Certificate was superseded.
Temporarily suspended.

Additional flags Set

The NotRenewable flag indicates that the certificate cannot be renewed. This state occurs when the keys for the certificate were generated by PKI Services, the certificate has a Mail RDN, and the user's email address has changed since the certificate was created.

KeyID

The SHA1 hash of the public key in EBCDIC format, 40 bytes in length. This line is only displayed if the key was generated by PKI Services.

Validity

The validity period of the certificate.

Revocation information location

The location of the revocation information of the end entity certificate. This location can be different than the location specified in the CRLDistributionPoint extension in the certificate if the CRLDistName value was changed after the certificate was created. This line is displayed only if there is revocation information and it can be retrieved successfully. The information can be a distribution point number, or "Master CRL".

Note: CA certificates issued by the PKI Services CA are always placed in the master authority revocation list (ARL) and the ARL distribution point if configured. The revocation information location is therefore not displayed for issued CA certificates.