Use the Certificate Utility to display the certificate hierarchy in your database. Optionally, it will display each certificate, its signing certificate, the certificates that it has signed, and all of the information provided with the CHKCERT and LIST commands.
- To execute SAFCRRPT, you need a region size of 1500K and READ access in the CSFSERV class for resources CSFIQA, CSFIQF, CSFOWH, and CSFDSV.
- If you are having a problem setting up TLS for an application, run the utility against the key ring to identify problems in the setup. If the certificates arenotobtained from a key ring, UPDATE access to IRR.DIGTCERT.LIST in the IBMFAC class is required to run the report. If the certificates are from a key ring, the utility uses the R_datalib callable service, which requires READ access to the IRR.DIGTCERT.LISTRING resource when the key ring is owned by the caller of the utility. If the key ring is not owned by the caller of the utility, or the key ring is owned by CERTAUTH or SITE, UPDATE access is required to the IRR.DIGTCERT.LISTRING resource.
You can tailor the output to display certificates:
- For a specified user
- For a specified key ring
- That have not expired
- That have a key in ICSF
- That are currently trusted
- That will expire within a specified number of days
Certificate Utility JCL
The following is sample JCL to run the certificate utility. This JCL is found in the CAI.CAKOJCL0 file on the distribution tape. The member name is CERTUTIL:
//SAFRPTCR EXEC PGM=SAFCRRPT,PARM='TITLE(Certificate detailed report)' //STEPLIB DD DISP=SHR,DSN=CAI.CAKOLINK //SYSUDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD * Recordid(CERT-) detail EXT
Certificate Utility Parameters
The input parameters can be specified in the PARM field or SYSIN data set. When parameters conflict, the product uses the last parameter that was entered (USER and RECORDID).
- TITLE (cccccccccc)Specifies a character string used as the title at the top of the report. If you do not specify this parameter, the title is 'SAFCRRPT - Certificate Utility'. If this string is longer than 35 characters, the report generator uses only the first 35 characters as the title.Range:1 to 35
- LINECNT(60|nnnn)Specifies the number of output lines to print on a page.Maximum:The physical constraints of the output media used or 99,999 lines.
- USER (userid|userid mask)Displays all certificates for the specified user(s). When specified with the RINGNAME parameter, the user field cannot be masked.Default:The caller's userid.
- DETAILSpecifies that the label, serial number, subject's distinguished name, issuer's distinguished name, validity dates, public key, PKDS label (if one exists), private key size and type are displayed.
- SUMMARYSpecifies that the record id of the displayed record, the record id of the signing certificate and the record ids of the certificates that this certificate signed are displayed.
- DUMPAdds a hexadecimal dump of the certificate to the display. Dump is ignored if DETAIL is not specified.
- EXTAdds a list of the extensions in the certificate to the display. EXT is ignored if DETAIL is not specified. If the utility cannot identify the name of the extension in the certificate, the OID of the extension is displayed.Extension values are also displayed. If the format of the extension can be identified, a meaningful description of the settings within the extension is displayed. If the format of the extension cannot be identified, a hexadecimal dump of the extension contents along with a character representation will be displayed.
- RINGNAME(ring name)Displays certificates from a specific key ring. The utility uses the R_datalib callable service to retrieve the certificates from the key ring. When RINGNAME is specified, the USER parameter cannot be masked.Note:The RINGNAME value is the same as the CA Top Secret LABLRING value of the up to 237-character label name of the keyring where the certificates reside.
- RECORDID(record id mask)Specifies the record id of the certificate(s) to be displayed. RECORDID cannot be used with the RINGNAME parameter.
- TRUST|NOTRUSTSpecifies that only certificates that have either TRUST or NOTRUST status are displayed.
- ICSFSpecifies that only certificates that have the public or private key saved in ICSF are displayed.
- PCICCSpecifies that only certificates that have the public or private key saved in saved in ICSF using the PCICC keyword are displayed.
- EDAYS(expire days)Specifies that only certificates that expire within the specified number of days are displayed.Range:1 to 365
- EXPIREDAllows you to display only certificates that have expired.
- RSASpecifies that only certificates that use the RSA algorithm to create the public-private key pair are displayed.
- DSASpecifies that only certificates that use the DSA algorithm to create the public-private key pair are displayed.
- FIELDS(subparameter1,subparameter2,...)Limits the information returned by the report. The subparameters are as follows:
The FIELDS parameter can be specified on the PARM of the EXEC within the JCL as well as via the SYSIN parameter.
- LABELDisplay certificate label.
- SERIALDisplay serial #.
- ISSUERDisplay Issuer DN.
- SUBJECTDisplay Subject DN.
- ACTIVEDisplay Active Date.
- EXPIREDisplay Expire Date.
- KEYSIZEDisplay key size.
- PUBLICDisplay public key.
- PKDSDisplay PKDS label.
- SIGNOFDisplay the certificates that this certificate has signed.
- SIGALGDisplays the signature algorithm used to create the signature.
- TRUSTDisplays an indication of whether the certificate is trusted or not.
- CERTLENDisplays the length of the certificate.
Example: Specify the FIELDS Parameter on the PARM of the EXEC without Other Parameters
This example specifies the FIELDS parameter on the PARM of the EXEC, without any other parameters. Each element of the list is separated by a comma.
//SAFRPTCR EXEC PGM=SAFCRRPT, // PARM=(FIELDS(LABEL,SERIAL,ISSUER,SUBJECT,ACTIVE,EXPIRE, // KEYSIZE,PUBLIC,PKDS,SIGNOF))
Example: Specify the FIELDS Parameter on the PARM of the EXEC with Other Parameters
This example specifies the FIELDS parameter on the PARM of the EXEC with other parameters; the other parameters are enclosed in single quotation marks, such as ‘RECORDID(-)’.
//SAFRPTCR EXEC PGM=SAFCRRPT, // PARM=('RECORDID(-)', // FIELDS(ACTIVE,EXPIRE,KEYSIZE,PUBLIC,PKDS,SIGNOF,LABEL, // SERIAL,ISSUER,SUBJECT))
Example: Specify the FIELDS Parameter within the SYSIN of the JCL
This example specifies the FIELDS parameter within the SYSIN of the JCL. Because the parameter extends to several lines, each element of the list is separated by a single space.
//SYSIN DD * FIELDS(ISSUER SUBJECT ACTIVE EXPIRE KEYSIZE PUBLIC PKDS SIGNOF LABEL SERIAL) RECORDID(-) /*
Sample Report Output
Sample Output - Summary
Mainframe Security - SAFCRRPT - Certificate Utility - PAGE 3 DATE 03/14/06 (06.073) TIME 10.18 Record id - CERTAUTH.AUTO014 Signed by: None - Self-Signed Signer of - CERTAUTH.AUTO013 Record id - CERTAUTH.BOB Signed by: None - Self-Signed Record id - CERTAUTH.CLIFFTA Signed by: None - Self-Signed Record id - CERTAUTH.DSACA Signed by: None - Self-Signed Signer of - BOB.DSA2048 CARLA01.DSA2048 CARLA01.DSA512 CARLA01.DSA768 CARLA01.RSA512 CARLA01.RSA768 DSATEST.DSA1024 DSATEST.DSA2048 DSATEST.DSA512 KERMIT.DSA KERMIT.RSA Record id - CERTAUTH.EDDIEABC Signed by: None - Self-Signed Record id - CERTAUTH.HAWKS01 Signed by: None - Self-Signed Record id - CERTAUTH.HAWKS02 Signed by: None - Self-Signed Record id - CERTAUTH.HAWKS03 Signed by: None - No Record Found Record id - CERTAUTH.HEROS Signed by: None - No Record Found Record id - CERTAUTH.ICSFCA Signed by: None - Self-Signed Signer of - CARLA01.ICSFCA IMWEBSRV.ICSFSSL IMWEBSRV.SSLICSF STANLEY.ICSFCA Record id - CERTAUTH.ICSF01 Signed by: None - Self-Signed Record id - CERTAUTH.LOCALCA Signed by: None - Self-Signed Signer of - CARLA01.T2048 GENC002A.AUTO001 GENC002A.AUTO002 GENC002A.AUTO003 GENC002A.AUTO004 IMWEBSRV.SERVER TIMOTHY.DEE WEBSRV Record id - CERTAUTH.MAJORLG Signed by: None - Self-Signed Signer of - CERTAUTH.AL CERTAUTH.NL
Sample Report Output - Detail
Mainframe Security - SAFCRRPT - Certificate Utility - PAGE 11 DATE 03/14/06 (06.073) TIME 10.18 Record id - CERTAUTH.AL Signed by: CERTAUTH.MAJORLG Label American League CA Serial # - 05 Issuer DN - CN=Major League Baseball Certificate Authority. OU=Used for testing PKCS 12 CA certificate insert processing.O=MLB Commissioners Office.C=US Subject DN - CN=American League Certificate Authority.O=Major League Baseball.C=US Active Date 2004/11/30 Expire Date 2015/12/20 Pub Key Size 1024 RSA Public Key 0000 30819F30 0D06092A 864886F7 0D010101 0010 05000381 8D003081 89028181 00D7F4B8 0020 BCA5B3B0 D33F5575 C7EF5F48 9ABC4C77 0030 5F46257B 13C3A9A7 B497F422 EFDD8B44 0040 9F756234 76D70DFC 2A6B3FE6 40532234 0050 0147CC94 4DB0ABD4 732729B4 9E8FBD44 0060 F7DAFB00 33ED254D EB0A6334 8FD0ECEB 0070 4374317C D4CBB1AE B7C6FD08 0412785B 0080 0A751C69 3BF4DC66 C2CBA8F1 093BAE10 0090 3604CC15 66CF8A5D 2EF9038A 03020301 00A0 0001 Signer of - CERTAUTH.ACENTRAL CERTAUTH.ALWEST Record id - CERTAUTH.LOCALCA Signed by: None - Self-Signed Label Local CA Serial # - 0000000000 Issuer DN - CN=CA-TSS Certificate Authority.OU=CA-AC F2 Development.OU=OS390 Development.O=Computer Associates Subject DN - CN=CA-TSS Certificate Authority.OU=CA-AC F2 Development.OU=OS390 Development.O=Computer Associates Active Date 2001/09/05 Expire Date 2002/09/05 Pvt Key Size 512 RSA Public Key 0000 305C300D 06092A86 4886F70D 01010105 0010 00034B00 30480241 00E3E055 322F34F9 0020 18099F1C 05D0EB3E 4011AD5B 8BE8CCC2 0030 54E83564 5DB02E6F 682D9A23 49C62077 0040 0ACFABAF C9847E4D 3646062B 4B1C249D 0050 44072EC6 577F98D4 AE020301 0001 Signer of - CARLA01.T2048 GENC002A.AUTO001 GENC002A.AUTO002 GENC002A.AUTO003 GENC002A.AUTO004 IMWEBSRV.SERVER TIMOTHY.DEE WEBSRV
Sample Report Output - Detail Ext
User - JONATHAN Digicert - Sweet4 Signed by: CERTAUTH.AUTH01 Label Sweet4 Serial # - 01 Issuer DN - CN=AUTH01.T=Auth 01 signer Subject DN - CN=Sweet4.T=Little Boy Active Date 2010/03/26 Expire Date 2011/03/26 Pub Key Size 1024 RSA Algorithm sha-1WithRSAEncryption Trusted Yes Cert Length 025F Extensions X509v3 Key Usage DOCSIGN (40) Netscape Comment Generated by CA SAF Certificate Management Facili X509v3 Authority Key Identifier 931222BCCD024D24CCA1D57216F69BA90735F2B6 X509v3 Subject Key Identifier 2F4B6E8E64AC5F3CF493E57691B2FCBCE141E9F1 Public Key 0000 30819F30 0D06092A 864886F7 0D010101 0010 05000381 8D003081 89028181 00CDC14D 0020 737C5704 52049344 7D0135C9 5EFE3456 0030 16FC6BF4 22A366AE 703B9E8B CBE2FF7F 0040 4F3DF663 7B699695 03FF11D4 40A0E6FC 0050 0D5DF167 C63450DC 92409A9A 07FEE89C 0060 96B6518A BA84921C DC276E9B AFE610AC 0070 E7147F29 E3622D6E EB8A0E1A ADDD8946 0080 42EF2D62 C6354DE7 FCC1C009 E212E899 0090 BF49032C E60B5C21 C69639DB 9D020301 00A0 0001
Sample Output - Totals
CA Mainframe Security - 'r15 example of totals for Cert Utility Rpt' DATE 11/22/10 (10.326) TIME 13.58 Total Certificates 80 CA Certificates 00 Site Certificates 00 User Certificates 80 Expired Certificates 00 Inactive Certificates 00 ICSF Certificates 00 PCICC Certificates 00 Self-signed certificates 80 RSA certificates 80 DSA certificates 00 ECC certificates 00 Trusted Certificates 80 High Trust Certificates 00
Sample Output “Signed by ” Field Definition
Each certificate record displayed in both the summary and detail reports includes a field to display the record ID of the CA Top Secret defined certificate used to sign the current certificate. This field is preceded by the “Signed by:” constant. Based on the results of the search performed by the utility, this field contains one of three possible values:
- The actual name of the signing certificate if found in the security file.
- “None - Self-signed”. There is no signing certificate because the current certificate is self-signed.
- “None - No Record Found”. The current certificate is signed by another certificate, but the signing certificate could not be found in the security file. This can happen when the certificate was signed by an external certificate authority (CA) before it was added to CA Top Secret, or if the signing certificate has been deleted from the security file.