nts

README

nts

The nts package provides a client implementation of Network Time Security (NTS) for the Network Time Protocol (NTP). It enables the secure querying of time-related information that can be used to synchronize the local system clock with a more accurate network clock. See RFC 8915 for further details.

This package is implemented as an extension to the go-based simple ntp client package, but it may be used without directly installing that package.

Creating an NTS session

Before requesting time synchronization data, you must first establish a "session" with an NTS key-exchange server.

session, err := nts.NewSession("time.cloudflare.com")

This is not a session in the typical sense of the word, which often implies a long-running network connection to a server. Rather, it is merely a collection of cryptographic keys and other state used to communicate securely with an NTS-capable NTP server. Once the session has been created, the network connection to the key-exchange server is immediately dropped and all future queries proceed via NTP using the session's query functions.

If you wish to customize the behavior of the session, you may do so by using NewSessionWithOptions instead of NewSession. For example:

opt := &nts.SessionOptions{
    TLSConfig: &tls.Config{
        RootCAs: certPool,
    },
    Timeout: 30 * time.Second,
    Dialer: customDialer,
    Resolver: customResolver,
}
session, err := nts.NewSessionWithOptions(host, opt)

See the documentation for SessionOptions for a list of available customizations.

Querying time synchronization data

After successful establishment of the session, you may issue NTP Query requests for time synchronization data.

if response, err := session.Query(); err != nil {
    accurateTime := time.Now().Add(response.ClockOffset)
    fmt.Printf("The current time is: %s\n", accurateTime)
}

In addition to the clock offset, the Response includes information you can use to tune future queries. For instance, it includes a Poll interval, which describes how long you should wait before querying again. The response also has a Validate function, which you can use to perform additional sanity checks on the data to determine whether it is suitable for time synchronization purposes.

err := response.Validate()
if err == nil {
    // response data is suitable for synchronization purposes
}

If you wish to customize the behavior of the query, you may do so by using QueryWithOptions instead of Query.

opt := &ntp.QueryOptions{ Timeout: 30 * time.Second }
response, err := session.QueryWithOptions(opt)

See the documentation for QueryOptions for a list of available customizations.

Choosing an NTS server

NTS is a relatively new protocol, having become an IETF RFC in September 2020. So there are a limited number of NTS key-exchange servers available for public use. You can find a list here. The NTP pool does not currently support NTS.

If you wish to operate your own NTS-capable NTP server, you may install NTPsec or Chrony.

Documentation

Overview

Package nts provides a client implementation of Network Time Security (NTS) for the Network Time Protocol (NTP). It enables the secure querying of time-related information that can be used to synchronize the local system clock with a more accurate network clock. See RFC 8915 (https://tools.ietf.org/html/rfc8915) for more details.

Index

• Variables
• type Session
  • func NewSession(address string) (*Session, error)
  • func NewSessionWithOptions(address string, opt *SessionOptions) (*Session, error)
  • func (s *Session) Address() string
  • func (s *Session) Query() (response *ntp.Response, err error)
  • func (s *Session) QueryWithOptions(opt *ntp.QueryOptions) (response *ntp.Response, err error)
  • func (s *Session) Refresh() error
• type SessionOptions

Variables

var (
	ErrAuthFailedOnClient = errors.New("authentication failed on client")
	ErrAuthFailedOnServer = errors.New("authentication failed on server")
	ErrInvalidFormat      = errors.New("invalid packet format")
	ErrNoCookies          = errors.New("no NTS cookies available")
	ErrUniqueIDMismatch   = errors.New("client and server unique ID mismatch")
)

var ErrKeyExchangeFailed = errors.New("key exchange failure")

Types

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session contains the state of an active NTS session. It is initialized by exchanging keys and cookies with an NTS key-exchange server, after which the connection to the key-exchange server is immediately dropped. The session's internal state is updated as NTP queries are made against an NTS-capable NTP server.

func NewSession

func NewSession(address string) (*Session, error)

NewSession creates an NTS session by connecting to an NTS key-exchange server and requesting keys and cookies to be used for future secure NTP queries. Once keys and cookies have been received, the connection is dropped. The address is of the form "host" or "host:port", where host is a domain name address. If no port is included, NTS default port 4460 is used.

func NewSessionWithOptions

func NewSessionWithOptions(address string, opt *SessionOptions) (*Session, error)

NewSessionWithOptions performs the same function as NewSession but allows for the customization of certain authentication behaviors.

func (*Session) Address

func (s *Session) Address() string

Address returns the NTP server "host:port" pair configured for the session.

func (*Session) Query

func (s *Session) Query() (response *ntp.Response, err error)

Query time data from the session's associated NTP server. The response contains information from which an accurate local time can be determined.

func (*Session) QueryWithOptions

func (s *Session) QueryWithOptions(opt *ntp.QueryOptions) (response *ntp.Response, err error)

QueryWithOptions performs the same function as Query but allows for the customization of certain NTP behaviors.

func (*Session) Refresh

func (s *Session) Refresh() error

Refresh the session by clearing the its current cookies and performing a new key exchange. This should only be done when no queries have been performed with the session for a very long time (i.e., more than 24 hours).

type SessionOptions

type SessionOptions struct {
	// TLSConfig is used to override the default TLS configuration for NTS key
	// exchange. Attempts to downgrade the TLS protocol version below 1.3
	// using this override are ignored.
	TLSConfig *tls.Config

	// Timeout determines how long the session waits for a response from the
	// key exchange server before failing with a timeout error. Defaults to 5
	// seconds.
	Timeout time.Duration

	// Dialer is a callback that overrides the default TLS dialer behavior
	// used to establish a connection with the NTS key exchange endpoint's
	// network address. The tlsConfig is the TLS configuration used to
	// establish the connection.
	Dialer func(network, addr string, tlsConfig *tls.Config) (*tls.Conn, error)

	// Resolver is a callback used to override the NTP address returned by the
	// NTS key exchange protocol. The addr parameter contains the "host:port"
	// address of the NTP server returned by the key exchange protocol. The
	// function is expected to return a "host:port" address to override this
	// address. This option is commonly used in proxy setups.
	Resolver func(addr string) string
}

SessionOptions contains options for customizing the behavior of an NTS session.