__poe() (BPX1POE, BPX4POE) — Port of entry information

Function

The __poe() callable service specifies the port of entry information the system is to use in determining various levels of permission checking in a multilevel-secure system. The authorization that is required to invoke this service is one of the following:
  • Read access to the BPX.POE resource in the FACILITY class
  • A UID of 0 when the BPX.POE resource is not defined

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1POE): 31-bit
AMODE (BPX4POE): 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.

Format

CALL BPX1POE,(Poecb_length,
              Poecb,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4POE with the same parameters.

Parameters

Poecb_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword field that contains the length of the Poecb control block that is being passed in the next parameter. To determine the value of Poecb_length, use the BPXYPOE macro (BPXYPOE — Map poe syscall parameters).

Poecb
Supplied and returned parameter
Type:
Structure
Length:
Specified by the Poecb_length parameter

The name of a Poecb structure that is to be used to control this port of entry operation. See the section on the Poecb control block in the usage notes for details on setting the fields of the Poecb. The BPXYPOE macro (BPXYPOE — Map poe syscall parameters) maps the Poecb.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the __poe() service returns one of the following:
  • 0, if the request is successful.
  • -1, if the request is not successful.
Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the __poe() service stores the return code. The __poe() service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The __poe() service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINVAL The Poecb structure is incorrect. Consult Reason_code to determine the exact reason the error occurred. The following reason codes unique to the __poe() service can accompany the return code: JRPoeLenErr, JRPoeScopeErr, JRPoeEntryTypeErr, and JRPoeEntryLenErr.
EPERM The calling address space does not have the appropriate privileges to set the POE attributes.
EFAULT A bad address was received in the POEEntryPtr field of the BPXYPOE mapping that was pointed to by the Poecb parameter.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the __poe() service stores the reason code. The __poe() service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

  1. The ability to register port of entry is a privileged operation. An installation has two ways of allowing an application to use this service:
    1. For the highest level of security, the installation defines the BPX.POE resource in the FACILITY class. For an application to use this service, the user ID it runs under must be given read access to that resource.
    2. For a lower security arrangement, you can assign the user ID under which the application runs a UID of 0 so that it operates as a superuser.
  2. Poecb control block: When the POEEntryPtr field in the BPXYPOE mapping contains the address of a file descriptor, the caller must indicate in the POEEntryType field what type of file the file descriptor represents. The two supported file types are:
    • POE#EntrySocket — the file descriptor is for a socket file.
    • POE#EntryFile — the file descriptor is for a non-socket file. This includes the following file types:
      • Character special
      • FIFO
      • Regular
      • Symbolic link
      • Directory
    To clear the POE data that has been registered for a thread or process, specify the following data and options in the poecb and call the __poe() service.
    • POE#Attributes set to zeros (X'00'') or blanks (X'40'')
    • POE#ActionWrite
    • POE#ScopeProcess or POE#ScopeThread

    When the POE data for a process or thread has been cleared, that data will no longer be included in the search order that z/OS® UNIX services use to determine the POE data to be passed to RACF® when creating a security context. For example, when both process and thread POE data has been registered, the thread-level data would take precedence over the process data. Clearing the thread-level data would cause it to be skipped and the process level data would be used if available.

    POE#ScopeThread, POE#ScopeProcess and POE#ScopeSocket are mutually exclusive; only one must be specified. If none or more than one are specified the request will fail with –1/EINVAL/JRPoeScopeErr

    POE#ReadPOE, POE#WritePOE and POE#SetGetPOE are mutually exclusive. If more than one is specified the request will fail with EINVAL/JRPoeActionErr.

    If the POE#ReadPOE, POE#WritePOE or POE#SetGetPOE options are specified the storage obtained for the POE control block should be POE#LenV2 bytes in length. POE#LenV2 must be specified for the Poecb_length parameter on the BPX1POE syscall. If the length is incorrect the request will fail with -1/EINVAL/JrPOELenErr

    Table 1. Poecb control block
    POE options POE data Description
    Scope Action Source Destination
    Socket Read Socket or file descriptor POEAttributes area in the BPXYPOE mapping POE data is extracted from the file/socket descriptor supplied by the caller and returned to the caller via the BPXYPOE area. The caller's thread and process level POE data in the Oaob and Otcb is unchanged.
    Write n/a n/a Request fails with EINVAL/JrPoeSocketScopeErr
    SetGet n/a n/a Request fails with EINVAL/JrPoeSocketScopeErr
    None n/a n/a Request fails with EINVAL/JrPoeSocketScopeErr
    Process R Process level (OapbPOEAttrs) POEAttributes area in the BPXYPOE mapping Process level POE data copied from the Oapb is returned to the caller via the BPXYPOE area
    W POEAttributes area in the BPXYPOE mapping Process level (OapbPOEAttrs) POE data received from the caller in the BPXYPOE area is copied to the process level POE data in the Oapb
    SetGet Socket or file descriptor Process level (OapbPOEAttrs) and POEAttributes area in the BPXYPOE mapping POE data is extracted form the file/socket descriptor supplied by the caller. The data is copied to the process level POE data in the Oapb and returned to the caller via the BPXYPOE area
    None Socket or file descriptor Process level (OapbPOEAttrs) POE data is extracted from the file/socket descriptor supplied by the caller and copied to the process level POE data in the Oapb
    Thread R Thread level (OtcbPOEAttrs) POEAttributes area in the BPXYPOE mapping Thread level POE data copied from the Otcb is returned to the caller via the BPXYPOE area
    W POEAttributes area in the BPXYPOE mapping Thread level (OtcbPOEAttrs) POE data received from the caller in the BPXYPOE area is copied to the thread-level POE data in the Otcb
    SetGet Socket or file descriptor Thread level (OtcbPOEAttrs) and POEAttributes area in the BPXYPOE mapping POE data is extracted form the file/socket descriptor supplied by the caller. The data is copied to the thread-level POE data in the Otcb and returned to the caller via the BPXYPOE area
    None Socket or file descriptor Thread level (OtcbPOEAttrs) POE data is extracted from the file/socket descriptor supplied by the caller and copied to the thread-level POE data in the Otcb
  3. The POE data registered via the __poe() service is passed to RACF by z/OS UNIX services that create a new security context (ACEE). The z/OS UNIX services that utilize POE data are:
    • __passwd()
    • pthread_security_np()
    • __login()
    • setuid()/seteuid()/setreuid()
    • spawn (only with userid change)
  4. When z/OS UNIX services call RACF to build a new security context, POE data is passed to RACF using the following parameters for RACROUTE REQUEST=VERIFY ENVIR=CREATE
    Table 2. RACROUTE parameters for POE data
    POE data RACROUTE parameter
    POELabel SECLABL
    POEProfile SERVAUTH
    POETermid TERMID (1)
    (1) TERMID is only specified by the z/OS UNIX __passwd() and setuid()/seteuid()/setreuid() services.
    The amount and source of POE data passed to RACF varies based on the caller's environment.
    • When the caller's address space security label is non-SYSMULTI, only the SECLABL parameter is specified.
    • When the caller's address space security label is SYSMULTI, the following RACROUTE parameters are specified when the corresponding POE data is found in the search order. POE data from only one level will ever be specified. When valid POE data is found in the search order the search stops. For example, if a thread-level POELabel (SECLABL) is found the search will continue for POEProfile (SERVAUTH) and POETermid (TERMID) thread-level data but will not search at the process or address space level.
      • SECLABL
        1. Thread level (Otcb)
        2. Process level (Oapb)
        3. Address space seclabel (SYSMULTI)
      • SERVAUTH
        1. Thread level (Otcb)
        2. Process level (Oapb)
      • TERMID (only for the __passwd() and setuid(0/seteuid()/setreuid() services)
        1. Thread level (Otcb)
        2. Process level (Oapb)
  5. The Table 3 describes the POE data propagation for z/OS UNIX services that create a new process, a new process image (exec), or a new thread.
    Table 3. POE data propagation for z/OS UNIX services
    POE data propagation
    Service Thread POE data Process POE data
    fork() Yes Yes
    spawn() No Yes
    exec() No Yes
    pthread_create() No Yes (*)
    attach_exec() No Yes
    attach_execMVS() No Yes
    execMVS() No Yes
    * The newly created thread is in the same process as the thread calling pthread_create(). By default, process level POE data is shared between all thread in the process.

Characteristics and restrictions

The __poe() service is restricted to users that have the appropriate privileges, as defined under Function.

Examples

For an example using this callable service, see BPX1POE (__poe) example.