Networking and data planes

SpaceOS gives each service only the interfaces declared in build.yaml. Interface declarations are part of the signed launch material. The runtime uses them to configure the service and to enforce network policy.

Interface	Carries	Policy input	Runtime check
IP	Application IP traffic	Named bridges	The requested bridges must be allowed by the admitted policy.
Frame bus	Fixed-size telemetry and command frames	APID range and send_to list	space-net checks the source APID and the destination service.
Supervision page	Heartbeat, health, mission time, and host commands	supervision_page declaration	The host treats guest-written fields as untrusted and reads them through bounded accessors.

The frame bus and supervision page are separate. A stalled frame bus does not prevent the host from reading the service heartbeat.

Declare service interfaces

Declare interfaces on each service in build.yaml:

schema: space.build
version: "1"
kernel: linuxkit/kernel:6.6.13
output: _build/spaceos

partitions:
  payload:
    services:
      - name: classifier
        image: ghcr.io/<your-org>/classifier:1
        runtime: oci
        isolation: runc
        interfaces:
          - type: ip
            bridges: [payload-net]
          - type: frame_bus
            apids: [0x120, 0x12F]
            send_to: [sdls-downlink]
          - type: supervision_page
      - name: sdls-downlink
        image: ghcr.io/parsimoni-labs/sdls-downlink:1
        runtime: oci
        isolation: runc
        interfaces:
          - type: frame_bus
            apids: [0x130, 0x13F]

Build the composition after changing an interface declaration:

$ space build build.yaml -t <your-registry>/payload:dev

See the build.yaml reference for the complete interface syntax.

IP interfaces

An ip interface lists the bridges the service may join. Bridge names are policy labels, not credentials. The runner rejects a bridge that is outside the admitted bridge budget.

A service with no ip interface has no declared IP bridge. The host_network interface is a separate capability for a runc service. It lists the TCP ports the service may bind in the node network namespace. A service cannot combine host_network with an ip bridge.

Do not use an IP address as service identity. Network policy is derived from the admitted service and interface declarations.

Frame bus

A frame_bus interface contains two fields:

• apids is one inclusive range written as [low, high].
• send_to is the default-deny list of local services this service may reach.

Each service on the frame bus gets its own Unix socket. The service does not choose the identity attached to that socket. space-net uses that identity to check the source APID and the destination allow-list.

Frames use the 256-byte space-wire message format. APIDs identify streams and route frames. They are not authentication credentials.

Ground relay

The relay sends frames between one source partition, other partitions, and the reserved ground destination. It also applies a token-bucket rate limit and a bounded egress queue.

The SDLS relay authenticates frames and checks the anti-replay sequence number. The association names its authentication suite, aes-256-cmac or hmac-sha-256, and the relay opens it with authentication enabled and encryption disabled. It does not encrypt frame payloads.

WIP: association key required on every launch

An authenticated relay requires an association key, and a flight release supplies one. A local development launch can still come up without that key being demanded of it, so a bench run is not evidence that the association was authenticated. Read a local run as a functional test of the frame path and take authentication evidence from a deployed target instead.

Supervision page

The supervision page is a 4096-byte shared-memory page between a service and the host runner.

The guest writes:

• a heartbeat counter;
• a status word;
• a bounded health string;
• acknowledgements for host commands.

The host writes:

• the heartbeat acknowledgement;
• mission time under a seqlock;
• the host command word.

The split is a protocol convention. A compromised guest can write any byte in the page. The runner therefore treats all guest fields as untrusted. It bounds the health string, reads status words as unsigned values, and compares heartbeat progress only with the host clock.

The runner reports a service as wedged when its heartbeat stops advancing past the configured timeout. A fresh heartbeat returns it to the alive state.

Ground transport security

The ground path uses separate transport and security layers:

• CFDP Class 2 handles acknowledged object transfer.
• BPv7 carries bundles over intermittent links.
• BPSec authenticates bundle payloads with a Block Integrity Block (BIB).
• SDLS authenticates frames on the relay association.

The BPSec receiver refuses an unprotected payload, a wrong key, insufficient integrity scope, a replayed bundle, and a bundle outside its acceptance window. The outgoing producer currently adds a BIB. It does not add a Block Confidentiality Block (BCB).

WIP: payload confidentiality

Neither the BPSec producer nor the SDLS relay encrypts payload data, and no setting turns encryption on. Do not treat either as a confidentiality boundary. What works today is integrity and source authentication end to end: a receiver refuses a modified, replayed or wrong-key bundle or frame. Encrypt sensitive payloads in your own application, above SpaceOS, until this row changes.

Network access does not authorize a workload or command. Software admission is a separate verification path.