From f5ef9bf2ce67d99829ebfc2407017a13bfd4640e Mon Sep 17 00:00:00 2001 From: Brett Vickers Date: Mon, 10 Jul 2023 23:05:22 -0700 Subject: [PATCH] Update comments and documentation --- LICENSE | 2 +- README.md | 29 +++++++++++++++++++---------- auth.go | 2 +- ntp.go | 20 +++++++++++++------- ntp_test.go | 2 +- 5 files changed, 35 insertions(+), 20 deletions(-) diff --git a/LICENSE b/LICENSE index ef7b286..a404327 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2015-2023 Brett Vickers. All rights reserved. +Copyright © 2015-2023 Brett Vickers. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions diff --git a/README.md b/README.md index 7149d71..ed8a917 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ntp === The ntp package is an implementation of a Simple NTP (SNTP) client based on -[RFC5905](https://tools.ietf.org/html/rfc5905). It allows you to connect to +[RFC 5905](https://tools.ietf.org/html/rfc5905). It allows you to connect to a remote NTP server and request information about the current time. @@ -17,9 +17,9 @@ time, err := ntp.Time("0.beevik-ntp.pool.ntp.org") ``` -## Querying time metadata +## Querying time synchronization data -To obtain the current time as well as some additional metadata about the time, +To obtain the current time as well as some additional synchronization data, use the [`Query`](https://godoc.org/github.com/beevik/ntp#Query) function: ```go response, err := ntp.Query("0.beevik-ntp.pool.ntp.org") @@ -28,11 +28,11 @@ time := time.Now().Add(response.ClockOffset) The [`Response`](https://godoc.org/github.com/beevik/ntp#Response) structure returned by `Query` includes the following information: -* `Time`: The time the server transmitted its response, according to its own - clock. * `ClockOffset`: The estimated offset of the local system clock relative to the server's clock. For a more accurate time reading, you may add this offset to any subsequent system clock reading. +* `Time`: The time the server transmitted its response, according to its own + clock. * `RTT`: An estimate of the round-trip-time delay between the client and the server. * `Precision`: The precision of the server's clock reading. @@ -57,8 +57,8 @@ returned by `Query` includes the following information: server. The `Response` structure's [`Validate`](https://godoc.org/github.com/beevik/ntp#Response.Validate) -method performs additional sanity checks to determine whether the response is -suitable for time synchronization purposes. +function performs additional sanity checks to determine whether the response +is suitable for time synchronization purposes. ```go err := response.Validate() if err == nil { @@ -80,16 +80,16 @@ include: * `Timeout`: How long to wait before giving up on a response from the NTP server. * `Version`: Which version of the NTP protocol to use (2, 3 or 4). -* `LocalAddress`: The local network address to use when connecting to the - server. -* `Port`: The remote NTP server port to contact. * `TTL`: The maximum number of IP hops before the request packet is discarded. * `Auth`: The symmetric authentication key and algorithm used by the server to authenticate the query. The same information is used by the client to authenticate the server's response. +* `Extensions`: Extensions may be added to modify NTP queries before they are + transmitted and to process NTP responses after they arrive. * `Dial`: A custom network connection "dialer" function used to override the default UDP dialer function. + ## Using the NTP pool The NTP pool is a shared resource provided by the [NTP Pool @@ -98,3 +98,12 @@ over the world. To prevent it from becoming overloaded, please avoid querying the standard `pool.ntp.org` zone names in your applications. Instead, consider requesting your own [vendor zone](http://www.pool.ntp.org/en/vendors.html) or [joining the pool](http://www.pool.ntp.org/join.html). + + +## Network Time Security (NTS) + +Network Time Security (NTS) is a recent enhancement of NTP, designed to add +better authentication and message integrity to the protocol. It is defined by +[RFC 8915](https://tools.ietf.org/html/rfc8915). If you wish to use NTS, see +the [nts package](https://github.com/beevik/nts). (The nts package is +implemented as an extension to this package.) diff --git a/auth.go b/auth.go index a6017cc..b5b1f4f 100644 --- a/auth.go +++ b/auth.go @@ -72,7 +72,7 @@ func calcDigest_SHA512(payload, key []byte) []byte { } func calcCMAC_AES(payload, key []byte) []byte { - // calculate the CMAC according to the algorithm defined in RFC4493. See + // calculate the CMAC according to the algorithm defined in RFC 4493. See // https://tools.ietf.org/html/rfc4493 for details. c, err := aes.NewCipher(key) if err != nil { diff --git a/ntp.go b/ntp.go index c1094a0..a67b899 100644 --- a/ntp.go +++ b/ntp.go @@ -1,10 +1,10 @@ -// Copyright 2015-2023 Brett Vickers. +// Copyright © 2015-2023 Brett Vickers. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. // Package ntp provides an implementation of a Simple NTP (SNTP) client // capable of querying the current time from a remote NTP server. See -// RFC5905 (https://tools.ietf.org/html/rfc5905) for more details. +// RFC 5905 (https://tools.ietf.org/html/rfc5905) for more details. // // This approach grew out of a go-nuts post by Michael Hofmann: // https://groups.google.com/forum/?fromgroups#!topic/golang-nuts/FlcdMU5fkLQ @@ -219,7 +219,7 @@ type QueryOptions struct { TTL int // Auth contains the settings used to configure NTP symmetric key - // authentication. See RFC5905 for further details. + // authentication. See RFC 5905 for further details. Auth AuthOptions // Extensions may be added to modify NTP queries before they are @@ -244,7 +244,8 @@ type QueryOptions struct { // and some of which is calculated by this client. type Response struct { // Time is the transmit time reported by the server just before it - // responded to the client's NTP query. + // responded to the client's NTP query. You should not use this value + // for time synchronization purposes. Use the ClockOffset instead. Time time.Time // ClockOffset is the estimated offset of the local system clock relative @@ -266,8 +267,13 @@ type Response struct { // issues too many requests to the server in a short period of time. Stratum uint8 - // ReferenceID is a 32-bit identifier identifying the server or - // reference clock. + // ReferenceID is a 32-bit identifier identifying the server or reference + // clock. For stratum 1 servers, this is typically a meaningful + // zero-padded ASCII-encoded string assigned to the clock. For stratum 2+ + // servers, this is a reference identifier for the server and is either + // the server's IPv4 address or a hash of its IPv6 address. For + // kiss-of-death responses (stratum=0), this field contains the + // ASCII-encoded "kiss code". ReferenceID uint32 // ReferenceTime is the time when the server's system clock was last @@ -299,7 +305,7 @@ type Response struct { MinError time.Duration // KissCode is a 4-character string describing the reason for a - // "kiss of death" response (stratum = 0). For a list of standard kiss + // "kiss of death" response (stratum=0). For a list of standard kiss // codes, see https://tools.ietf.org/html/rfc5905#section-7.4. KissCode string diff --git a/ntp_test.go b/ntp_test.go index c95ec8d..939f378 100644 --- a/ntp_test.go +++ b/ntp_test.go @@ -1,4 +1,4 @@ -// Copyright 2015-2023 Brett Vickers. +// Copyright © 2015-2023 Brett Vickers. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file.