====== std.net.ntp ======

NTP (Network Time Protocol, RFC 5905) synchronisiert die Uhrzeit von Systemen mit einem Zeitserver. Die Unit baut NTP-Anfragepakete auf (Version 3, Client-Modus, UDP Port 123) und parst die Antwort des Servers inklusive Stratum-Angabe, Referenzzeitquelle und Zeitstempel im NTP-Epoch-Format (Sekunden seit 1900).

Einsatzbereiche sind zeitkritische Anwendungen, präzises Log-Timestamping, verteilte Systeme mit Uhrzeitsynchronisation und Anwendungen, die ohne libc-Systemzeit-APIs eine verlässliche UTC-Zeit benötigen.

----

===== Imports =====

  * ''std.net.socket''
  * ''std.net.dns''
  * ''std.net.types''

----

===== Konstanten =====

^ Name ^ Typ ^ Wert ^ Sichtbarkeit ^
| ''NTP_PORT'' | ''int64'' | ''123'' | pub |
| ''NTP_VERSION'' | ''int64'' | ''4'' | pub |
| ''NTP_MODE_CLIENT'' | ''int64'' | ''3'' | pub |
| ''NTP_MODE_SERVER'' | ''int64'' | ''4'' | pub |
| ''NTP_EPOCH_OFFSET'' | ''int64'' | ''2208988800'' | pub |
| ''NTP_PACKET_SIZE'' | ''int64'' | ''48'' | pub |
| ''NTP_STRATUM_KOD'' | ''int64'' | ''0'' | pub |
| ''NTP_STRATUM_PRIMARY'' | ''int64'' | ''1'' | pub |
| ''NTP_STRATUM_SECONDARY'' | ''int64'' | ''2'' | pub |
| ''NTP_ERR_OK'' | ''int64'' | ''0'' | pub |
| ''NTP_ERR_NETZ'' | ''int64'' | ''-1'' | pub |
| ''NTP_ERR_MODE'' | ''int64'' | ''-2'' | pub |
| ''NTP_ERR_ORIGIN'' | ''int64'' | ''-3'' | pub |
| ''NTP_ERR_KOD'' | ''int64'' | ''-4'' | pub |
| ''NTP_ERR_UNSYNC'' | ''int64'' | ''-5'' | pub |

----

===== Typen =====

==== NTPTime (struct) ====

^ Feld ^ Typ ^ Bedeutung ^
| ''unixTime'' | ''int64'' | Unix-Zeitstempel in Sekunden |
| ''fractional'' | ''int64'' | Bruchteil der Sekunde (Nanosekunden × 2^32) |
| ''stratum'' | ''int64'' | Stratum des Servers |
| ''precision'' | ''int64'' | Präzisionsangabe des Servers |
| ''delay'' | ''int64'' | Umlaufzeit in Millisekunden |
| ''offset'' | ''int64'' | Abweichung der eigenen Uhr in Millisekunden |
| ''status'' | ''int64'' | ''NTP_ERR_*'' — ''0'' heißt „Antwort ist brauchbar" |

----

===== Funktionen =====

^ Signatur ^ Sichtbarkeit ^ Beschreibung ^
| ''NTPJetzt(): int64'' | pub | aktuelle Zeit als NTP-Zeitstempel (32 Bit Sekunden seit 1900 + 32 Bit Bruchteil) |
| ''NTPBuildRequest(): int64'' | pub | NTP-Anfrage-Paket (48 Byte) aufbauen — trägt den eigenen Sendezeitstempel ein |
| ''NTPReadTS64(buf: int64, offset: int64): int64'' | pub | NTP-Zeitstempel (64 Bit) aus dem Puffer lesen |
| ''NTPWriteTS64(buf: int64, offset: int64, ts: int64): void'' | pub | NTP-Zeitstempel in den Puffer schreiben |
| ''NTPReadU32BE(buf: int64, offset: int64): int64'' | pub | 32-Bit-Big-Endian-Wert aus Puffer lesen |
| ''NTPReadTimestamp(buf: int64, offset: int64): int64'' | pub | NTP-Zeitstempel in Unix-Zeit umrechnen |
| ''NTPParseResponse(buf: int64, T1: int64, T4: int64): NTPTime'' | pub | Antwort parsen; ''T1'' = eigener Sendezeitstempel, ''T4'' = Empfangszeitstempel |
| ''NTPGetTime(host: int64): NTPTime'' | pub | Aktuelle Zeit per Hostname abfragen |
| ''NTPGetTimeFromIP(ip: int64): NTPTime'' | pub | Aktuelle Zeit per IP-Adresse abfragen |
| ''NTPFormatTime(unixTime: int64): int64'' | pub | Unix-Zeit als Datumsstring formatieren |
----

===== Auswertung und Zuordnung =====

<WRAP alert>
**''status'' prüfen, bevor ''unixTime'' benutzt wird.** Bis lyxc 1.1.1C blieben ''offset'' und ''delay'' **immer 0**, und die Antwort wurde der Anfrage nicht zugeordnet ([[https://github.com/SEOLizer/LyX-Compiler/issues/1609|#1609]]). Über UDP genügte einem Angreifer damit ein Paket mit der richtigen Absenderadresse — er musste die Anfrage nicht einmal gesehen haben. Zeit trägt Zertifikatsgültigkeit, Einmalkennwörter und Protokolle.
</WRAP>

Seither gilt:

  * ''NTPBuildRequest'' schreibt den **eigenen Sendezeitstempel** in die Bytes 40–47. Genau den spiegelt der Server zurück.
  * ''NTPParseResponse'' weist eine Antwort mit fremdem Origin-Stempel ab (''NTP_ERR_ORIGIN'') und prüft zusätzlich Betriebsart 4 (''NTP_ERR_MODE''), ''LI != 3'' und Stratum ≥ 16 (''NTP_ERR_UNSYNC'') sowie Stratum 0, also Kiss-o'-Death (''NTP_ERR_KOD'').
  * ''offset'' und ''delay'' werden nach RFC 5905 aus **allen vier** Zeitstempeln gerechnet. Deshalb nimmt ''NTPParseResponse'' jetzt ''T1'' und ''T4'' — die beiden Zeitpunkte, die nur der Aufrufer kennt.

Die eigene Uhr stellt man nicht auf ''unixTime'', sondern korrigiert sie um ''offset'': der rohe Sendezeitstempel des Servers ist beim Eintreffen bereits um die halbe Umlaufzeit veraltet.

----

Letzte Aktualisierung: 2026-08-18 — Zuordnung der Antwort, ''NTP_ERR_*'', ''offset''/''delay'' und die geänderte Signatur von ''NTPParseResponse'' nachgezogen ([[https://github.com/SEOLizer/LyX-Compiler/issues/1609|#1609]]).