protocol

Documentation

Overview

Package protocol implements the core of the Roughtime protocol.

Index

• Constants
• func CalculateChainNonce(nonce, prevReply, blind []byte)
• func CreateReplies(ver Version, requests []Request, midpoint time.Time, radius time.Duration, ...) ([][]byte, error)
• func CreateRequest(versionPreference []Version, rand io.Reader, prevReply []byte, ...) (nonce, blind []byte, request []byte, err error)
• func Decode(bytes []byte) (map[uint32][]byte, error)
• func Encode(msg map[uint32][]byte) ([]byte, error)
• func VerifyReply(versionPreference []Version, replyBytes, publicKey []byte, nonce []byte) (midp time.Time, radi time.Duration, err error)
• type Certificate
  • func NewCertificate(minTime, maxTime time.Time, ...) (cert *Certificate, err error)
  • func SelectCertificateForRequest(req *Request, certs []Certificate) *Certificate
  • func (cert *Certificate) BytesForVersion(ver Version) []byte
• type Error
  • func (e Error) Error() string
• type ErrorType
• type Request
  • func ParseRequest(bytes []byte) (req *Request, err error)
• type Version
  • func ResponseVersionFromSupported(supportedVersions []Version) (Version, error)
  • func (ver Version) String() string

Constants

const (

	// MinRequestSize is the minimum number of bytes in a request.
	MinRequestSize = 1024
)

Functions

func CalculateChainNonce

func CalculateChainNonce(nonce, prevReply, blind []byte)

CalculateChainNonce fills the `nonce` buffer with the nonce used in the next request in a chain given a reply and a blinding factor. The length of the buffer is expected to match the nonce length for the protocol version.

func CreateReplies

func CreateReplies(ver Version, requests []Request, midpoint time.Time, radius time.Duration, cert *Certificate) ([][]byte, error)

CreateReplies signs, using privateKey, a batch of nonces along with the given time and radius. It returns one reply for each nonce using that signature and includes cert in each.

The same version is indicated in each reply. It's the callers responsibility to ensure that each client supports this version. Likewise, the server indicated by each request, if any, must match the certificate.

func CreateRequest

func CreateRequest(versionPreference []Version, rand io.Reader, prevReply []byte, rootPublicKey ed25519.PublicKey) (nonce, blind []byte, request []byte, err error)

CreateRequest creates a Roughtime request given an entropy source and the contents of a previous reply for chaining. If this request is the first of a chain, prevReply can be empty. It returns the nonce (needed to verify the reply), the blind (needed to prove correct chaining to an external party) and the request itself.

func Decode

func Decode(bytes []byte) (map[uint32][]byte, error)

Decode parses the output of encode back into a map of tags to bytestrings.

func Encode

func Encode(msg map[uint32][]byte) ([]byte, error)

Encode converts a map of tags to bytestrings into an encoded message. The number of elements in msg and the sum of the lengths of all the bytestrings must be ≤ 2**32.

func VerifyReply

func VerifyReply(versionPreference []Version, replyBytes, publicKey []byte, nonce []byte) (midp time.Time, radi time.Duration, err error)

VerifyReply parses the Roughtime reply in replyBytes, authenticates it using publicKey and verifies that nonce is included in it. It returns the included timestamp and radius.

Types

type Certificate

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

func NewCertificate

func NewCertificate(minTime, maxTime time.Time, onlinePrivateKey, rootPrivateKey ed25519.PrivateKey) (cert *Certificate, err error)

NewCertificate returns a signed certificate, using rootPrivateKey, delegating authority for the given timestamp to onlinePrivateKey.

func SelectCertificateForRequest

func SelectCertificateForRequest(req *Request, certs []Certificate) *Certificate

Select a certificate suitable for responding to the request.

func (*Certificate) BytesForVersion

func (cert *Certificate) BytesForVersion(ver Version) []byte

BytesForVersion returns a serialized certificate compatible with the given version. Legacy clients (Google-Roughtime) expect a non-standard encoding of the MINT and MAXT fields.

type Error

type Error struct {
	// Type is the error type.
	Type ErrorType

	// Info includes optional info.
	Info string
}

Error represents a protocol error.

func (Error) Error

func (e Error) Error() string

type ErrorType

type ErrorType uint16

ErrorType is an error type.

const (
	ErrorDecode ErrorType = iota
	ErrorNonceLen
	ErrorRequestLen
	ErrorUnsupportedVersion
	ErrorMissingVersion
)

type Request

type Request struct {
	// Nonce is the request nonce.
	Nonce []byte
	// Nonce is the sequence of versions advertised by the client, ordered from
	// most to least preferred.
	Versions []Version
	// contains filtered or unexported fields
}

Request is a request sent by a client.

func ParseRequest

func ParseRequest(bytes []byte) (req *Request, err error)

ParseRequest resolves the supported versions indicated by the client and parses the values required to produce a response.

type Version

type Version uint32

Version indicates the version of the Roughtime protocol in use.

const (
	// VersionGoogle is Google-Roughtime as described here:
	// https://roughtime.googlesource.com/roughtime/+/HEAD/PROTOCOL.md
	VersionGoogle Version = 0

	// VersionDraft08 is draft-ietf-ntp-roughtime-08.
	VersionDraft08 Version = 0x80000008

	// VersionDraft11 is draft-ietf-ntp-roughtime-11.
	VersionDraft11 Version = 0x8000000b
)

func ResponseVersionFromSupported

func ResponseVersionFromSupported(supportedVersions []Version) (Version, error)

ResponseVersionFromSupported selects a version to use from the list of versions supported by the clients. Returns an error if the input slice is zero-length.

func (Version) String

func (ver Version) String() string