Understanding how the mainframe manages authorized and non-authorized code is crucial for anyone performing system-level tasks. The concepts are simple, but understanding how they relate to one another can get dicey. This post is geared towards someone who needs to write authorized mainframe code.
The system considers a task authorized when the executing program has the following characteristics:
It runs in supervisor state (bit 15 of the program status word (PSW) is zero).
It runs with PSW key 0 to 7 (bits 8 through 11 of the PSW contain a value in the range 0 to 7).
All previous programs executed in the same task were APF programs.
Here are the three things you need to know about:
APF AUTHORIZED: APF stands for A.uthorized P.rogram F.acility. It allows for the system programmer (for those of you who are new to the field, in mainframe-land a system programmer is like a system-administrator) to identify data sets and programs that are allowed to perform sensitive system functions. There are two components to APF authorization. The first is link-editing a module (program) with the AC 1 option set. By using the AC 1 option, we are making the module eligible to be APF authorized. The second component is to place the module into an APF authorized library. APF-authorized programs must reside in one of the following authorized libraries (data set):
SYS1.LINKLIB
SYS1.SVCLIB
SYS1.LPALIB
Authorized libraries specified by your installation.
Now that we've got our module properly link-edited and placed in an authorized library, we can move onto PSW key and system state. Normally, the system will run in what's referred to as “problem state”. This means there is a set of instructions that are unavailable. Only when the user is in supervisor state are these privileged instructions available. APF authorized programs are permitted to put the system into supervisor state. THIS IS IMPORTANT ---> APF AUTHORIZED PROGRAMS DO NOT RUN IN SUPERVISOR STATE AUTOMATICALLY! APF AUTHORIZATION ONLY ALLOWS FOR THE SYSTEM TO BE PLACED SUPERVISOR STATE.
So now that we're in supervisor state, there's one more thing we need to think about. Every page of storage (a page is 4 kilobytes) has a key associated with it. Keys 0-7 are considered protected, and 8-15 are considered unprotected. If a page of storage is protected, module attempting to access it must be authorized. The system needs to be in supervisor state in order to change the default PSW key from 8 to one that is authorized.
So, let's review. To create a program that is capable of executing privileged instructions and accessing protected storage, it needs to be APF authorized (link edited with the AC 1 option and placed in an APF authorized library), it needs to use the MODESET macro to place the system in supervisor state, and it needs to use the SPKA instruction to change the PSW key to 0-7 (whatever is appropriate).
Well, that's about it. I hope it helps. Here's a link that provides a bit more info if you need it.
Thank you for this awesome blog.
ReplyDeleteGood job keep going!
Hello, David!
ReplyDeleteThank you for your blog - it's very useful.
I have some questions for you about APF authorized programs:
What is the difference between APF authorized program and common program. Is it only PSW-bits related to security or it's something else?
And how APF authorized programs are handled by RACF? Are they bypass RACF checking procedures or it's something special case of RACF handling?
Sorry for my English, hope you understand me ;-)
Best regards, Alexander.
Hi Alexander,
ReplyDeleteGlad you are finding the blog useful!
The functional difference between an APF authorized program and a "common" one is the former has the ability to put the system into supervisor state, the later doesn't.
As for how RACF deals with APF authorized programs, can you be more specific?
-David
Thank you for answer, David.
ReplyDeleteAbout RACF: as far as I know, when program requests some resource, e.g . data set, it makes a call to resource manager which calls RACF to perform access check. While RACF performs check it uses a user profile, that contains user ID, user's password and attributes, and resource profile, that contains data set name, access list etc.
Also, as I know every program (task) which executes on system inherits profile of user that have launched that task.
So, the question is - what profile does APF program inherit? Or there are no access checks when system is in supervisor state?
Hi Alexander,
ReplyDeleteThere really isn't much of a relationship between APF authorization and RACF. The answer to your question is "it depends". Some resource managers won't call RACF if the system is in supervisor state, and others will. Further, there are RACF functions that can only be access if the system is in supervisor state.
Thank you again, David.
ReplyDeleteI've understood.
David,
ReplyDeleteIs there anything like Temp APF and PERM APF?
Hi Prema!
ReplyDeleteI am not sure I understand the question. Are you looking for an analogue to the SUDO command in unix - ie, a way to execute a single command as authorized?
Prema,
ReplyDeleteI guess your question is about dynamic and static updates.
yes you can update the APFLIST dynamically.
SETPROG APF,ADD,DSNAME=XXX.XXX.XXX,VOLUME=******
yes the above command gives temporary authorization, means upto next cold start. if you want permanent autherization after the above cmd, add it in PROGxx.
DeleteI guess your question is about dynamic updates.
ReplyDeleteYes you can do dynamic updates.
/SETPROG APF,ADD,DSNAME=XXX.XXX.XXX,VOLUME=******
Hi David,
ReplyDeleteThanks for this blog !
the blog says:
The system needs to be in supervisor state in order to change the default PSW key from 8 to one that is authorized
What is the default PSW key ? Is it the default value of the PSW bits 8-11?
And, Im confused between the role of the keys where a page of memory has an associated key. (what does this mean?) and the role of the keys providing a value either less than or GTE 8 which determines if a program is authorized. Is there a coupling between program authorization and memory protection ?
thx,
Rich
Hi Rich!
DeleteGlad you found the blog helpful. To ensure you got the most accurate information possible, I double checked my responses with my former colleague, Karl. His responses are the ones labeled "KDS"
1) I seem to recall key 8 being the default.
KDS: Yes.
2) I'm not sure about 'the default value of the PSW bits 8-11', but I do believe those are the bits which indicate what key the system is in.
KDS: bits 8-11 of the Program-Status Word are the key of the currently running program.
3) keyed storage - if I remember correctly, keyed storage does two things. First, given that there are two kinds of keys (auth and non-auth), it's a way to prevent untrusted programs from accessing sensitive system resources. Second, each key has an associated service, so putting everything in key 9, for example, is a way to help prevent programs from poking at data that isn't theirs. That is, despite the fact that key's 8-15 are unauthorized keys, a call that is specifically checking for key 9 won't be able to touch key 10 storage without an abend occurring.
KDS: That's basically it, but it's more complicated. Each page of storage has a storage key along with an attribute of being fetch protected of not fetch protected. When a program tries to access a page, the success of the operation depends on the programs PSW key and the page's storage key and fetch attribute. Here's the basic rules:
trying to read
- allowed if page is not fetch protected
- allowed if PSW key is 0
- allowed if PSW key equals storage key of the page
- allowed if storage key is 9
trying to write
- allowed if PSW key is 0
- allowed if PSW key equals storage key of the page
- allowed if storage key is 9
There's other factors besides keys that play into whether a write would be successful, but ignoring those, the above are the rules as far as keys are concerned.
4) I'm not sure what he means by 'coupling' here. They are a lot like physical keys and locks in that related concepts but two discrete elements which are part of a larger system integrity scheme.
KDS: There's certainly a relationship in that an unauthorized key 8 program cannot write to storage in keys 0 to 7 and cannot read fetch protected storage in keys 0 to 7. That is the main way that the operating system protects itself from tampering by unauthorized programs and is therefore critical for system integrity.