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
- 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
- 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.)
- ,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:
Return Code | Meaning and Action |
---|---|
00 | Meaning: Task is authorized. Action: None. |
04 | Meaning: Task is not authorized. Action: None. |
Example 1
TESTAUTH FCTN=1
Example 2
TESTAUTH STATE=YES,KEY=NO,FCTN=1