native-ipc-platform 0.4.0

Least-authority native OS capabilities and mappings for native-ipc
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

# native-ipc-platform

Least-authority native shared-memory mappings, authenticated capability
transfer, and owned helper lifecycles for
[`native-ipc`](https://crates.io/crates/native-ipc).

No kernel-portable primitive provides sealed, least-authority anonymous shared
memory: `memfd_create` and file seals exist only on Linux, macOS clamps rights
through Mach memory entries, and Windows through exact-access duplicated
section handles. This crate implements one capability policy on each kernel's
own mechanism so callers never touch the divergent native APIs.

Supported targets:

- Linux ARM64/AMD64: sealed `memfd`, `SCM_RIGHTS`, `SO_PEERCRED`, and pidfds.
- macOS ARM64: typed Mach memory entries and audit-token PID authentication.
- Windows ARM64/AMD64: least-rights unnamed sections, PID-checked private
  pipes, held process handles, and kill-on-close Job Objects.

## Transaction invariant

Every transfer is a consuming transaction:

```text
CAPABILITY -> READY -> COMMIT -> runtime ReaderRegion / WriterRegion
```

`CAPABILITY` transfers native rights and a canonical manifest. The peer maps
and validates every region into pending values with no payload API. `READY`
confirms the exact batch, and `COMMIT` activates both endpoints atomically.
Runtime mappings cannot be obtained through an independent safe `bind`.

The manifest binds the control version, nonce, authenticated parent/child PIDs,
session-unique transfer ID, canonical role order, schema, generation, writer
endpoint, peer access, and exact page-rounded length. Control methods require
exclusive mutable channel access so transactions cannot interleave.

## API flow

The runnable [`ready_commit` example](https://github.com/ro-ag/native-ipc-rs/blob/main/crates/native-ipc-platform/examples/ready_commit.rs)
shows the consuming API signatures for every backend. Full native helper
fixtures live beside each backend because capability transfer requires two
authenticated processes.

Linux creator and peer:

```text
QuiescentRegion::prepare_writer
  -> AuthenticatedChannel::transfer_writer
  -> WriterRegion (only after COMMIT)

AuthenticatedChannel::receive_reader
  -> pending validated reader internally
  -> ReaderRegion (only after COMMIT)
```

macOS and Windows build both directional pending mappings, then commit the
whole batch with `commit_transfers` / `commit_imports`.

See also the runnable
[`quiescent_region` example](https://github.com/ro-ag/native-ipc-rs/blob/main/crates/native-ipc-platform/examples/quiescent_region.rs).

Licensed under MIT or Apache-2.0.