Generate Profile Token Extended (QsyGenPrfTknE) API

Syntax for QsyGenPrfTknE:

 #include <qsyptkn.h>

 void QsyGenPrfTknE
        (unsigned char  *Profile_token,
         char           *User_profile_name,
         char           *User_password,
         int             Length_of_user_password,
         unsigned int    CCSID_of_user_password,
         int             Time_out_interval,
         char            Profile_token_type,
         void           *Error_code);

  Service Program: QSYPTKN

  Default Public Authority: *USE

  Threadsafe: Yes

The Generate Profile Token Extended (QsyGenPrfTknE) API 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.

This API requires the password for the profile to be specified. If you need to generate a profile token for a profile without specifying the password, see the Generate Profile Token (QsyGenPrfTkn) API.

The Generate Profile Token API follows this process:

Verifies that the user ID and password value are correct. Incorrect password values and special cases are handled as follows:
- If the password is not correct, the incorrect password count is increased. (The QMAXSIGN system value contains the maximum number of incorrect attempts to sign on.) If the QMAXSGNACN system value is set to disable the user profile, repeated attempts to generate a profile token using an incorrect password disables the user ID. This keeps applications from methodically determining user passwords.
- To obtain a profile token for a profile that does not have a password, use the Generate Profile Token (QsyGenPrfTkn) API.
- To obtain a profile token for a profile that is disabled, use the Generate Profile Token (QsyGenPrfTkn) API.
- To obtain a profile token when the password is expired, use the Generate Profile Token (QsyGenPrfTkn) API.
Generates the profile token designating the user's authorities.
The maximum number of profile tokens that can be generated is approximately 2,000,000; after that, the space to store them is full. Message CPF4AAA is sent to the application, and no more profile tokens can be generated until one is removed.
Updates the last-used date for the user and its group profiles.
Resets the signon attempts not valid count to zero when a profile token is successfully generated for a user.
If security-related events are being audited, adds an entry to the QAUDJRN audit journal to indicate that a profile token is created.

Authorities and Locks

API Public Authority: *USE
User Profile Lock: *LSRD

Required Parameter Group

Profile token

OUTPUT; CHAR(32)

The profile token that is generated.

User profile name

INPUT; CHAR(10)

The name of the user for which to generate the profile token.

User password

INPUT; CHAR(*)

The password of the user for which to generate the profile token.

Special values are not allowed for this parameter.

Length of user password

INPUT; BINARY(4)

The length, in bytes, of the password contained in the user password parameter.

The valid values are:

1-512

The length of the password in the password parameter.

CCSID of user password

INPUT; BINARY(4)

The CCSID of the user password parameter. For a list of valid CCSIDs, see the IBM i globalization topic collection.

The valid values are:

-1	The current password level for the system is used to determine the CCSID of the password data. When calling this API on password level 0 or 1, CCSID 37 is used. When calling this API on password level 2 or 3, the default CCSID (DFTCCSID) job attribute is used. See usage notes for more details.
0	The CCSID of the job is used to determine the CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from the default CCSID (DFTCCSID) job attribute is used.
1-65533	A valid CCSID in this range.

Time out interval

INPUT; BINARY(4)

The time before the profile token times out.

You can specify one of the following values:

-1	Use system default value (3600 seconds)
1-3600	Time out value in seconds.

Profile token type

INPUT; CHAR(1)

The type of the profile token to be generated.

You can specify one of the following values:

1	Single-use profile token. A single-use profile token can be used only on the Set To Profile Token (QSYSETPT; QsySetToProfileToken) API once and cannot be used to generate new profile tokens.
2	Multiple-use profile token. A multiple-use profile token can be used on the Set To Profile Token (QSYSETPT; QsySetToPrfTkn) API an unlimited number of times, but cannot be used to generate new profile tokens.
3	Multiple-use, regenerable profile token. A multiple-use, regenerable profile token can be used on the Set To Profile Token (QSYSETPT; QsySetToPrfTkn) API an unlimited number of times and can be used to generate a new single-use, multiple-use, or multiple-use, regenerable profile token.

Error code

I/O; CHAR(*)

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

Usage Notes

The CCSID parameter on this API can lead to potential problems if coded with inconsistent CCSID values. Passwords created using the CRTUSRPRF, CHGUSRPRF, and CHGPWD CL commands, as well as the QSYCHGPW API (when called without passing the CCSID parameter), while the system is running password level 0 or 1 are created using CCSID 37. Passwords created using these CL commands and the QSYCHGPW API (without the CCSID parameter specified) when running password level 2 or 3 are created using the default job CCSID. Using variant characters $, @ and #, as well as other variant characters, in a user password may result in inconsistencies when converting from one CCSID to another. When calling this API on password level 0 or 1, CCSID 37 should be specified unless the password string is in a known CCSID. When calling this API on password level 2 or 3, pass the default job CCSID unless the password string is in a known CCSID.

Error Messages

Message ID	Error Message Text
CPF2204 E	User profile &1 not found.
CPF2213 E	Not able to allocate user profile &1.
CPF2225 E	Not able to allocate internal system object.
CPF227F E	*NOPWD not allowed for current user.
CPF22E2 E	Password not correct for user profile &1.
CPF22E3 E	User profile &1 is disabled.
CPF22E4 E	Password for user profile &1 has expired.
CPF22E5 E	No password associated with user profile &1.
CPF22E9 E	*USE authority to user profile &1 required.
CPF3BC7 E	CCSID &1 outside of valid range.
CPF3BDE E	CCSID &1 not supported by API.
CPF3CF1 E	Error code parameter not valid.
CPF3C1D E	Length specified in parameter &1 not valid.
CPF3C90 E	Literal value cannot be changed.
CPF4AAA E	Maximum number of profile tokens have been generated.
CPF4AAB E	Time out value not valid.
CPF4AAD E	Profile token type not valid.
CPF4AB8 E	Insufficient authority for user profile &1.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V5R1

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