Check Encrypted User Password (QSYCUPWD) API

The Check Encrypted User Password (QSYCUPWD) API checks to see if the encrypted password data for the specified user profile on the system on which this API is run is the same as the encrypted password data for the user on the system where the Retrieve Encrypted User Password (QSYRUPWD) API was run.

The API does not check IBM i NetServer™ encrypted password information. Only the encrypted passwords used to sign on from a sign-on display are checked.

The QSYCUPWD API follows this process:

• Verifies that the user calling this API is authorized.
  
  
• Verifies that the user profile specified in the receiver variable from QSYRUPWD parameter exists and is correct.
  
  

• If the user profile is disabled, the incorrect password count is incremented and the appropriate value is set in the encrypted password return code.
  
  
• If the password for the user profile is *NONE, the appropriate value is set in the encrypted password return code. If the local password management (LCLPWDMGT) value for the user profile is *NO, then the password for the user profile will be *NONE.

• Checks to see if the encrypted passwords can be compared. If the passwords cannot be compared, the appropriate value is set in the encrypted password return code.

  The release versions and password levels must be compatible between the system on which this API is run and the system where the QSYRUPWD API was run to be able to compare the passwords. The passwords can be compared only if the user profile has a password for password level 0 or 1 on both systems or a password for password level 2 or 3 on both systems. If a system is at a release previous to V5R1M0, then the password for the user profile on that system is a password for password level 0 or 1.

  To determine if the user profile has a password for password level 0 or 1 or for password level 2 or 3, run either the Display Authorized Users (DSPAUTUSR) command and use the F11 key to see password level information, the Print User Profile (PRTUSRPRF) command using TYPE(*PWDLVL), or the Display User Profile (DSPUSRPRF) command using TYPE(*BASIC) to an outfile. These commands must be run on a V5R1M0 (or later) system.

• Compares the passwords. If the passwords do not match, the incorrect password count is incremented. 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 check the encrypted password when there is a mismatch will disable the user profile.
  
  
• If the password for the user profile is expired, the appropriate value is set in the encrypted password return code.

Authorities and Locks

User Profile Authority

Caller of this API must have *ALLOBJ and *SECADM special authorities

API Public Authority

*EXCLUDE

Required Parameter Group

Encrypted password return code

OUTPUT; CHAR(1)

Whether the encrypted password for the user profile on the system on which this API is run matches the encrypted password for the same user profile that is specified in the receiver variable from QSYRUPWD parameter. This parameter contains one of the following:

0	The passwords match.
1	The user profile on the system on which this API is run is disabled. The passwords may or may not match.
2	The password for the user on the system on which this API is run is *NONE.
3	The passwords for the user profile on the system on which this API is run match, but the password is expired.
4	The passwords could not be compared.
9	The passwords do not match.

Receiver variable from QSYRUPWD

INPUT; CHAR(*)

The variable that is used to check the encrypted password for the user. The receiver variable from the QSYRUPWD API must be used as input to this API. For this API to successfully check the encrypted password for the user, the bytes returned value must be equal to the bytes available value in the input data. The input data must be retrieved from the receiver variable used by the QSYRUPWD API and cannot be changed in any way.

Format

INPUT; CHAR(8)

The name of the format that is used to check the user's encrypted password data. The following value is allowed:

UPWD0100

Encrypted password will be checked.

Error code

I/O; CHAR(*)

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

UPWD0100 Format

The following table describes the input variable that is to be passed as the second parameter to QSYCUPWD. This input variable must be the same data as the receiver variable that is returned by the QSYRUPWD API. The receiver variable, returned by the QSYRUPWD API, cannot be changed in any way prior to passing the data as input to the QSYCUPWD API. If this data is changed, the QSYCUPWD API will not be able to successfully check the password for the user. For detailed descriptions of the fields in the tables, see Field Descriptions.

Field Descriptions

Bytes available. The number of bytes of data available when retrieved by the QSYRUPWD API. For the QSYCUPWD API to successfully check the encrypted password for the user, this value must be equal to the bytes returned value. If the bytes available field is greater than the bytes returned field, this input cannot be used to successfully check the encrypted password for the user.

Bytes returned. The number of bytes of data.

Encrypted user password data. The encrypted password data for the user profile.

User profile name. The name of the user profile for which the password will be checked.

Error Messages

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