|
PurposeThe 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 setupUpdate 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.
Formaticlview {-d vsam-dataset-name [-r] | -b db2-subsystem-name -k db2-package-name
| -c [-p path]}
[-D CA-domain-name] [-s decode-command-string]
ParametersYou 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.
Note: - 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.
ExamplesTo 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.
OutputThe 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.
|