login(), login_applid() — Create a new security environment for process

Standards

Standards / Extensions	C or C++	Dependencies
z/OS® UNIX	both	OS/390 V2R6

Format

#define  _OPEN_SYS
#include <unistd.h>

int __login(int   function_code,
            int   identity_type,
            int   identity_length,
            void  *identity,
            int   pass_length,
            char  *pass,
            int   certificate_length,
            char  *certificate,
            int   option_flags);

int __login_applid(int function_code,
				int identity_type,
				int identity_length,
				void *identity,
				int pass_length,
				char *pass,
				int certificate_length,
				char *certificate,
				int option_flags,
				const char *applid);

General description

The __login() function provides a way for a process to change its identity so as to be different than the address space identity and create a new security environment for the process. Once changed the process should not revert back to a previous identity and security environment. The following rules apply:

Any single-threaded process can issue a __login to change its security environment.
If the process is in a multiprocessing or multiple user environment and there is no task level security associated with the process, then the new security environment will be associated with the process.
If the process is in a multiprocessing or multiple user environment and there is task level security associated with the process, then the old security environment will be replaced by the new security environment.

The __login_applid() function is equivalent to __login() with the added feature that it also allows the application identifier (APPLID) to be supplied that will be passed on to the security product to assist with authentication. This is useful, for example, in situations where a pass ticket is provided and the pass ticket was created with a USERID/APPLID combination. When applid is NULL or a pointer to NULL, no application identifier will be passed on to the security product.

The function has the following parameters:

Parameter: Description
function_code: Specifies the function. Specify __LOGIN_CREATE, as defined in the unistd.h header file, to create a process level security environment for the caller's process.
identity_type: Specifies the format of the the user identity being provided in *identity. Specify __LOGIN_USERID, as defined in the unistd.h header file. The user ID identity is in the format of a 1-to-8-character userid and is passed as input.
identity_length: Specifies the length of the identity as defined by identity_type.
*identity: Specifies the user identity as defined by identity_type.
pass_length: Specifies the length of the password or PassTicket, or the password phrase defined by pass.
*pass: Specifies a user password or PassTicket, or a password phrase.
certificate_length: Is not used presently and must be set to zero.
certificate: Is not used presently and must point to void.
option_flags: Specifies options used to tailor request. Must be set to 0.
applid: Specifies the application identifier that will be used for authentication with the security product.

Usage notes

The intent of the __login() service is to provide a way for a process to change its identity so as to be different than the address space identity. The process should either terminate or select a new user ID, but should not try to revert back to the original identity. The user could issue the __login() again with the original user identity, but the task would retain its own security environment and not share the the security environment at the address space level.
A security product supporting multiprocessing or multiple user environment must be installed and operational.

Returned value

If successful, __login() returns 0.

If unsuccessful, __login() returns -1 and sets errno to one of the following values:

Error Code: Description
EACCES: Permission is denied.
EINVAL: A parameter is not valid. For example, length of applid exceeds 8 bytes.
EMVSERR: An MVS™ environmental error or internal occurred.
EMVSEXPIRE: The password or PassTicket, or a password phrase for the specified resource has expired.
EMVSSAF2ERR: An error occurred in the security product. The userid has been revoked or is unable to use the application.
ENOSYS: The function is not implemented.
EPERM: The operation is not permitted. Calling process may not be authorized in BPX.DAEMON facility class. The function is not supported in an address space where a load was done from an uncontrolled library. A required password or PassTicket, or a password phrase was not specified.
ESRCH: The USERID cannot become an OMVS process. The userid provided is not defined to the security product or doesn't have an OMVS segment defined.

Related information

unistd.h