Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1TLS): | 31-bit |
AMODE (BPX4TLS): | 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 BPX4TLS with the same parameters.
Constant | Function |
---|---|
TLS_CREATE_THREAD_SEC# | Creates a thread-level security environment for the caller's thread. If a thread-level security environment already exists, it is deleted before the new environment is created. |
TLS_DAEMON_THREAD_SEC# | Creates a thread-level security environment for the caller's thread without the need for a password if the caller has READ access to the BPX.DAEMON resource in the FACILITY class. |
TLS_DELETE_THREAD_SEC# | Deletes the thread-level security environment for the caller's thread, if one exists. If the security environment was created using the TLS_TASK_ACEE# option, only the POSIX security information is deleted; the task-level ACEE is left alone. |
TLS_TASK_ACEE# | Initializes the UNIX (POSIX) security data for a task that has an existing task-level security environment (task-level ACEE). If the UNIX security data already exists for the calling task, the existing UNIX security data is deleted, and a new set of UNIX security data is established. |
TLS_TASK_ACEE_USP# | Takes an existing USP from a task-level ACEE and extracts the UID and GID information. This information is then used to build a complete MVS™ and POSIX security environment for the caller's thread. |
Constant | Identity Format |
---|---|
TLS_IDENTITY_USERID# | The user identity is in the format of a 1-to-8-character user ID. |
TLS_IDENTITY_CERT# | The user identity is in the form of a certificate control block. |
If the identity type is specified as TLS_IDENTITY_USERID#, this area is the name of a field that contains the user identity in the specified format.
If the identity type is specified as TLS_IDENTITY_CERT#, this area is mapped by the BPXYOCRT macro (see BPXYOCRT — Map the OE certificate support structure).
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.
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 binary field that contains the pthread_security_np options. If no options are required, specify the name of a fullword field that contains 0.
The name of a fullword where the pthread_security_np service returns 0 if the request is successful, or -1 if it is not successful.
Return_code | Explanation |
---|---|
EACCES | Permission is denied; the specified password is incorrect. The following reason code can accompany the return code: JROK. |
EMVSEXPIRE | The password for the specified identity has expired. The following reason code can accompany the return code: JROK. |
EINVAL | One or more of the following conditions were detected:
The following reason codes can accompany the return code: JRTLSCertIDLenInvalid, JRTLSCertTypeInvalid, JRTLSCertLengthInvalid, JRTLSRequestInvalid, JRTLSIdTypeInvalid, JRTLSIdLengthInvalid, JRTLSAddressLengthInvalid, and JRBadOptions. |
EMVSERR | An MVS environmental error has been detected. The following reason codes can accompany the return code: JRTLSCallerIsIPT, JRSecActive, JRTLSNotDoneByOE, JRNoPtraceTaskSec, JRNotWLMACEE, JRUnexpectedError, JRTLSDoneOnIPT, JRNoTaskACEE, JRSAFNoUID, JRSAFNoGID, JRSAFNoUSER JRSAFGroupNoOMVS, JRSAFUserNoOMVS, JRUnexpectedError and JRSAFInternal. |
EPERM | One or more of the following conditions were detected:
|
EMVSSAF2ERR | An error occurred in the security product. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRCertInvalid, JRRACFBlankExits, JRSAFInternal, and JRSAFParmlistError. The reason code can also contain the RACF return and reason codes, respectively, in the two low-order bytes. For more information, see Table 1 and z/OS Security Server RACF Callable Services. |
EMVSSAFEXTRERR | The user's access was revoked. |
ENOSYS | The function is not supported on this system. The following reason code can accompany the return code: JRNoSecurityProduct. |
ESRCH | The identity that was specified is not defined to the security product. The following reason code can accompany the return code: JROK and JRNoCertForUser. |
The name of a fullword in which the pthread_security_np service stores the reason code. The pthread_security_np 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.
The permission checks are done on the first call to this service, and a successful result is remembered so that future calls to the service run faster. Therefore, revoking access to the BPX.SERVER profile in the FACILITY class does not stop a running server from continuing to create task-level security environments.
The contents of the password phrase string are passed unchanged to the installed security product.
The pthread_security_np service is restricted to users that have the appropriate privileges.
For an example using this callable service, see BPX1TLS (pthread_security_np) example.