ntor

Documentation

Overview

Package ntor implements the Tor Project's ntor handshake as defined in proposal 216 "Improved circuit-creation key exchange". It also supports using Elligator to transform the Curve25519 public keys sent over the wire to a form that is indistinguishable from random strings.

Before using this package, it is strongly recommended that the specification is read and understood.

Index

• Constants
• func ClientHandshake(clientKeypair *Keypair, serverPublic *PublicKey, idPublic *PublicKey, ...) (ok bool, keySeed *KeySeed, auth *Auth)
• func CompareAuth(auth1 *Auth, auth2 []byte) bool
• func Kdf(keySeed []byte, okmLen int) []byte
• func ServerHandshake(clientPublic *PublicKey, serverKeypair *Keypair, idKeypair *Keypair, ...) (ok bool, keySeed *KeySeed, auth *Auth)
• type Auth
  • func (auth *Auth) Bytes() *[AuthLength]byte
• type KeySeed
  • func (key_seed *KeySeed) Bytes() *[KeySeedLength]byte
• type Keypair
  • func KeypairFromHex(encoded string) (*Keypair, error)
  • func NewKeypair(elligator bool) (*Keypair, error)
  • func (keypair *Keypair) HasElligator() bool
  • func (keypair *Keypair) Private() *PrivateKey
  • func (keypair *Keypair) Public() *PublicKey
  • func (keypair *Keypair) Representative() *Representative
• type NodeID
  • func NewNodeID(raw []byte) (*NodeID, error)
  • func NodeIDFromHex(encoded string) (*NodeID, error)
  • func (id *NodeID) Bytes() *[NodeIDLength]byte
  • func (id *NodeID) Hex() string
• type NodeIDLengthError
  • func (e NodeIDLengthError) Error() string
• type PrivateKey
  • func (private *PrivateKey) Bytes() *[PrivateKeyLength]byte
  • func (private *PrivateKey) Hex() string
• type PrivateKeyLengthError
  • func (e PrivateKeyLengthError) Error() string
• type PublicKey
  • func NewPublicKey(raw []byte) (*PublicKey, error)
  • func PublicKeyFromHex(encoded string) (*PublicKey, error)
  • func (public *PublicKey) Bytes() *[PublicKeyLength]byte
  • func (public *PublicKey) Hex() string
• type PublicKeyLengthError
  • func (e PublicKeyLengthError) Error() string
• type Representative
  • func (repr *Representative) Bytes() *[RepresentativeLength]byte
  • func (repr *Representative) ToPublic() *PublicKey

Constants

const (
	// PublicKeyLength is the length of a Curve25519 public key.
	PublicKeyLength = 32

	// RepresentativeLength is the length of an Elligator representative.
	RepresentativeLength = 32

	// PrivateKeyLength is the length of a Curve25519 private key.
	PrivateKeyLength = 32

	// SharedSecretLength is the length of a Curve25519 shared secret.
	SharedSecretLength = 32

	// NodeIDLength is the length of a ntor node identifier.
	NodeIDLength = 20

	// KeySeedLength is the length of the derived KEY_SEED.
	KeySeedLength = sha256.Size

	// AuthLength is the lenght of the derived AUTH.
	AuthLength = sha256.Size
)

Functions

func ClientHandshake

func ClientHandshake(clientKeypair *Keypair, serverPublic *PublicKey, idPublic *PublicKey, id *NodeID) (ok bool, keySeed *KeySeed, auth *Auth)

ClientHandshake does the client side of a ntor handshake and returnes status, KEY_SEED, and AUTH. If status is not true or AUTH does not match the value recieved from the server, the handshake MUST be aborted.

func CompareAuth

func CompareAuth(auth1 *Auth, auth2 []byte) bool

CompareAuth does a constant time compare of a Auth and a byte slice (presumably received over a network).

func Kdf

func Kdf(keySeed []byte, okmLen int) []byte

Kdf extracts and expands KEY_SEED via HKDF-SHA256 and returns `okm_len` bytes of key material.

func ServerHandshake

func ServerHandshake(clientPublic *PublicKey, serverKeypair *Keypair, idKeypair *Keypair, id *NodeID) (ok bool, keySeed *KeySeed, auth *Auth)

ServerHandshake does the server side of a ntor handshake and returns status, KEY_SEED, and AUTH. If status is not true, the handshake MUST be aborted.

Types

type Auth

type Auth [AuthLength]byte

Auth is the verifier that results from a handshake (AUTH).

func (*Auth) Bytes

func (auth *Auth) Bytes() *[AuthLength]byte

Bytes returns a pointer to the raw auth.

type KeySeed

type KeySeed [KeySeedLength]byte

KeySeed is the key material that results from a handshake (KEY_SEED).

func (*KeySeed) Bytes

func (key_seed *KeySeed) Bytes() *[KeySeedLength]byte

Bytes returns a pointer to the raw key material.

type Keypair

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

Keypair is a Curve25519 keypair with an optional Elligator representative. As only certain Curve25519 keys can be obfuscated with Elligator, the representative must be generated along with the keypair.

func KeypairFromHex

func KeypairFromHex(encoded string) (*Keypair, error)

KeypairFromHex returns a Keypair from the hexdecimal representation of the private key.

func NewKeypair

func NewKeypair(elligator bool) (*Keypair, error)

NewKeypair generates a new Curve25519 keypair, and optionally also generates an Elligator representative of the public key.

func (*Keypair) HasElligator

func (keypair *Keypair) HasElligator() bool

HasElligator returns true if the Keypair has an Elligator representative.

func (*Keypair) Private

func (keypair *Keypair) Private() *PrivateKey

Private returns the Curve25519 private key belonging to the Keypair.

func (*Keypair) Public

func (keypair *Keypair) Public() *PublicKey

Public returns the Curve25519 public key belonging to the Keypair.

func (*Keypair) Representative

func (keypair *Keypair) Representative() *Representative

Representative returns the Elligator representative of the public key belonging to the Keypair.

type NodeID

type NodeID [NodeIDLength]byte

NodeID is a ntor node identifier.

func NewNodeID

func NewNodeID(raw []byte) (*NodeID, error)

NewNodeID creates a NodeID from the raw bytes.

func NodeIDFromHex

func NodeIDFromHex(encoded string) (*NodeID, error)

NodeIDFromHex creates a new NodeID from the hexdecimal representation.

func (*NodeID) Bytes

func (id *NodeID) Bytes() *[NodeIDLength]byte

Bytes returns a pointer to the raw NodeID.

func (*NodeID) Hex

func (id *NodeID) Hex() string

Hex returns the hexdecimal representation of the NodeID.

type NodeIDLengthError

type NodeIDLengthError int

NodeIDLengthError is the error returned when the node ID being imported is an invalid length.

func (NodeIDLengthError) Error

func (e NodeIDLengthError) Error() string

type PrivateKey

type PrivateKey [PrivateKeyLength]byte

PrivateKey is a Curve25519 private key in little-endian byte order.

func (*PrivateKey) Bytes

func (private *PrivateKey) Bytes() *[PrivateKeyLength]byte

Bytes returns a pointer to the raw Curve25519 private key.

func (*PrivateKey) Hex

func (private *PrivateKey) Hex() string

Hex returns the hexdecimal representation of the Curve25519 private key.

type PrivateKeyLengthError

type PrivateKeyLengthError int

PrivateKeyLengthError is the error returned when the private key being imported is an invalid length.

func (PrivateKeyLengthError) Error

func (e PrivateKeyLengthError) Error() string

type PublicKey

type PublicKey [PublicKeyLength]byte

PublicKey is a Curve25519 public key in little-endian byte order.

func NewPublicKey

func NewPublicKey(raw []byte) (*PublicKey, error)

NewPublicKey creates a PublicKey from the raw bytes.

func PublicKeyFromHex

func PublicKeyFromHex(encoded string) (*PublicKey, error)

PublicKeyFromHex returns a PublicKey from the hexdecimal representation.

func (*PublicKey) Bytes

func (public *PublicKey) Bytes() *[PublicKeyLength]byte

Bytes returns a pointer to the raw Curve25519 public key.

func (*PublicKey) Hex

func (public *PublicKey) Hex() string

Hex returns the hexdecimal representation of the Curve25519 public key.

type PublicKeyLengthError

type PublicKeyLengthError int

PublicKeyLengthError is the error returned when the public key being imported is an invalid length.

func (PublicKeyLengthError) Error

func (e PublicKeyLengthError) Error() string

type Representative

type Representative [RepresentativeLength]byte

Representative is an Elligator representative of a Curve25519 public key in little-endian byte order.

func (*Representative) Bytes

func (repr *Representative) Bytes() *[RepresentativeLength]byte

Bytes returns a pointer to the raw Elligator representative.

func (*Representative) ToPublic

func (repr *Representative) ToPublic() *PublicKey

ToPublic converts a Elligator representative to a Curve25519 public key.