kex2

Documentation

Index

• Constants
• Variables
• func NewConn(ctx context.Context, lctx LogContext, r MessageRouter, s Secret, d DeviceID, ...) (con net.Conn, err error)
• func RunProvisionee(arg ProvisioneeArg) error
• func RunProvisioner(arg ProvisionerArg) error
• type Conn
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() (addr net.Addr)
  • func (c *Conn) Read(out []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() (addr net.Addr)
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(buf []byte) (n int, err error)
• type DeviceID
  • func (d DeviceID) Eq(d2 DeviceID) bool
• type ErrBadPacketSequence
  • func (e ErrBadPacketSequence) Error() string
• type KexBaseArg
• type LogContext
• type MessageRouter
• type Provisionee
• type ProvisioneeArg
• type Provisioner
• type ProvisionerArg
• type Secret
• type Seqno
• type SessionID
  • func (s SessionID) Eq(s2 SessionID) bool

Constants

const SecretLen = 32

SecretLen is the number of bytes in the secret.

Variables

var ErrAgain = errors.New("no data were ready to read")

ErrAgain indicates that no data was available to read, but the reader was in non-blocking mode, so to try again later.

var ErrBadMetadata = errors.New("bad metadata")

ErrBadMetadata indicates that the metadata outside the encrypted message didn't match what was inside.

var ErrBadSecret = errors.New("bad secret")

ErrBadSecret indicates that the secret received was invalid.

var ErrCanceled = errors.New("kex canceled by caller")

ErrCanceled is returned if Kex is canceled by the caller via the Context argument

var ErrDecryption = errors.New("decryption failed")

ErrBadDecryption indicates that a ciphertext failed to decrypt or MAC properly

var ErrHelloTimeout = errors.New("hello timeout")

ErrHelloTimeout indicates that the Hello() part of the protocol timed out. Most likely due to an incorrect secret phrase from the user.

var ErrNotEnoughRandomness = errors.New("not enough random data")

ErrNotEnoughRandomness indicates that encryption failed due to insufficient randomness

var ErrSelfRecieve = errors.New("got message back that we sent")

ErrSelfReceive indicates that the client received a message sent by itself, which should never happen

var ErrTimedOut net.Error = timedoutError{}

ErrTimedOut is the signleton error we use if the operation timedout.

var ErrUnimplemented = errors.New("unimplemented")

ErrUnimplemented indicates the given method isn't implemented

var ErrWrongSession = errors.New("got message for wrong Session ID")

ErrWrongSession indicates that the given session didn't match the clients expectations

Functions

func NewConn

func NewConn(ctx context.Context, lctx LogContext, r MessageRouter, s Secret, d DeviceID, readTimeout time.Duration) (con net.Conn, err error)

NewConn establishes a Kex session based on the given secret. Will work for both ends of the connection, regardless of which order the two started their connection. Will communicate with the other end via the given message router. You can specify an optional timeout to cancel any reads longer than that timeout.

func RunProvisionee

func RunProvisionee(arg ProvisioneeArg) error

RunProvisionee runs a provisionee given the necessary arguments.

func RunProvisioner

func RunProvisioner(arg ProvisionerArg) error

RunProvisioner runs a provisioner given the necessary arguments.

Types

type Conn

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

Conn is a struct that obeys the net.Conn interface. It establishes a session abstraction over a message channel bounced off the Keybase API server, applying the appropriate e2e encryption/MAC'ing.

func (*Conn) Close

func (c *Conn) Close() error

Close the connection to the server, sending an empty buffer via POST through the `MessageRouter`. Fulfills the `net.Conn` interface

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() (addr net.Addr)

LocalAddr returns the local network address, fulfilling the `net.Conn interface`

func (*Conn) Read

func (c *Conn) Read(out []byte) (n int, err error)

Read data from the connection, returning plaintext data if all cryptographic checks passed. Obeys the `net.Conn` interface. Returns the number of bytes read into the output buffer.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() (addr net.Addr)

RemoteAddr returns the remote network address, fulfilling the `net.Conn interface`

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

A deadline is an absolute time after which I/O operations fail with a timeout (see type Error) instead of blocking. The deadline applies to all future I/O, not just the immediately following call to Read or Write.

An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.

A zero value for t means I/O operations will not time out.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls. A zero value for t means Read will not time out.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out. We're not implementing this feature for now, so make it an error if we try to do so.

func (*Conn) Write

func (c *Conn) Write(buf []byte) (n int, err error)

Write data to the connection, encrypting and MAC'ing along the way. Obeys the `net.Conn` interface

type DeviceID

type DeviceID [16]byte

DeviceID is a 16-byte identifier that each side of key exchange has. It's used primarily to tell sender from receiver.

func (DeviceID) Eq

func (d DeviceID) Eq(d2 DeviceID) bool

Eq returns true if the two device IDs are equal

type ErrBadPacketSequence

type ErrBadPacketSequence struct {
	SessionID     SessionID
	SenderID      DeviceID
	ReceivedSeqno Seqno
	PrevSeqno     Seqno
}

ErrBadPacketSequence indicates that packets arrived out of order from the server (which they shouldn't).

func (ErrBadPacketSequence) Error

func (e ErrBadPacketSequence) Error() string

type KexBaseArg

type KexBaseArg struct {
	Ctx           context.Context
	LogCtx        LogContext
	Mr            MessageRouter
	Secret        Secret
	DeviceID      keybase1.DeviceID // For now, this deviceID is different from the one in the transport
	SecretChannel <-chan Secret
	Timeout       time.Duration
}

KexBaseArg are arguments common to both Provisioner and Provisionee

type LogContext

type LogContext interface {
	Debug(format string, args ...interface{})
}

type MessageRouter

type MessageRouter interface {

	// Post a message. Message will always be non-nil and non-empty.
	// Even for an EOF, the empty buffer is encrypted via SecretBox,
	// so the buffer posted to the server will have data.
	Post(I SessionID, sender DeviceID, seqno Seqno, msg []byte) error

	// Get messages on the channel.  Only poll for `poll` milliseconds. If the timeout
	// elapses without any data ready, then just return an empty result, with nil error.
	// Several messages can be returned at once, which should be processed in serial.
	// They are guaranteed to be in order; otherwise, there was an issue.
	// Get() should only return a non-nil error if there was an HTTPS or TCP-level error.
	// Application-level errors like EOF or no data ready are handled by modulating
	// the `msgs` result.
	Get(I SessionID, receiver DeviceID, seqno Seqno, poll time.Duration) (msg [][]byte, err error)
}

MessageRouter is a stateful message router that will be implemented by JSON/REST calls to the Keybase API server.

type Provisionee

type Provisionee interface {
	GetLogFactory() rpc.LogFactory
	HandleHello(ctx context.Context, a keybase1.HelloArg) (keybase1.HelloRes, error)
	HandleHello2(ctx context.Context, a keybase1.Hello2Arg) (keybase1.Hello2Res, error)
	HandleDidCounterSign(ctx context.Context, b []byte) error
	HandleDidCounterSign2(ctx context.Context, a keybase1.DidCounterSign2Arg) error
}

Provisionee is an interface that abstracts out the crypto and session management that a provisionee needs to do as part of the protocol.

type ProvisioneeArg

type ProvisioneeArg struct {
	KexBaseArg
	Provisionee Provisionee
}

ProvisioneeArg provides the details that a provisionee needs in order to run its course

type Provisioner

type Provisioner interface {
	GetHelloArg() (keybase1.HelloArg, error)
	GetHello2Arg() (keybase1.Hello2Arg, error)
	CounterSign(keybase1.HelloRes) ([]byte, error)
	CounterSign2(keybase1.Hello2Res) (keybase1.DidCounterSign2Arg, error)
	GetLogFactory() rpc.LogFactory
}

Provisioner is an interface that abstracts out the crypto and session management that a provisioner needs to do as part of the protocol.

type ProvisionerArg

type ProvisionerArg struct {
	KexBaseArg
	Provisioner  Provisioner
	HelloTimeout time.Duration
}

ProvisionerArg provides the details that a provisioner needs in order to run its course

type Secret

type Secret [SecretLen]byte

Secret is the 32-byte shared secret identifier

type Seqno

type Seqno uint32

Seqno increments on every message sent from a Kex sender.

type SessionID

type SessionID [32]byte

SessionID is a 32-byte session identifier that's derived from the shared session secret. It's used to route messages on the server side.

func (SessionID) Eq

func (s SessionID) Eq(s2 SessionID) bool

Eq returns true if the two session IDs are equal