crypto

Documentation

Overview

Package crypto is a wrapper around packages under golang.org/x/crypto/, particulaly curve25519, ed25519, and nacl/box. This is used to avoid explicitly importing and using these packages throughout yggdrasil. It also includes the all-important NodeID and TreeID types, which are used to identify nodes in the DHT and in the spanning tree's root selection algorithm, respectively.

Index

• Constants
• func BoxOpen(shared *BoxSharedKey, boxed []byte, nonce *BoxNonce) ([]byte, bool)
• func NewBoxKeys() (*BoxPubKey, *BoxPrivKey)
• func NewSigKeys() (*SigPubKey, *SigPrivKey)
• func Verify(pub *SigPubKey, msg []byte, sig *SigBytes) bool
• type BoxNonce
  • func BoxSeal(shared *BoxSharedKey, unboxed []byte, nonce *BoxNonce) ([]byte, *BoxNonce)
  • func NewBoxNonce() *BoxNonce
  • func (n *BoxNonce) Increment()
  • func (n *BoxNonce) Minus(m *BoxNonce) int64
• type BoxPrivKey
  • func (p BoxPrivKey) Public() BoxPubKey
• type BoxPubKey
  • func (n BoxPubKey) Network() string
  • func (k BoxPubKey) String() string
• type BoxSharedKey
  • func GetSharedKey(myPrivKey *BoxPrivKey, othersPubKey *BoxPubKey) *BoxSharedKey
• type Handle
  • func NewHandle() *Handle
• type NodeID
  • func GetNodeID(pub *BoxPubKey) *NodeID
  • func (n *NodeID) Network() string
  • func (n *NodeID) PrefixLength() int
  • func (n *NodeID) String() string
• type SigBytes
  • func Sign(priv *SigPrivKey, msg []byte) *SigBytes
• type SigPrivKey
  • func (p SigPrivKey) Public() SigPubKey
• type SigPubKey
• type TreeID
  • func GetTreeID(pub *SigPubKey) *TreeID

Constants

const BoxNonceLen = 24

BoxNonceLen is the length of a BoxNonce in bytes.

const BoxOverhead = box.Overhead

BoxOverhead is the length of the overhead from boxing something.

const BoxPrivKeyLen = 32

BoxPrivKeyLen is the length of a BoxPrivKey in bytes.

const BoxPubKeyLen = 32

BoxPubKeyLen is the length of a BoxPubKey in bytes.

const BoxSharedKeyLen = 32

BoxSharedKeyLen is the length of a BoxSharedKey in bytes.

const NodeIDLen = sha512.Size

NodeIDLen is the length (in bytes) of a NodeID.

const SigLen = ed25519.SignatureSize

SigLen is the length of SigBytes.

const SigPrivKeyLen = ed25519.PrivateKeySize

SigPrivKeyLen is the length of a SigPrivKey in bytes.

const SigPubKeyLen = ed25519.PublicKeySize

SigPubKeyLen is the length of a SigPubKey in bytes.

const TreeIDLen = sha512.Size

TreeIDLen is the length (in bytes) of a TreeID.

Functions

func BoxOpen

func BoxOpen(shared *BoxSharedKey,
	boxed []byte,
	nonce *BoxNonce) ([]byte, bool)

BoxOpen returns a message and true if it successfully opens a crypto box using the provided shared key and nonce. The boxed input slice's backing array is reused for the unboxed output when possible.

func NewBoxKeys

func NewBoxKeys() (*BoxPubKey, *BoxPrivKey)

NewBoxKeys generates a new pair of public/private crypto box keys.

func NewSigKeys

func NewSigKeys() (*SigPubKey, *SigPrivKey)

NewSigKeys generates a public/private ed25519 key pair.

func Verify

func Verify(pub *SigPubKey, msg []byte, sig *SigBytes) bool

Verify returns true if the provided signature matches the key and message.

Types

type BoxNonce

type BoxNonce [BoxNonceLen]byte

BoxNonce is the nonce used in NaCl-like crypto "box" operations (curve25519+xsalsa20+poly1305), and must not be reused for different messages encrypted using the same BoxSharedKey.

func BoxSeal

func BoxSeal(shared *BoxSharedKey, unboxed []byte, nonce *BoxNonce) ([]byte, *BoxNonce)

BoxSeal seals a crypto box using the provided shared key, returning the box and the nonce needed to decrypt it. If nonce is nil, a random BoxNonce will be used and returned. If nonce is non-nil, then nonce.Increment() will be called before using it, and the incremented BoxNonce is what is returned. The unboxed input slice's backing array is reused for the boxed output when possible.

func NewBoxNonce

func NewBoxNonce() *BoxNonce

NewBoxNonce generates a (cryptographically) random BoxNonce.

func (*BoxNonce) Increment

func (n *BoxNonce) Increment()

Increment adds 2 to a BoxNonce, which is useful if one node intends to send only with odd BoxNonce values, and the other only with even BoxNonce values.

func (*BoxNonce) Minus

func (n *BoxNonce) Minus(m *BoxNonce) int64

Minus is the result of subtracting the provided BoNonce from this BoxNonce, bounded at +- 64. It's primarily used to determine if a new BoxNonce is higher than the last known BoxNonce from a crypto session, and by how much. This is used in the machinery that makes sure replayed packets can't keep a session open indefinitely or stuck using old/bad information about a node.

type BoxPrivKey

type BoxPrivKey [BoxPrivKeyLen]byte

BoxPrivKey is a NaCl-like "box" private key (curve25519+xsalsa20+poly1305).

func (BoxPrivKey) Public

func (p BoxPrivKey) Public() BoxPubKey

Public returns the BoxPubKey associated with this BoxPrivKey.

type BoxPubKey

type BoxPubKey [BoxPubKeyLen]byte

BoxPubKey is a NaCl-like "box" public key (curve25519+xsalsa20+poly1305).

func (BoxPubKey) Network

func (n BoxPubKey) Network() string

Network returns "curve25519" for "box" keys.

func (BoxPubKey) String

func (k BoxPubKey) String() string

String returns a string representation of the "box" key.

type BoxSharedKey

type BoxSharedKey [BoxSharedKeyLen]byte

BoxSharedKey is a NaCl-like "box" shared key (curve25519+xsalsa20+poly1305).

func GetSharedKey

func GetSharedKey(myPrivKey *BoxPrivKey,
	othersPubKey *BoxPubKey) *BoxSharedKey

GetSharedKey returns the shared key derived from your private key and the destination's public key.

type Handle

type Handle [handleLen]byte

func NewHandle

func NewHandle() *Handle

NewHandle returns a new (cryptographically random) Handle, used by the session code to identify which session an incoming packet is associated with.

type NodeID

type NodeID [NodeIDLen]byte

NodeID is how a yggdrasil node is identified in the DHT, and is used to derive IPv6 addresses and subnets in the main executable. It is a sha512sum hash of the node's BoxPubKey

func GetNodeID

func GetNodeID(pub *BoxPubKey) *NodeID

GetNodeID returns the NodeID associated with a BoxPubKey.

func (*NodeID) Network

func (n *NodeID) Network() string

Network returns "nodeid" nearly always right now.

func (*NodeID) PrefixLength

func (n *NodeID) PrefixLength() int

PrefixLength returns the number of bits set in a masked NodeID.

func (*NodeID) String

func (n *NodeID) String() string

type SigBytes

type SigBytes [SigLen]byte

SigBytes is an ed25519 signature.

func Sign

func Sign(priv *SigPrivKey, msg []byte) *SigBytes

Sign returns the SigBytes signing a message.

type SigPrivKey

type SigPrivKey [SigPrivKeyLen]byte

SigPrivKey is a private ed25519 signing key.

func (SigPrivKey) Public

func (p SigPrivKey) Public() SigPubKey

Public returns the SigPubKey associated with this SigPrivKey.

type SigPubKey

type SigPubKey [SigPubKeyLen]byte

SigPubKey is a public ed25519 signing key.

type TreeID

type TreeID [TreeIDLen]byte

TreeID is how a yggdrasil node is identified in the root selection algorithm used to construct the spanning tree.

func GetTreeID

func GetTreeID(pub *SigPubKey) *TreeID

GetTreeID returns the TreeID associated with a BoxPubKey