1Mach IPC Port Types 2========================== 3 4This document is not a tutorial on or encouragement to write new mach code, but 5serves as documentation for darwin engineers to map security policies to ports 6used in the lower layers of the OS. See the warning/disclaimer at 7https://at.apple.com/dont_write_new_mach_code and come talk to us in 8#help-darwin before using the knowledge contained here. 9 10# Port Types 11A port can have exactly one of the following types, and we describe what each 12port means from the userspace perspective, including what you are/aren't allowed 13to do with a particular port and how to construct it. The source of truth for 14security policies in the kernel is the `ipc_policy_array` in `ipc_policy.c` 15 16### IOT_PORT_SET 17#### Creation 18- `mach_port_allocate(... MACH_PORT_RIGHT_PORT_SET ...)` 19#### Behavior/Usage 20- Allows you to monitor an entire set of ports for messages at once, similar to 21`select(2)` 22#### Security Restrictions 23- No special security restrictions on this port 24 25### IOT_PORT 26#### Creation 27- Your standard port that you obtain through the port allocation APIs if you 28don't pass any special flags. 29#### Behavior/Usage 30- Sends traditional mach messages and is generally associated with "raw mach" - 31new code generally should not use these. 32#### Security Restrictions 33- No special security restrictions on this port 34 35### IOT_SERVICE_PORT 36#### Creation 37- pass `MPO_SERVICE_PORT` to `mach_port_construct` 38#### Behavior/Usage 39- Used by `launchd` as the port which drives the launch-on-demand behavior of 40services/daemons on the system. Clients lookup the service port for some service 41using `bootstrap_lookup` and then can form a connection with that service. - 42`launchd` reclaims these ports when the process owning the service port is 43killed so that the service port is always active. 44#### Security Restrictions 45- This is the "hardened" version of the service port which has various security 46policies such as immovabile receive right and enforced reply port semantics. - 47`launchd` enforces that all platform binary services use this version of the 48service port (as opposed to the `WEAK` version below), and allows third parties 49to opt into this following the completion of rdar://137633308. See the `launchd` 50documentation for more details about how to opt into this restriction - The 51kernel will enforce that platform restrictions binaries receive this version of the service 52port following completion of rdar://133304899. 53 54### IOT_WEAK_SERVICE_PORT 55#### Creation 56- pass `MPO_WEAK_SERVICE_PORT` to `mach_port_construct` 57#### Behavior/Usage 58- Same feature set and usage as `IOT_SERVICE_PORT` above, the only difference is 59the associated security policy. 60#### Security Restrictions 61- No security hardening. Launchd entirely controls which processes get the weak 62vs. "strong" service ports, and the kernel will eventually enforce that launchd 63has created the right kind of port for hardened processes. See `launchd` 64documentation for more info. 65 66### IOT_CONNECTION_PORT 67#### Creation 68- pass `MPO_CONNECTION_PORT` to `mach_port_construct` 69#### Behavior/Usage 70- A connection port models an established connection between two parties, 71commonly between a client and a service, but it's also generalizable to peer 72connections. 73#### Security Restrictions 74- We assume that the handshake mechanism to create the connection between these 75two parties is sufficiently hardened, so the security boundary we want to 76protect here is that the connection and its replies are contained between the 77two parties. To accomplish this the connection port is marked as immovable 78receive and requires reply port semantics, both of which combined kills man in 79the middle attacks at this layer. 80 81### IOT_CONNECTION_PORT_WITH_PORT_ARRAY 82#### Creation 83- pass `MPO_CONNECTION_PORT_WITH_PORT_ARRAY` to `mach_port_construct` 84#### Behavior/Usage 85- Serves as a connection port, however does not have the mechanics/behaviors 86of `IOT_CONNECTION_PORT`. Unlike other port types, this type is allowed to 87receive out-of-line port array descriptors (`MACH_MSG_OOL_PORTS_DESCRIPTOR`) 88in platform binaries. For enhanced security v2, it's the only port type that 89is allowed to receive `MACH_MSG_OOL_PORTS_DESCRIPTOR`. 90- In addition to that, we enforce the following restrictions on messages with 91`MACH_MSG_OOL_PORTS_DESCRIPTOR` descriptor (also, only for platform binaries): 92 1. a message cannot carry more than ONE single OOL port array. 93 2. the only allowed disposition is `MACH_MSG_TYPE_COPY_SEND`. 94 95#### Security Restrictions 96- Can only be created by binaries that have the 97`com.apple.developer.allow-connection-port-with-port-array` entitlement. 98 99### IOT_EXCEPTION_PORT 100#### Creation 101- pass `MPO_EXCEPTION_PORT` to `mach_port_construct` 102#### Behavior/Usage 103- Used in mach exception handling, if you have the entitlement 104`com.apple.security.only-one-exception-port` then you must use the 105`task_register_hardened_exception_handler` workflow which only accepts this type 106of port. Otherwise the historical, non-hardened exception handling workflow 107using `task_set_exception_ports` accepts either a standard `IOT_PORT` or an 108`IOT_EXCEPTION_PORT`. 109#### Security Restrictions 110- This port must be immovable receive when using the hardened exception flow to 111ensure that exceptions cannot be diverted and handled/stalled outside of the 112process generating them. 113 114## Reply Ports 115- If your port type requires reply port semantics, then you must use one of the 116following reply port types as the reply field (`msgh_local_port`) when sending a 117message to `p`. See [reply port 118defense](ipc_security_concepts.md#reply-port-defense) for more details. 119 120### IOT_REPLY_PORT 121#### Creation 122- pass `MPO_REPLY_PORT` to `mach_port_construct` 123#### Behavior/Usage 124- A reply port exists in your space, and you use it to receive replies from 125clients in response to messages that you send them. It's intended to model 126synchronous IPC where you send a message to a peer and expect a single message 127in response. 128#### Security Restrictions 129- Reply ports guarantee that a reply comes back to you from the person you are 130messaging - in other words, it counters person-in-the-middle attacks. It 131accomplishes this by using send-once rights to ensure that *exactly* one reply 132from the destination will come back to your reply port, which is marked as 133immovable receive, and the send right must be a make-send-once so that it cannot 134be moved after its creation. 135 136### IOT_SPECIAL_REPLY_PORT 137#### Creation 138- Created by the kernel: libxpc and dispatch call into 139`thread_get_special_reply_port` to obtain the send/receive right for this 140thread-specific port. 141#### Behavior/Usage 142- Has the same properties as a reply port above, but this is used by libxpc and 143dispatch to provide turnstile/importance inheritance capabilities. 144#### Security Restrictions 145- same as reply ports above 146 147### IOT_PROVISIONAL_REPLY_PORT 148#### Creation 149- pass `MPO_PROVISIONAL_REPLY_PORT` to `mach_port_construct` 150#### Behavior/Usage 151- This has the mechanics of a normal `IOT_PORT` in that it has no special 152behaviors/usage/restrictions, but it counts as reply port for the purposes of 153enforced reply port semantics. 154#### Security Restrictions 155- None, this requires special entitlements in platform restrictions binaries. 156 157# Violations of Port Security Policies 158 159If you violate the security policies outlined above, expect to receive a 160`mach_port_exc_guard` exception, which will either emit telemetry or fatally 161crash your process depending on the enforcement level of the security violation. 162See [List of fatal Mach IPC guard 163exceptions](guard_exceptions.md#List-of-fatal-Mach-Port-Guard-Exceptions) or 164at.apple.com/exc-guard for more details. 165