| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format | Input | Char(8) |
| 4 | User profile name | Input | Char(10) |
| 5 | Error code | I/O | Char(*) |
The Retrieve Encrypted User Password (QSYRUPWD) API returns to the caller the encrypted password data for the specified user profile. This API works with the Set Encrypted User Password (QSYSUPWD) API in that the APIs allow the user to more easily mirror the user profile activity on a second system based on the activity at the first system.
The data returned by the QSYRUPWD APIs should not be sent to a system that is at a different release or at a different password level. If data from this API is applied to a down-level system or a system with a different password level, unexpected changes to the user's password data could occur. For example, if the encrypted password data is retrieved from a system operating at password level 3 and is set on a system operating at password level 0 (or a pre-V5R1 system), the user profile's password is changed to *NONE. No checks are made to enforce these recommendations.
If the local password management (LCLPWDMGT) value for the specified user profile is *NO, then the local IBM i password will be set to *NONE when the QSYSUPWD API is called. Also, if the LCLPWDMGT value is *NO for the user profile on the system where the QSYSUPWD API is called, then the local IBM i password will be set to *NONE.
Except for the IBM i NetServer™ password, the QSYRUPWD API does not retrieve product-level encrypted data that may be associated with a user profile.
Note: If an error occurs while you are attempting to retrieve the IBM i NetServer password, the CPF22F0 error will be returned and no encrypted password data is returned.
The variable used to return the information about the user. The necessary size of this receiver variable can be obtained by calling the QSYRUPWD API with the length of receiver variable set to 8 bytes. The bytes available value that is returned in this receiver variable will indicate the necessary size of the receiver variable. The receiver variable format is defined in UPWD0100 Format.
The length of the receiver variable. This value must be at least 8 bytes in length. To obtain all information necessary to call the QSYSUPWD API, you must use a receiver variable at least as long as the bytes available value that is returned by this API.
The name of the format that is used to return the user's encrypted password.
The following value is allowed:
| UPWD0100 | Encrypted password is returned. |
The name of the user for whom the encrypted password will be returned.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following tables describe the receiver variable that is returned by the QSYRUPWD API. This receiver variable is used as input to the QSYSUPWD API (first parameter). The receiver variable cannot be changed in any way prior to passing the data to the QSYSUPWD API. If this data is changed, the QSYSUPWD API will not be able to successfully change the password for the user.
For detailed descriptions of the fields in this table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | User profile name |
| 18 | 12 | CHAR(*) | Encrypted user password data |
Bytes available. The number of bytes of data available to be returned to the user. Bytes available may increase from release to release but will always be a minimum of 2000 bytes. This field should be used to set the length of receiver variable input parameter. If the bytes available field is greater than the bytes returned field, the receiver variable cannot successfully be used as input to the QSYSUPWD API as not all encrypted password data will be returned by this API.
Bytes returned. The number of bytes of data returned to the user in the receiver variable.
Encrypted user password data. The encrypted password data for the specified user profile.
User profile name. The name of the user profile for which information is being returned.
| Message ID | Error Message Text |
|---|---|
| CPF2203 E | User profile &1 not correct. |
| CPF2225 E | Not able to allocate internal system object. |
| CPF222E E | &1 special authority is required. |
| CPF22F0 E | Unexpected errors occurred during processing. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Security APIs | APIs by category ]