Authorizing administrative functions

The administrative functions are:

CERTDETAILS: Get detailed information about one PKI Services issued certificate.
MODIFYCERTS: Change PKI Services issued certificates.
MODIFYREQS: Change PKI Services certificate requests.
QUERYCERTS: Query PKI Services issued certificates.
QUERYREQS: Query PKI Services about certificate requests.
PREREGISTER: Preregister clients who use Simple Certificate Enrollment Protocol (SCEP).
REQDETAILS: Get detailed information about one PKI Services certificate request.

To control access to these functions:

Use resources in the RACF® FACILITY class. This class allows you to control access based on the CA domain.
Use resources in the RACF PKISERV class. This class allows you to control access on a more granular level than the FACILITY class, which is based on the CA domain, the administrative function, and the template.

Using the FACILITY class to control access to administrative functions

For the all administrative functions, the following single FACILITY class resource protects this interface.

IRR.RPKISERV.PKIADMIN[.ca_domain]

ca_domain: Optionally specifies the PKI Services certificate authority (CA) domain name. Use this when your installation has established multiple PKI Services CAs and the CA_domain parameter is provided with IRRSPX00 for 31 bit and IRRSPX64 for 64 bit.
Restriction: If the name of your initial CA domain is longer than 8 characters, you must truncate it to exactly 8 characters when you define the resource name in the FACILITY class.

If the caller is RACF SPECIAL, no further access is necessary.
Otherwise, the caller needs:
- READ access to perform read operations (QUERYREQS, QUERYCERTS, REQDETAILS, and CERTDETAILS)
- UPDATE access for the action operations (PREREGISTER, MODIFYREQS, and MODIFYCERTS).

Example:

For administrative functions, when the ca_domain is named Customers and the CA_domain parameter is provided with IRRSPX00 for 31 bit and IRRSPX64 for 64 bit, the FACILITY class resource controlling this interface is IRR.RPKISERV.PKIADMIN.CUSTOMER. (The name Customers was truncated to CUSTOMER. See the restriction for the ca_domain value.) When the CA_domain parameter is not provided with IRRSPX00 for 31 bit and IRRSPX64 for 64 bit, IRR.RPKISERV.PKIADMIN is the name of the FACILITY class resource. End of change

To determine the appropriate access level of the caller, the current TCB is checked for an ACEE. If one is found, the authority of that user is checked. If there is no ACEE associated with the current TCB, the ACEE associated with the address space is used to locate the user ID.

Attention: UPDATE access to the IRR.RPKISERV.PKIADMIN[.ca_domain] resource also controls who can act as PKI Services administrators. PKI Services administrators play a very powerful role in your organization. The decisions they make when managing certificates and certificate requests determine who accesses your computer systems and what privileges they have when doing so.

Guideline: Give UPDATE authority to only highly trusted individuals, but avoid allowing these same individuals to have direct access to the end-user functions of the R_PKIServ callable service described in Authorizing end-user functions. This helps to maintain a secure separation of duties.

Using the PKISERV class to control access to administrative functions

You can use profiles in the PKISERV class to control access to R_PKIServ administrative functions on a more granular level than you can with profiles in the FACILITY class. If the AdminGranularControl switch in the pkiserv.conf configuration file is set to T, profiles in the PKISERV class are checked in addition to profiles in the FACILITY class to determine authorization to these functions. If no profile is found protecting a function, authorization to the function fails.

To use the PKISERV class, you need to take the following steps:

Activate generic profile checking for the class:
```
SETROPTS GENERIC(PKISERV)
```

Define profiles for the PKISERV class resources and authorize users to use the resources:

RDEFINE PKISERV profile_name UACC(NONE)
PERMIT profile_name CLASS(PKISERV) ID(user_ID or group) ACCESS(access_level)

Activate and RACLIST the class:

SETROPTS CLASSACT(PKISERV) RACLIST(PKISERV)

Any time that you update the profiles in the class, refresh the in-storage profiles:

SETROPTS RACLIST(PKISERV) REFRESH

For the query functions (QUERYREQS, QUERYCERTS, REQDETAILS, and CERTDETAILS), the resources in the PKISERV class are of the form:

ca_domain.action.template_nickname

where

ca_domain

Specifies the PKI Services certificate authority (CA) domain name.

Rules:

The domain name is at most 8 characters long.
The domain name can contain only alphanumeric characters and the national characters @, #, and $.
If there is no domain name, the qualifier must be NOCADOMAIN.

action

Specifies the function. It has one of the following values:

QUERYREQS
QUERYCERTS
QUERYREQDETAILS
QUERYCERTDETAILS

Rules:

For the REQDETAILS function, if the administrator has READ access to the QUERYREQDETAILS profile, the password value is replaced by blanks before it is returned. If the administrator has UPDATE access, the password value is returned.
For the CERTDETAILS function, if the administrator has READ access to the QUERYCERTDETAILS profile, the password value is replaced by blanks before it is returned. If the administrator has UPDATE access, the password value is returned.
For all other functions, READ access is sufficient.

template_nickname

Specifies the nickname of the certificate template.

Rules:

The template nickname is at most 8 characters long.
The template nickname can contain only alphanumeric characters and the national characters @, #, and $.
If there is no template nickname, the qualifier must be NONICKNAME.

Example: An administrator has either READ or UPDATE access to the FACILITY class profile IRR.RPKISERV.PKIADMIN.MYDOMAIN and also has READ access to the PKISERV class profiles MYDOMAIN.QUERYREQS.1YBSSL and MYDOMAIN.QUERYCERTS.1YBSSL. That administrator can perform QUERYREQS and QUERYCERTS functions on the requests and certificates created with the template '1-Year PKI SSL Browser Certificate' in the domain MYDOMAIN. If that same administrator does not have READ or UPDATE access to the PKISERV class profile MYDOMAIN.QUERYREQS.5YSSSL, that administrator would not be able to perform QUERYREQS functions on requests created with the template '5-Year PKI SSL Server Certificate' in the same domain.

For the update functions (MODIFYREQS, MODIFYCERTS, and PREREGISTER), the resources in the PKISERV class are of the form:

ca_domain.action.template_nickname

where

ca_domain

Specifies the PKI Services certificate authority (CA) domain name.

Rules:

The domain name is at most 8 characters long.
The domain name can contain only alphanumeric characters and the national characters @, #, and $.
If there is no domain name, the qualifier must be NOCADOMAIN.

action

Specifies the function. It has one of the following values:

PREGISTER
APPROVE (for MODIFYREQS)
APPROVEWITHMODS (for MODIFYREQS)
REJECT (for MODIFYREQS)
DELETEREQS (for MODIFYREQS)
REVOKE (for MODIFYCERTS)
DELETECERTS (for MODIFYCERTS)
RESUME (for MODIFYCERTS)
AUTORENEWENABLE (for MODIFYCERTS)
AUTORENEWDISABLE (for MODIFYCERTS)
CHANGEMAIL (for MODIFYCERTS)
CREATECRL (for MODIFYCERTS)
POSTCERT (for MODIFYCERTS)

template_nickname

Specifies the nickname of the certificate template.

Rules:

The template nickname is at most 8 characters long.
The template nickname can contain only alphanumeric characters and the national characters @, #, and $.
The template is irrelevant for CREATECRL and POSTCERT and the template nickname is not included in the resource name for these actions.
You must specify a template nickname for the PREREGISTER action.
For all actions other than CREATECRL, POSTCERT, and PREREGISTER, If there is no template nickname, the qualifier must be NONICKNAME.

Examples:

READ access to the profile MYDOMAIN.APPROVE.1YBSSL allows the administrator to approve requests under the template '1-Year PKI SSL Browser Certificate' in the domain MYDOMAIN.
READ access to the profile MYDOMAIN.APPROVEWITHMODS.1YBSSL allows the administrator to modify the content of requests and then approve them under the '1-Year PKI SSL Browser Certificate' template in the domain MYDOMAIN.
READ access to the profile MYDOMAIN.REVOKE.1YBSSL allows the administrator to revoke or suspend certificates under the '1-Year PKI SSL Browser Certificate' template in the domain MYDOMAIN.
READ access to the profile MYDOMAIN.PREREGISTER.5YSCEPP allows the administrator to preregister requests under the '5-Year SCEP Certificate - Preregistration' template in the domain MYDOMAIN.