Security-related APIs

Security-related APIs ** Program . . : CBX117 ** Description : Profile Token APIs ** Author . . : Carsten Flensburg ** Published . : Club Tech iSeries Programming Tips Newsletter ** Date . . . : April 29, 2004 ** ** ** Program summary ** --------------- ** ** Security-related APIs: ** QsyGetProfileHandle Validates the user profile and password ** passed to the API and generates a profile ** handle. ** ** The profile handle can be used to set the ** current user profile of the job running. ** ** Invalid passwords will increase the ** incorrect password count and possibly ** disable the specified user profile. ** ** A maximum of approximately 20,000 handles ** can be created in one job. ** ** QsySetToProfileHandle Validates the profile handle, locks the ** user profile, and changes the current ** job (or thread) to run under the user and ** group profiles represented by the profile ** handle. ** ** The qualified job name does not change to ** reflect the new user profile. Any objects ** created while running under the new user ** profile will be owned by this user profile. ** ** Spooled files created during the profile ** swap will be put under a QPRTJOB job. ** ** QsyReleaseProfileHandle Validates a given profile handle and then ** releases it. To use the user profile ** represented by the deleted profile handle ** again, you must generate a new profile ** handle for the user profile. ** ** QsyGenPrfTknE Verifies that the caller has authority to ** generate a profile token for the requested ** profile and then generates a profile token. ** ** This profile token can be passed to one or ** more additional processes which can then ** use it to perform tasks on behalf of the ** authenticated user. ** ** A maximum of approximately 2,000,000 ** profile tokens can be generated on a ** system. At that point further profile ** tokens can only be generated after one ** or more tokens have been removed. ** ** APIs are available to remove all profile ** tokens generated for a specific user or ** systemwide: QsyRemoveAllPrfTknsForUser ** respectively QsyRemoveAllPrfTkns. ** ** Introduced on V5R1, the QsyGenPrfTkn API ** is available on V4R5. ** ** QsySetToPrfTkn Validates the profile token and changes ** the current job (or 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 objects ** created while running under the new user ** profile will be owned by this user profile. ** ** Spooled files created during the profile ** swap will be put under a QPRTJOB job. ** ** QsyChkPrfTknUser Verifies that the user profile associated ** with the token is the same as the current ** user profile. Introduced on V5R1. ** ** QsyGenPrfTknFromPrfTkn Generates a profile token based on an ** existing profile token. ** ** The existing profile token must be a valid, ** multiple-use, regenerable profile token. ** The new profile token will represent the ** same user and group information as the ** original profile token. ** ** The existing profile token will be ** invalidated by this process. ** ** QsyGetPrfTknTimeOut Gets the number of seconds until a profile ** token is no longer valid. ** ** QsyRemovePrfTkn Removes the specified profile token. The ** profile token will no longer be valid for ** use with other profile token APIs. ** ** QsyInvalidatePrfTkn Invalidates a profile token. The profile ** token is no longer usable for other ** profile token APIs except the Remove ** Profile Token API. ** ** User interface manager APIs: ** QUILNGTX Display long text Displays the text string passed ** to the API in a pop-up window. ** Optionally a panel title can be ** retrieved from a message file. ** ** Maximum string length is 15360k. ** ** C library function: ** system Run system command Executes a system command. In the ** event of an resulting error the ** error message ID is exported in ** the _EXCP_MSGID variable. ** ** Programmer's notes: ** The majority of the Profile Token APIs were introduced on V4R5. ** ** A profile token can be passed between processes and jobs, so a ** profile token created in one job can be passed to and activated ** in another job. The time-out value, multiple-use and regenerable ** token attributes enables the creating process to stay in control ** of the further use of a profile token. ** ** A profile handle can only be used in the job that created it. ** ** According to Memo to Users V5R2 a number of changes is going to be ** introduced in a future release to the following of the APIs in this ** example: ** ** QsyGetProfileHandle - Special values will not be allowed for the ** password value. The QSYGETPH API should be ** used instead. ** ** QsyGenPrfTknE - Special values will not be allowed for the ** password value. The QsyGenPrfTkn API should ** be used instead. ** ** The following changes are pending for the replacement APIs mentioned ** above: ** ** QSYGETPH - When specifying a password for the password ** parameter, the password length and CCSID ** parameters will be required. When specifying ** a special value for the password parameter, ** the password length and CCSID parameters will ** not be allowed. ** ** QsyGenPrfTkn - Password values will not be allowed for the ** password parameter, only password special ** values. The QsyGenPrfTknE API should be used ** if password values are to be specified. ** ** To run this API Example program issue the following command from ** a command line: ** ** Call Pgm( CBX117 ) Parm( 'user profile' ) ** ** The user profile specified as the parameter is the one being swapped ** to during the Profile Token API demonstration performed by this ** program. ** ** The process of user profile swapping and restore is demonstrated and ** commented in a message display window and also documented using the ** DSPJOB (Display job) and DSPMSGD (Display message description) ** commands. To this process, extra steps have been added to show the ** use of the APIs that regenerates profile tokens, validates the user ** profile and profile token correlation as well as checks the profile ** token time-out value. ** ** Please note that only allowing this program to complete normally and ** execute all program statements will ensure that the initial current ** job user profile is restored correctly. ** ** ** Authority and security restrictions: ** To get a profile handle or token using special values *NOPWD or ** *NOPWDCHK, *USE authority is required to the user profile for which ** the handle is requested. ** ** If appropriate, the required authority can be obtained by means of ** adopted authority - se Compile options and Runtime requirement ** below. ** ** Profile handles or tokens will not be generated for user profiles ** that are disabled or whose passwords have expired. This restriction ** can, however, be circumvented if the special value *NOPWDCHK is ** specified for the password - and the requesting user profile has ** *ALLOBJ and *SECADM special authority. There are also a number of ** system supplied user profiles that cannot have profile handles or ** tokens generated. ** ** ** Compile options: ** CrtBndRpg Pgm( CBX117 ) ** ** Runtime requirement: ** ChgObjOwn Obj( CBX117 ) ** ObjType( *PGM ) ** NewOwn( QSECOFR ) ** ** **-- Control spec: -----------------------------------------------------** H Option( *SrcStmt ) UsrPrf( *Owner ) H DftActGrp( *No ) ActGrp( 'QILE' ) BndDir( 'QC2LE' ) **-- System information: -----------------------------------------------** D PgmSts SDs D PsPgmNam *Proc D PsSts 5a Overlay( PgmSts: 11 ) D PsCurJob 10a Overlay( PgmSts: 244 ) D PsUsrPrf 10a Overlay( PgmSts: 254 ) D PsJobNbr 6a Overlay( PgmSts: 264 ) D PsCurUsr 10a Overlay( PgmSts: 358 ) **-- API error data structure: -----------------------------------------** D ApiError Ds D AeBytPrv 10i 0 Inz( %Size( ApiError )) D AeBytAvl 10i 0 D AeExcpId 7a D 1a D AeExcpDta 128a **-- system function error id: -----------------------------------------** D SysError s 7a Import( '_EXCP_MSGID' ) **-- Global variables: -------------------------------------------------** D PrfHdlCur s 12a D PrfTkn s 32a D PrfTknNew s 32a D PrfChk s 10i 0 D TknTmo s 10i 0 **-- Get profile handle: -----------------------------------------------** D GetPrfHdl Pr ExtProc( 'QsyGetProfileHandle' ) D GpPrfHdl 12a D GpUsrPrf 10a Const D GpPwd 512a Const Options( *VarSize ) D GpPwdLen 10i 0 Value D GpPwdCcsId 10u 0 Value D GpError 32767a Options( *VarSize ) **-- Set profile handle: -----------------------------------------------** D SetPrfHdl Pr ExtProc( 'QsySetToProfileHandle' ) D SpPrfHdl 12a Const D SpError 32767a Options( *VarSize: *NoPass ) **-- Release profile handle: -------------------------------------------** D RlsPrfHdl Pr ExtProc( 'QsyReleaseProfileHandle' ) D RpPrfHdl 12a Const D RpError 32767a Options( *VarSize: *NoPass ) **-- Generate profile token extended: ----------------------------------** D GenPrfTknE Pr ExtProc( 'QsyGenPrfTknE' ) D GtPrfTkn 32a D GtUsrPrf 10a Const D GtPwd 512a Const Options( *VarSize ) D GtPwdLen 10i 0 Value D GtPwdCcsId 10u 0 Value D GtTimOutInt 10i 0 Value D GtPrtTknTyp 1a Value D GtError 32767a Options( *VarSize ) **-- Set to profile token: ---------------------------------------------** D SetPrfTkn Pr ExtProc( 'QsySetToPrfTkn' ) D StPrfTkn 32a Const D StError 32767a Options( *VarSize ) **-- Check profile token user: -----------------------------------------** D ChkPrfTkn Pr ExtProc( 'QsyChkPrfTknUser' ) D CtChkRes 10i 0 D CtPrfTkn 32a Const D CtError 32767a Options( *VarSize ) **-- Generate profile token from profile token; ------------------------** D GenPrfTknFt Pr ExtProc( 'QsyGenPrfTknFromPrfTkn' ) D GtNewTkn 32a D GtFrmTkn 32a Const D GtTimOutInt 10i 0 Const D GtPrtTknTyp 1a Const D GtError 32767a Options( *VarSize ) **-- Get profile token time out: ---------------------------------------** D GetTknTmo Pr ExtProc( 'QsyGetPrfTknTimeOut' ) D GtTknTmo 10i 0 D GtPrfTkn 32a Const D GtError 32767a Options( *VarSize ) **-- Remove profile token: ---------------------------------------------** D RmvPrfTkn Pr ExtProc( 'QsyRemovePrfTkn' ) D RtPrfTkn 32a Const D RtError 32767a Options( *VarSize ) **-- Invalidate profile token: -----------------------------------------** D InvPrfTkn Pr ExtProc( 'QsyInvalidatePrfTkn' ) D ItPrfTkn 32a Const D ItError 32767a Options( *VarSize ) **-- Display long text: ------------------------------------------------** D DspLngTxt Pr ExtPgm( 'QUILNGTX' ) D DtLngTxt 1024a Const Options( *VarSize ) D DtLngTxtLen 10i 0 Const D DtMsgId 7a Const D DtMsgF 20a Const D DtError 10i 0 Const **-- Run system command: -----------------------------------------------** D system Pr 10i 0 ExtProc( 'system' ) D command * Value Options( *String ) **-- Display message window: -------------------------------------------** D DspMsgWdw Pr D PxMsgStr 512a Const Varying **-- Parameter: --------------------------------------------------------** D PxUsrPrf s 10a ** C *Entry Plist C Parm PxUsrPrf ** **-- Mainline: ---------------------------------------------------------** ** C CallP DspMsgWdw ( 'Step 1: Save profile handle ' + C 'to original user profile ' + C %TrimR( PsUsrPrf ) + C ' to enable a subsequent ' + C 'restore - press Enter to ' + C 'continue.' C ) ** C CallP GetPrfHdl( PrfHdlCur C : '*CURRENT' C : '*NOPWD' C : 6 C : *Zero C : ApiError C ) ** C If AeBytAvl > *Zero ** C CallP DspMsgWdw ( 'Save of profile handle ended' + C ' in error - test terminated.' + C ' Press Enter.' C ) ** C Else C CallP DspMsgWdw ( 'Step 2: Generate a profile ' + C 'token for requested user ' + C 'profile: ' + C %TrimR( PxUsrPrf ) + C '. The token will be a ' + C 'multiple-use, regenerable ' + C 'profile token with a default' + C ' time-out value of 3600 ' + C 'seconds. Press Enter to ' + C 'continue.' C ) ** C CallP GenPrfTknE( PrfTkn C : PxUsrPrf C : '*NOPWD' C : 6 C : *Zero C : -1 C : '3' C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 3: Generate a profile ' + C 'token from the previously ' + C 'obtained profile token for ' + C %TrimR( PxUsrPrf ) + C '. The new token will be a ' + C 'single-use, non-regenerable ' + C 'profile token with a time-' + C 'out value of 100 seconds. ' + C 'Press Enter to continue.' C ) ** C CallP GenPrfTknFt( PrfTknNew C : PrfTkn C : 100 C : '1' C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 4: Set current profile ' + C 'of this job using the profile'+ C ' token from step 3. Please ' + C 'note "Current user profile" ' + C 'in the Display Job Status ' + C 'panel to follow. ' + C 'Press Enter to continue.' C ) ** C CallP SetPrfTkn( PrfTknNew C : ApiError C ) ** C If AeBytAvl > *Zero ** C CallP DspMsgWdw ( 'Setting of current profile ' + C 'ended in error. Press Enter ' + C 'to terminate test.' C ) ** C Else C CallP system( 'DSPJOB JOB(*) OPTION(*STSA)' ) ** C CallP ChkPrfTkn( PrfChk C : PrfTknNew C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 5: Check of token and ' + C 'user profile correlation ' + C 'returned result code: ' + C %Char( PrfChk ) + C ' (0=Different, 1=Same) ' + C '- press Enter to continue.' C ) ** C Reset ApiError ** C CallP GetTknTmo( TknTmo C : PrfTkn C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 6: Check of token time' + C '-out for initial profile ' + C 'token from step 2 returned ' + C 'error message ID: ' + C %Trim( AeExcpId ) + C '. Press Enter to continue.' C ) ** C CallP system( 'DSPMSGD ' + AeExcpId ) ** C CallP GetTknTmo( TknTmo C : PrfTknNew C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 7: Check of token time' + C '-out for new profile token ' + C 'from step 3 returned: ' + C %Char( TknTmo ) + C ' seconds. Press Enter to ' + C 'continue.' C ) ** C CallP InvPrfTkn( PrfTknNew C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 8: New profile token ' + C 'has been invalidated. ' + C 'Press Enter to continue.' C ) ** C CallP RmvPrfTkn( PrfTkn C : ApiError C ) ** C CallP RmvPrfTkn( PrfTknNew C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 9: Both profile tokens ' + C 'have been removed. ' + C 'Press Enter to continue.' C ) ** C CallP DspMsgWdw ( 'Step 10: Set current profile '+ C 'of this job using the profile'+ C ' handle from step 1. Please ' + C 'note "Current User profile" ' + C 'in the Display Job Status ' + C 'panel to follow. ' + C 'Press Enter to continue.' C ) ** C CallP SetPrfHdl( PrfHdlCur C : ApiError C ) ** C CallP system( 'DSPJOB JOB(*) OPTION(*STSA)' ) ** C EndIf ** C CallP RlsPrfHdl( PrfHdlCur C : ApiError C ) ** C CallP DspMsgWdw ( 'Step 11: The profile handle ' + C 'from step 1 has been released'+ C '. Press Enter to end test ' + C 'normally.' C ) ** C EndIf ** C Return ** **-- Display message window: -------------------------------------------** P DspMsgWdw B Export D Pi D PxMsgStr 512a Const Varying ** C CallP(e) DspLngTxt( PxMsgStr C : %Len( PxMsgStr ) C : *Blanks C : *Blanks C : *Zero C ) ** P DspMsgWdw E Thanks to Carsten Flensburg and Club Tech iSeries Programming Tips Newsletter