network.html 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336
  1. <!doctype html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Networking | NebOS Architecture</title>
  7. <meta name="description" content="NebOS networking: the netdev registry and NIC drivers, ARP/ICMP/UDP, DHCP, DNS, the TCP client and listener, TLS 1.3, sys_net ownership, netconsole and netkexec.">
  8. <link rel="icon" href="favicon.svg" type="image/svg+xml">
  9. <link rel="stylesheet" href="style.css">
  10. </head>
  11. <body>
  12. <a class="skip" href="#main">Skip to content</a>
  13. <header class="site-header">
  14. <a class="brand" href="index.html">
  15. <span class="brand-mark" aria-hidden="true"></span>
  16. <span>NebOS <span class="brand-sub">Architecture</span></span>
  17. </a>
  18. <nav class="site-nav" aria-label="Architecture sections">
  19. <a href="index.html">Overview</a>
  20. <a href="boot.html">Boot</a>
  21. <a href="memory.html">Memory</a>
  22. <a href="cpu.html">CPU</a>
  23. <a href="drivers.html">Drivers</a>
  24. <a href="filesystems.html">Filesystems</a>
  25. <a href="graphics.html">Graphics</a>
  26. <a href="network.html" aria-current="page">Network</a>
  27. <a href="userland.html">Userland</a>
  28. <a href="development.html">Development</a>
  29. </nav>
  30. </header>
  31. <main id="main" class="page">
  32. <div class="page-head">
  33. <p class="kicker">Networking</p>
  34. <h1>A small stack with one receiver owner.</h1>
  35. <p class="lede">
  36. The NIC and the protocol stack live in the kernel; ring-3 commands
  37. drive them through <code>SYS_NET_*</code> and <code>SYS_TCP_*</code>.
  38. Only one process may own the receiver at a time, which keeps the
  39. polled drivers and the single TCP connection simple.
  40. </p>
  41. <div class="meta">
  42. <span class="pill">ARP · ICMP · UDP · TCP</span>
  43. <span class="pill">DHCP · DNS</span>
  44. <span class="pill">TLS 1.3 · X25519</span>
  45. <span class="pill">netconsole + netkexec</span>
  46. </div>
  47. </div>
  48. <nav class="toc" aria-label="On this page">
  49. <h2>On this page</h2>
  50. <ul>
  51. <li><a href="#stack">Protocol stack</a></li>
  52. <li><a href="#netdev">NIC drivers</a></li>
  53. <li><a href="#core">Link &amp; IP layer</a></li>
  54. <li><a href="#dhcp">DHCP &amp; DNS</a></li>
  55. <li><a href="#tcp">TCP</a></li>
  56. <li><a href="#tls">TLS</a></li>
  57. <li><a href="#abi">sys_net ABI</a></li>
  58. <li><a href="#console">Netconsole &amp; netkexec</a></li>
  59. <li><a href="#http">HTTP clients</a></li>
  60. <li><a href="#security">Security posture</a></li>
  61. <li><a href="#sources">Source map</a></li>
  62. </ul>
  63. </nav>
  64. <section id="stack">
  65. <h2>Protocol stack</h2>
  66. <p>
  67. NebOS does not expose sockets. A ring-3 program asks the kernel for
  68. info and configuration, acquires the receiver, then uses raw frame
  69. paths or the single TCP connection. HTTP and TLS are libraries linked
  70. into the command, not kernel services.
  71. </p>
  72. <figure class="figure">
  73. <svg viewBox="0 0 920 380" role="img" aria-labelledby="net-title net-desc">
  74. <title id="net-title">NebOS network stack</title>
  75. <desc id="net-desc">Ring-3 curl, browser and websrv use uhttp and TLS, then sys_net syscalls, then TCP/DNS/DHCP, IPv4/ARP/ICMP, netdev drivers and the NIC.</desc>
  76. <rect class="svg-box accent" x="70" y="18" width="780" height="58" rx="9"/>
  77. <text class="svg-text" x="92" y="43">curl · browser · websrv · ping · dhcp</text>
  78. <text class="svg-sub" x="92" y="63">ring-3 programs</text>
  79. <path class="svg-line" d="M460 76v20"/>
  80. <path class="svg-line" d="M454 90l6 7 6-7"/>
  81. <rect class="svg-box blue" x="70" y="98" width="380" height="58" rx="9"/>
  82. <text class="svg-text" x="92" y="123">uhttp · tls.c</text>
  83. <text class="svg-sub" x="92" y="143">HTTP/1.1 · redirects · chunked · TLS 1.3</text>
  84. <rect class="svg-box" x="470" y="98" width="380" height="58" rx="9"/>
  85. <text class="svg-text" x="492" y="123">kernel services</text>
  86. <text class="svg-sub" x="492" y="143">sys_fs for WebDAV · netlog · netkexec</text>
  87. <path class="svg-line blue" d="M260 156v18"/>
  88. <path class="svg-line blue" d="M254 168l6 7 6-7"/>
  89. <path class="svg-line" d="M660 156v18"/>
  90. <path class="svg-line" d="M654 168l6 7 6-7"/>
  91. <rect class="svg-box green" x="70" y="176" width="780" height="58" rx="9"/>
  92. <text class="svg-text" x="92" y="201">SYS_NET_* · SYS_TCP_* · SYS_DNS_RESOLVE · SYS_DHCP_RUN</text>
  93. <text class="svg-sub" x="92" y="221">one receiver owner · interrupt-enabled waits</text>
  94. <path class="svg-line green" d="M460 234v20"/>
  95. <path class="svg-line green" d="M454 248l6 7 6-7"/>
  96. <rect class="svg-box" x="70" y="256" width="780" height="58" rx="9"/>
  97. <text class="svg-text" x="92" y="281">tcp.c · dns.c · dhcp.c</text>
  98. <text class="svg-sub" x="92" y="301">TCP client + listener · one A query · DISCOVER/OFFER/REQUEST/ACK</text>
  99. <path class="svg-line" d="M460 314v16"/>
  100. <path class="svg-line" d="M454 324l6 7 6-7"/>
  101. <rect class="svg-box blue" x="70" y="332" width="780" height="44" rx="9"/>
  102. <text class="svg-text" x="92" y="359">IPv4 · ARP · ICMP · UDP · netdev registry · NIC driver</text>
  103. </svg>
  104. <figcaption>
  105. <strong>Thin kernel, thick command.</strong> The kernel owns
  106. addressing, ARP, routing and the single TCP connection. HTTP, TLS
  107. and WebDAV run in ring 3, so a protocol bug kills a command rather
  108. than the kernel.
  109. </figcaption>
  110. </figure>
  111. </section>
  112. <section id="netdev">
  113. <h2>NIC drivers</h2>
  114. <p>
  115. <span class="file">netdev.c</span> keeps a registry of
  116. <code>struct netdev</code> drivers; the first one whose probe succeeds
  117. becomes active. All drivers are polled and share the same transmit,
  118. receive, register-dump and reset interface. <code>netdev</code> with
  119. no argument shows the active driver; <code>netdev asix</code> switches
  120. to a named one, leaving the current driver untouched if the probe
  121. fails.
  122. </p>
  123. <div class="table-wrap">
  124. <table>
  125. <thead>
  126. <tr><th>Driver</th><th>Hardware</th><th>Transport</th><th>Notes</th></tr>
  127. </thead>
  128. <tbody>
  129. <tr><td><span class="file">e1000e.c</span></td><td>Intel 82540EM, 82577LM, 82578, 82579</td><td>PCI MMIO</td><td>PCI INTx disabled before MMIO; PCH D0; skips the global MAC reset while the link is up.</td></tr>
  130. <tr><td><span class="file">r8168.c</span></td><td>RTL8111/8168</td><td>PCIe MMIO</td><td>C+ mode, 64-entry RX ring, polled.</td></tr>
  131. <tr><td><span class="file">ne2000.c</span></td><td>RTL8029</td><td>ISA / QEMU PCI</td><td>Simple DP8390 path used by <code>make run-net</code>.</td></tr>
  132. <tr><td><span class="file">asix.c</span></td><td>AX88772</td><td>USB bulk</td><td>Runs over the USB core; usable on EHCI/xHCI dongles.</td></tr>
  133. </tbody>
  134. </table>
  135. </div>
  136. <p>
  137. The management NIC used by netlog and netkexec prefers the ASIX dongle
  138. so a direct debug link survives <code>netdev e1000e</code>; otherwise
  139. it falls back to the active driver. <code>netregs</code> dumps registers
  140. and decoded interrupt status; <code>netloop</code> runs a PHY loopback
  141. self-test; <code>netreset</code> re-initialises the active NIC.
  142. </p>
  143. </section>
  144. <section id="core">
  145. <h2>Link &amp; IP layer</h2>
  146. <ul>
  147. <li><strong>Ethernet decode</strong> recognises IPv4, ARP and IPv6 frame types (IPv6 is not implemented).</li>
  148. <li><strong>ARP</strong> resolves a next hop with three tries, one second apart; <code>net_arp_resolve()</code> polls the active NIC and the caller must own it.</li>
  149. <li><strong>Routing</strong> sends off-subnet traffic to the gateway when one is known; <code>net_next_hop()</code> is shared by ping, DNS and TCP.</li>
  150. <li><strong>ICMP echo</strong> backs <code>ping</code>, with ARP resolution and round-trip timing.</li>
  151. <li><strong>UDP</strong> has send and parse helpers; DNS, DHCP and netlog are its users.</li>
  152. <li><strong>Checksums</strong> use the Internet one's-complement sum, with a TCP pseudo-header variant.</li>
  153. </ul>
  154. <p>
  155. The static default address is <code>192.168.178.240</code>. At boot,
  156. with a NIC present, a DHCP client runs with a 4-second budget
  157. (requesting the current address); if no server answers, the static
  158. address stays. The idle WM loop answers ARP/ICMP for the board's IP
  159. even when no command is running, so the board is reachable and
  160. MAC-resolvable.
  161. </p>
  162. </section>
  163. <section id="dhcp">
  164. <h2>DHCP &amp; DNS</h2>
  165. <h3>DHCP</h3>
  166. <p>
  167. <span class="file">dhcp.c</span> is a minimal client:
  168. DISCOVER → OFFER → REQUEST → ACK. It learns the mask, gateway and DNS
  169. server (option 6), and <code>dhcp</code> re-runs it on demand. The
  170. configuration is retained across kexec through the boot-info
  171. <code>BOOTINFO_FLAG_NET</code> fields.
  172. </p>
  173. <h3>DNS</h3>
  174. <p>
  175. <span class="file">dns.c</span> sends one recursive A query over UDP
  176. and handles name compression in the response. <code>netdns</code>
  177. shows or sets the server; <code>host &lt;name&gt;</code> resolves.
  178. Numeric hosts skip DNS entirely.
  179. </p>
  180. </section>
  181. <section id="tcp">
  182. <h2>TCP</h2>
  183. <p>
  184. <span class="file">tcp.c</span> deliberately implements one client
  185. connection, not a general socket layer: connect, send, receive and
  186. close. An 8 KB receive queue lets data arriving during a send survive;
  187. the window update is sent whenever the application drains the queue,
  188. so a full queue cannot deadlock until the peer's zero-window probe.
  189. </p>
  190. <ul>
  191. <li><strong>MSS / window.</strong> Our MSS is 1460 bytes and the advertised window is 4 KB.</li>
  192. <li><strong>Retransmit.</strong> A 500 ms retry timer with a small retry count carries the connection through loss; there is no full congestion-control state machine.</li>
  193. <li><strong>Listener.</strong> The server side has one active connection plus three backlog/closing slots. SYN-ACK advertises a zero window while queued; a queued connection may hold 1 KB of early request, and the window opens when <code>tcp_srv_accept()</code> runs.</li>
  194. <li><strong>Bursts.</strong> Responses go out in up to four-segment bursts with a cumulative ACK, rather than one segment per ACK.</li>
  195. <li><strong>No keep-alive.</strong> With one active connection, an idle persistent connection would block the parallel connections Nautilus opens.</li>
  196. </ul>
  197. <p>
  198. New SYNs and data are also handed to <code>tcp_srv_input()</code> from
  199. the active connection's receive/send poll loops, not only between
  200. requests, so parallel gvfs clients make progress.
  201. </p>
  202. </section>
  203. <section id="tls">
  204. <h2>TLS 1.3</h2>
  205. <p>
  206. <span class="file">tls.c</span> is a ring-3 client with a deliberately
  207. narrow cipher suite: <code>TLS_CHACHA20_POLY1305_SHA256</code> and
  208. X25519 only. It is stream-oriented over the existing TCP connection
  209. and prints the leaf SHA-256 fingerprint for manual comparison.
  210. </p>
  211. <ul>
  212. <li><strong>Not verified.</strong> Phase A provides encryption without authentication; a MITM is undetected. <code>curl</code> warns, and the browser marks HTTPS as unverified.</li>
  213. <li><strong>Weak DRBG.</strong> <span class="file">tls_rng.c</span> mixes RDTSC jitter, ticks and the MAC; it is not a hardware-backed CSPRNG.</li>
  214. <li><strong>Host tests.</strong> The crypto files are pure freestanding C with host vectors (<code>make test-crypto</code>, <code>tls_test.c</code>).</li>
  215. </ul>
  216. <div class="warn">
  217. <p><strong>Do not treat HTTPS as secure authentication.</strong> The
  218. cipher suite is real, but without certificate verification the
  219. connection authenticates nothing. Use it for confidentiality on a
  220. trusted network, not for secrets against an active attacker.</p>
  221. </div>
  222. </section>
  223. <section id="abi">
  224. <h2>sys_net ABI &amp; ownership</h2>
  225. <p>
  226. <span class="file">sys_net.c</span> exposes NIC info, MAC/IP/mask/
  227. gateway/DNS getters and setters, raw frame TX/RX, decode, reply,
  228. loopback, register dump, reset, speed and MAC overrides. It also
  229. exposes the DNS and DHCP clients and the TCP/HTTP helpers.
  230. </p>
  231. <ul>
  232. <li><strong>One owner.</strong> <code>SYS_NET_ACQUIRE</code> takes the receiver for the calling process; the background kexec watcher pauses while a command owns it.</li>
  233. <li><strong>Reaper safety.</strong> If the owner dies, <code>sys_net_reap</code> force-releases the receiver through <code>netdev_release_all()</code>.</li>
  234. <li><strong>Wait semantics.</strong> ARP, DNS, DHCP and TCP waits re-enable interrupts for their duration and spin on <code>get_ticks_ms()</code>; the syscall stub enters with interrupts off.</li>
  235. <li><strong>No sockets.</strong> The connection state lives in the kernel, one connection at a time; this is why the browser opens a fresh connection per fetch job.</li>
  236. </ul>
  237. </section>
  238. <section id="console">
  239. <h2>Netconsole &amp; netkexec</h2>
  240. <p>
  241. <span class="file">netlog.c</span> mirrors the serial console and
  242. terminal output to UDP port 19290. The mirror is on by default and
  243. broadcasts; <code>netconsole host &lt;laptop-ip&gt;</code> narrows it,
  244. <code>netconsole off</code>/<code>on</code> toggles it, and
  245. <code>netlog &lt;text&gt;</code> sends an ad-hoc line. The producer
  246. never blocks: a full buffer drops characters and reports it.
  247. </p>
  248. <p>
  249. <span class="file">netkexec.c</span> receives a new kernel/rootfs over
  250. UDP port 19288 using <code>KXN2</code>, and a runtime command pack
  251. using <code>KXNP</code>. Datagrams are acknowledged with the next
  252. expected offset and verified with a 32-bit checksum before the jump
  253. or pack swap. On the host, <code>make netmon</code> and
  254. <code>make net-dev</code> wrap these protocols.
  255. </p>
  256. </section>
  257. <section id="http">
  258. <h2>HTTP clients</h2>
  259. <ul>
  260. <li><strong>curl</strong> — <code>http://</code> or <code>https://</code> GET with DNS, ARP, redirects (up to five hops), chunked decoding, status/headers/body dump and a TLS warning.</li>
  261. <li><strong>uhttp</strong> — shared ring-3 HTTP/1.1 client used by curl and the browser: URL parsing, redirects, chunked decoding, timeouts and TLS.</li>
  262. <li><strong>browser</strong> — runs network fetches in a headless <code>curl __fetch</code> helper that writes the body and metadata under <code>/share</code>, so the UI keeps drawing and scrolling. Each fetch opens a fresh connection.</li>
  263. <li><strong>websrv</strong> — the server side, speaking HTTP/1.1 + WebDAV over the TCP listener; see <a href="filesystems.html#webdav">Filesystems → WebDAV</a>.</li>
  264. </ul>
  265. <p>
  266. The browser's helper requests identity encoding because inflating
  267. multi-megabyte pages in the UI process stalled. If a server still
  268. sends gzip, the browser's inflate hook pumps the UI while decoding.
  269. </p>
  270. </section>
  271. <section id="security">
  272. <h2>Security posture</h2>
  273. <div class="table-wrap">
  274. <table>
  275. <thead>
  276. <tr><th>Surface</th><th>State</th><th>Consequence</th></tr>
  277. </thead>
  278. <tbody>
  279. <tr><td>TLS certificates</td><td>Not verified</td><td>Encryption without authentication; MITM is undetected.</td></tr>
  280. <tr><td>TLS DRBG</td><td>Weak (RDTSC/ticks/MAC)</td><td>Not suitable for high-value secrets.</td></tr>
  281. <tr><td>WebDAV</td><td>No authentication</td><td>Anyone on the LAN can read mounts and write <code>/share</code>.</td></tr>
  282. <tr><td>NIC ownership</td><td>One process at a time</td><td>Packet-level commands are mutually exclusive; a killed owner is force-released.</td></tr>
  283. <tr><td>Kernel/user isolation</td><td>None (identity map)</td><td>A ring-3 bug can reach any mapped kernel page.</td></tr>
  284. </tbody>
  285. </table>
  286. </div>
  287. </section>
  288. <section id="sources">
  289. <h2>Source map</h2>
  290. <ul class="filelist">
  291. <li><code>netdev.c</code>, <code>netdev.h</code> — registry</li>
  292. <li><code>e1000e.c</code>, <code>r8168.c</code>, <code>ne2000.c</code>, <code>asix.c</code></li>
  293. <li><code>net.c</code>, <code>net.h</code> — ARP/ICMP/UDP/IP</li>
  294. <li><code>dhcp.c</code>, <code>dns.c</code></li>
  295. <li><code>tcp.c</code>, <code>tcp.h</code> — client + listener</li>
  296. <li><code>tls.c</code>, <code>tls_*.c</code> — TLS 1.3</li>
  297. <li><code>sys_net.c</code> — ring-3 service</li>
  298. <li><code>netlog.c</code>, <code>netkexec.c</code></li>
  299. <li><code>uhttp.c</code>, <code>ucmd_curl.c</code>, <code>ucmd_websrv.c</code></li>
  300. </ul>
  301. </section>
  302. </main>
  303. <footer class="site-footer">
  304. <div class="inner">
  305. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  306. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  307. </div>
  308. </footer>
  309. </body>
  310. </html>