TESTAUTH — Test authorization of caller

Description

The TESTAUTH macro is used on behalf of a privileged or sensitive function to verify that its caller is appropriately authorized.

TESTAUTH supports the authorized program facility (APF) - a facility that permits the identification of programs that are authorized to use restricted functions. In addition, TESTAUTH provides the capability for testing for system key 0-7 and supervisor state. An EUT FRR may not be in force for a caller using BRANCH=NO.

Environment

The requirements for the caller are:

When BRANCH=NO

Environmental factor	Requirement
Minimum authorization:	Problem or supervisor state, any key
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
Asc mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control Parameters:	Must be in primary address space

When BRANCH=YES

Note: When BRANCH=YES, the caller must include the CVT mapping macro.

Environmental factor	Requirement
Minimum authorization:	Supervisor state, any key
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
Asc mode:	Primary
Interrupt status:	No requirement
Locks:	Local lock held
Control Parameters:	Must be in primary address space

Programming requirements

None.

Restrictions

When using BRANCH=NO, the caller cannot have an EUT FRR established.

Input register information

Before issuing the TESTAUTH macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

The TESTAUTH macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede TESTAUTH.

TESTAUTH

␢	One or more blanks must follow TESTAUTH.

FCTN=`fctn`	`fctn`: Decimal digit 0 or 1 or register (2) - (12).
	Default: FCTN=0 if STATE or KEY is specified. Otherwise, the default is FCTN=1.

,STATE=NO	Default: STATE=NO
,STATE=YES

,KEY=NO	Default: KEY=NO
,KEY=YES

,RBLEVEL=2	Default: RBLEVEL=2
,RBLEVEL=1	RBLEVEL is used only if KEY and/or STATE are specified; otherwise RBLEVEL is ignored.

,BRANCH=NO	Default: BRANCH=NO
,BRANCH=YES

Parameters

The parameters are explained as follows:

FCTN=fctn

Specifies the authorization of a program to be checked through APF.

FCTN=0 specifies that APF-authorization is not checked.

FCTN=1 specifies that APF-authorization is checked.

,STATE=NO

,STATE=YES

Specifies whether or not (YES or NO) a check is to be made for supervisor/problem program state. (Supervisor state is authorized, problem program state is not authorized.)

,KEY=NO

,KEY=YES

Specifies whether or not (YES or NO) a check is to be made of the protection keys. (Protection keys 0-7 are authorized, protection keys 8-15 are not authorized.)

Note: TESTAUTH is used to test one or more of three conditions: FCTN, STATE, or KEY. If any of the requested conditions are tested favorably, a return code of zero is returned in register 15. If all of the requested conditions are tested unfavorably, the return code is set to 4.

,RBLEVEL=2
,RBLEVEL=1: Specifies whether the TESTAUTH caller is a type 2, 3, or 4 SVC (RBLEVEL=2) or a type 1 SVC (RBLEVEL=1). If the TESTAUTH caller is not an SVC, specify RBLEVEL=1. Specify RBLEVEL only if you also specify KEY and/or STATE; otherwise RBLEVEL is ignored.
,BRANCH=NO
,BRANCH=YES: Specifies a branch entry (YES) or an SVC entry (NO). If BRANCH=YES is specified, registers 2 and 3 are modified by the TESTAUTH routine. Only SVC routines can use BRANCH=YES.

ABEND codes

None.

Return codes

When control is returned, register 15 contains one of the following hexadecimal return codes:

Table 1. Return Codes for the SAMPLE Macro
Return Code	Meaning and Action
00	Meaning: Task is authorized. Action: None.
04	Meaning: Task is not authorized. Action: None.

Example 1

Test jobstep for APF authorization.

TESTAUTH FCTN=1

Example 2

Test for APF authorization and supervisor state and do not check protection keys.

TESTAUTH STATE=YES,KEY=NO,FCTN=1