The __passwd callable service verifies and/or changes the input user_name's password or password phrase, or verifies the input user_name's PassTicket.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key. |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1PWD): | 31-bit |
AMODE (BPX4PWD): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4PWD with the same parameters.
The name of a fullword that contains the length of User_name.
The name of a field, of length User_name_length, that contains, left-justified, the name of the user whose Pass value is to be verified and/or changed.
The name of a fullword that contains the length of the Pass parameter. This length must be between 1 and 8 characters for a password or PassTicket or between 9 and 100 characters for a password phrase. A length of zero indicates that the Pass parameter is to be ignored and causes a SURROGAT class check.
See Usage notes.The name of a field, of length Pass_length, that contains, left-justified, the password, PassTicket or password phrase that is to be verified.
The name of a fullword that contains the length of New_Pass. This length must be between 1 and 8 characters for a password or between 9 and 100 characters for a password phrase. A length of zero indicates that New_Pass is to be ignored.
The name of a field, of length New_Pass_length, that contains, left-justified, the new password or password phrase for the specified user.
The name of a fullword in which the __passwd service returns 0 if the request is successful, or -1 if it is not successful.
The name of a fullword in which the __passwd service stores the return code. The __passwd service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes.
Return_code | Explanation |
---|---|
EINVAL | User_name, Pass, or New_Pass length is incorrect; or the user name has an illegal first character. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRUserNameLenError, JRPasswordLenError, JRNewPasswordLenError, and JRUserNameBad. |
ESRCH | The user name specified is not defined to OMVS. |
EACCES | The password specified is not authorized; access is denied. |
EMVSERR | There is an error in the USER definition in
the security product data base. The following reason codes can accompany
the return code: JREnvDirty, JRPNoSAFUser, JRSAFGroupNoOMVS, JRSAFUserNoOMVS,
and JRSAFNoGid. The caller environment is dirty; that is, a program was loaded from an unauthorized library. |
EMVSEXPIRE | The password has expired. |
EMVSPASSWORD | The new password is not valid. |
EMVSSAFEXTRERR | A RACF® authorization error has occurred. The reason code contains the RACF return and reason codes, respectively, in the two low-order bytes. See Table 1 for more information. |
EMVSSAF2ERR | A RACF authorization occurred. The reason code contains the RACF return and reason codes, respectively, in the two low-order bytes. See Table 1 for more information. |
The name of a fullword in which the __passwd service stores the reason code. The __passwd service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
RACF Return Code | RACF Reason Code | Explanation |
---|---|---|
8 | 12 | Internal error during RACF processing |
8 | 16 | Unable to establish recovery |
8 | 20 | The user does not have appropriate RACF access to either the SECLABEL, SERVAUTH profile, or APPL. |
30 | 00 | The user is not authorized to the port of entry. |
30 | 04 | The user is not authorized to access the system on this day, or at this time of day. |
30 | 08 | The port of entry cannot be used on this day, or at this time of day. |
34 | N/A | The user is not authorized to use the application. |
38 | 04 | MLACTIVE requires a SECLABEL; none was specified. |
38 | 08 | The user is not authorized to the SECLABEL. |
38 | 0C | The system was in a multilevel secure status, and the dominance check failed. |
38 | 10 | Neither the user's nor the submitter's security label dominates. They are disjoint. |
38 | 14 | The client's security label is not equivalent to the server's security label. |
Table 1 is not a complete list of all possible RACF return code and reason code combinations. For RACF codes not listed here, see initACEE (IRRSIA00) callable service in z/OS Security Server RACF Callable Services.
The contents of the password phrase string are passed unchanged to the installed security product.
If, however, a New_Pass is specified and Pass_length is specified as 0, the __passwd service fails with an EINVAL.
If there is no applid value passed and the calling process has NOT done a pthread_security_np() call, the applid defaults to a null value.
Some applications may need the applid to be specified as the JOBNAME. The application should set the ThliF2_SetApp bit prior to calling the password service. When this bit is on, the password service uses the application JOBNAME as the applid value passed to the security product. This is honored only if the process has not done a pthread_security_np() call. Specification of the applid in the THLIEP_APPLID field or via the __passwd_applid() call overrides the ThliF2_SetApp setting.
None.
For an example using this callable service, see BPX1PWD (__passwd, __passwd__applid) example.