Set To Profile Token (QSYSETPT, QsySetToPrfTkn) API

 #include <qsyptkn.h>

 void QsySetToPrfTkn
        (unsigned char  *Profile_token,
         void           *Error_code);

The Set To Profile Token (OPM, QSYSETPT; ILE, QsySetToPrfTkn) API validates the profile token and changes the current thread to run under the user and group profiles represented by the profile token.

The qualified job name does not change to reflect the new user profile. Any object, however, created by the thread while running under the new profile is owned by the new profile or its group profile. If the job is running single threaded and the job user identity has not been explicitly set by an API, the job user identity is changed to the name of the new profile. If the job is running multithreaded, the job user identity does not change.

If the profile token is not valid, this API signals the message CPF2274 and puts an AF-W audit entry in the QAUDJRN audit journal.

If you use this API to begin running under a specific profile, any spooled files created are, by default, owned by that profile. This is controlled by the spool file owner (SPLFOWN) parameter on the CRTPRTF command and is done by putting the spooled file under a QPRTJOB job. Any spooled file command that references the spooled file with the job special value * will access only those files that were created before the profiles were swapped.

QPRTJOB

A QPRTJOB job is the name of a job under which files are spooled when the current job's user name is not the same as the user profile running currently. For example, if you use this API to set the profile to user JOE and create a spooled file, the file is spooled under job nnnnnn/JOE/QPRTJOB. This ensures that user JOE owns the spooled file and if that user uses the WRKSPLF command, the file is displayed.

Output Queue Considerations

The output queue that a spooled file is placed in may be different after using this API. If the application using this API produces spooled output that needs to be on a secure output queue or the application is expecting the spooled output to be found on a particular output queue, configuration changes may be required. See the Printing topic collections for information about which output queue contains the spooled output.

Auditing Considerations

The Job Change for modify profile or group profile using a profile token (JS-T) audit records are written by this API to the security audit journal when *JOBDTA or *JOBCHGUSR action auditing is active. There are special auditing considerations when *JOBDTA and *JOBCHGUSR are not specified as part of the action auditing system values QAUDLVL and QAUDLVL2 but have been specified as part of the user action auditing for one of the profiles involved in the set to profile token operation. The determination of whether a JS-T audit record is written to the security audit journal is made after this API has changed the current thread to run under the user profile represented by the profile token. *JOBDTA or *JOBCHGUSR user action auditing must be active for the user profile represented by the profile token in order for a JS-T audit record to be written. The following examples describe when JS-T audit records are written.

In these examples, it is assumed that system wide auditing of *JOBDTA and *JOBCHGUSR is not active (system values QAUDLVL and QAUDLVL2 do not contain *JOBDTA or *JOBCHGUSR).

• UserA - *JOBDTA or *JOBCHGUSR user profile action auditing is active.
• UserB - *JOBDTA and *JOBCHGUSR user profile action auditing are not active.

Example 1 - Thread profile (UserA) has *JOBDTA or *JOBCHGUSR user profile action auditing active.

If UserA is the thread profile and uses this API to run under profile UserB, then there will not be a JS-T audit record written to the security audit journal. An audit record is not written because when the API makes the determination of whether an audit record should be written, the thread is running as UserB who does not have *JOBDTA or *JOBCHGUSR user action auditing active.

Example 2 - Thread profile (UserB) does not have *JOBDTA or *JOBCHGUSR user profile action auditing active.

If UserB is the thread profile and uses this API to run under profile UserA, then there will be a JS-T audit record written to the security audit journal. An audit record is written because when the API makes the determination of whether an audit record should be written, the thread is running as UserA who has *JOBDTA or *JOBCHGUSR user action auditing active.

Authorities and Locks

API Public Authority

*USE

Required Parameter Group

Profile token

INPUT; CHAR(32)

The profile token returned by the Generate Profile Token (QSYGENPT, QsyGenPrfTkn)API or Generate Profile Token From Profile Token (QSYGENFT, QsyGenPrfTknFromPrfTkn) API that represents the user profile to which to switch.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Error Messages

Usage Notes

Considerations for Scope and Thread Safety

This API sets the user profile for the thread in which it is called. Thus, if the API is called while running multithreaded, it will result in different threads in the same process simultaneously running under different user profiles.

While this API itself is threadsafe, it should only be used in a job that is running multithreaded when all code running in the job is known to be trusted and operating in a coordinated manner. Some considerations when running multiple threads under different user profiles are:

• The design of threads is for every thread in the job to share the same resources. With threads, programs share the same static and heap storage, and by passing pointers, they can get at each other's automatic storage. They also share open files and other resources, such as the same QTEMP library and the profile tokens used by this API.
• Assume two users are allowed to run their own commands or programs in different threads of a single job. One of the users may be able to read or write data of the other user. This access may occur without the system doing an authority check or even auditing the fact that they read or modified the data.

[ Back to top | Security APIs | APIs by category ]