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.DIGITCERT.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.DIGITCERT.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:
  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.DIGITCERT.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.
  Note: Private keys can never be extracted from the CERTAUTH or SITE virtual key ring.
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 PKCS #1.
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.