pthread_security_np, pthread_security_applid_np (BPX1TLS, BPX4TLS) — Create|delete thread-level security

Function

Requirements

Parameters

Function_code

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that specifies a numeric value that identifies the function that is to be performed. The following Function_code constants are defined by the BPXYCONS macro. See BPXYCONS — Constants used by services.

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.

Identity_Type

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that specifies a numeric value that identifies the format of the user identity that is provided in the Identity parameter. Constants are defined by the BPXYCONS macro. See BPXYCONS — Constants used by services.

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.

Identity_Length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the Identity. The specified length must be consistent with the allowable Identity types:

• USERID - 1 to 8 characters
• CERTIFICATE - the length of the constant OCRT_LEN, defined in the BPXYOCRT control block. See BPXYOCRT — Map the OE certificate support structure.

Identity

Supplied parameter

Type:

Character string or number, if using an identity type of USERID; structure, if using an identity type of CERTIFICATE.

Character set:

Not applicable for an identity type of CERTIFICATE. For an identity type of USERID, the XPG4 portable character set that includes upper and lower case letters (A-Z, a-z), numerics (0-9), period (.), dash (-), and underbar(_). In addition, the special characters $, %, and # may be specified. (Since these characters are not part of the XPG4 portable character set, however, the future possibility of program portability should be considered before using these characters.)

Length:

Specified by the Identity_Length parameter

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

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.

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.

Option_Flags

Supplied parameter

Type:

Structure

Length:

Fullword

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.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_security_np service stores the return code. The pthread_security_np service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The pthread_security_np service can return one of the following values in the Return_code parameter:

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 Function_Code that was specified is undefined. The Identity_Type that was specified is undefined. The Identity_Length that was specified was not valid for the Identity_Type. The Password_Length that was specified was not in the range 0 to 8. An undefined option flag was set. 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: The calling address space is not authorized to use this service. A password was not supplied and the RACF® SURROGAT class has not been activated; or no SURROGAT class profile has been defined for the specified user identity. A password was not supplied and the caller's address space does not have READ permission to the specified user identity's RACF SURROGAT class profile. A load from an unauthorized (not Program Control protected) library was done in the address space. The following reason codes can accompany the return code: JRNotServerAuthorized, JRSurrogateUndefined, JRNoSurrogatePerm, JRNoChangeIdentity, and JREnvDirty.
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.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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.

Usage notes

1. The ability to create a task-level security environment (ACEE) using the function codes TLS_CREATE_ THREAD_SEC# and TLS_DAEMON_THREAD_SEC# is a privileged operation. An installation has the following two ways of allowing an application to use this service with these two function codes:
   1. For the highest level of security, the installation defines the BPX.SERVER resource profile in the FACILITY class. For the application to access this service, it must be given read access to this profile. In addition, all load modules that are executing in the application's address space must be defined to RACF. See the section on establishing UNIX security in z/OS UNIX System Services Planning for more information about setting up this security.
   2. For a lower security arrangement, you can assign the user ID under which the application is run a UID of 0 so that it operates as a superuser.
2. When a task-level security environment is established, the other z/OS UNIX services are divided into two categories:
   • Services that are used to access data in the file system base the permission checks on the task-level security. Therefore, a function like open() will only work if the identity of the user in the task security environment has permission to the file. The pthread_security_np is very useful for creating a file server.
   • Services that tend to be process oriented continue to base the permission checking on the security identity of the process. Functions like kill only work if the process has permission to send the signal to the target process. The IPC functions of shared memory, message queues, and semaphores are also accessed with the security environment of the process.

   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.

3. If a thread with a task level security environment issues a spawn (non-local only), the child process is created with the identity of the thread. If a thread with a task level security environment issues a fork, the child process is created with the identity of the process.
4. Access to most MVS resources is based on the security identity of the thread.
5. Mixed case passwords and password phrases are supported when the installed security product (such as RACF) 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.

6. The specification of a Pass value is optional. The following are some examples of situations in which a server would want to create a task-level security environment without a Pass value:
   • Some servers allow access to a system with a user ID known as ANONYMOUS. The ANONYMOUS user ID is defined to the system with access to data available to the general public. It is up to the installation to define and manage an ANONYMOUS user ID so that integrity is not compromised.
   • Some servers are connected to global security servers. If other services are used to authenticate a user, it is not necessary to provide a Pass value to this service. It is up to the application and the installation to define the level of user authentication that is acceptable.
7. Debugging in this environment is only allowed for users with read permission to the BPX.DEBUG resource profile in the FACILITY class.
8. This service cannot be called from the Initial Pthread Task (IPT) with function code TLS_CREATE_THREAD_SEC#. The RTL performs certain process-related functions on the IPT that would be adversely affected by a task-level security environment.
9. If the user identity that is specified by the caller has been defined as a SURROGAT user ID (see Defining servers to process users without passwords in z/OS UNIX System Services Planning for details on how to define a SURROGAT user), and no password was specified, the task-level ACEE that is created for the calling thread has the CLIENT feature turned on. When RACF encounters a task-level ACEE with the CLIENT feature turned on, authority checking is done using both the task and process-level ACEEs. Both ACEEs must have permission to be able to access the resource.
10. If the identity type is TLS_IDENTITY_CERT#, the user ID is returned to the caller, filled in with the user ID that is associated with the certificate and ended with a null character.
11. If the function code specified is TLS_TASK_ACEE#, the values specified for the Identity_Type, Identity_Length, Identity, Pass_Length, Pass, and Option_Flags parameters are ignored. Because the user had the authority to create a task-level ACEE and attach it to the TCB, no additional credentials are necessary to redub the thread with the POSIX identity associated with the user ID of the task-level ACEE.
12. For the TLS_TASK_ACEE# and TLS_TASK_ACEE_USP# function codes to be used successfully, either the caller must be supervisor state and system key (0–7), or the ACEE for the calling task must have been created by WLM.
13. The POSIX identity established by a TLS_TASK_ACEE# can be deleted in one of three ways:
    • Issue another TLS_TASK_ACEE#. This deletes the old thread-level POSIX identity before establishing the new identity. This method fails, however, if the previous thread-level identity was not established by a previous TLS_TASK_ACEE#.
    • Issue a TLS_DELETE_THREAD_SEC#. This deletes the POSIX thread-level identity, and the thread takes on the POSIX identity of the process.
    • Issue a pthread_exit(). If the thread is heavyweight, the task terminates. If the thread is mediumweight, only the POSIX identity is cleaned up; the task-level MVS identity remains.
14. The pthread_security_applid_np() function is equivalent to pthread_security_np() with the added feature that it 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 is also used in conjunction with the USERID to verify the PassTicket.
    If an application is not using the pthread_security_applid_np() 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, the applid value defaults to OMVSAPPL.
15. If the calling task does not have a USP associated with the task-level ACEE, the kernel treats this call as if the TLS_TASK_ACEE# function was called. If a USP is present, the kernel initializes the thread security environment with the UIDs and GIDs of the USP (supp groups are not used). Calling the pthread_security_np service with TLS_DELETE_THREAD_SEC# will return the thread to its original state. It is up to the caller to delete the ACEE or USP and maintain the task's TCBSENV field.
16. If the caller's IPT task has previously called BPX1TLS to create a thread-level security environment, then calling BPX1TLS with TLS_TASK_ACEE# or TLS_TASK_ACEE_USP# function codes from a pthread will fail.
17. If the pthread_security_np service returns a Return_code of EMVSSAF2ERR and the TLS_TASK_ACEE_USP# function code was specified, then the Reason_code will contain the propagated Return_code and Reason_code from the IRRSGE00 service.
18. Using the TLS_DAEMON_THREAD_SEC# function code without specifying a password is similar to using the BPX.SRV.userid surrogate support. The difference is that the installation need not set up individual surrogate profiles for each client that desires a thread-level identity in the target server process. The server is allowed to create any identity without authentication as long as it has been given READ permission to the BPX.DAEMON resource in the FACILITY class.
19. When function code TLS_CREATE_THREAD_SEC# is specified without specifying a PASS parameter, a SURROGAT class check is made, ensuring the caller has access to the profile BPX.SRV.userid (where userid is the value specified on the IDENTITY parameter). If the userid portion of the profile name has blanks in it, then the RACROUTE REQUEST=AUTH results in ABEND282 RC5C. The dump is suppressed and the request fails with a return code of EMVSSAF2ERR and reason code of JrRACFBlankExists.
20. 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.
21. The pthread_security_np() will recognize and use the ICR passed if a previous __passwd() had been made that specified the same 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() and the preceding __passwd() must be identical.
    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.
22. 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

• oe_env_np (BPX1ENV, BPX4ENV) — Examine, change, or examine and change an environmental attribute
• getlogin (BPX1GLG, BPX4GLG) — Get the user login name

Characteristics and restrictions

The pthread_security_np service is restricted to users that have the appropriate privileges.