auth_check_resource_np (BPX1ACK, BPX4ACK) — Determine a user's access to a RACF-protected resource
Function
- 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
The syntax has the following 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 uppercase and lowercase letters (A-Z,a-z), numerics (0-9), period (.), dash (-) and underscore(_). In addition, the special characters $, %, and # can 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 return code values, see Return codes (errnos) in 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 was 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 was 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 was 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. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and 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 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.
- The access check can be made with several forms of identity. The
first identity that is specified in the following list is used to
make the authorization check:
- User ID.
- Principal/Cell UUIDs.
- Caller's task level ACEE.
- 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
Characteristics and restrictions
The auth_check_resource_np service is restricted to users that have the appropriate privileges.