__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.