RACDCERT CHECKCERT (Check certificate or certificate chain)

Purpose

Use the RACDCERT CHECKCERT command to check if the digital certificate (or certificates) contained in the specified data set has (or have) already been added to the RACF® database and associated with a user ID.

For authorized users, CHECKCERT lists additional information about certificates in the RACF database. It also provides a summary of certificate chain information.

The output will look like the LISTCHAIN output, except that it will not contain the ring information.

If the certificate is not in the RACF database or the user is not authorized, the output will not show the RACF related information.

If there is no error encountered, the certificates will be displayed with the end-entity certificate listed first, followed by the subsequent issuers', and the following information about the chain:

the number of certificates in the chain
whether the dataset contains the complete chain
- chain is complete
- chain is incomplete
indication of expired certificate(s), if any
- chain contains expired certificate(s)

If an error is encountered, the output may show the chain up to the problem certificate, in the same order as in the valid chain. IRRD302I will be issued followed by another specific message on the cause. See examples below.

See UTF-8 and BMP character restrictions for information about how UTF-8 and BMP characters in certificate names are displayed using RACDCERT functions.

Issuing options

The following table identifies the eligible options for issuing the RACDCERT CHECKCERT command:

As a RACF TSO command?	As a RACF operator command?	With command direction?	With automatic command direction?	From the RACF parameter library?
Yes	No	No. (See rules.)	No. (See rules.)	No
Rules: The following rules apply when issuing this command. The RACDCERT command cannot be directed to a remote system using the AT or ONLYAT keyword. The updates made to the RACF database by RACDCERT are eligible for propagation with automatic direction of application updates based on the RRSFDATA profiles AUTODIRECT.target-node.DIGTCERT.APPL and AUTODIRECT.target-node.DIGTRING.APPL, where target-node is the remote node to which the update is to be propagated.

Authorization required

To issue the RACDCERT CHECKCERT command, you must have the SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.LIST resource in the FACILITY class for your intended purpose, as shown in Table 1.

You must also have READ access to the specified data set that contains the certificate to prevent an authorization abend from occurring when the data set is read.

If any certificate involved in CHECKCERT has the ECC key type, you must have READ authority to CSF1PKV, CSF1TRC, CSF1TRD and CSFOWH resources in the CSFSERV class.

Table 1. Authority required for the RACDCERT CHECKCERT function
IRR.DIGTCERT.LIST
Access level	Purpose
READ	Check your own certificate.
UPDATE	Check another user's certificate.
CONTROL	Check a SITE or CERTAUTH certificate.

Related commands

To add a certificate, see RACDCERT ADD (Add certificate).
To list a certificate, see RACDCERT LIST (List certificate).
To list a certificate, see RACDCERT LISTCHAIN (List certificate chain).

Syntax

For the key to the symbols used in the command syntax diagrams, see Syntax of RACF commands and operands. The complete syntax of the RACDCERT CHECKCERT command is:


RACDCERT CHECKCERT(data-set-name)
[PASSWORD('pkcs12-password')]

Note: The ID(certificate-owner) | SITE | CERTAUTH parameter is ignored for this RACDCERT function.

If you specify more than one RACDCERT function, only the last specified function is processed. Extraneous keywords that are not related to the function being performed are ignored.

If you do not specify a RACDCERT function, LIST is the default function.

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

Parameters

CHECKCERT(data-set-name)

CHECKCERT lists the certificate (or the chain of certificates) in the specified data set. If the certificate request is made by a user with proper authority, information in the RACF database pertaining to that certificate (or certificate chain) is also displayed. Additionally, an authority check is performed by data management when the data set is opened.

The CHECKCERT keyword also supports the evaluation of site certificates and certificate authority certificates. It indicates if the certificate is defined and to whom it is defined after checking the resource IRR.DIGTCERT.LIST in the FACILITY class. READ authority is required if the certificate is associated with the user issuing the command. UPDATE authority is required if the certificate is associated with a user other than the issuer of the command. CONTROL authority is required if the certificate is a certificate authority or a site certificate.

The CHECKCERT keyword can be used on the same set of certificate packages that is allowed by RACDCERT ADD. See RACDCERT ADD for more information.

Note:

The issuer of the RACDCERT command must have READ access to the data-set-name data set to prevent an authorization abend from occurring when the data set is read.
No certificate ID is displayed if the certificate is not installed. If the certificate is installed, the certificate ID is displayed only if the certificate has a label and the user is authorized to list the specific certificate information.

PASSWORD('pkcs12-password')

Specifies the password that is associated with the PKCS #12 certificate package. It is required if the data set contains a PKCS #12 certificate package and it must not be specified if the data set contents are not PKCS #12.

Note: The password specified will be visible on the screen, so care should be taken to prevent it from being viewed when entered. Because PKCS #12 passwords do not follow the normal TSO/E rules for password content, they cannot be suppressed as they normally would be.

The 'pkcs12-password' can be up to 255 characters in length, is case-sensitive, and can contain blanks.

Examples


Example 1	Operation	User NETADMN wishes to check the certificates of another user. Either NETADMN is not authorized to perform that function or none of the user’s certificate are in RACF.
	Known	User NETADMN has UPDATE access to profile IRR.DIGTCERT.LIST in the FACILITY class.
	Command	`RACDCERT CHECKCERT('TEST.FILE')`
	Output	See Figure 1
Example 2	Operation	User NETADMN wishes to check the certificates of another user and is authorized to perform that function. Only the end-entity certificate is in RACF, and it is expired.
	Known	User NETADMN has UPDATE access to profile IRR.DIGTCERT.LIST in the FACILITY class.
	Command	`RACDCERT CHECKCERT('TEST.FILE')`
	Output	See Figure 2
Example 3	Operation	User NETADMN wishes to check the certificates of another user and is authorized to perform that function. Not all certificates are in RACF, and the signature on certificate is bad.
	Known	User NETADMN has CONTROL access to profile IRR.DIGTCERT.LIST in the FACILITY class.
	Command	`RACDCERT CHECKCERT('TEST.FILE')`
	Output	See Figure 3
Example 4	Operation	User NETADMN wishes to check the certificates of another user and is authorized to perform that function. Not all certificates are in RACF, and the subject name on certificate 2 has an invalid character (certificate 2 is not displayed).
	Known	User NETADMN has CONTROL access to profile IRR.DIGTCERT.LIST in the FACILITY class.
	Command	`RACDCERT CHECKCERT('TEST.FILE')`
	Output	See Figure 4

Figure 1. Output for the RACDCERT CHECKCERT command where none of the user’s certificates are in RACF.

RACDCERT CHECKCERT('TEST.FILE')

Certificate 1:  
  Start Date: 2011/10/20 00:00:00  
  End Date:   2012/10/20 23:59:59  
  Serial Number:                   
       >05<                        
  Issuer's Name:                   
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=samplecert.O=Test.SP=Poughkeepsie.C=US<                  
  Subject's AltNames:                           
    IP: 127.0.0.5 
    EMail: choi at us.ibm.com                           
    Domain: www.ibm.com                           
  Signing Algorithm: sha1RSA 
  Key Usage: HANDSHAKE   
  Key Type: RSA
  Key Size: 1024  
  
  
Certificate 2:
  Start Date: 2010/03/22 00:00:00  
  End Date:   2020/10/22 23:59:59  
  Serial Number:                   
       >02<                        
  Issuer's Name:                   
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<             
  Signing Algorithm: sha256RSA 
  Key Usage: CERTSIGN   
  Key Type: RSA
  Key Size: 2048
  

Certificate 3:                                              
  Start Date: 2008/04/20 00:00:00  
  End Date:   2038/04/20 23:59:59  
  Serial Number:                   
       >00<                        
  Issuer's Name:                   
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                  
  Signing Algorithm: sha256RSA 
  Key Usage: CERTSIGN
  Key Type: RSA
  Key Size: 4096
  

  Chain information:
  Chain contains 3 certificate(s), chain is complete

Figure 2. Output for the RACDCERT CHECKCERT command from an authorized issuer, only the end-entity certificate is in RACF, and it expired.

RACDCERT CHECKCERT('TEST.FILE')

  Certificate 1:  
Digital certificate information for user CHOI:              
                                                              
  Label: samplecert                                              
  Certificate ID: 2QbmxsPI1smJl4OFmaPy                        
  Status: TRUST                                               
  Start Date: 2010/10/20 00:00:00  
  End Date:   2011/10/20 23:59:59  
  Serial Number:                   
       >05<                        
  Issuer's Name:                   
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=samplecert.O=Test.SP=Poughkeepsie.C=US<                  
  Subject's AltNames:                           
    IP: 127.0.0.5 
    EMail: choi at us.ibm.com                           
    Domain: www.ibm.com                           
  Signing Algorithm: sha1RSA 
  Key Usage: HANDSHAKE   
  Key Type: RSA
  Key Size: 1024
  Private Key: Yes 
  PKDS Label: SAMPLECERT                        
  

  Certificate 2:
  Start Date: 2010/03/22 00:00:00  
  End Date:   2020/10/22 23:59:59  
  Serial Number:                   
       >02<                        
  Issuer's Name:                   
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<             
  Signing Algorithm: sha256RSA 
  Key Usage: CERTSIGN   
  Key Type: RSA
  Key Size: 2048
  

  Certificate 3:                                              
  Start Date: 2008/04/20 00:00:00  
  End Date:   2038/04/20 23:59:59  
  Serial Number:                   
       >00<                        
  Issuer's Name:                   
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                  
  Signing Algorithm: sha256RSA 
  Key Usage: CERTSIGN
  Key Type: RSA
  Key Size: 4096
  

  Chain information:
  Chain contains 3 certificate(s), chain is complete
  Chain contains expired certificate(s)

Figure 3. Output for the RACDCERT CHECKCERT command from an authorized issuer, all the certificates are not in RACF, signature on certificate 2 is not good.

RACDCERT CHECKCERT('TEST.FILE')

Certificate 1:  
  Start Date: 2011/10/20 00:00:00  
  End Date:   2012/10/20 23:59:59  
  Serial Number:                   
       >05<                        
  Issuer's Name:                   
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=samplecert.O=Test.SP=Poughkeepsie.C=US<                  
  Subject's AltNames:                           
    IP: 127.0.0.5 
    EMail: choi at us.ibm.com                           
    Domain: www.ibm.com                           
  Signing Algorithm: sha1RSA 
  Key Usage: HANDSHAKE   
  Key Type: RSA
  Key Size: 1024  
  Private Key: No 
  
Certificate 2:
  Start Date: 2010/03/22 00:00:00  
  End Date:   2020/10/22 23:59:59  
  Serial Number:                   
       >02<                        
  Issuer's Name:                   
       >CN=MasterCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<             
  Signing Algorithm: sha256RSA 
  Key Usage: CERTSIGN   
  Key Type: RSA
  Key Size: 2048
  Private Key: No

IRRD302I Processing terminated. Problem found in certificate 2 in the dataset.
IRRD112I The certificate that you are processing does not have a valid signature.

Figure 4. Output for the RACDCERT CHECKCERT command from an authorized issuer, all the certificates are not in RACF, subject name on certificate 2 has invalid character (certificate 2 is not displayed)

RACDCERT CHECKCERT('TEST.FILE')

 Certificate 1:  
  Start Date: 2011/10/20 00:00:00  
  End Date:   2012/10/20 23:59:59  
  Serial Number:                   
       >05<                        
  Issuer's Name:                   
       >CN=sampleCA.O=Test.SP=Poughkeepsie.C=US<                   
  Subject's Name:                  
       >CN=samplecert.O=Test.SP=Poughkeepsie.C=US<                  
  Subject's AltNames:                           
    IP: 127.0.0.5 
    EMail: choi at us.ibm.com                           
    Domain: www.ibm.com                           
  Signing Algorithm: sha1RSA 
  Key Usage: HANDSHAKE   
  Key Type: RSA
  Key Size: 1024  
  Private Key: No 

IRRD302I Processing terminated. Problem found in certificate 2 in the dataset.
IRRD182I Unexpected character encountered.