ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qsygenpt.htm

629 lines
16 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Generate Profile Token (QSYGENPT) API</title>
<!-- Begin Header Records ========================================== -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- QSYGENPT SCR450 A converted by B2H R4.1 (346) (CMS) by V2DCIJB -->
<!-- at RCHVMW2 on 2 Oct 1999 at 10:00:48 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited by Kersten Dec 2001 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Generate Profile Token (QSYGENPT) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Profile token</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(32)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">User profile name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">User password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Time out interval</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Bin(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Profile token type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">7</td>
<td align="left" valign="top" width="50%">Length of user password</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Bin(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CCSID of user password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Bin(4)</td>
</tr>
<tr>
<td></td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Service Program: QSYPTKN<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Generate Profile Token (OPM, QSYGENPT) 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.</p>
<p>The Generate Profile Token API follows this process:</p>
<ul>
<li>Verifies that the user ID and password value are correct. Incorrect
password values and special cases are handled as follows:<br>
<br>
<ul>
<li>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.<br>
<br>
</li>
<li>*NOPWD is not allowed if the user profile name is the name of the user
profile running currently.<br>
<br>
</li>
<li>To obtain a profile token for a profile that does not have a password,
specify *NOPWDCHK or *NOPWDSTS for the password parameter.
<p>You cannot obtain a profile token for the following system-supplied user
profiles:</p>
<pre>
QAUTPROF QDLFM QMSF QSNADS QTSTRQS
QCLUMGT QDOC QNETSPLF QSPL
QCOLSRV QDSNX QNFSANON QSPLJOB
QDBSHR QFNC QNTP QSRVAGT
QDBSHRDO QGATE QPEX QSYS
QDFTOWN QLPAUTO QPM400 QTCP
QDIRSRV QLPINSTALL QRJE QTFTP
</pre>
<br>
<br>
</li>
<li>To obtain a profile token
for a profile that is disabled, specify *NOPWDCHK for the password parameter.
<br>
<br>
</li>
<li>To obtain a profile token when the password is expired,
specify *NOPWDCHK or *NOPWDSTS for the password parameter.
<br>
<br>
</li>
</ul>
</li>
<li>Generates the profile token designating the user's authorities.
<p>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.<br>
<br>
</p>
</li>
<li>Updates the last-used date for the user and its group profiles.<br>
<br>
</li>
<li>Resets the signon attempts not valid count to zero when a profile token is
successfully generated for a user.<br>
<br>
</li>
<li>If security-related events are being audited, adds an entry to the QAUDJRN
audit journal to indicate that a profile token is created.<br>
<br>
</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*USE</dd>
<dt><em>User profile authority, if the password is *NOPWD
*NOPWDCHK or *NOPWDSTS.</em></dt>
<dd>*USE</dd>
<dt><em>User Profile Lock</em></dt>
<dd>*LSRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Profile token</strong></dt>
<dd>OUTPUT; CHAR(32)
<p>The profile token that is generated.</p>
<br>
</dd>
<dt><strong>User profile name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the user for which to generate the profile token.</p>
<br>
</dd>
<dt><strong>User password</strong></dt>
<dd>INPUT; CHAR(*)
<p>The password of the user for which to generate the profile token or a special value.</p>
<p><strong>Password of the user</strong></p>
<ul>
<li><em>Length of password</em> and <em>CCSID of password</em> are
required</li>
</ul>
<p><strong>Special value</strong></p>
<ul>
<li><em>Length of password</em> and <em>CCSID of password</em> are not allowed
when specifying a special value.</li>
<li>A special value must be a 10 character, blank padded value in CCSID
37.</li>
<li>Special values allowed are:<br>
<br>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*NOPWD</em></td>
<td align="left" valign="top">The user requesting the profile token must have *USE authority to the user
profile.
<p>A profile token does not get created for a disabled user profile.</p>
<p>A profile token does not get created for a user profile with an expired password.</p>
<p>This value is not allowed if the name of the currently running profile is
specified for the user profile name parameter.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOPWDCHK</em></td>
<td align="left" valign="top">The user requesting the profile token must have
*USE authority to the user profile.
<p>If the profile is disabled,
the user requesting the profile token must have *ALLOBJ and *SECADM special
authorities to get a token.</p>
<p>If the password is expired, the user requesting the profile token must have
*ALLOBJ and *SECADM special authorities to get a token.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOPWDSTS</em></td>
<td align="left" valign="top">The user requesting the profile
token must have *USE authority to the user profile.
<p>
A profile token does not get created for a disabled user profile.
</p>
<p>
If the password is expired,
the user requesting the profile
token must have *ALLOBJ and
*SECADM special authorities
to get a token.</p>
</td>
</tr>
</table>
<br>
</li>
</ul>
</dd>
<dt><strong>Time out interval</strong></dt>
<dd>INPUT; BINARY(4)
<p>The time before the profile token times out.</p>
<p>You can specify one of the following values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">Use system default value (3600 seconds)</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1-3600</em></td>
<td align="left" valign="top">Time out value in seconds.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Profile token type</strong></dt>
<dd>INPUT; CHAR(1)
<p>The type of the profile token to be generated.</p>
<p>You can specify one of the following values:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group</h3>
<p>This parameter group is
required when specifying a password for the <em>password</em> parameter. It is
not allowed when specifying a special value.</p>
<dl>
<dt><strong>Length of user password</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length, in bytes, of the password contained in the user password
parameter.</p>
<p>The valid values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>1-512</em></td>
<td align="left" valign="top">The length of the password in the user password
parameter.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>CCSID of user password</strong></dt>
<dd>INPUT; BINARY(4)
<p>The CCSID of the user password parameter.
For a list of valid CCSIDs, see the <a href=
"../nls/rbagsglobalmain.htm">Globalization</a> topic in the iSeries Information
Center.</p>
<p>The valid values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">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.
</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1-65533</em></td>
<td align="left" valign="top">A valid CCSID in this range.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Usage Notes</h3>
<p>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.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF2204 E</td>
<td align="left" valign="top">User profile &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2213 E</td>
<td align="left" valign="top">Not able to allocate user profile &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2225 E</td>
<td align="left" valign="top">Not able to allocate internal system object.</td>
</tr>
<tr>
<td align="left" valign="top">CPF227F E</td>
<td align="left" valign="top">*NOPWD not allowed for current user.</td>
</tr>
<tr>
<td width="15%" valign="top">CPF22E2 E</td>
<td width="85%" valign="top">Password not correct for user profile &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E3 E</td>
<td align="left" valign="top">User profile &amp;1 is disabled.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E4 E</td>
<td align="left" valign="top">Password for user profile &amp;1 has
expired.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E5 E</td>
<td align="left" valign="top">No password associated with user profile
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E9 E</td>
<td align="left" valign="top">*USE authority to user profile &amp;1
required.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BC7 E</td>
<td align="left" valign="top">CCSID &amp;1 outside of valid range.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BDE E</td>
<td align="left" valign="top">CCSID &amp;1 not supported by API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3C E</td>
<td align="left" valign="top">Value for parameter &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF4AAA E</td>
<td align="left" valign="top">Maximum number of profile tokens have been
generated.</td>
</tr>
<tr>
<td align="left" valign="top">CPF4AAB E</td>
<td align="left" valign="top">Time out value not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF4AAD E</td>
<td align="left" valign="top">Profile token type not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF4AB8 E</td>
<td align="left" valign="top">Insufficient authority for user profile
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R5
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>