RACF authorization

There are two authorization modes for the R_datalib callable service: global or granular. Global checking uses the FACILITY class; granular checking uses the RDATALIB class. Global checking applies to all the key rings and certificates. Granular checking applies to a specific ring and / or a specific certificate. To use the granular checking, the RDATALIB class must be RACLISTed.

With ring-specific checking using the RDATALIB class, 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, GetUpdateCode and GetRingInfo. 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.

With certificate-specific checking using the RDATALIB class, a resource with the format IRR.DIGTCERT.<certOwner>.<certLabel>.UPD.ADD/DELETE/ALTER is used to provide access control to a specific certificate on the DataPut (when it is used to add a certificate without connecting to a key ring), DataRemove (when it is used to delete a certificate) or DataAlter functions.

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

For the CheckStatus and IncSerialNum functions, only global profile checking is used.
For the DataGetFirst, DataGetNext, GetUpdateCode and GetRingInfo functions, global profile checking is used when there is no matching profile to the <ringOwner>.<ringName>.LST resource in the RDATALIB class.
For the NewRing, DataPut, DataRemove, and DelRing functions, global profile checking is used when there is no matching profile to the <ringOwner>.<ringName>.UPD resource in the RDATALIB class.
For the DataPut function (when it is used to add a certificate without connecting to a key ring), global profile checking is used when there is no matching profile to the IRR.DIGTCERT.<certOwner>.<certLabel>.UPD.ADD resource in the RDATALIB class.
For the DataRemove function (when it is used to delete a certificate), global profile checking is used when there is no matching profile to the IRR.DIGTCERT.<certOwner>.<certLabel>.UPD.DELETE resource in the RDATALIB class.
For the DataAlter function, global profile checking is used when there is no matching profile to the IRR.DIGTCERT.<certOwner>.<certLabel>.UPD.ALTER resource in the RDATALIB class.

With ring-specific profile checking, the ringOwner must be in uppercase. The ringName is folded into uppercase during profile checking.

Note: ringNames which differ only in case 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 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 under RDATALIB class
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 under FACILITY class
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 under FACILITY class
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 under FACILITY class
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

Table 5. Ring-specific profile checking for the NewRing function
Function	Authority required under RDATALIB class
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 under FACILITY class
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 under RDATALIB class
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 under FACILITY class
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

When the DataRemove function is used for removing a certificate from a key ring.

Table 9. Ring-specific profile checking for the DataRemove function
Function	Authority required under RDATALIB class
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 if the removed certificate is not to be deleted
Function	Authority required under FACILITY class
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	UPDATE 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	CONTROL authority to IRR.DIGTCERT.REMOVE
Remove a SITE or CERTAUTH certificate from other's ring	CONTROL authority to IRR.DIGTCERT.REMOVE
Remove 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. Additional profile checking for the DataRemove function if the removed certificate is to be deleted
Function	Authority required under FACILITY class
Delete one's own certificate after it is removed from the ring	READ authority to IRR.DIGTCERT.DELETE
Delete someone else's certificate after it is removed from the ring	UPDATE authority to IRR.DIGTCERT.DELETE
Delete a SITE or CERTAUTH certificate after it is removed from the ring	CONTROL authority to IRR.DIGTCERT.DELETE

When the DataRemove function is used for deleting a certificate only.

The authority on the 'remove from key ring' step is not required, only authority on the existing delete step is needed if the ring name is an '*', as follows:

Table 12. Certificate-specific profile checking for the DataRemove function
Function	Authority required under RDATALIB class
Delete one's own certificate	READ authority to IRR.DIGTCERT.<CERT_user_ID>.<cert label>.UPD.DELETE
Delete someone else's certificate	READ authority to IRR.DIGTCERT.<CERT_user_ID>.<cert label>.UPD.DELETE
Delete a SITE certificate	READ authority to IRR.DIGTCERT.SITECERTIF.<cert label>.UPD.DELETE
Delete a CERTAUTH certificate	READ authority to IRR.DIGTCERT.CERTIFAUTH.<cert label>.UPD.DELETE

See Table 11 for Authority required if global profile checking under the FACILITY class is used.

Authority required for the DataPut function

If the DataPut function is used for adding a certificate and connecting the certificate to a key ring:

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. 'Add' might be involved if the input certificate does not exists in RACF; 'Alter' might be involved if the input certificate already exists with a different status.

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 13. Ring-specific profile checking for the DataPut function - Authority required to connect with the Personal usage
Function	Authority required under RDATALIB class
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	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)

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

Table 15. Global profile checking for the DataPut function - Authority required to connect with the Personal usage
Function	Authority required under FACILITY class
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	CONTROL authority to IRR.DIGTCERT.CONNECT
Connect a SITE or CERTAUTH certificate to one's own ring	CONTROL 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 connect with the SITE or CERTAUTH usage
Function	Authority required under FACILITY class
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	CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.CONNECT
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

Note: For information about the additional authority required to add or re-add, see Table 17.

Table 17. Global profile checking for the DataPut function - Authority required under the FACILITY class to add or re-add a certificate
Function	Authority required under FACILITY class
Add one's own certificate	READ authority to IRR.DIGTCERT.ADD
Add someone else's certificate	UPDATE authority to IRR.DIGTCERT.ADD
Add a SITE or CERTAUTH certificate	CONTROL authority to IRR.DIGTCERT.ADD
Re-add one's own existing certificate with a different status	READ authority to IRR.DIGTCERT.ALTER
Re-add someone else's existing certificate with a different status	UPDATE authority to IRR.DIGTCERT.ALTER
Re-add a SITE or CERTAUTH's existing certificate with a different status	CONTROL authority to IRR.DIGTCERT.ALTER

Note: ALTER authority is checked only when no private key is to be added, otherwise ADD authority is checked.

If the DataPut function is used for adding a certificate without connecting it to a key ring (when Ring_name is "*"):

If the caller is RACF special, no authority checking is done; otherwise the resource IRR.DIGTCERT.<CERT_user_ID>.<cert label>.UPD.ADD or possibly IRR.DIGTCERT.<cert label>.UPD.ALTER in the RDATALIB class will be checked first. If there is no match, the IRR.DIGTCERT.ADD, or possibly IRR.DIGTCERT.ALTER in the FACILITY class will be used.

Table 18. Certificate-specific profile checking for the DataPut function - Authority required under the RDATALIB class to add or re-add a certificate
Function	Authority required using the RDATALIB class
Add one's own or someone else's certificate with label specified	READ authority to IRR.DIGTCERT.<CERT_user_ID>.<cert label>.UPD.ADD
Add a SITE certificate with label specified	READ authority to IRR.DIGTCERT.SITECERTIF.<cert label>.UPD.ADD
Add a CERTAUTH certificate with label specified	READ authority to IRR.DIGTCERT.CERTIFAUTH.<cert label>.UPD.ADD
Add one's own or someone else's certificate with no label specified	READ authority to IRR.DIGTCERT.<CERT_user_ID>.LABEL*.UPD.ADD
Add a SITE certificate with no label specified	READ authority to IRR.DIGTCERT.SITECERTIF.LABEL*.UPD.ADD
Add a CERTAUTH certificate with no label specified	READ authority to IRR.DIGTCERT.CERTIFAUTH.LABEL*.UPD.ADD
Re-add one's own or someone else's existing certificate with a different status	READ authority to IRR.DIGTCERT.<CERT_user_ID>.<cert label>.UPD.ALTER
Re-add a SITE's existing certificate with a different status	READ authority to IRR.DIGTCERT.SITECERTIF.<cert label>.UPD.ALTER
Re-add a CERTAUTH's existing certificate with a different status	READ authority to IRR.DIGTCERT.CERTIFAUTH.<cert label>.UPD.ALTER

Note: ALTER authority is checked only when no private key is to be added, otherwise ADD authority is checked.

Authority required for the DataAlter function

Profile in the RDATALIB class will be checked first. If it doesn't exist, check that in the FACILITY class.

Table 19. Certificate-specific profile checking for the DataAlter function - Authority required under the RDATALIB class to alter a certificate
Function	Authority required using the RDATALIB class
Alter one's own or someone else's certificate's status	READ authority to IRR.DIGTCERT.<CERT_user_ID>.<cert label>.UPD.ALTER
Alter a SITE certificate's status	READ authority to IRR.DIGTCERT.SITECERTIF.<cert label>.UPD.ALTER
Alter a CERTAUTH certificate's status	READ authority to IRR.DIGTCERT.CERTIFAUTH.<cert label>.UPD.ALTER
Alter one's own or someone else's certificate's label	READ authority to IRR.DIGTCERT.<CERT_user_ID>.<original cert label>.UPD.ALTER and READ authority to IRR.DIGTCERT.<CERT_user_ID>.<new cert label>.UPD.ALTER
Alter a SITE certificate's label	READ authority to IRR.DIGTCERT.SITECERTIF.<original cert label>.UPD.ALTER and READ authority to IRR.DIGTCERT.SITECERTIF.<new cert label>.UPD.ALTER
Alter a CERTAUTH certificate's label	READ authority to IRR.DIGTCERT.CERTIFAUTH.<original cert label>.UPD.ALTER and READ authority to IRR.DIGTCERT.CERTIFAUTH.<new cert label>.UPD.ALTER

Table 20. Global profile checking for the DataAlter function - - Authority required under the FACILITY class to alter a certificate
Function	Authority required using the Facility class
Alter one's own certificate's status	READ authority to IRR.DIGTCERT.ALTER
Alter one's own certificate's label	READ authority to IRR.DIGTCERT.ALTER
Alter someone else's certificate's status	UPDATE authority to IRR.DIGTCERT.ALTER
Alter someone else's certificate's label	UPDATE authority to IRR.DIGTCERT.ALTER
Alter a SITE or CERTAUTH certificate's status	CONTROL authority to IRR.DIGTCERT.ALTER
Alter a SITEor CERTAUTH certificate's label	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.

Authority required for the GetRingInfo function

Profile in the RDATALIB class will be checked first. If it doesn't exist, check that in the FACILITY class.

Table 21. Ring-specific profile checking for the GetRingInfo function - Authority required under the RDATALIB class to list information for one or more key rings
Function	Authority required using the RDATALIB class
List a specific ring owned by a specific user	READ authority to <Ring owner>.<Ring name>.LST
List all the rings owned by a specific user	READ authority to <Ring owner>.*.LST
List all rings in the RACF database with a specific name	READ authority to *.<Ring name>.LST
List all rings in the RACF database	READ authority to ..LST

Note: For search type 0 which is used for getting ring information for a specific ring, if insufficient authority is granted, 8 8 8 will be returned. For other search types which are used for getting ring information for multiple rings, only the authorized entries will be returned, with return/reason code 4 4 8.

Table 22. Global profile checking for the GetRingInfo function - Authority required under the FACILITY class to list information for one or more key ring's
Function	Authority required using the FACILITY class
List one's own rings	READ authority to IRR.DIGTCERT.LISTRING
List someone else's rings	UPDATE authority to IRR.DIGTCERT.LISTRING