# strangebit-io/hip-vpls architecture

> Architecture diagram of the GitHub repository strangebit-io/hip-vpls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strangebit-io/hip-vpls
- Repository: https://github.com/strangebit-io/hip-vpls

## Overview

HIP-VPLS provides a HIP control plane that establishes authenticated associations between routers, then carries customer LAN traffic across a virtual private LAN. The documented kernel-mode path keeps base exchange and key derivation in Python while Linux bridge/gretap forwarding and XFRM ESP handle customer frames; Python thread/process forwarding remains a fallback. The four router trees appear to be per-router copies, so paths below use router1 as the representative implementation. Unsampled modules are included where the README or source index establishes their role; uncertain internal wiring is omitted.

Main entry points: [`router1/hiplib/hlib.py`](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/hlib.py) (HIP Exchange), [`router1/switchd.py`](https://github.com/strangebit-io/hip-vpls/blob/main/router1/switchd.py) (Router Daemon), [`router1/hiplib/dataplane_mp.py`](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/dataplane_mp.py) (Python Forwarder), [`router1/hiplib/network/xfrm.py`](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/network/xfrm.py) (XFRM ESP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["HIP Control Plane"]
  node_switchd["Router Daemon<br/>[switchd.py]"]
  node_hip["HIP Exchange<br/>[hlib.py]"]
  node_hipwire["HIP Messages<br/>[HIP.py]"]
  node_ctrlwire["Controller Messages<br/>[Controller.py]"]
  node_config["Router Config<br/>[config.py]"]
  node_state[("HIP State<br/>[HIPState.py]")]
  node_firewall[("Firewall Rules<br/>[Firewall.py]")]
  node_sa[("Security Associations<br/>[SA.py]")]
end

subgraph group_identity["Identity and Crypto"]
  node_identity["Host Identity<br/>[hi.py]"]
  node_hit["HIT Utilities<br/>[hit.py]"]
  node_crypto["Crypto Algorithms<br/>[asymmetric.py]"]
  node_crypto_factory["Crypto Selection<br/>[factory.py]"]
  node_key_utils["Key Derivation<br/>[misc.py]"]
end

subgraph group_kernel["Kernel Data Plane"]
  node_bridge["Linux Bridge<br/>[xfrm.py]"]
  node_esp["XFRM ESP<br/>[xfrm.py]"]
  node_fabric["Switch Fabric<br/>[switchfabric.py]"]
end

subgraph group_python["Python Data Plane"]
  node_ip_frames["IP Packet Models<br/>[IPv4.py]"]
  node_ipv6_frames["IPv6 Packet Model<br/>[IPv6.py]"]
  node_esp_packet["ESP Packet Model<br/>[IPSec.py]"]
  node_python_dp["Python Forwarder<br/>[dataplane_mp.py]"]
end

node_host(("LAN Hosts"))

node_switchd -->|"starts control"| node_hip
node_switchd -->|"loads settings"| node_config
node_switchd -->|"configures fabric"| node_fabric
node_switchd -->|"selects fallback"| node_python_dp
node_switchd -->|"configures kernel mode"| node_esp
node_hip -->|"builds messages"| node_hipwire
node_hip -->|"validates identity"| node_identity
node_hip -->|"checks HITs"| node_hit
node_hip -->|"selects algorithms"| node_crypto_factory
node_crypto_factory -->|"selects primitives"| node_crypto
node_hip -->|"derives key material"| node_key_utils
node_hip -->|"installs derived keys"| node_esp
node_host -->|"sends LAN frames"| node_bridge
node_bridge -->|"protects tunnel traffic"| node_esp
node_hip -.->|"tracks exchange state"| node_state
node_hip -.->|"maintains associations"| node_sa
node_switchd -.->|"loads firewall rules"| node_firewall
node_python_dp -.->|"handles IP packets"| node_ip_frames
node_python_dp -.->|"handles IPv6 packets"| node_ipv6_frames
node_python_dp -.->|"handles ESP packets"| node_esp_packet

click node_switchd "https://github.com/strangebit-io/hip-vpls/blob/main/router1/switchd.py"
click node_hip "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/hlib.py"
click node_hipwire "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/HIP.py"
click node_ctrlwire "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/Controller.py"
click node_config "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/config/config.py"
click node_state "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/databases/HIPState.py"
click node_firewall "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/databases/Firewall.py"
click node_sa "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/databases/SA.py"
click node_identity "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/utils/hi.py"
click node_hit "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/utils/hit.py"
click node_crypto "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/crypto/asymmetric.py"
click node_crypto_factory "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/crypto/factory.py"
click node_key_utils "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/utils/misc.py"
click node_bridge "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/network/xfrm.py"
click node_esp "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/network/xfrm.py"
click node_ip_frames "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/IPv4.py"
click node_ipv6_frames "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/IPv6.py"
click node_esp_packet "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/IPSec.py"
click node_python_dp "https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/dataplane_mp.py"
click node_fabric "https://github.com/strangebit-io/hip-vpls/blob/main/router1/switchfabric.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_switchd,node_hip,node_hipwire,node_ctrlwire,node_config,node_state,node_firewall,node_sa toneBlue
class node_identity,node_hit,node_crypto,node_crypto_factory,node_key_utils toneAmber
class node_bridge,node_esp,node_fabric toneMint
class node_ip_frames,node_ipv6_frames,node_esp_packet,node_python_dp toneRose
class node_host toneIndigo
```

## Components

### HIP Control Plane

- [Router Daemon](https://github.com/strangebit-io/hip-vpls/blob/main/router1/switchd.py): `router1/switchd.py`
- [HIP Exchange](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/hlib.py): `router1/hiplib/hlib.py`
- [HIP Messages](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/HIP.py): `router1/hiplib/packets/HIP.py`
- [Controller Messages](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/Controller.py): `router1/hiplib/packets/Controller.py`
- [Router Config](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/config/config.py): `router1/hiplib/config/config.py`
- [HIP State](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/databases/HIPState.py): `router1/hiplib/databases/HIPState.py`
- [Firewall Rules](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/databases/Firewall.py): `router1/hiplib/databases/Firewall.py`
- [Security Associations](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/databases/SA.py): `router1/hiplib/databases/SA.py`

### Identity and Crypto

- [Host Identity](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/utils/hi.py): `router1/hiplib/utils/hi.py`
- [HIT Utilities](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/utils/hit.py): `router1/hiplib/utils/hit.py`
- [Crypto Algorithms](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/crypto/asymmetric.py): `router1/hiplib/crypto/asymmetric.py`
- [Crypto Selection](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/crypto/factory.py): `router1/hiplib/crypto/factory.py`
- [Key Derivation](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/utils/misc.py): `router1/hiplib/utils/misc.py`

### Kernel Data Plane

- [Linux Bridge](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/network/xfrm.py): `router1/hiplib/network/xfrm.py`
- [XFRM ESP](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/network/xfrm.py): `router1/hiplib/network/xfrm.py`
- [Switch Fabric](https://github.com/strangebit-io/hip-vpls/blob/main/router1/switchfabric.py): `router1/switchfabric.py`

### Python Data Plane

- [IP Packet Models](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/IPv4.py): `router1/hiplib/packets/IPv4.py`
- [IPv6 Packet Model](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/IPv6.py): `router1/hiplib/packets/IPv6.py`
- [ESP Packet Model](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/packets/IPSec.py): `router1/hiplib/packets/IPSec.py`
- [Python Forwarder](https://github.com/strangebit-io/hip-vpls/blob/main/router1/hiplib/dataplane_mp.py): `router1/hiplib/dataplane_mp.py`

### Other components

- **LAN Hosts**

## Connections

- Router Daemon → HIP Exchange: starts control (evidence: `router1/switchd.py`)
- Router Daemon → Router Config: loads settings (evidence: `router1/switchd.py`)
- Router Daemon → Switch Fabric: configures fabric (evidence: `router1/switchd.py`)
- Router Daemon → Python Forwarder: selects fallback (evidence: `router1/switchd.py`)
- Router Daemon → XFRM ESP: configures kernel mode (evidence: `router1/switchd.py`)
- HIP Exchange → HIP Messages: builds messages (evidence: `router1/hiplib/hlib.py`)
- HIP Exchange → Host Identity: validates identity (evidence: `router1/hiplib/hlib.py`)
- HIP Exchange → HIT Utilities: checks HITs (evidence: `router1/hiplib/hlib.py`)
- HIP Exchange → Crypto Selection: selects algorithms (evidence: `router1/hiplib/hlib.py`)
- Crypto Selection → Crypto Algorithms: selects primitives (evidence: `router1/hiplib/crypto/factory.py`)
- HIP Exchange → Key Derivation: derives key material (evidence: `router1/hiplib/hlib.py`)
- HIP Exchange → XFRM ESP: installs derived keys (evidence: `router1/hiplib/hlib.py`)
- LAN Hosts → Linux Bridge: sends LAN frames
- Linux Bridge → XFRM ESP: protects tunnel traffic (evidence: `router1/hiplib/network/xfrm.py`)
- HIP Exchange → HIP State: tracks exchange state (evidence: `router1/hiplib/hlib.py`)
- HIP Exchange → Security Associations: maintains associations (evidence: `router1/hiplib/hlib.py`)
- Router Daemon → Firewall Rules: loads firewall rules
- Python Forwarder → IP Packet Models: handles IP packets
- Python Forwarder → IPv6 Packet Model: handles IPv6 packets
- Python Forwarder → ESP Packet Model: handles ESP packets