Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
POSIX(ON)
|
Format
#define _OPEN_SYS 1
#include <pthread.h>
int pthread_security_np(int function_code,
int identity_type,
size_t identity_length,
void *identity,
char *password,
int options);
int pthread_security_applid_np(int function_code,
int identity_type,
size_t identity_length,
void *identity,
char *password,
int options
const char *applid);
General description
pthread_security_np()
creates or deletes a thread-level security environment for the calling
thread.
The __pthread_security_applid_np()
function is equivalent to pthread_security_np() 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 supports
the following parameters:
- Parameter
- Description
- function_code
- Specify one of the following:
- __CREATE_SECURITY_ENV
- Create a thread-level security environment for the calling thread.
If a thread-level security environment already exists, it is deleted
before a new one is created.
- __DAEMON_SECURITY_ENV
-
Creates a thread-level security environment for the caller's
thread without the need for a password if the caller is a superuser
and has permission to BPX.DAEMON facility class profile if BPX.DAEMON
facility class profile is defined. If a thread-level security environment
already exists, it is deleted before the new environment is created.
Using the _DAEMON_SECURITY_ENV function code and not specifying a
password is similar to using the current BPX.SRV.userid surrogate
support. The difference is that the installation does not have to
setup individual surrogate profiles for each of the clients that desire
a thread level identity in the target server process.
The server
will be allowed to create any identity without authentication if it
is given permission to the BPX.DAEMON facility class profile.
- __DELETE_SECURITY_ENV
- Delete the thread-level security environment for the calling thread,
if one exists. If the security environment was created using the __TLS_TASK_ACEE option,
then only the z/OS UNIX security data is deleted (the
task-level ACEE is unchanged).
- __TLS_TASK_ACEE
- Initializes the z/OS UNIX security data for a task that
has an existing task-level security environment (task-level ACEE).
If the z/OS UNIX security data already exists for the calling
task, the existing z/OS UNIX security data is deleted and
a new set of z/OS UNIX security data is established.
- __TLS_TASK_ACEE_USP
- Takes a pre-existing user security packet (USP) from a task-level
ACEE and extracts the UID and GID information. This information is
then used to build a complete z/OS UNIX security environment for the
calling thread. If the calling thread does not have a USP associated
with the task-level ACEE, this call is treated as if the __TLS_TASK_ACEE
function was specified.
- identity_type
- Specifies the format of the user identity in the argument identity.
It can have one of the following values:
- __USERID_IDENTITY
- User identity in the form of a character string (1 to 8 bytes
in length).
- __CERTIFICATE_IDENTITY
- User identity in the form of a __certificate_t.
A
__certificate_t is a structure
containing the following elements:
- __cert_type
- The type of security certificate. Setting value __CERT_X509, for
example, indicates the certificate is an X.509 security certificate.
- __userid
- An output field in the __certificate structure
that will be filled with the user ID associated with the certificate.
This output will be up to 8 characters long and NULL-terminated.
- __cert_length
- The length in bytes of the security certificate.
- __cert_ptr
- A pointer to the start of the security certificate.
- identity_length
- Specifies the length of the identity parameter.
If identity_type is __USERID_IDENTITY, identity_length is
the length of the user identity character string. If identity_type is
__CERTIFICATE_IDENTITY, identity_length is
the length of the __certificate structure.
- identity
- Specifies the user identity according to the identity_type parameter.
- password
- Specifies a user password or PassTicket, or a
password phrase.
- options
- Specifies options used to tailor the request. options must
be set to 0.
- applid
- Specifies the application identifier that will be used for authentication
with the security product.
This function is intended to be used by servers
which process requests from multiple clients. By creating and building
a thread-level security environment for the client, a server can process
many client requests without the overhead of issuing fork/setuid/exec.
See usage notes in z/OS UNIX System Services Programming: Assembler Callable Services Reference for
additional information.
Returned value
If successful, pthread_security_np()
returns 0.
If unsuccessful, pthread_security_np()
returns -1 and sets errno to one the following values:
- Error Code
- Description
- EACCES
- The password or PassTicket, or the password phrase provided is
not valid for the passed userid.
- EINVAL
- A parameter is not valid.
- EMVSERR
- An MVS™ environmental error
or internal error occurred.
- EMVSEXPIRE
- The password or PassTicket, or the password phrase provided has
expired.
- EMVSSAF2ERR
- The SAF call to the security product incurred an error.
- EMVSSAFEXTRERR
- The SAF call to the security product incurred an error.
- ENOSYS
- The function is not implemented.
- EPERM
-
- The process does not have appropriate privileges to set a thread-level
security environment. The caller is not permitted to the BPX.SERVER
FACILITY class profile or BPX.SERVER is not defined and the caller
is not a superuser. No
password or PassTicket, or password phrase is provided and the caller
is not defined as a surrogate of the passed user ID.
- The caller is not a superuser and permitted to the
BPX.DAEMON FACILITY class profile or BPX.DAEMON is not defined and
the caller is not a superuser.
- ESRCH
- The user ID provided as input is not defined to the security product
or does not have an OMVS segment defined.