Usage notes

For real key rings, a certificate's ring usage is set when the certificate is connected to the key ring.
For virtual key rings, all certificates within the ring have the same usage as follows:
- CERTAUTH for the CERTAUTH virtual key ring (RACF® reserved user ID irrcerta or *AUTH*).
- SITE for the SITE virtual key ring (RACF-reserved user ID irrsitec or *SITE*).
- PERSONAL for the virtual key rings of all other non-reserved user IDs.
For z/OS® PKCS #11 tokens, a certificate's token usage is set when the certificate is bound to the token.
Applications can call the R_datalib callable service (IRRSDL00) to extract the private keys from certain certificates after they have access to the key ring. A private key is returned only when the following conditions are met:
1. For RACF real key rings:
  - User certificates
    An application can extract the private key from a user certificate if the following conditions are met:
    - The certificate is connected to the key ring with the PERSONAL usage option.
    - One of the following two conditions is true:
      - The caller's user ID is the user ID associated with the certificate if the access to the key ring is through the checking on IRR.DIGTCERT.LISTRING in the FACILITY CLASS, or
      - The caller's user ID has READ or UPDATE authority to the <ringOwner>.<ringName>.LST resource in the RDATALIB class. READ access enables retrieving one's own private key, UPDATE access enables retrieving other's.
  - CERTAUTH and SITE certificates
    An application can extract the private key from a CERTAUTH or SITE certificate if the following conditions are met:
    - The certificate is connected to its key ring with the PERSONAL usage option.
    - One of the following three conditions is true:
      - The caller's user ID is RACF special regardless of access checking method, or
      - The caller's user ID has CONTROL authority to the IRR.DIGTCERT.GENCERT resource in the FACILITY class if the access to the key ring is through the checking on IRR.DIGTCERT.LISTRING in the FACILITY CLASS, or
      - The caller's user ID has CONTROL authority to the <ringOwner>.<ringName>.LST resource in the RDATALIB class.
2. For RACF virtual key rings:
  - User certificates
    An application can extract the private key from a user certificate if either of the following conditions is met:
    - The caller's user ID is the user ID associated with the certificate if the access to the key ring is through the checking on the IRR.DIGTCERT.LISTRING in the FACILITY CLASS, or
    - The caller's user ID has READ or UPDATE authority to the <virtual ring owner>.IRR_VIRTUAL_KEYRING.LST resource in the RDATALIB class. READ access enables retrieving one's own private key, UPDATE access enables retrieving other's.
  - CERTAUTH and SITE certificates
    An application can extract the private key from a CERTAUTH or SITE certificate if either of the following conditions is met:
    - Caller is SPECIAL
    - Caller has the authority required based on the RDATALIB class, using one of the following access methods:
      
      Base on virtual key ring – similar to the case for virtual key ring of a regular user described above, but use special Id CERTIFAUTH or SITECERTIF for ring owner:
      
      CONTROL authority to CERTIFAUTH.IRR_VIRTUAL_KEYRING.LST for CERTAUTH's virtual ring
      
      CONTROL authority to SITECERTIF.IRR_VIRTUAL_KEYRING.LST for SITE's virtual ring
      
      Base on certificate:
      
      READ authority to IRR.DIGTCERT.CERTIFAUTH.<cert label>.UPD.EXPORT for CERTAUTH's certificate with label <cert label>
      
      READ authority to IRR.DIGTCERT.SITECERTIF.<cert label>.UPD.EXPORT for SITE's certificate with label <cert label>
3. For z/OS PKCS #11 tokens:
  An application can extract the private key from a user certificate if all of the following conditions are met:
  - The certificate's token usage is PERSONAL.
  - The caller has permission to read private objects in the token, as determined by ICSF.
  - A private key object exists for the certificate (CKA_ID attributes match).
  - The private key object contains all the attributes defined in the RSA private key object, or the Elliptic Curve private key object.
The DataAbortQuery function must be called once for each DataGetFirst call, whether or not DataGetNext calls are made between the DataGetFirst and DataAbortQuery calls. The caller must pass the same dbToken to DataAbortQuery call as was returned from the DataGetFirst call. If these conditions are not met, system resources will not be freed.
ICSF services must be loaded from an APF-authorized library when they are required. If the ICSF library is part of the STEPLIB or JOBLIB concatenation, the entire concatenation must be APF-authorized.

For the function GetRingInfo, the data returned may vary with different parameters. Some usages of GetRingInfo are described in the following examples:

If User1 has 3 rings with some certificates connected to them. 4 4 0 will be returned for the call with the specified RACF_user_ID User1 and Search_type 0, provided that the Ring_result_length has enough room for 2 rings and the connected certificates information. A second call with the last returned values of the ring owner and ring name and Search_type 2 as parameters may return the third ring and its connected certificates information, if the same allocated area is sufficient.
These rings are in the RACF DB:
- User1.RingX User2.RingX User3.RingX
- User1.RingY User2.RingY User3.RingZ
- User1.RingZ User2.RingZ User5.RingY
1. If the value of RACF_user_ID or Ring_name exist, the rings returned will be like Table 1.
2. If the value of RACF_user_ID or Ring_name does not exist, the rings returned will be like Table 2.

The information returned from GetRingInfo can be used as input parameters to the DataGetFirst/DataGetNext function to extract further information on the certificate/private key.

Table 1. GetRingInfo results with input contains existing owner or ring
Specified RACF_user_ID	Specified Ring_name	Specified Search_type	Data returned if sufficient area provided and caller has sufficient authority	Data returned if sufficient area for 2 objects	Note
User1	RingX	0	User1.RingX	User1.RingX	RC=0
User1	RingX	1	User1.RingY, User1.RingZ, User2.RingX, User2.RingY, User2.RingZ, User3.RingX, User3.RingZ, User5.RingY	User1.RingY, User1.RingZ	RC=4 4 0, call again 3 times with type 1 (1Z, 2Y, 3X)
User1	RingX	2	User1.RingY, User1.RingZ	User1.RingY, User1.RingZ	RC=0
User1	RingX	3	User2.RingX, User3.RingX	User2.RingX, User3.RingX	RC=0
User1	-	ignored	User1.RingX, User1.RingY, User1.RingZ	User1.RingX, User1.RingY	RC=4 4 0, call again type 2(1Y)
-	RingX	ignored	User1.RingX, User2.RingX, User3.RingX	User1.RingX, User2.RingX	RC=4 4 0, call again type 3(2X)
-	-	ignored	User1.RingY, User1.RingY, User1.RingZ, User2.RingX, User2.RingY, User2.RingZ, User3.RingX, User3.RingY, User5.RingY	User1.RingX, User1.RingY	RC=4 4 0, call again 4times with type 1 (1Y, 2X, 2Z, 3Z)

Table 2. GetRingInfo results with input contains non existing owner or ring
Specified RACF_user_ID	Specified Ring_name	Specified Search_type	Data returned if sufficient area provided and caller has sufficient authority	Data returned if sufficient area for 2 objects	Note
User0	RingX	0	none	none	RC=8 8 32
User0	RingX	1	User1.RingX, User1.RingY, User1.RingZ, User2.RingX, User2.RingY, User2.RingZ, User3.RingX, User3.RingY, User5.RingY	User1.RingX, User1.RingY	RC=4 4 0, call again 4times with type 1 (1Y, 2X, 2Z, 3Z)
User0	RingT	2	none	none	RC=8 8 32
User4	RingY	3	User5.RingY	User5.RingY	RC=0
User4	-	ignored	none	none	RC=8 8 44
-	RingT	ignored	none	none	RC=8 8 32
-	-	ignored	User1.RingX, User1.RingY User1.RingY, User1.RingY, User1.RingZ, User2.RingX, User2.RingY, User2.RingZ, User3.RingX, User3.RingY, User5.RingY	User1.RingX, User1.RingY	RC=4 4 0, call again 4times with type 1 (1Y, 2X, 2Z, 3Z)