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:
- 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.
- User certificates
- 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>
- 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:
- User certificates
- 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.
- For RACF real key rings:
- 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
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.RingYUser1.RingY,
User1.RingZRC=4 4 0, call again 3 times with type 1 (1Z, 2Y, 3X) User1 RingX 2 User1.RingY, User1.RingZ User1.RingY,
User1.RingZRC=0 User1 RingX 3 User2.RingX, User3.RingX User2.RingX,
User3.RingXRC=0 User1 - ignored User1.RingX, User1.RingY, User1.RingZ User1.RingX,
User1.RingYRC=4 4 0, call again type 2(1Y) - RingX ignored User1.RingX, User2.RingX, User3.RingX User1.RingX,
User2.RingXRC=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.RingYUser1.RingX,
User1.RingYRC=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.RingYUser1.RingX,
User1.RingYRC=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.RingYUser1.RingX, User1.RingY RC=4 4 0, call again 4times with type 1 (1Y, 2X, 2Z, 3Z)