tka

package
v1.33.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 7, 2022 License: BSD-3-Clause Imports: 17 Imported by: 0

Documentation

Overview

Package tka (WIP) implements the Tailnet Key Authority.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoIntersection = errors.New("no intersection")

ErrNoIntersection is returned when a shared AUM could not be determined when evaluating a remote sync offer.

View Source 
var ErrNoSuchKey = errors.New("key not found")

ErrNoSuchKey is returned if the key referenced by a KeyID does not exist.

Functions

func Create 

func Create(storage Chonk, state State, signer Signer) (*Authority, AUM, error)

Create initializes a brand-new TKA, generating a genesis update and committing it to the given storage.

The given signer must also be present in state as a trusted key.

Do not use this to initialize a TKA that already exists, use Open() or Bootstrap() instead.

Types

type AUM 

type AUM struct {
	MessageKind AUMKind `cbor:"1,keyasint"`
	PrevAUMHash []byte  `cbor:"2,keyasint"`

	// Key encodes a public key to be added to the key authority.
	// This field is used for AddKey AUMs.
	Key *Key `cbor:"3,keyasint,omitempty"`

	// KeyID references a public key which is part of the key authority.
	// This field is used for RemoveKey and UpdateKey AUMs.
	KeyID tkatype.KeyID `cbor:"4,keyasint,omitempty"`

	// State describes the full state of the key authority.
	// This field is used for Checkpoint AUMs.
	State *State `cbor:"5,keyasint,omitempty"`

	// DisablementSecret is used to transmit a secret for disabling
	// the TKA.
	// This field is used for DisableNL AUMs.
	DisablementSecret []byte `cbor:"6,keyasint,omitempty"`

	// Votes and Meta describe properties of a key in the key authority.
	// These fields are used for UpdateKey AUMs.
	Votes *uint             `cbor:"7,keyasint,omitempty"`
	Meta  map[string]string `cbor:"8,keyasint,omitempty"`

	// Signatures lists the signatures over this AUM.
	// CBOR key 23 is the last key which can be encoded as a single byte.
	Signatures []tkatype.Signature `cbor:"23,keyasint,omitempty"`
}

AUM describes an Authority Update Message.

The rules for adding new types of AUMs (MessageKind):

  • CBOR key IDs must never be changed.
  • New AUM types must not change semantics that are manipulated by other AUM types.
  • The serialization of existing data cannot change (in other words, if an existing serialization test in aum_test.go fails, you need to try a different approach).

The rules for adding new fields are as follows:

  • Must all be optional.
  • An unset value must not result in serialization overhead. This is necessary so the serialization of older AUMs stays the same.
  • New processing semantics of the new fields must be compatible with the behavior of old clients (which will ignore the field).
  • No floats!

func (*AUM) Hash 

func (a *AUM) Hash() AUMHash

Hash returns a cryptographic digest of all AUM contents.

func (*AUM) Parent 

func (a *AUM) Parent() (h AUMHash, ok bool)

Parent returns the parent's AUM hash and true, or a zero value and false if there was no parent.

func (*AUM) Serialize 

func (a *AUM) Serialize() []byte

Serialize returns the given AUM in a serialized format.

func (AUM) SigHash 

func (a AUM) SigHash() tkatype.AUMSigHash

SigHash returns the cryptographic digest which a signature is over.

This is identical to Hash() except the Signatures are not serialized. Without this, the hash used for signatures would be circularly dependent on the signatures.

func (*AUM) StaticValidate 

func (a *AUM) StaticValidate() error

StaticValidate returns a nil error if the AUM is well-formed.

func (*AUM) Weight 

func (a *AUM) Weight(state State) uint

Weight computes the 'signature weight' of the AUM based on keys in the state machine. The caller must ensure that all signatures are valid.

More formally: W = Sum(key.votes)

AUMs with a higher weight than their siblings are preferred when resolving forks in the AUM chain.

type AUMHash 

type AUMHash [blake2s.Size]byte

AUMHash represents the BLAKE2s digest of an Authority Update Message (AUM).

type AUMKind 

type AUMKind uint8

AUMKind describes valid AUM types. 

const (
	AUMInvalid AUMKind = iota
	// An AddKey AUM describes a new key trusted by the TKA.
	//
	// Only the Key optional field may be set.
	AUMAddKey
	// A RemoveKey AUM describes hte removal of a key trusted by TKA.
	//
	// Only the KeyID optional field may be set.
	AUMRemoveKey
	// A DisableNL AUM describes the disablement of TKA.
	//
	// Only the DisablementSecret optional field may be set.
	AUMDisableNL
	// A NoOp AUM carries no information and is used in tests.
	AUMNoOp
	// A UpdateKey AUM updates the metadata or votes of an existing key.
	//
	// Only KeyID, along with either/or Meta or Votes optional fields
	// may be set.
	AUMUpdateKey
	// A Checkpoint AUM specifies the full state of the TKA.
	//
	// Only the State optional field may be set.
	AUMCheckpoint
)

Valid AUM types. Do NOT reorder.

func (AUMKind) String 

func (k AUMKind) String() string

type Authority 

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

Authority is a Tailnet Key Authority. This type is the main coupling point to the rest of the tailscale client.

Authority objects can either be created from an existing, non-empty tailchonk (via tka.Open()), or created from scratch using tka.Bootstrap() or tka.Create().

func Bootstrap 

func Bootstrap(storage Chonk, bootstrap AUM) (*Authority, error)

Bootstrap initializes a TKA based on the given checkpoint.

Call this when setting up a new nodes' TKA, but other nodes with initialized TKA's exist.

Pass the returned genesis AUM from Create(), or a later checkpoint AUM.

TODO(tom): We should test an authority bootstrapped from a later checkpoint works fine with sync and everything.

func Open 

func Open(storage Chonk) (*Authority, error)

Open initializes an existing TKA from the given tailchonk.

Only use this if the current node has initialized an Authority before. If a TKA exists on other nodes but theres nothing locally, use Bootstrap(). If no TKA exists anywhere and you are creating it for the first time, use New().

func (*Authority) Head 

func (a *Authority) Head() AUMHash

Head returns the AUM digest of the latest update applied to the state machine.

func (*Authority) Inform 

func (a *Authority) Inform(updates []AUM) error

Inform is called to tell the authority about new updates. Updates should be ordered oldest to newest. An error is returned if any of the updates could not be processed.

func (*Authority) MissingAUMs 

func (a *Authority) MissingAUMs(remoteOffer SyncOffer) ([]AUM, error)

MissingAUMs returns AUMs a remote may be missing based on the remotes' SyncOffer.

func (*Authority) NewUpdater 

func (a *Authority) NewUpdater(signer Signer) *UpdateBuilder

NewUpdater returns a builder you can use to make changes to the tailnet key authority.

The provided signer function, if non-nil, is called with each update to compute and apply signatures.

Updates are specified by calling methods on the returned UpdatedBuilder. Call Finalize() when you are done to obtain the specific update messages which actuate the changes.

func (*Authority) SyncOffer 

func (a *Authority) SyncOffer() (SyncOffer, error)

SyncOffer returns an abbreviated description of the current AUM chain, which can be used to synchronize with another (untrusted) Authority instance.

The returned SyncOffer structure should be transmitted to the remote Authority, which should call MissingAUMs() using it to determine AUMs which need to be transmitted. This list of AUMs from the remote can then be applied locally with Inform().

This SyncOffer + AUM exchange should be performed by both ends, because its possible that either end has AUMs that the other needs to find out about.

func (*Authority) VerifySignature 

func (a *Authority) VerifySignature(nodeKeySignature tkatype.MarshaledSignature) error

VerifySignature returns true if the provided nodeKeySignature is signed correctly by a trusted key.

type Chonk 

type Chonk interface {
	// AUM returns the AUM with the specified digest.
	//
	// If the AUM does not exist, then os.ErrNotExist is returned.
	AUM(hash AUMHash) (AUM, error)

	// ChildAUMs returns all AUMs with a specified previous
	// AUM hash.
	ChildAUMs(prevAUMHash AUMHash) ([]AUM, error)

	// CommitVerifiedAUMs durably stores the provided AUMs.
	// Callers MUST ONLY provide AUMs which are verified (specifically,
	// a call to aumVerify() must return a nil error).
	// as the implementation assumes that only verified AUMs are stored.
	CommitVerifiedAUMs(updates []AUM) error

	// Heads returns AUMs for which there are no children. In other
	// words, the latest AUM in all possible chains (the 'leaves').
	Heads() ([]AUM, error)

	// SetLastActiveAncestor is called to record the oldest-known AUM
	// that contributed to the current state. This value is used as
	// a hint on next startup to determine which chain to pick when computing
	// the current state, if there are multiple distinct chains.
	SetLastActiveAncestor(hash AUMHash) error

	// LastActiveAncestor returns the oldest-known AUM that was (in a
	// previous run) an ancestor of the current state. This is used
	// as a hint to pick the correct chain in the event that the Chonk stores
	// multiple distinct chains.
	LastActiveAncestor() (*AUMHash, error)
}

Chonk implementations provide durable storage for AUMs and other TKA state.

All methods must be thread-safe.

The name 'tailchonk' was coined by @catzkorn.

type FS 

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

FS implements filesystem storage of TKA state.

FS implements the Chonk interface.

func ChonkDir 

func ChonkDir(dir string) (*FS, error)

ChonkDir returns an implementation of Chonk which uses the given directory to store TKA state.

func (*FS) AUM 

func (c *FS) AUM(hash AUMHash) (AUM, error)

AUM returns the AUM with the specified digest.

If the AUM does not exist, then os.ErrNotExist is returned.

func (*FS) ChildAUMs 

func (c *FS) ChildAUMs(prevAUMHash AUMHash) ([]AUM, error)

AUM returns any known AUMs with a specific parent hash.

func (*FS) CommitVerifiedAUMs 

func (c *FS) CommitVerifiedAUMs(updates []AUM) error

CommitVerifiedAUMs durably stores the provided AUMs. Callers MUST ONLY provide AUMs which are verified (specifically, a call to aumVerify must return a nil error), as the implementation assumes that only verified AUMs are stored.

func (*FS) Heads 

func (c *FS) Heads() ([]AUM, error)

Heads returns AUMs for which there are no children. In other words, the latest AUM in all possible chains (the 'leaves').

Heads is expected to be called infrequently compared to AUM() or ChildAUMs(), so we haven't put any work into maintaining an index. Instead, the full set of AUMs is scanned.

func (*FS) LastActiveAncestor 

func (c *FS) LastActiveAncestor() (*AUMHash, error)

LastActiveAncestor returns the oldest-known AUM that was (in a previous run) an ancestor of the current state. This is used as a hint to pick the correct chain in the event that the Chonk stores multiple distinct chains.

Nil is returned if no last-active ancestor is set.

func (*FS) SetLastActiveAncestor 

func (c *FS) SetLastActiveAncestor(hash AUMHash) error

SetLastActiveAncestor is called to record the oldest-known AUM that contributed to the current state. This value is used as a hint on next startup to determine which chain to pick when computing the current state, if there are multiple distinct chains.

type Key 

type Key struct {
	Kind KeyKind `cbor:"1,keyasint"`

	// Votes describes the weight applied to signatures using this key.
	// Weighting is used to deterministically resolve branches in the AUM
	// chain (i.e. forks, where two AUMs exist with the same parent).
	Votes uint `cbor:"2,keyasint"`

	// Public encodes the public key of the key. For 25519 keys,
	// this is simply the point on the curve representing the public
	// key.
	Public []byte `cbor:"3,keyasint"`

	// Meta describes arbitrary metadata about the key. This could be
	// used to store the name of the key, for instance.
	Meta map[string]string `cbor:"12,keyasint,omitempty"`
}

Key describes the public components of a key known to network-lock.

func (Key) Clone 

func (k Key) Clone() Key

Clone makes an independent copy of Key.

NOTE: There is a difference between a nil slice and an empty slice for encoding purposes, so an implementation of Clone() must take care to preserve this.

func (Key) ID 

func (k Key) ID() tkatype.KeyID

func (Key) StaticValidate 

func (k Key) StaticValidate() error

type KeyKind 

type KeyKind uint8

KeyKind describes the different varieties of a Key. 

const (
	KeyInvalid KeyKind = iota
	Key25519
)

Valid KeyKind values.

func (KeyKind) String 

func (k KeyKind) String() string

type Mem 

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

Mem implements in-memory storage of TKA state, suitable for tests.

Mem implements the Chonk interface.

func (*Mem) AUM 

func (c *Mem) AUM(hash AUMHash) (AUM, error)

AUM returns the AUM with the specified digest.

func (*Mem) ChildAUMs 

func (c *Mem) ChildAUMs(prevAUMHash AUMHash) ([]AUM, error)

ChildAUMs returns all AUMs with a specified previous AUM hash.

func (*Mem) CommitVerifiedAUMs 

func (c *Mem) CommitVerifiedAUMs(updates []AUM) error

CommitVerifiedAUMs durably stores the provided AUMs. Callers MUST ONLY provide well-formed and verified AUMs, as the rest of the TKA implementation assumes that only verified AUMs are stored.

func (*Mem) Heads 

func (c *Mem) Heads() ([]AUM, error)

Heads returns AUMs for which there are no children. In other words, the latest AUM in all chains (the 'leaf').

func (*Mem) LastActiveAncestor 

func (c *Mem) LastActiveAncestor() (*AUMHash, error)

func (*Mem) Orphans 

func (c *Mem) Orphans() ([]AUM, error)

Orphans returns all AUMs which do not have a parent.

func (*Mem) SetLastActiveAncestor 

func (c *Mem) SetLastActiveAncestor(hash AUMHash) error

type NodeKeySignature 

type NodeKeySignature struct {
	// SigKind identifies the variety of signature.
	SigKind SigKind `cbor:"1,keyasint"`
	// Pubkey identifies the public key which is being certified.
	Pubkey []byte `cbor:"2,keyasint"`

	// KeyID identifies which key in the tailnet key authority should
	// be used to verify this signature. Only set for SigDirect and
	// SigCredential signature kinds.
	KeyID []byte `cbor:"3,keyasint,omitempty"`

	// Signature is the packed (R, S) ed25519 signature over the rest
	// of the structure.
	Signature []byte `cbor:"4,keyasint,omitempty"`
}

NodeKeySignature encapsulates a signature that authorizes a specific node key, based on verification from keys in the tailnet key authority.

func (*NodeKeySignature) Serialize 

func (s *NodeKeySignature) Serialize() tkatype.MarshaledSignature

Serialize returns the given NKS in a serialized format.

type SigKind 

type SigKind uint8

SigKind describes valid NodeKeySignature types. 

const (
	SigInvalid SigKind = iota
	// SigDirect describes a signature over a specific node key, using
	// the keyID specified.
	SigDirect
)

func (SigKind) String 

func (s SigKind) String() string

type Signer 

type Signer interface {
	SignAUM(tkatype.AUMSigHash) ([]tkatype.Signature, error)
}

Types implementing Signer can sign update messages.

type State 

type State struct {
	// LastAUMHash is the blake2s digest of the last-applied AUM.
	// Because AUMs are strictly ordered and form a hash chain, we
	// check the previous AUM hash in an update we are applying
	// is the same as the LastAUMHash.
	LastAUMHash *AUMHash `cbor:"1,keyasint"`

	// DisablementSecrets are KDF-derived values which can be used
	// to turn off the TKA in the event of a consensus-breaking bug.
	// An AUM of type DisableNL should contain a secret when results
	// in one of these values when run through the disablement KDF.
	//
	// TODO(tom): This is an alpha feature, remove this mechanism once
	//            we have confidence in our implementation.
	DisablementSecrets [][]byte `cbor:"2,keyasint"`

	// Keys are the public keys currently trusted by the TKA.
	Keys []Key `cbor:"3,keyasint"`
}

State describes Tailnet Key Authority state at an instant in time.

State is mutated by applying Authority Update Messages (AUMs), resulting in a new State.

func (State) Clone 

func (s State) Clone() State

Clone makes an independent copy of State.

NOTE: There is a difference between a nil slice and an empty slice for encoding purposes, so an implementation of Clone() must take care to preserve this.

func (State) GetKey 

func (s State) GetKey(key tkatype.KeyID) (Key, error)

GetKey returns the trusted key with the specified KeyID.

type SyncOffer 

type SyncOffer struct {
	Head      AUMHash
	Ancestors []AUMHash
}

SyncOffer conveys information about the current head & ancestor AUMs, for the purpose of synchronization with some remote end.

Ancestors should contain a subset of the ancestors of the chain. The last entry in that slice is the oldest-known AUM in the chain.

type UpdateBuilder 

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

UpdateBuilder implements a builder for changes to the tailnet key authority.

Finalize must be called to compute the update messages, which must then be applied to all Authority objects using Inform().

func (*UpdateBuilder) AddKey 

func (b *UpdateBuilder) AddKey(key Key) error

AddKey adds a new key to the authority.

func (*UpdateBuilder) Finalize 

func (b *UpdateBuilder) Finalize() ([]AUM, error)

Finalize returns the set of update message to actuate the update.

func (*UpdateBuilder) RemoveKey 

func (b *UpdateBuilder) RemoveKey(keyID tkatype.KeyID) error

RemoveKey removes a key from the authority.

func (*UpdateBuilder) SetKeyMeta 

func (b *UpdateBuilder) SetKeyMeta(keyID tkatype.KeyID, meta map[string]string) error

SetKeyMeta updates key-value metadata stored against an existing key.

TODO(tom): Provide an API to update specific values rather than the whole map.

func (*UpdateBuilder) SetKeyVote 

func (b *UpdateBuilder) SetKeyVote(keyID tkatype.KeyID, votes uint) error

SetKeyVote updates the number of votes of an existing key.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.