roughtime

README

Roughtime

This package implements a simple Roughtime client based on Google's implementation. To run it, do:

$ go get -u github.com/cloudflare/roughtime
$ go install github.com/cloudflare/roughtime...
$ getroughtime -ping roughtime.cloudflare.com:2002 \
    -pubkey gD63hSj3ScS+wuOeGrubXlq35N1c5Lby/S+T7MNTjxo=
ping response: 2018-09-20 10:26:56.327 -0400 EDT ±1s (in 16ms)

Or, better yet, use multiple servers!

$ getroughtime -config ~/go/src/github.com/cloudflare/roughtime/ecosystem.json
Cloudflare-Roughtime: 2018-09-20 10:25:10.568 -0400 EDT ±1s (in 14ms)
Google-Sandbox-Roughtime: 2018-09-20 10:25:10.587429 -0400 EDT ±1s (in 20ms)
int08h-Roughtime: 2018-09-20 10:25:10.618522 -0400 EDT ±1s (in 40ms)
delta: -12ms

For more information about Roughtime and tips for writing your own client, visit the developer documentation.

Ecosystem guidelines

We welcome pull requests for adding your Roughtime service to our list. Your PR should do the following:

• Add your server's configuration to ecosystem.json. The list of servers will be alphabetized by the "name" field.

• Add some information about your service to ecosystem.md. (This is also kept in alphabetical order.) This should include details about how your service is provisioned:

  1. how you synchronize your server's clock;
  2. if your code is open source, a link to the code;
  3. where in the world your server is located; and
  4. whether you will guarantee up time, and if so, how you will do so.

A couple things to keep in mind:

• To be healthy, the Roughtime ecosystem needs a diverse set of time sources. The list already contains servers that are synced with Google's NTP servers; as such, servers that expose new sources will be preferred. (An atomic clock would be cool!)

• We reserve the right to prune this list at any time. (For example, if a server is unreliable, or its root secret key has been compromised.)

Finally, a disclaimer: the ecosystem is growing, and ours might not be the definitive list of who is serving Roughtime at any given time. For details about the current state and the future of the protocol, see Adam Langley's write up about the Roughtime ecosystem. There's also a Google group with ongoing discussion.

Documentation

Overview

This package defines some functionalities useful for building Roughtime clients. It's based on Google's original Go implementation of Roughtime. For more information, visit https://roughtime.googlesource.com/roughtime/.

Index

• Constants
• func AvgDeltaWithRadiusThresh(results []Result, t0 time.Time, thresh time.Duration) (time.Duration, error)
• func LoadConfig(configFile string) (servers []config.Server, skipped int, err error)
• func ParseConfig(jsonData []byte) (servers []config.Server, skipped int, err error)
• func SetLogger(l *log.Logger)
• type Chain
  • func NewChain(results []Result) *Chain
  • func (chain *Chain) Verify(prev *Roughtime) (bool, error)
• type Result
  • func Do(servers []config.Server, attempts int, timeout time.Duration, prev *Roughtime) []Result
  • func DoFromFile(configFile string, attempts int, timeout time.Duration, prev *Roughtime) ([]Result, error)
  • func (r *Result) Error() error
• type Roughtime
  • func Get(server *config.Server, attempts int, timeout time.Duration, prev *Roughtime) (*Roughtime, error)
  • func (rt *Roughtime) Now() (time.Time, time.Duration)
  • func (rt *Roughtime) String() string

Constants

const (
	DefaultQueryAttempts = 3
	DefaultQueryTimeout  = time.Second
)

Functions

func AvgDeltaWithRadiusThresh

func AvgDeltaWithRadiusThresh(results []Result, t0 time.Time, thresh time.Duration) (time.Duration, error)

AvgDeltaWithRadiusThresh computes the average difference between t0 and the time reported by each server, rejecting responses whose uncertainty radii aren't within the accepted limit. The calculation accounts for the network latency measured by the client.

func LoadConfig

func LoadConfig(configFile string) (servers []config.Server, skipped int, err error)

LoadConfig reads and parses a JSON-encoded string from configFile.

func ParseConfig

func ParseConfig(jsonData []byte) (servers []config.Server, skipped int, err error)

ParseConfig loads parses a JSON-encoded Roughtime-server configuration, skipping those servers that the client doesn't support. It returns the sequenc of servers with valid configurations, as well as the number of configurations it skipped.

If the server's address is a domain name, the client will attempt to resolve it. At the moment, the client only supports servers with an Ed25519 root public key and who are listening on UDP.

func SetLogger

func SetLogger(l *log.Logger)

SetLogger sets the logger used to log the output of Do and DoFromFile. If l == nil, then no output will be logged.

Types

type Chain

type Chain struct {
	*Roughtime

	// The server who signed the response.
	Server *config.Server

	// The next query in the chain.
	Next *Chain
}

Chain represents a sequence of ordered Roughtime responses.

func NewChain

func NewChain(results []Result) *Chain

NewChain returns a Roughtime chain comprised of the successful queries in a sequence of results.

func (*Chain) Verify

func (chain *Chain) Verify(prev *Roughtime) (bool, error)

Verify returns true if the chain is valid. A chain is valid if for each link in the chain (1) the signature in the server's response is valid, and (2) the response was used to generate the nonce in the next link's request.

If prev != nil, then prev.Resp is used to compute the nonce for the first request in the chain.

type Result

type Result struct {
	*Roughtime

	// The configuration of the server used for the query.
	Server *config.Server

	// The network delay incurred by the query.
	Delay time.Duration
	// contains filtered or unexported fields
}

Result stores the request and response of a Roughtime query to a server. It is either a server's time or an error.

func Do

func Do(servers []config.Server, attempts int, timeout time.Duration, prev *Roughtime) []Result

Do requests Roughtime from a sequence of servers in order. If the request fails, then the error is recorded. The nonce of each request is computed from the response of the last, skipping requests that fail.

func DoFromFile

func DoFromFile(configFile string, attempts int, timeout time.Duration, prev *Roughtime) ([]Result, error)

DoFromFile loads a sequence of server configurations from configFile and requests Roughtime from them in order.

func (*Result) Error

func (r *Result) Error() error

Error returns the error resulting from the query, if any.

type Roughtime

type Roughtime struct {
	// The request.
	Req []byte

	// The blind used to generate the nonce of the request.
	Blind []byte

	// The bytes of the response.
	Resp []byte

	// The time reported by the server (microseconds since the Unix epoch).
	Midpoint uint64

	// The "uncertainty radius" of the server's reported time (in microseconds).
	// It indicates that the server is "reasonably sure" that the real is within
	// this number of microseconds of the real time.
	Radius uint32
}

Roughtime stores the request and response of a successful Roughtime query. It implements the Stringer interface.

func Get

func Get(server *config.Server, attempts int, timeout time.Duration, prev *Roughtime) (*Roughtime, error)

Get sends a request to a server and verifies the response. It makes at most as many attempts as specified, waiting for the given amount of time for each reply. It uses prev to generate the nonce of the request. This may be nil, in which case this request is the first in a chain.

func (*Roughtime) Now

func (rt *Roughtime) Now() (time.Time, time.Duration)

Now returns the time provided by a Roughtime server. The first output parameter is the timestamp and the second is the uncertainty radius.

func (*Roughtime) String

func (rt *Roughtime) String() string