Norn – Secure Time

This software library allow you to implement and use the Network Time Secure protocol as defined by the IETF together with some vendor extensions for additional use cases.

Quickstart

Minimal NTS client

using org.GraphDefined.Vanaheimr.Hermod;
using org.GraphDefined.Vanaheimr.Norn.NTS;

var client = new NTSClient(
    DomainName.Parse("time.cloudflare.com")
);

var ntske = await client.GetNTSKERecords();
if (!ntske.Success)
    throw new Exception(ntske.ErrorMessage);

var ntp = await client.QueryTime(NTSKEResponse: ntske.Response);
if (!ntp.Success)
    throw new Exception(ntp.ErrorMessage);

Console.WriteLine(ntp.Response?.TransmitTimestamp);
Console.WriteLine(ntp.Diagnostics.StopwatchRoundTripTime);

Monitoring client

NTSKEResult.Diagnostics exposes NTS-KE timing, TLS information, announced NTP servers/ports and warning records. NTSQueryResult.Diagnostics exposes the selected endpoint, high-resolution send/receive timestamps, RTT, validation result and cookie-pool state.

var ntske = await client.GetNTSKERecords(RequestNTSPublicKeys: true);

Console.WriteLine(ntske.Diagnostics.TimingInfo?.DNSLookupDuration);
Console.WriteLine(ntske.Diagnostics.TLSInfo?.NegotiatedCipherSuite);
Console.WriteLine(String.Join(", ", ntske.Diagnostics.WarningMessages));

var ntp = await client.QueryTime(
    ntske.Response,
    SignedResponseMode: SignedResponseMode.Scheduled
);

Console.WriteLine(ntp.Diagnostics.RemoteDescription);
Console.WriteLine(ntp.Diagnostics.StopwatchRoundTripTime);
Console.WriteLine(ntp.Diagnostics.CookiePoolDiagnostics?.AvailableCookieCount);

NTS server

using org.GraphDefined.Vanaheimr.Hermod;
using org.GraphDefined.Vanaheimr.Hermod.HTTP;
using org.GraphDefined.Vanaheimr.Norn.NTS;

var server = new NTSServer(
    NTSKEPort:          IPPort.Parse(4460),
    NTSPort:            IPPort.Parse(123),
    ExternalURLs:       [ URL.Parse("udp://time.example.org:123") ],
    MasterKeysFilePath: "masterKeys.json"
);

await server.Start();

var metrics = server.Metrics;
Console.WriteLine(metrics.NTPRequestsReceived);

Production server with certificate

For production deployments, provide a real TLS certificate and matching private key. The self-signed certificate generated by the default constructor is meant for local tests and development only.

Org.BouncyCastle.X509.X509Certificate certificate = LoadCertificate();
Org.BouncyCastle.Crypto.Parameters.ECPrivateKeyParameters privateKey = LoadPrivateKey();

var server = new NTSServer(
    TLSCertificate:       certificate,
    TLSPrivateKey:        privateKey,
    TLSServerSubjectName: "time.example.org",
    ExternalURLs:         [ URL.Parse("udp://time.example.org:123") ]
);

Interoperability

The client is tested against local Norn/chrony-style deployments and public NTS servers. Useful test targets include PTB, Cloudflare and OpenChargingCloud servers. For monitoring deployments prefer explicit certificate validation, record NTS-KE warnings, and inspect NTSKEResult.Diagnostics plus NTSQueryResult.Diagnostics for timing and validation data.

RFCs

• rfc4330 - Simple Network Time Protocol (SNTP) Version 4
• rfc5297 - Synthetic Initialization Vector (SIV) Authenticated Encryption Using the Advanced Encryption Standard (AES)
• rfc5905 - Network Time Protocol Version 4: Protocol and Algorithms Specification
• rfc7384 - Security Requirements of Time Protocols in Packet Switched Networks
• rfc7822 - Network Time Protocol Version 4 (NTPv4) Extension Fields
• rfc8915 - Network Time Security for the Network Time Protocol

Project Security Policy

We take security very seriously abd continuously review security vulnerabilities within the code, and try to provide fixes in a timely manner.

Please report security vulnerabilities in the Issues section of this repository. By keeping security issues visible, we leverage our community in helping fix them promptly.

If you are concerned sharing a vulnerability with the rest of the community, you can also send your report to: github@graphdefined.com

Your participation

This software is Open Source under the GNU Affero General Public License (AGPL). We appreciate your participation in this ongoing project, and your help to improve it. If you find bugs, want to request a feature or send us a pull request, feel free to use the normal GitHub features to do so. For this please read the Contributor License Agreement carefully and send us a signed copy or use a similar free and open license.