__passwd, __passwd__applid (BPX1PWD, BPX4PWD) — Verify or change security information

Function

The __passwd callable service verifies or changes the input user_name's password or password phrase, or verifies the input user_name's PassTicket.

Requirements

Parameters

User_name_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of User_name.

User_name

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the User_name_length parameter

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 or changed.

Pass_length

Supplied parameter

Type:

Integer

Length:

Fullword

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.

Pass

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Pass_length parameter

The name of a field, of length Pass_length, that contains, left-justified, the password, PassTicket or password phrase that is to be verified.

New_Pass_length

Supplied parameter

Type:

Integer

Length:

Fullword

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.

New_Pass

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the New_Pass_length parameter

The name of a field, of length New_Pass_length, that contains, left-justified, the new password or password phrase for the specified user.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __passwd service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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.

The __passwd service can return one of the following values in the Return_code parameter:

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.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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.

Table 1. RACF return and reason codes

Return code	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.

1. All return and reason codes are in hexadecimal.
2. Return codes 30, 34 and 38 are associated with the RACF RACROUTE REQ=VERIFY macro.
3. Return code 8 is associated with the initACEE (IRRSIA00) RACF callable service.

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.

Usage notes

1. If a profile is defined in the FACILITY class protecting the BPX.DAEMON resource, all programs that are loaded into the caller's address space must be controlled programs by the installed security product (such as RACF). If the __passwd service detects that a load of a non-program control was done, it fails with an errno of EMVSERR and an errnnojr of JRENVDIRTY. See Establishing the correct level of security for daemons in z/OS UNIX System Services Planning.
2. New_Pass is ignored if New_Pass_length is 0. If New_Pass is specified for a password, the length must be less than or equal to 8. Further installation requirements might apply; for example, the length might need to be a minimum of 6. For a password phrase, the length must be less than or equal to 100 and greater than or equal to 9. If the Return_code indicates EMVSPASSWORD, the installation exit routine might have failed the request because the New_Pass did not meet some installation standard. If no installation exit is installed on this system, RACF rejected the password.
3. Mixed case passwords and PassTickets are supported if the installed security product supports mixed case; otherwise, passwords and PassTickets are folded to uppercase. Non-graphic characters are always folded to blanks.

   The contents of the password phrase string are passed unchanged to the installed security product.

4. If an entry for the specified User_name is not found in the user database, or if the User_name is not defined to the OMVS segment, an ESRCH error is returned.
5. If the caller of the __passwd service has read access to the BPX.SRV.userid SURROGAT class profile, where userid is the user ID specified in the User_name parameter, a null Pass value (Pass_length set to zero) can be specified, and the __passwd service will return a successful Return_value. See Defining servers to process users without passwords in z/OS UNIX System Services Planning for more information about setting up SURROGAT profiles.

   If, however, a New_Pass is specified and Pass_length is specified as 0, the __passwd service fails with an EINVAL.

6. When no Pass value is specified, a SURROGAT class check is made, ensuring the caller has access to the profile BPX.SRV.userid (where userid is the value that is specified on the User_Name parameter). If the userid portion of the profile name has blanks in it, then RACROUTE REQUEST=AUTH results in ABEND282 RC5C. The dump is suppressed and the request fails with a return code of EMVSSAF2ERR and a reason code of JrRACFBlankExists
7. The __passwd_applid() function is equivalent to __passwd() with the added feature that it also allows an application identifier (applid) to be supplied. The applid is used to verify the user's authority to access the application. When a PassTicket is specified, the applid value is also used in conjunction with the USERID to verify the PassTicket.
   If an application is not using the __passwd_applid() function but still wants to pass an applid to this service, the application can set the applid value in the BPXYTHLI.

   • THLIEP_FunctionCode is set with ThliEP_ApplSet.
   • THLIEP_ApplidLen is set to the length of the APPLID. If this value is less than 1 or greater than 8, then the ThliEP_APPLID value is ignored.
   • ThliEP_APPLID is set to the APPLID value.

   If there is no applid value passed and the calling process has done a pthread_security_np() call, the applid value defaults to OMVSAPPL.

   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.

8. Although z/OS UNIX System Services supports password phrases that are 9-100 characters in length, your installation, or the installed security product can have additional rules for password phrase lengths. Ask your security administrator or system programmer if any additional rules apply.
9. The __passwd() service supports identity context references (ICR). When __passwd() is used in conjunction with pthread_security_np(), an ICR can be used to authenticate a user and then create a thread-level security context (ACEE), similar to using a user ID and password. Because an ICR is a one-time-use entity, the __passwd() and pthread_security_np() services must be called from the same thread and the ICR specified on pthread_security_np() must be identical to the ICR specified on the preceding __passwd().
   Note: An ICR is not a user ID and password. It is a reference in the local identity context cache. See z/OS Integrated Security Services EIM Guide and Reference for more information regarding identity context references.
10. If environment variable BPXK_MIN_PWFOLD=YES is set then non-graphic characters will not be changed to blanks before being passed to the security product. This behavior will exist for all threads in the process where the environment variable was set

Related services

• getpwnam (BPX1GPN, BPX4GPN) — Access the user database by user name

Characteristics and restrictions

None.