key

package
v1.79.0-mod Latest Latest
Warning

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

Go to latest
Published: Dec 9, 2024 License: BSD-3-Clause Imports: 17 Imported by: 0

Documentation

Overview

Package key contains types for different types of public and private keys used by Tailscale.

Index

Constants

View Source
const (

	// DiscoPublicRawLen is the length in bytes of a DiscoPublic, when
	// serialized with AppendTo, Raw32 or WriteRawWithoutAllocating.
	DiscoPublicRawLen = 32
)
View Source
const (

	// NodePublicRawLen is the length in bytes of a NodePublic, when
	// serialized with AppendTo, Raw32 or WriteRawWithoutAllocating.
	NodePublicRawLen = 32
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ChallengePrivate

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

ChallengePrivate is a challenge key, used to test whether clients control a key they want to prove ownership of.

A ChallengePrivate is ephemeral and not serialized to the disk or network.

func NewChallenge

func NewChallenge() ChallengePrivate

NewChallenge creates and returns a new node private key.

func (ChallengePrivate) MarshalText

func (k ChallengePrivate) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, but by returning an error. It shouldn't need to be marshalled anywhere.

func (ChallengePrivate) OpenFrom

func (k ChallengePrivate) OpenFrom(p NodePublic, ciphertext []byte) (cleartext []byte, ok bool)

OpenFrom opens the NaCl box ciphertext, which must be a value created by NodePrivate.SealToChallenge, and returns the inner cleartext if ciphertext is a valid box from p to k.

func (ChallengePrivate) Public

func (k ChallengePrivate) Public() ChallengePublic

Public returns the ChallengePublic for k. Panics if ChallengePublic is zero.

type ChallengePublic

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

ChallengePublic is the public portion of a ChallengePrivate.

func (ChallengePublic) AppendText

func (k ChallengePublic) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (ChallengePublic) IsZero

func (k ChallengePublic) IsZero() bool

IsZero reports whether k is the zero value.

func (ChallengePublic) MarshalText

func (k ChallengePublic) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (ChallengePublic) String

func (k ChallengePublic) String() string

String returns the output of MarshalText as a string.

func (*ChallengePublic) UnmarshalText

func (k *ChallengePublic) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type ControlPrivate deprecated

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

ControlPrivate is a Tailscale control plane private key.

It is functionally equivalent to a MachinePrivate, but serializes to JSON as a byte array rather than a typed string, because our control plane database stores the key that way.

Deprecated: this type should only be used in Tailscale's control plane, where existing database serializations require this less-good serialization format to persist. Other control plane implementations can use MachinePrivate with no downsides.

func NewControl

func NewControl() ControlPrivate

NewControl generates and returns a new control plane private key.

func (ControlPrivate) IsZero

func (k ControlPrivate) IsZero() bool

IsZero reports whether k is the zero value.

func (ControlPrivate) MarshalJSON

func (k ControlPrivate) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (ControlPrivate) OpenFrom

func (k ControlPrivate) OpenFrom(p MachinePublic, ciphertext []byte) (cleartext []byte, ok bool)

OpenFrom opens the NaCl box ciphertext, which must be a value created by SealTo, and returns the inner cleartext if ciphertext is a valid box from p to k.

func (ControlPrivate) Public

func (k ControlPrivate) Public() MachinePublic

Public returns the MachinePublic for k. Panics if ControlPrivate is zero.

func (ControlPrivate) SealTo

func (k ControlPrivate) SealTo(p MachinePublic, cleartext []byte) (ciphertext []byte)

SealTo wraps cleartext into a NaCl box (see golang.org/x/crypto/nacl) to p, authenticated from k, using a random nonce.

The returned ciphertext is a 24-byte nonce concatenated with the box value.

func (ControlPrivate) SharedKey

SharedKey returns the precomputed Nacl box shared key between k and p.

func (*ControlPrivate) UnmarshalJSON

func (k *ControlPrivate) UnmarshalJSON(bs []byte) error

UnmarshalJSON implements json.Unmarshaler.

type DiscoPrivate

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

DiscoPrivate is a disco key, used for peer-to-peer path discovery.

func NewDisco

func NewDisco() DiscoPrivate

NewDisco creates and returns a new disco private key.

func (DiscoPrivate) Equal

func (k DiscoPrivate) Equal(other DiscoPrivate) bool

Equal reports whether k and other are the same key.

func (DiscoPrivate) IsZero

func (k DiscoPrivate) IsZero() bool

IsZero reports whether k is the zero value.

func (DiscoPrivate) Public

func (k DiscoPrivate) Public() DiscoPublic

Public returns the DiscoPublic for k. Panics if DiscoPrivate is zero.

func (DiscoPrivate) Shared

func (k DiscoPrivate) Shared(p DiscoPublic) DiscoShared

Shared returns the DiscoShared for communication between k and p.

type DiscoPublic

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

DiscoPublic is the public portion of a DiscoPrivate.

func DiscoPublicFromRaw32

func DiscoPublicFromRaw32(raw mem.RO) DiscoPublic

DiscoPublicFromRaw32 parses a 32-byte raw value as a DiscoPublic.

This should be used only when deserializing a DiscoPublic from a binary protocol.

func (DiscoPublic) AppendText

func (k DiscoPublic) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (DiscoPublic) AppendTo

func (k DiscoPublic) AppendTo(buf []byte) []byte

AppendTo appends k, serialized as a 32-byte binary value, to buf. Returns the new slice.

func (DiscoPublic) Compare

func (k DiscoPublic) Compare(l DiscoPublic) int

Compare returns an integer comparing DiscoPublic k and l lexicographically. The result will be 0 if k == l, -1 if k < l, and +1 if k > l. This is useful for situations requiring only one node in a pair to perform some operation, e.g. probing UDP path lifetime.

func (DiscoPublic) IsZero

func (k DiscoPublic) IsZero() bool

IsZero reports whether k is the zero value.

func (DiscoPublic) MarshalText

func (k DiscoPublic) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (DiscoPublic) Raw32 deprecated

func (k DiscoPublic) Raw32() [32]byte

Raw32 returns k encoded as 32 raw bytes.

Deprecated: only needed for a temporary compat shim in tailcfg, do not add more uses.

func (DiscoPublic) ShortString

func (k DiscoPublic) ShortString() string

ShortString returns the Tailscale conventional debug representation of a disco key.

func (DiscoPublic) String

func (k DiscoPublic) String() string

String returns the output of MarshalText as a string.

func (*DiscoPublic) UnmarshalText

func (k *DiscoPublic) UnmarshalText(b []byte) error

MarshalText implements encoding.TextUnmarshaler.

type DiscoShared

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

func (DiscoShared) Equal

func (k DiscoShared) Equal(other DiscoShared) bool

Equal reports whether k and other are the same key.

func (DiscoShared) IsZero

func (k DiscoShared) IsZero() bool

func (DiscoShared) Open

func (k DiscoShared) Open(ciphertext []byte) (cleartext []byte, ok bool)

Open opens the NaCl box ciphertext, which must be a value created by Seal, and returns the inner cleartext if ciphertext is a valid box using shared secret k.

func (DiscoShared) Seal

func (k DiscoShared) Seal(cleartext []byte) (ciphertext []byte)

Seal wraps cleartext into a NaCl box (see golang.org/x/crypto/nacl), using k as the shared secret and a random nonce.

type MachinePrecomputedSharedKey

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

MachinePrecomputedSharedKey is a precomputed shared NaCl box shared key.

func (MachinePrecomputedSharedKey) Open

func (k MachinePrecomputedSharedKey) Open(ciphertext []byte) (cleartext []byte, ok bool)

Open opens the NaCl box ciphertext, which must be a value created by MachinePrecomputedSharedKey.Seal or MachinePrivate.SealTo, and returns the inner cleartext if ciphertext is a valid box for the shared key k.

func (MachinePrecomputedSharedKey) Seal

func (k MachinePrecomputedSharedKey) Seal(cleartext []byte) (ciphertext []byte)

Seal wraps cleartext into a NaCl box (see golang.org/x/crypto/nacl) using the shared key k as generated by MachinePrivate.SharedKey.

The returned ciphertext is a 24-byte nonce concatenated with the box value.

type MachinePrivate

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

MachinePrivate is a machine key, used for communication with the Tailscale coordination server.

func NewMachine

func NewMachine() MachinePrivate

NewMachine creates and returns a new machine private key.

func (MachinePrivate) AppendText

func (k MachinePrivate) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (MachinePrivate) Equal

func (k MachinePrivate) Equal(other MachinePrivate) bool

Equal reports whether k and other are the same key.

func (MachinePrivate) IsZero

func (k MachinePrivate) IsZero() bool

IsZero reports whether k is the zero value.

func (MachinePrivate) MarshalText

func (k MachinePrivate) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (MachinePrivate) OpenFrom

func (k MachinePrivate) OpenFrom(p MachinePublic, ciphertext []byte) (cleartext []byte, ok bool)

OpenFrom opens the NaCl box ciphertext, which must be a value created by SealTo, and returns the inner cleartext if ciphertext is a valid box from p to k.

func (MachinePrivate) Public

func (k MachinePrivate) Public() MachinePublic

Public returns the MachinePublic for k. Panics if MachinePrivate is zero.

func (MachinePrivate) SealTo

func (k MachinePrivate) SealTo(p MachinePublic, cleartext []byte) (ciphertext []byte)

SealTo wraps cleartext into a NaCl box (see golang.org/x/crypto/nacl) to p, authenticated from k, using a random nonce.

The returned ciphertext is a 24-byte nonce concatenated with the box value.

func (MachinePrivate) SharedKey

SharedKey returns the precomputed Nacl box shared key between k and p.

func (*MachinePrivate) UnmarshalText

func (k *MachinePrivate) UnmarshalText(b []byte) error

MarshalText implements encoding.TextUnmarshaler.

func (MachinePrivate) UntypedBytes deprecated

func (k MachinePrivate) UntypedBytes() []byte

UntypedBytes returns k, encoded as an untyped 64-character hex string.

Deprecated: this function is risky to use, because it produces serialized values that do not identify themselves as a MachinePrivate, allowing other code to potentially parse it back in as the wrong key type. For new uses that don't require this specific raw byte serialization, please use MarshalText/UnmarshalText.

type MachinePublic

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

MachinePublic is the public portion of a a MachinePrivate.

func MachinePublicFromRaw32

func MachinePublicFromRaw32(raw mem.RO) MachinePublic

MachinePublicFromRaw32 parses a 32-byte raw value as a MachinePublic.

This should be used only when deserializing a MachinePublic from a binary protocol.

func ParseMachinePublicUntyped deprecated

func ParseMachinePublicUntyped(raw mem.RO) (MachinePublic, error)

ParseMachinePublicUntyped parses an untyped 64-character hex value as a MachinePublic.

Deprecated: this function is risky to use, because it cannot verify that the hex string was intended to be a MachinePublic. This can lead to accidentally decoding one type of key as another. For new uses that don't require backwards compatibility with the untyped string format, please use MarshalText/UnmarshalText.

func (MachinePublic) AppendText

func (k MachinePublic) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (MachinePublic) IsZero

func (k MachinePublic) IsZero() bool

IsZero reports whether k is the zero value.

func (MachinePublic) MarshalText

func (k MachinePublic) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (MachinePublic) ShortString

func (k MachinePublic) ShortString() string

ShortString returns the Tailscale conventional debug representation of a public key: the first five base64 digits of the key, in square brackets.

func (MachinePublic) String

func (k MachinePublic) String() string

String returns the output of MarshalText as a string.

func (*MachinePublic) UnmarshalText

func (k *MachinePublic) UnmarshalText(b []byte) error

MarshalText implements encoding.TextUnmarshaler.

func (MachinePublic) UntypedBytes deprecated

func (k MachinePublic) UntypedBytes() []byte

UntypedBytes returns k, encoded as an untyped 64-character hex string.

Deprecated: this function is risky to use, because it produces serialized values that do not identify themselves as a MachinePublic, allowing other code to potentially parse it back in as the wrong key type. For new uses that don't require this specific raw byte serialization, please use MarshalText/UnmarshalText.

func (MachinePublic) UntypedHexString deprecated

func (k MachinePublic) UntypedHexString() string

UntypedHexString returns k, encoded as an untyped 64-character hex string.

Deprecated: this function is risky to use, because it produces serialized values that do not identify themselves as a MachinePublic, allowing other code to potentially parse it back in as the wrong key type. For new uses that don't require backwards compatibility with the untyped string format, please use MarshalText/UnmarshalText.

type NLPrivate

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

NLPrivate is a node-managed network-lock key, used for signing node-key signatures and authority update messages.

func NewNLPrivate

func NewNLPrivate() NLPrivate

NewNLPrivate creates and returns a new network-lock key.

func (NLPrivate) AppendText

func (k NLPrivate) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (NLPrivate) Equal

func (k NLPrivate) Equal(other NLPrivate) bool

Equal reports whether k and other are the same key.

func (NLPrivate) IsZero

func (k NLPrivate) IsZero() bool

IsZero reports whether k is the zero value.

func (NLPrivate) KeyID

func (k NLPrivate) KeyID() tkatype.KeyID

KeyID returns an identifier for this key.

func (NLPrivate) MarshalText

func (k NLPrivate) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (NLPrivate) Public

func (k NLPrivate) Public() NLPublic

Public returns the public component of this key.

func (NLPrivate) SignAUM

func (k NLPrivate) SignAUM(sigHash tkatype.AUMSigHash) ([]tkatype.Signature, error)

SignAUM implements tka.Signer.

func (NLPrivate) SignNKS

func (k NLPrivate) SignNKS(sigHash tkatype.NKSSigHash) ([]byte, error)

SignNKS signs the tka.NodeKeySignature identified by sigHash.

func (*NLPrivate) UnmarshalText

func (k *NLPrivate) UnmarshalText(b []byte) error

MarshalText implements encoding.TextUnmarshaler.

type NLPublic

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

NLPublic is the public portion of a a NLPrivate.

func NLPublicFromEd25519Unsafe

func NLPublicFromEd25519Unsafe(public ed25519.PublicKey) NLPublic

NLPublicFromEd25519Unsafe converts an ed25519 public key into a type of NLPublic.

New uses of this function should be avoided, as its possible to accidentally construct an NLPublic from a non network-lock key.

func (NLPublic) AppendText

func (k NLPublic) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (NLPublic) CLIString

func (k NLPublic) CLIString() string

CLIString returns a marshalled representation suitable for use with tailnet lock commands, of the form tlpub:<hex> instead of the nlpub:<hex> form emitted by MarshalText. Both forms can be decoded by UnmarshalText.

func (NLPublic) Equal

func (k NLPublic) Equal(other NLPublic) bool

Equal reports whether k and other are the same key.

func (NLPublic) IsZero

func (k NLPublic) IsZero() bool

IsZero reports whether k is the zero value.

func (NLPublic) KeyID

func (k NLPublic) KeyID() tkatype.KeyID

KeyID returns a tkatype.KeyID that can be used with a tka.Authority.

func (NLPublic) MarshalText

func (k NLPublic) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, emitting a representation of the form nlpub:<hex>.

func (*NLPublic) UnmarshalText

func (k *NLPublic) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler. This function is able to decode both the CLI form (tlpub:<hex>) & the regular form (nlpub:<hex>).

func (NLPublic) Verifier

func (k NLPublic) Verifier() ed25519.PublicKey

Verifier returns a ed25519.PublicKey that can be used to verify signatures.

type NodePrivate

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

NodePrivate is a node key, used for WireGuard tunnels and communication with DERP servers.

func NewNode

func NewNode() NodePrivate

NewNode creates and returns a new node private key.

func NodePrivateFromRaw32 deprecated

func NodePrivateFromRaw32(raw mem.RO) NodePrivate

NodePrivateFromRaw32 parses a 32-byte raw value as a NodePrivate.

Deprecated: only needed to cast from legacy node private key types, do not add more uses unrelated to #3206.

func ParseNodePrivateUntyped

func ParseNodePrivateUntyped(raw mem.RO) (NodePrivate, error)

func (NodePrivate) AppendText

func (k NodePrivate) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender.

func (NodePrivate) Equal

func (k NodePrivate) Equal(other NodePrivate) bool

Equal reports whether k and other are the same key.

func (NodePrivate) IsZero

func (k NodePrivate) IsZero() bool

IsZero reports whether k is the zero value.

func (NodePrivate) MarshalText

func (k NodePrivate) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (NodePrivate) OpenFrom

func (k NodePrivate) OpenFrom(p NodePublic, ciphertext []byte) (cleartext []byte, ok bool)

OpenFrom opens the NaCl box ciphertext, which must be a value created by SealTo, and returns the inner cleartext if ciphertext is a valid box from p to k.

func (NodePrivate) Public

func (k NodePrivate) Public() NodePublic

Public returns the NodePublic for k. Panics if NodePrivate is zero.

func (NodePrivate) SealTo

func (k NodePrivate) SealTo(p NodePublic, cleartext []byte) (ciphertext []byte)

SealTo wraps cleartext into a NaCl box (see golang.org/x/crypto/nacl) to p, authenticated from k, using a random nonce.

The returned ciphertext is a 24-byte nonce concatenated with the box value.

func (NodePrivate) SealToChallenge

func (k NodePrivate) SealToChallenge(p ChallengePublic, cleartext []byte) (ciphertext []byte)

SealToChallenge is like SealTo, but for a ChallengePublic.

func (*NodePrivate) UnmarshalText

func (k *NodePrivate) UnmarshalText(b []byte) error

MarshalText implements encoding.TextUnmarshaler.

func (NodePrivate) UntypedHexString

func (k NodePrivate) UntypedHexString() string

type NodePublic

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

NodePublic is the public portion of a NodePrivate.

func NodePublicFromRaw32

func NodePublicFromRaw32(raw mem.RO) NodePublic

NodePublicFromRaw32 parses a 32-byte raw value as a NodePublic.

This should be used only when deserializing a NodePublic from a binary protocol.

func NodePublicWithBadOldPrefix

func NodePublicWithBadOldPrefix(k NodePublic) NodePublic

NodePublicWithBadOldPrefix returns a copy of k with its leading public key bytes mutated such that it base64's to a ShortString of [bad01] ("bad ol'" [expired node key]).

func ParseNodePublicUntyped deprecated

func ParseNodePublicUntyped(raw mem.RO) (NodePublic, error)

ParseNodePublicUntyped parses an untyped 64-character hex value as a NodePublic.

Deprecated: this function is risky to use, because it cannot verify that the hex string was intended to be a NodePublic. This can lead to accidentally decoding one type of key as another. For new uses that don't require backwards compatibility with the untyped string format, please use MarshalText/UnmarshalText.

func (NodePublic) AppendText

func (k NodePublic) AppendText(b []byte) ([]byte, error)

AppendText implements encoding.TextAppender. It appends a typed prefix followed by hex encoded represtation of k to b.

func (NodePublic) AppendTo

func (k NodePublic) AppendTo(buf []byte) []byte

AppendTo appends k, serialized as a 32-byte binary value, to buf. Returns the new slice.

func (NodePublic) Compare

func (p NodePublic) Compare(p2 NodePublic) int

Compare returns -1, 0, or 1, depending on whether p orders before p2, using bytes.Compare on the bytes of the public key.

func (NodePublic) IsZero

func (k NodePublic) IsZero() bool

IsZero reports whether k is the zero value.

func (NodePublic) Less

func (k NodePublic) Less(other NodePublic) bool

Less reports whether k orders before other, using an undocumented deterministic ordering.

func (NodePublic) MarshalBinary

func (k NodePublic) MarshalBinary() (data []byte, err error)

MarshalBinary implements encoding.BinaryMarshaler.

func (NodePublic) MarshalText

func (k NodePublic) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It returns a typed prefix followed by a hex encoded representation of k.

func (NodePublic) Raw32 deprecated

func (k NodePublic) Raw32() [32]byte

Raw32 returns k encoded as 32 raw bytes.

Deprecated: only needed for a single legacy use in the control server and a few places in the wireguard-go API; don't add more uses.

func (*NodePublic) ReadRawWithoutAllocating

func (k *NodePublic) ReadRawWithoutAllocating(br *bufio.Reader) error

ReadRawWithoutAllocating initializes k with bytes read from br. The reading is done ~4x slower than io.ReadFull, but in exchange is allocation-free.

func (NodePublic) Shard

func (p NodePublic) Shard() uint8

Shard returns a uint8 number from a public key with mostly-uniform distribution, suitable for sharding.

func (NodePublic) ShortString

func (k NodePublic) ShortString() string

ShortString returns the Tailscale conventional debug representation of a public key: the first five base64 digits of the key, in square brackets.

func (NodePublic) String

func (k NodePublic) String() string

String returns k as a hex-encoded string with a type prefix.

func (*NodePublic) UnmarshalBinary

func (k *NodePublic) UnmarshalBinary(in []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*NodePublic) UnmarshalText

func (k *NodePublic) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It expects a typed prefix followed by a hex encoded representation of k.

func (NodePublic) UntypedHexString deprecated

func (k NodePublic) UntypedHexString() string

UntypedHexString returns k, encoded as an untyped 64-character hex string.

Deprecated: this function is risky to use, because it produces serialized values that do not identify themselves as a NodePublic, allowing other code to potentially parse it back in as the wrong key type. For new uses that don't require backwards compatibility with the untyped string format, please use MarshalText/UnmarshalText.

func (NodePublic) WireGuardGoString

func (k NodePublic) WireGuardGoString() string

WireGuardGoString prints k in the same format used by wireguard-go.

func (NodePublic) WriteRawWithoutAllocating

func (k NodePublic) WriteRawWithoutAllocating(bw *bufio.Writer) error

WriteRawWithoutAllocating writes out k as 32 bytes to bw. The writing is done ~3x slower than bw.Write, but in exchange is allocation-free.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL