RACF authorization

There are two ways of authority checking for the R_datalib callable service: global profile checking in the FACILITY class and ring-specific profile checking in the RDATALIB class. Global profile checking applies to all the key rings. Ring-specific profile checking applies to a specific key ring. To use the ring-specific profile checking, the RDATALIB class must be RACLISTed.

With ring-specific profile checking, a resource with the format <ringOwner>.<ringName>.LST is used to provide access control to a specific key ring on R_datalib READ functions, that are, DataGetFirst, DataGetNext, and GetUpdateCode. A resource with the format <ringOwner>.<ringName>.UPD is used to provide access control to a specific key ring on the UPDATE functions, that are, NewRing, DataPut, DataRemove, and DelRing.

Global profile checking using the IRR.DIGTCERT.<function> resource is also applicable in the following circumstances:

For the CheckStatus and IncSerialNum functions, only global profile checking is used.
For the other functions that first use ring-specific profile checking, global profile checking is used when there is no matching profile to the <ringOwner>.<ringName>.<function> resource.

With ring-specific profile checking, the ringOwner must be in uppercase. The ringName is folded into uppercase during profile checking. The ringNames that differ only in cases use the same profile.

If the data entered in the ringOwner and ringName fields has reached the field size limits, and you want to create a discrete profile, you can truncate the ring name from the end to make the whole profile name length 246 characters.

For example, if the owner ID is JOESMITH and the ring name is: THISISARINGWITH237CHARACTERS…RINGEND (with a length of 237), the discrete profile will be JOESMITH.THISISARINGWITH237CHARACTERS…RIN.UPD.

If the owner ID is JOES, the entire ring name can be used.

The following lists describe a detailed breakdown of authority checking.

Authority required for the DataGetFirst, DataGetNext, and GetUpdateCode functions:

Note: Supervisor or system key callers can bypass the authorization checks for the DataGetFirst, DataGetNext, and GetUpdateCode functions by setting the CDDL(X)_ATT_SKIPAUTH flag in the Attributes parameter.

The resource <ringOwner>.<ringName>.LST in the RDATALIB class is checked first. If there is no match for <ringOwner>.<ringName>.LST, the IRR.DIGTCERT.LISTRING resource is used.

Table 1. Ring-specific profile checking for the DataGetFirst, DataGetNext, and GetUpdateCode functions
Function	Authority required
List certificates and get the sequence number for a real key ring	READ authority to <ringOwner>.<ringName>.LST
List certificates and get the sequence number for a virtual key ring	READ authority to <virtual ring owner>.IRR_VIRTUAL_KEYRING.LST Note: The virtual ring owner can be an ordinary user ID, a CERTAUTH user ID (CERTIFAUTH), or a SITE user ID (SITECERTIF).

Table 2. Global profile checking for the DataGetFirst, DataGetNext, and GetUpdateCode functions
Function	Authority required
List certificates and get the sequence number for one's own key ring, a CERTAUTH, or a SITE's virtual key ring	READ authority to IRR.DIGTCERT.LISTRING
List certificates and get the sequence number for other's ring	UPDATE authority to IRR.DIGTCERT.LISTRING

For information about the additional authority needed for the private key retrieval, see Usage notes.

Authority required for the CheckStatus function
Note: Supervisor or system key callers can bypass the authorization checks for the CheckStatus function by setting the CDDL(X)_ATT_SKIPAUTH flag in the Attributes parameter.

The CheckStatus function requires READ authority to the resource IRR.DIGTCERT.LIST in the FACILITY class.

Table 3. Profile checking for the CheckStatus function
Function Authority required
Return the TRUST or NOTRUST status for a specified certificate READ authority to IRR.DIGTCERT.LIST
Authority required for the DataAbortQuery function
The DataAbortQuery function requires no authority.

Authority required for the IncSerialNum function

If the caller is RACF® special, no authority checking is done; otherwise appropriate authority to the resource IRR.DIGTCERT.GENCERT in the FACILITY class is required: READ authority if the certificate is owned by the caller, or CONTROL authority if the certificate is a SITE or CERTAUTH certificate.

Table 4. Profile checking for the IncSerialNum function
Function	Authority required
Increment and return the last serial number field (CERTLSER) associated with one's own input certificate	READ authority to IRR.DIGTCERT.GENCERT
Increment and return the last serial number field (CERTLSER) associated with a SITE or CERTAUTH certificate	CONTROL authority to IRR.DIGTCERT.GENCERT

Authority required for the NewRing function

If the caller is RACF special, no authority checking is done; otherwise the resource <ringOwner>.<ringName>.UPD is checked first. If there is no match for <ringOwner>.<ringName>.UPD, the IRR.DIGTCERT.ADDRING and IRR.DIGTCERT.REMOVE resources are used.

Table 5. Ring-specific profile checking for the NewRing function
Function	Authority required
Create a new ring for <ringOwner> named <ringName>	READ authority to <ringOwner>.<ringName>.UPD
Remove all certificates from an existing ring	READ authority to <ringOwner>.<ringName>.UPD

Table 6. Global profile checking for the NewRing function
Function	Authority required
Create a new ring for oneself	READ authority to IRR.DIGTCERT.ADDRING
Create a new ring for someone else	UPDATE authority to IRR.DIGTCERT.ADDRING
Remove all certificates from one's own ring	READ authority to IRR.DIGTCERT.REMOVE
Remove all certificates from someone else's ring	UPDATE authority to IRR.DIGTCERT.REMOVE

Authority required for the DelRing function

Table 7. Ring-specific profile checking for the DelRing function
Function	Authority required
Delete a ring owned by <ringOwner> named <ringName>	READ authority to <ringOwner>.<ringName>.UPD

Table 8. Global profile checking for the DelRing function
Function	Authority required
Delete one's own ring	READ authority to IRR.DIGTCERT.DELRING
Delete someone else's ring	UPDATE authority to IRR.DIGTCERT.DELRING

Authority required for the DataRemove function

Table 9. Ring-specific profile checking for the DataRemove function
Function	Authority required
Remove one's own certificate	READ authority to <ringOwner>.<ringName>.UPD
Remove someone else's certificate	UPDATE authority to <ringOwner>.<ringName>.UPD
Remove a SITE or CERTAUTH certificate	CONTROL authority to <ringOwner>.<ringName>.UPD

Table 10. Global profile checking for the DataRemove function
Function	Authority required
Remove one's own certificate from one's own ring	READ authority to IRR.DIGTCERT.REMOVE
Remove someone else's certificate from one's own ring	READ authority to IRR.DIGTCERT.REMOVE
Remove one's own certificate from other's ring	CONTROL authority to IRR.DIGTCERT.REMOVE
Remove someone else's certificate from other's ring
Removes a SITE or CERTAUTH certificate from other's ring
Removes a SITE or CERTAUTH certificate from one's own ring	UPDATE authority to IRR.DIGTCERT.REMOVE

If CDDL(X)_ATT_DEL_CERT_TOO is also specified, IRR.DIGTCERT.DELETE is checked in addition to the checking on the <ringOwner>.<ringName>.UPD resource or the IRR.DIGTCERT.REMOVE resource.

Note: There are two types of mapping, 31-bit mapping and 64-bit mapping. For every CDDL_xx entry, which comes from the 31-bit mapping, there is a corresponding CDDLX_xx entry from the 64-bit mapping. In this information, CDDL(X) is used to indicate both of the mappings.

Table 11. Profile checking for the DataRemove function if CDDL(X)_ATT_DEL_CERT_TOO is specified
Function	Authority required (if the certificate also needs to be deleted)
Remove one's own certificate	READ authority to IRR.DIGTCERT.DELETE
Remove someone else's certificate	UPDATE authority to IRR.DIGTCERT.DELETE
Remove a SITE or CERTAUTH certificate	CONTROL authority to IRR.DIGTCERT.DELETE

Authority required for the DataPut function

If the caller is RACF special, no authority checking is done; otherwise the resource <ringOwner>.<ringName>.UPD is checked first. If there is no match for <ringOwner>.<ringName>.UPD, the IRR.DIGTCERT.CONNECT, and possibly IRR.DIGTCERT.ADD, or IRR.DIGTCERT.ALTER resources are used, because "Add" and "Alter" might be involved in the operation.

With global profile checking, authorization to connect is always required. However, additional authorization to add or alter might be required depending on the following factors:

Whether the certificate already exists in RACF
Whether the certificate status needs to be changed to TRUST or HIGHTRUST through the CDDL(X)_ATT_TRUST or CDDL(X)_ATT_HIGHTRUST attribute

Appropriate access to IRR.DIGTCERT.ALTER is also required when the following two conditions apply.

The DIGTCERT resources are used.
The DataPut function changes the existing certificate's status from NOTRUST to TRUST through the CDDL(X)_ATT_TRUST attribute.

The following tables show the breakdown of profile checking for the DataPut function with the two different methods: ring-specific profile checking and global profile checking.

Table 12. Ring-specific profile checking for the DataPut function - Authority required to connect with the Personal usage
Function	Authority required
Connect one's own certificate to the ring	READ authority to <ringOwner>.<ringName>.UPD
Connect someone else's certificate to the ring	CONTROL authority to <ringOwner>.<ringName>.UPD (If the private key is not specified) UPDATE authority to <ringOwner>.<ringName>.UPD (If the private key is specified)
Connect a SITE or CERTAUTH certificate to the ring

Table 13. Ring-specific profile checking for the DataPut function - Authority required to connect with the SITE or CERTAUTH usage
Function	Authority required
Connect one's own certificate to the ring	UPDATE authority to <ringOwner>.<ringName>.UPD
Connect someone else's certificate to the ring
Connect a SITE or CERTAUTH certificate to the ring

Table 14. Global profile checking for the DataPut function - Authority required to connect with the Personal usage
Function	Authority required
Connect one's own certificate to one's own ring	READ authority to IRR.DIGTCERT.CONNECT
Connect someone else's certificate to one's own ring	UPDATE authority to IRR.DIGTCERT.CONNECT
Connect one's own certificate to someone else's ring	CONTROL authority to IRR.DIGTCERT.CONNECT
Connect someone else's certificate to someone else's ring
Connect a SITE or CERTAUTH certificate to one's own ring
Connect a SITE or CERTAUTH certificate to someone else's ring

Note: For information about the additional authority required to add or alter, see Table 16.

Table 15. Global profile checking for the DataPut function - Authority required to connect with the SITE or CERTAUTH usage
Function	Authority required
Connect one's own certificate to one's own ring	CONTROL authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.CONNECT
Connect someone else's certificate to one's own ring	CONTROL authority to IRR.DIGTCERT.ADD and UPDATE authority to IRR.DIGTCERT.CONNECT
Connect one's own certificate to someone else's ring	CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.CONNECT
Connect someone else's certificate to someone else's ring
Connect a SITE or CERTAUTH certificate to one's own ring	UPDATE authority to IRR.DIGTCERT.CONNECT
Connect a SITE or CERTAUTH certificate to someone else's ring	CONTROL authority to IRR.DIGTCERT.CONNECT

Table 16. Global profile checking for the DataPut function - Authority required to add or alter a certificate
Function	Authority required
Add a certificate for oneself	READ authority to IRR.DIGTCERT.ADD
Add a certificate for someone else	UPDATE authority to IRR.DIGTCERT.ADD
Add a SITE or CERTAUTH certificate	CONTROL authority to IRR.DIGTCERT.ADD
Alter one's own certificate	READ authority to IRR.DIGTCERT.ALTER
Alter someone else's certificate	UPDATE authority to IRR.DIGTCERT.ALTER
Alter a SITE or CERTAUTH certificate	CONTROL authority to IRR.DIGTCERT.ALTER

Authority required for the DataRefresh function
If the caller is RACF special, no authority checking is done; otherwise if the DIGTCERT class is RACLISTed, the caller must have class authority for the DIGTCERT class.