auth_check_resource_np (BPX1ACK, BPX4ACK) — Determine a user's access to a RACF-protected resource

Function

The auth_check_resource_np service checks the authority of a RACF-defined user to access a RACF-defined resource. Resources in the DATASET class cannot be checked. The authorization required to invoke this service is one of the following:

Read access to the BPX.SERVER resource in the FACILITY class
A UID of 0 when the BPX.SERVER resource is not defined in the FACILITY class

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1ACK):	31-bit
AMODE (BPX4ACK):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1ACK,(Cell_UUID,
              Principal_UUID,
              Userid_Length,
              Userid,
              Security_Class_Length,
              Security_Class,
              Entity_Name_Length,
              Entity_Name,
              Access_Type,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4ACK with the same parameters.

Parameters

Cell_UUID

Supplied parameter

Type:: Character string
Length:: 36 bytes

The name of a 36-byte area that contains the cell DCE UUID. If the cell DCE UUID is not specified, the first byte of this 36-byte area must contain NUL (X'00').

Principal_UUID

Supplied parameter

Type:: Character string
Length:: 36 bytes

The name of a 36-byte area that contains the principal DCE UUID. If the principal DCE UUID is not specified, the first byte of this 36-byte area must contain NUL (X'00').

Userid_Length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the Userid parameter. Userid_Length can be in the range of 0 to 8. If a user ID is not required, specify the name of a fullword that contains zero.

Userid

Supplied parameter

Type:: Character string
Character set:: The XPG4 portable character set, which includes upper and lowercase letters (A-Z,a-z), numerics (0-9), period (.), dash (-) and underbar(_). In addition, the special characters $, %, and # may be specified. (Since these characters are not part of the XPG4 portable character set, however, you should consider the future possibility of program portability before using these characters.)
Length:: Specified by the Userid_Length parameter

The name of an area, 0 to 8 characters in length, that contains a user ID. If a user ID is not required (Userid_Length is zero), this parameter is ignored.

Security_Class_Length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the Security_Class. The Security_Class_Length must be in the range of 1 to 8.

Security_Class

Supplied parameter

Type:: Character string
Character set:: Uppercase alphanumeric
Length:: Specified by the Security_Class_Length parameter

The name of an area, 1 to 8 characters in length, that contains the Security_Class. The Security_Class parameter cannot specify DATASET. For systems using RACF®, the class name specified must be in the RACF class descriptor table.

Entity_Name_Length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the Entity_Name. The Entity_Name_Length can be in the range of 1 to 246.

Entity_Name

Supplied parameter

Type:: Character string
Character set:: Uppercase alphanumeric
Length:: Specified by the Entity_Name_Length parameter

The name of an area, 1 to 246 characters in length, that contains the Entity_Name.

Access_Type

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains a numeric value that identifies the type of access to check for. The following Access_Type constants are defined by the BPXYCONS macro. See BPXYCONS — Constants used by services.

Constant	Access
ACK_READ#	check READ authority
ACK_UPDATE#	check UPDATE authority
ACK_CONTROL#	check CONTROL authority
ACK_ALTER#	check ALTER authority

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the auth_check_resource_np service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the auth_check_resource_np service stores the return code. The auth_check_resource_np service returns Return_code only if Return_value is -1. For a list of possible return code values, see z/OS UNIX System Services Messages and Codes. The auth_check_resource_np service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One or more of the following conditions were detected: Access_Type specified is undefined Userid_Length is outside allowable range (0-8) Security_Class_Length is outside allowable range (1-8) Entity_Name_Length is outside allowable range (1-246) The following reason codes can accompany the return code: JRAccessUndefined, JRUserNameLenError, JRClassLenErr, or JREntityLenErr.
ESRCH	One or more of the following conditions were detected: The user ID is not defined to the security product No mapping to a user ID exists for the specified UUIDs The resource is not defined to the security product The DCEUUIDS class is not active The following reason codes can accompany the return code: JRSAFNoUser,JRSAFNoUUIDtoUser, JRSAFResourceUndefined, or JRSAFNoDCEClass.
ENOSYS	One or more of the following conditions were detected: No security product is installed SAF support for this function is not installed The following reason codes can accompany the return code: JRNoSecurityProduct, or JRSNoSAFSupport.
EMVSSAF2ERR	An error occurred in the security product. One or more of the following conditions were detected: An internal error occurred in the security product An error was detected in the parameter list There was an undefined return code or reason code The following reason codes can accompany the return code: JRSAFInternal, JRSAFParmListErr, or JRUnexpectedError.
EPERM	One or more of the following conditions were detected: If BPX.SERVER is defined, the caller does not have update permission to BPX.SERVER. If BPX.SERVER is not defined, the caller is not a superuser. The user does not have the access specified to the resource. The caller's address space has done a load from an uncontrolled library The following reason codes can accompany the return code: JRNotServerAuthorized, JRNoResourceAccess, or JREnvDirty.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the auth_check_resource_np service stores the reason code. The auth_check_resource_np service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

The ability to query a user's access to protected resources is a privileged operation. An installation has the following ways of allowing an application to use this service:
- For the highest level of security, the installation can define the BPX.SERVER resource in the FACILITY class. In order for the application to access this service, it must have at least read access to this profile. In addition, all load modules executing in the application's address space must be defined to RACF. For more information about setting up this security, see the section on establishing UNIX security in z/OS UNIX System Services Planning.
- For a lower security arrangement, assign a UID of 0 to the user ID with which the application is run, so that it operates as a superuser.
This service cannot be used to determine access to POSIX resources, such as HFS files.
The access check can be made with several forms of identity. The first identity specified in the following list is used to make the authorization check:
1. User ID
2. Principal/Cell UUIDs
3. Caller's task level ACEE
4. Caller's address space level ACEE
When no identity is specified by the caller and the caller's task has an ACEE created with pthread_security_np (BPX1TLS, BPX4TLS) for a SURROGATE (non-password) client, both the task and address space level ACEEs are used in determining the type of access permitted to a resource.
Both the principal and cell UUIDs are in string form. A UUID string is 36 characters long. The string must contain the delimiter - in character positions 9, 14, 19, and 24. The general form of a UUID string is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x represents a valid numeric or hexadecimal character.

Related services

pthread_security_np, pthread_security_applid_np (BPX1TLS, BPX4TLS) — Create|delete thread-level security

Characteristics and restrictions

The auth_check_resource_np service is restricted to users that have the appropriate privileges.

Examples

For an example using this callable service, see BPX1ACK (auth_check_resource_np) example.