Update comments and documentation

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

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.)

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 {

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
 

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.