X'01'

DataGetFirst: Locate and return the first trusted certificate in the ring specified in Ring_name, based on the selection criteria.

On a DataGetFirst function, the user may specify some selection criteria by setting Number_predicates to 1, and then supplying some attribute information, such as attribute type, and the length and address of the attribute data. The data in the returned certificate will match the attribute data supplied.

X'02'

DataGetNext: Locate and return the next trusted certificate in the ring, based on the criteria specified in DataGetFirst.

X'03'

DataAbortQuery: Free resources from previous DataGetFirst and DataGetNext requests.

X'04'

CheckStatus: Return the TRUST/ NOTRUST status for a specified certificate.

X'05'

GetUpdateCode: Return the sequence number for the ring specified. A change in the ring sequence number (from a previously obtained ring sequence number) indicates that the ring has changed. A ring is considered changed when the list of certificates in the ring has changed, or the digital certificate information for a certificate in the ring has changed.

X'06'

IncSerialNum: Increment and return the last serial number field (CERTLSER) associated with the input certificate.

X'07'

NewRing: Create a new key ring or remove all the certificates from an existing key ring.

The RACF_user_ID and Ring_name are used to identify the ring. If the RACF_user_ID is not specified, it is equal to the user ID of the caller by default.

The syntax of Ring_name follows that of the RACDCERT ADDRING resource, that are, the restrictions imposed by the TSO parse, RACF's conversion rules, and the ADDRING validation exit.

X'08'

DataPut: Add a certificate to the RACF database (if it does not already exist), and connect it to a key ring.

RACF_user_ID and Ring_name are used to identify the ring. If the RACF_user_ID is not specified, it is equal to the user ID of the caller by default.

If the input certificate does not exist in the RACF database, it will be added to RACF with a specified or system-generated label under the specified user ID. The certificate will be added with either of the following status:

• A specified status through the CDDL(X)_ATT_TRUST or CDDL(X)_ATT_HIGHTRUST attribute, or
• A status determined by RACF.

For more information, see the topic.

If the private key associated with the certificate is specified in a DER-encoded format or as a key label, the certificate will be added with the following key types accordingly in the RACF database:

• Software RSA key
• Software DSA key
• Software Elliptic Curve Cryptography (ECC) National Institute of Standards and Technology (NIST) key
• Software Elliptic Curve Cryptography (ECC) Brainpool key
• ICSF RSA Modulus-Exponent key token
• ICSF RSA Chinese Remainder Theorem key token
• Elliptic Curve Cryptography (ECC) National Institute of Standards and Technology (NIST) key token
• Elliptic Curve Cryptography (ECC) Brainpool key token

The DataPut function checks the validity of the private key in both the software and hardware cases. If the private key is a software key, it should be in a DER-encoded format. If the private key is a PKDS or TKDS hardware key, it must be the label of an existing PKDS or TKDS private key entry.

Note: Retained hardware keys and Clear hardware keys are not supported.

If the certificate specified to be added is not already in the RACF database, after it is added, it will be connected to the key ring with the specified USAGE and DEFAULT value.

If the certificate specified to be added is already connected to the key ring, it will be reconnected with the specified USAGE and DEFAULT value.

If the certificate specified to be added is already in the RACF database with no associated private key, it might be re-added with a specified private key under the original ID, label, and status if the TRUST or HIGHTRUST attribute is not specified.

If the DIGTCERT class is RACLISTed, a successful DataPut operation indicates that a DataRefresh call is needed.

X'09'

DataRemove: Remove a certificate from the key ring, and optionally delete it from the RACF database if the certificate is not connected to any other rings.

RACF_user_ID and Ring_name are used to identify the ring. If the RACF_user_ID is not specified, it is equal to the user ID of the caller by default.

X'0A'

DelRing: Delete a key ring.

X'0B'

DataRefresh: Refresh the in-storage certificates in the RACF database if the DIGTCERT class is RACLISTed. If the DIGTCERT class is not RACLISTed, no action is performed. DataRefresh might be required after calling DataPut or DataRemove.

The DIGTCERT class can be RACLISTed for digital certificates (processing the in-storage version instead of the database version) after calling the DataPut or DataRemove function. Therefore you need to refresh the in-storage version to reflect any changes to the certificate profiles. This can be done either through a RACF SETROPTS command SETROPTS RACLIST(DIGTCERT) REFRESH by a RACF administrator, or through the DataRefresh function by the caller.

To call the DataRefresh function, the caller needs to have class authority for the DIGTCERT class, and the RACF subsystem needs to be running. Having class authority for the DIGTCERT class enables the refresh of that class only; other updates such as deleting, updating, and adding certificate profiles are still prohibited.

If the function code is not one of the preceding values, a parameter list error is returned.

• The DataGetFirst (X'01') and DataGetNext (X'02') functions

  X'80000000' - CDDL(X)_ATT_ALL_KEYTYPES flag. This flag directs R_datalib to differentiate between PCICC key types, ICSF key types, DSA key types, Diffie-Hellman(DH) key types, Elliptic Curve Cryptography(ECC) key types and PKCS #1 key types, when returning the Function Specific Parameter List field Private_key_type. When this flag is off, R_datalib will handle the PCICC key type as an ICSF key type and return the value X'00000002'. It will also handle the DSA key type, DH key type and ECC key type as a PKCS #1 key type and return the value X'00000001'.

  X'20000000' - CDDL(X)_ATT_SKIPAUTH flag. This flag directs R_datalib to bypass authorization checks to RACF key rings for a supervisor state or system key caller. This does not bypass the authorization required in order to retrieve private key information, nor does this bypass authorization checks for PKCS #11 tokens. This flag is ignored for problem state callers.

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

• The CheckStatus (X'04') function

  X'20000000' - CDDL(X)_ATT_SKIPAUTH flag. This flag directs R_datalib to bypass authorization checks to RACF key rings for a supervisor state or system key caller. This does not bypass the authorization required in order to retrieve private key information, nor does this bypass authorization checks for PKCS #11 tokens. This flag is ignored for problem state callers.

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

• The IncSerialNum (X'06') function

  X'80000000' - CDDL(X)_ATT_SET_MIN_SERIAL flag. This flag is used to indicate that the last used serial number field (CERTLUER) is to be incremented to at least the input serial number parameter. When this flag is set the serial number will only be changed if the current actual value is less than the input serial number value.

• The GetUpdateCode (X'05) function

  X'20000000' - CDDL(X)_ATT_SKIPAUTH flag. This flag directs R_datalib to bypass authorization checks to RACF key rings for a supervisor state or system key caller. This does not bypass the authorization required in order to retrieve private key information, nor does this bypass authorization checks for PKCS #11 tokens. This flag is ignored for problem state callers.

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

• The NewRing (X'07') function

  X'80000000' - CDDL(X)_ATT_REUSE_RING flag. This flag directs R_datalib to reuse the existing key ring and remove all the certificates from it. When this flag is off, it indicates the creation of a new key ring.

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

• The DataPut (X'08') function
  X'80000000' - CDDL(X)_ATT_TRUST flag. This flag is used to add certificates, with the TRUST status. When this flag is off, RACF will determine the status based on the following factors in the same way that the RACDCERT ADD command behaves:

  • Whether the issuer of the certificate is trusted
  • Whether the signature of the certificate can be verified
  • Whether the certificate has expired
  • Whether the validity date range of the certificate is within that of its issuer

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements. If the certificate already exists, turning on this attribute will change its status from NOTRUST to TRUST when connecting it to the key ring. However, if the status is already HIGHTRUST, it will remain unchanged.

  X'40000000' - CDDL(X)_ATT_HIGHTRUST flag. This flag is used to add or change certificates with the HIGHTRUST status if the certificate to be added or changed is under CERTAUTH; otherwise this value will be treated as CDDL(X)_ATT_TRUST, that is, add or change certificates with the TRUST status.

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

• The DataRemove (X'09') function

  X'80000000’ - CDDL(X)_ATT_DEL_CERT_TOO flag. This flag is used to indicate the deletion of the certificate from the RACF database after being removed from the ring, if the certificate is not connected to any other rings. When this flag is off, it indicates the removal of the certificate from the key ring only. When this attribute is specified and the DIGTCERT class is RACLISTed, a successful DataRemove returns 4 4 12 instead of 0 0 0 to indicate that a DataRefresh call is needed.

  All other bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

• All other functions

  All bit positions are reserved and must be set to zero to ensure compatibility with future enhancements.

The user ID is case sensitive. For normal user IDs, the value must be specified in uppercase.

For the DataGetFirst function code, the RACF-reserved user IDs (“irrcerta” or “irrsitec” in lowercase) or their alternate forms (*AUTH* or *SITE* in uppercase) can also be specified.

The value “*TOKEN*” can be specified to indicate that a z/OS® PKCS #11 token, rather than a RACF key ring, is the target of the operation. If the length is not specified, it must be equal to 0. If the current user ID is not specified, it is equal to the user ID of the ring owner or the token owner.

For DataGetFirst and GetUpdateCode, the Ring_name can represent a real or virtual key ring or a z/OS PKCS #11 token name. A real key ring must be explicitly created before being used by this service. A virtual key ring is the collection of certificates assigned to a given user ID, including the RACF reserved user IDs for CERTAUTH (“irrcerta” or “*AUTH*”) and SITE (“irrsitec” or “*SITE*”). A virtual key ring can be specified by coding an asterisk (“*”) for the Ring_name with the corresponding RACF_user_ID, such as user01/* or *SITE*/*.

A z/OS PKCS #11 token is a collection of certificates and keys similar to a key ring, but it is managed by the Integrated Cryptographic Service Facility (ICSF). Like a real key ring, it must be explicitly created before being used by this service.

For DataGetNext, the Ring_name is specified on the initial DataGetFirst call and cannot be re-specified.

For CheckStatus, DataAbortQuery, IncSerialNum, and DataGetNext, the Ring_name field is ignored.