RACDCERT LIST (List certificate)

Purpose

Use the RACDCERT LIST command to display digital certificate information, including certificate authority and site certificate information. You can also use the RACDCERT LIST command to list all certificates owned by a user ID.

Because the virtual key ring for a user ID consists of all certificates owned by the user ID, using the RACDCERT LIST command to list all certificates owned by a user ID is the same as listing the contents of the virtual key ring for that user ID.

For each digital certificate defined, the following information is displayed:

Label
Certificate ID
Status (trusted, not trusted, or highly trusted)
Validity dates
Serial number
Issuer's distinguished name
Up to 256 bytes of the subject's name, as found in the certificate itself
Signing algorithm (md2RSA, md5RSA, sha1RSA, sha1DSA, sha256DSA, sha256RSA, sha224RSA, sha224DSA, sha384RSA, sha512RSA, sha1ECDSA, sha256ECDSA, sha224ECDSA, sha384ECDSA, sha512ECDSA or UNKNOWN if none of the preceding)
Extensions, if present (specifically, keyUsage and subjectAltName)
Key type:
- RSA (if the certificate was installed in RACF with no key type specified or with keyword RSA)
- RSA Mod-Exp (if the certificate was installed in RACF with keyword ICSF)
- DSA (if the certificate was installed in RACF with keyword DSA)
- NIST ECC (if the certificate was installed in RACF with keyword NISTECC)
- Brainpool ECC (if the certificate was installed in RACF with keyword BPECC)
Key size
Presence of a private key (YES or NO)
PKDS label, if the public or private key is stored in the ICSF PKA key data set (PKDS); TKDS token and TKDS ID, if the private key is stored in the ICSF Token data set (TKDS)
Ring associations, if present (the ring name to which this certificate is connected and the ring owner)

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 LIST 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 LIST command, you must have the SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.LIST resource in the FACILITY class for your intended purpose.

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

Related commands

To list a key ring, see RACDCERT LISTRING.
To list a token, see RACDCERT LISTTOKEN.

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 LIST command is:

RACDCERT [ LIST

[ (LABEL('label-name')) ]
| [ (SERIALNUMBER(serial-number) [ ISSUERSDN('issuer's-dn') ]
) ] ]
[ ID(certificate-owner) | SITE | CERTAUTH ]

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

LIST(LABEL('label-name'))

LIST(SERIALNUMBER(serial-number) ISSUERSDN('issuer's-dn'))

If the RACDCERT command is issued with no other operands, LIST is the default and the RACDCERT command lists the command issuer's digital certificate information. If the RACDCERT command is issued with the ID keyword and no other operands, it lists the digital certificate information associated with the user ID specified with the ID keyword.

The issuer's distinguished name and the subject's distinguished name can contain blanks. If the name displayed in the output is subsequently entered with the ISSUERSDN keyword, the blanks must be included. In the output of LIST, the characters > and < are used to mark the beginning and end of the serial number, issuer's name, and subject's name. When information continues to the next line, < appears in column 79 of the output, and > appears in column 9 of the continuation line.

If the user has only one certificate, or if all certificates are to be displayed, the SERIALNUMBER and ISSUERSDN keywords, or the LABEL keyword, and their associated values can be omitted. If the user has more than one certificate the LABEL, SERIALNUMBER, or SERIALNUMBER and ISSUERSDN can be used to select which certificate to list.

When specifying the issuer's distinguished name or the label, you must specify any mixed-case or blank characters exactly as they are defined in the certificate.

Restriction: The ISSUERSDN keyword is not supported for lengthy issuer's distinguished names when the name of the certificate's DIGTCERT profile contains a certificate hash value. For more information about DIGTCERT profile names, see the "Purpose" topic of RACDCERT ADD.

For a description of label-name, see the description of the WITHLABEL keyword for RACDCERT ADD.

If present, the SubjectAltName values are displayed under the heading Subject's AltNames. The subheadings IP, EMail, Domain, and URI are followed by their first value. If more than one line is required to display the value, the additional lines will start in the same column. The word at replaces the @ symbol for email-address.

Example:

EMail: JRoenick at US.Mycompany.Com-More-Info-About-An-EMail-Addr
ess-follows-Some-More-Info-About-An-EMail-Address

If present, the keyUsage values are displayed next to the heading Key Usage. The possible values are:

HANDSHAKE - indicates digitalSignature and keyEncipherment are on
DATAENCRYPT - indicates dataEncipherment is on
DOCSIGN - indicates nonRepudiation is on
CERTSIGN - indicates keyCertSign and cRLSign is on
KEYAGREE - indicates keyAgreement is on

The keyUsage values are displayed as GENCERT options separated by commas.

Example:

Key Usage: HANDSHAKE, CERTSIGN

Note: If the certificate was created using a previous z/OS release of RACF that did not support certificate labels, the certificate listing will contain the following output:

No label
assigned

ID(certificate-owner) | SITE | CERTAUTH

Specifies that the certificate to list is either a user certificate associated with the specified user ID, a site certificate, or a certificate-authority certificate. If you do not specify ID, SITE, or CERTAUTH, the default is ID, and certificate-owner defaults to the user ID of the command issuer. If more than one keyword is specified, the last specified keyword is processed and the others are ignored by TSO command parse processing.

Examples

Example	Activity label	Description
1	Operation	User NETB0Y requests the listing of his Savings Account digital certificate to ensure it has been defined, and that it is marked trusted. He has READ access to the FACILITY class profile IRR.DIGTCERT.LIST. He issues the RACDCERT command with the LIST keyword, specifying the label to identify his certificate.
	Known	User NETB0Y has been given READ access to profile IRR.DIGTCERT.LIST in the FACILITY class.
	Command	`RACDCERT LIST(LABEL('Savings Account'))`
	Output	See Figure 3.
2	Operation	User GEORGEM requests the listing of all certificates associated with his user ID.
	Known	User ID GEORGEM has 3 certificates, one of which is not associated with any rings.
	Command	`RACDCERT LIST`
	Output	See Figure 4.
3	Operation	User CADUDE wants to list the information from the local certificate-authority certificate with HIGHTRUST status.
	Known	User CADUDE has CONTROL authority to the profile IRR.DIGTCERT.`*` in the FACILITY class.
	Command	`RACDCERT CERTAUTH LIST(LABEL('Local PKIX CA'))`
	Output	See Figure 5.
4	Operation	User CADUDE wants to list information from the certificate of user MSURESH.
	Known	User CADUDE has CONTROL authority to the profile IRR.DIGTCERT.`*` in the FACILITY class. User SURESH has only one certificate. The certificate is self-signed and was issued by the `Show Me The € Bank`. Because the Euro symbol (€) does not map to the IBM®-1047 code page, the certificate listing contains the Euro symbol represented by six characters in the format U+20AC, where 20AC is the hexadecimal form of the Unicode code point for the Euro symbol.
	Command	`RACDCERT ID(MSURESH) LIST`
	Output	See Figure 6.
5	Operation	User CADUDE wants to list information from the certificate of user CHLOE.
	Known	User CADUDE has CONTROL authority to the profile IRR.DIGTCERT.`*` in the FACILITY class. User CHLOE has only one certificate. The private key of the certificate was generated with the elliptic curve cryptography (ECC) algorithm and the keyAgreement indicator is set on.
	Command	`RACDCERT ID(CHLOE) LIST`
	Output	See Figure 7.

Figure 1. Output for the RACDCERT LIST command showing an assigned PKDS label (based on RACDCERT GENCERT: Example 2)

RACDCERT LIST(LABEL('Wen Ting''s certificate'))

Digital certificate information for user WENTING:
   Label: Wen Ting's certificate
   Certificate ID: 2QfHxdbZx8XUaqweQMOFmaNA46iXhUBgQOKFmUB7QPDw
   Status: TRUST
   Start Date: 2005/08/11 00:00:00
   End Date:   2020/08/10 23:59:59
   Serial Number:
       >00<
   Issuer's Name:
       >CN=Wen Ting's certificate<
   Subject's Name:
       >CN=Wen Ting's certificate<
   Signing Algorithm: sha256RSA 
   Key Type: RSA
   Key Size: 2048
   Private Key: YES
   PKDS Label: IRR.DIGTCERT.WENTING.SY1.BD7103108611F42F

Figure 2. Output for the RACDCERT LIST command showing a PKDS label that is derived from a specified certificate label (based on RACDCERT ADD: Example 2)

RACDCERT SITE LIST(LABEL('WenTing'))

Digital certificate information for SITE:
   Label: WenTing
   Certificate ID: egljcv8XUaqweQMOFmaNA46iXhUBgQOKFmUB7QPDw
   Status: TRUST
   Start Date: 2005/08/11 00:00:00
   End Date:   2020/08/10 23:59:59
   Serial Number:
       >00<
   Issuer's Name:
       >CN=Wen Ting's certificate<
   Subject's Name:
       >CN=Wen Ting's certificate<
   Signing Algorithm: sha1RSA 
   Key Type: RSA
   Key Size: 1024
   Private Key: NO
   PKDS Label: WENTING

Figure 3. Output for the RACDCERT LIST command specifying the certificate by label

RACDCERT LIST(LABEL('Savings Account'))

Digital certificate information for user NETB0Y:
  Label: Savings Account
  Certificate ID: 2QbVxePC1ujigaWJlYeiQMGDg5aklaNA
  Status: TRUST
  Start Date: 2010/11/10 00:00:00
  End Date:   2011/11/10 23:59:59
  Serial Number:
    >5D666C20207A6638727A413872D8413B<
  Issuer's Name:
    >OU=BobsBank Savers.O=BobsBank.L=Internet<
  Subject's Name:
    >CN=S.S.Smith.OU=Digital ID Class 1 - NetScape.OU=BobsBank Class 1 - S<
    >avingsAcct.O=BobsBank.L=Internet<
    Signing Algorithm: sha256ECDSA
    Key Type: Brainpool ECC        
    Key Size: 192                  
    Private Key: YES               
    Ring Associations:             
    *** No rings associated ***

Figure 4. Output for the RACDCERT LIST command listing all certificates owned by the command issuer

RACDCERT LIST

 Digital certificate information for user GEORGEM:

  Label: New Cert Type - Ser # 00
  Certificate ID: 2QfHxdbZx8XU1YWmQMOFmaNA46iXhUBgQOKFmUB7QPDw
  Status: TRUST
  Start Date: 2010/04/18 03:01:13
  End Date:  2020/02/13 03:01:13
  Serial Number:
    >00<
  Issuer's Name:
    >OU=Internet Demo CertAuth.O=The Cert Software Inc.<
  Subject's Name:
    >OU=Internet Demo CertAuth.O=The Cert Software Inc.<
  Signing Algorithm: sha1RSA 
  Key Type: RSA Mod-Exp
  Key Size: 1024
  Private Key: YES
  PKDS Label: IRR.DIGTCERT.GEORGEM.SY1.BD7103108611F42F
  Ring Associations:
  Ring Owner: GEORGEM
  Ring:
    >GEORGEMsNewRing01<
  Ring Owner: GEORGEM
  Ring:
    >GEORGEMsRing<

  Label: New Type Cert - VsignC1
  Certificate ID: 2QfHxdbZx8XU1YWmQOOol4VAw4WZo0BgQOWiiYeVw/FA
  Status: TRUST
  Start Date: 2010/04/22 23:23:26
  End Date:  2020/01/15 23:23:26
  Serial Number:
    >3511A552906FE7D029A44019D411FC3E<
  Issuer's Name:
    >OU=Class 1 Public Primary Certification Authority.O=VeriSign, Inc..C=<
    >US<
  Subject's Name:
    >OU=VeriSign Class 1 CertAuth - Individual Subscriber.O=VeriSign, Inc..L=Int<
    >ernet<
  Signing Algorithm: sha1RSA
  Key Type: RSA
  Key Size: 512
  Private Key: YES
  Ring Associations:
  Ring Owner: GEORGEM
  Ring:
    >GEORGEMsNewRing01<

  Label: New Type Cert - VsignC2
  Certificate ID: 2QfHxdbZx8XU1YWmQOOol4VAw4WZo0BgQOWiiYeVw/JA
  Status: NOTRUST
  Start Date: 2010/03/19 15:39:52
  End Date:  2020/03/19 15:39:52
  Serial Number:
    >50D35294912F79D315E32B31AC8548F0<
  Issuer's Name:
    >OU=Class 2 Public Primary Certification Authority.O=VeriSign, Inc..C=<
    >US<
  Subject's Name:
    >OU=VeriSign Class 2 CertAuth - Individual Subscriber.O=VeriSign, Inc..L=Int<
    >ernet<
  Signing Algorithm: sha256ECDSA
  Key Type: NIST ECC
  Key Size: 256
  Private Key: NO
  Ring Associations:
    *** No rings associated ***

Figure 5. Output for the RACDCERT LIST command showing a CERTAUTH certificate

RACDCERT CERTAUTH LIST(LABEL('Local PKIX CA'))

 Digital certificate information for CERTAUTH:

  Label: Local PKIX CA
  Certificate ID: Sc9bjZwKwLNxKw2myumPlGy8iGzJQSYi/u35j0eyFe213XgGBMTsUvCW
  Status: HIGHTRUST
  Start Date: 2008/08/05 00:00:00
  End Date:  2020/08/05 23:59:59
  Serial Number:
      >00<
  Issuer's Name:
      >CN=Local CA<
  Subject's Name:
      >CN=Local CA<
  Subject's AltNames:
  IP: 9.117.170.150
  EMail: localca at www.widgits.com
  Domain: www.widgits.com
  URI: http://www.widgits.com/welcome.html
  Signing Algorithm: sha1RSA
  Key Usage: HANDSHAKE, DATAENCRYPT, DOCSIGN, CERTSIGN
  Key Type: RSA
  Key Size: 1024
  Private Key: YES
  Ring Associations:
  *** No rings associated ***

Figure 6. Output for the RACDCERT LIST command showing a UTF-8 or BMP character that does not map to the IBM-1047 code page

RACDCERT ID(MSURESH) LIST

Digital certificate information for user MSURESH:
   Label: Euro 
   Certificate ID: 2QfJwtTk4sXZxaSZlkBA 
   Status: NOTRUST 
   Start Date: 2008/10/04 00:00:00 
   End Date: 2020/01/01 00:00:00 
   Serial Number: 
       >68655BB4D15CDF8D45ED01BC551E8ED7< 
   Issuer's Name: 
       >CN=Show Me The U+20AC Bank< 
   Subject's Name: 
       >CN=Show Me The U+20AC Bank< 
   Signing Algorithm: sha1RSA
   Key Type: RSA
   Key Size: 512
   Private Key: NO
   Ring Associations: 
   *** No rings associated ***

Figure 7. Output for the RACDCERT LIST command for a certificate with an NIST ECC private key

RACDCERT ID(CHLOE) LIST

Digital certificate information for user CHLOE:                                
   Label: Joans Personal Certificate                                           
   Certificate ID: 2QfJwtTk4sXZ0ZaBlaJA14WZopaVgZNAw4WZo4mGiYOBo4VA            
   Status: TRUST                                                               
   Start Date: 2010/01/26 00:00:00                                             
   End Date:   2011/01/26 23:59:59                                             
   Serial Number:                                                              
       >01<                                                                    
   Issuer's Name:                                                              
       >CN=Certificate Authority for First Savings Bank.OU=Mortgage Departmen< 
       >t.O=First Savings Bank.C=US<                                           
   Subject's Name:                                                             
       >CN=Joan Doe.OU=Mortgage.L=Red Hook.SP=NY.C=US<                         
   Signing Algorithm: sha256ECDSA
   Key Usage: KEYAGREE                                                         
   Key Type: NIST ECC
   Key Size: 192
   Private Key: YES
   Ring Associations:                                                          
   *** No rings associated ***

Figure 8. Output for the RACDCERT LIST command for a certificate with a Brainpool ECC private key that is stored in the PKDS.

RACDCERT LIST(LABEL('Anna's certificate'))

Digital certificate information for user ANNA   
                                                
    Label: Anna's certificate                   
    Certificate ID: 2QfJwtTk4sXZ08HCxdNAwUBA    
    Status: TRUST                               
    Start Date: 2010/09/16 00:00:00             
    End Date:   2011/09/16 23:59:59             
    Serial Number:                              
         >00<                                   
    Issuer's Name:                              
         >CN=Company A<                         
    Subject's Name:                             
         >CN=Company A<                         
    Signing Algorithm: sha256ECDSA
    Key Type: Brainpool ECC                     
    Key Size: 192                               
    Private Key: YES                            
    PKDS Label: ECCKEY4ANNASCERTIFICATE         
    Ring Associations:                          
    *** No rings associated ***