message

Documentation

Overview

Package message provides message identifiers and structures used in PAKEs with encoding and decoding features.

Messages have identifiers and associated structures. Messages come in three categories: OPRF, registration, and key exchange (kex) messages.

Once values for a message are ready to be send, the desired message structure can be filled and then encoded with a call to the Encode() function. The receiver must know in advance at which stage it is in the protocol and what message to expect to correctly decode it. A call to Decode() of the message identifier with the encoded message returns the corresponding message structure.

e.g.

 // Sender
 m := message.OPRFInit{
		UserID:    c.username,
		InitBlind: blinded,
	}
 encoded, err := m.Encode(encoding.JSON)

 // Receiver
 m, err := OPRFStart.Decode(encoded, encoding.JSON)

Index

• type ExplicitAuth
• type Identifier
  • func (i Identifier) Decode(message []byte, enc encoding.Encoding) (interface{}, error)
• type Kex
  • func (k *Kex) Encode(enc encoding.Encoding) ([]byte, error)
• type Message
• type OPRFInit
  • func (o *OPRFInit) Encode(enc encoding.Encoding) ([]byte, error)
• type OPRFResponse
  • func (o *OPRFResponse) Encode(enc encoding.Encoding) ([]byte, error)
• type Registration
  • func (r *Registration) Encode(enc encoding.Encoding) ([]byte, error)
• type Response
  • func (r *Response) Encode(enc encoding.Encoding) ([]byte, error)
• type Start
  • func (s *Start) Encode(enc encoding.Encoding) ([]byte, error)

Types

type ExplicitAuth

type ExplicitAuth = Kex

ExplicitAuth is the continuity of the two previous messages, but since the OPRF is two messages this is an alias to the key exchange explicit authentication message.

type Identifier

type Identifier byte

Identifier identifies the message id of the protocol or phase, and can be seen as a stage.

const (

	// OPRFStart identifies the first message of the OPRF, also used in the registration phase (client to server).
	OPRFStart Identifier = iota + 1

	// OPRFFinish identifies the second message of the OPRF, also used in the registration phase (server to client).
	OPRFFinish

	// RegisterFinish identifies the third and last message of the registration phase (client to server),
	// usually the verification element relative to the client.
	RegisterFinish

	// StageStart identifies the first message of the PAKE protocol (client to server).
	StageStart

	// StageResponse identifies the second message of the PAKE protocol (server to client).
	StageResponse

	// StageAuth identifies the authentication messages of the PAKE protocols, usually the last message.
	StageAuth

	// StageTerminated identifies the last stage which does not correspond to any message,
	// and indicates the protocol is over and the procedure should be terminated.
	StageTerminated

	// RegisterStart identifies the first message of the registration phase (client to server),
	// usually the OPRF initiation message.
	RegisterStart = OPRFStart

	// RegisterResponse identifies the second message of the registration phase (server to client),
	// usually the OPRF response message.
	RegisterResponse = OPRFFinish
)

func (Identifier) Decode

func (i Identifier) Decode(message []byte, enc encoding.Encoding) (interface{}, error)

Decode attempts to decode the input message in the enc format assuming it corresponds to the receiver's message Identifier.

type Kex

type Kex struct {
	// Protocol is a one byte element identifying which protocol is in use.
	Protocol byte `json:"proto"`

	// Ciphersuite identifies the cipher suite used.
	Parameters cryptotools.CiphersuiteEncoding `json:"params"`

	// ClientID is the agreed upon client/user identifier.
	ClientID []byte `json:"id"`

	// Element is the Diffie-Hellman element.
	Element []byte `json:"element"`

	// Auth is the authentication element.
	Auth []byte `json:"auth"`
}

Kex represents a key exchange message, containing the client Identifier, a public element and an authentication element.

func (*Kex) Encode

func (k *Kex) Encode(enc encoding.Encoding) ([]byte, error)

Encode returns an encoding of k in the specified encoding.

type Message

type Message interface {
	// Encode encodes the message with the specified format (wraps the other methods)
	Encode(encoding encoding.Encoding) ([]byte, error)
}

Message interface allows abstract handling of PAKE messages and their encoding.

type OPRFInit

type OPRFInit struct {
	UserID    []byte `json:"user"`
	InitBlind []byte `json:"init"`
}

OPRFInit holds the necessary information for the OPRF initiation step.

func (*OPRFInit) Encode

func (o *OPRFInit) Encode(enc encoding.Encoding) ([]byte, error)

Encode returns an encoding of o in the specified encoding.

type OPRFResponse

type OPRFResponse struct {
	RespBlind     []byte `json:"resp"`   // UQ or beta
	PublicOPRFKey []byte `json:"pubkey"` // X=g*x, or vU = g*k
	Extra         []byte `json:"extra"`  // piggybacking ihf params, envelope, etc.
}

OPRFResponse holds the necessary information for the OPRF response step. The extra data allows for piggybacking more information.

func (*OPRFResponse) Encode

func (o *OPRFResponse) Encode(enc encoding.Encoding) ([]byte, error)

Encode returns an encoding of o in the specified encoding.

type Registration

type Registration struct {
	Verifier []byte `json:"verifier"`
}

Registration is simply an alias representing the verifying element send to the server by the client on registration.

func (*Registration) Encode

func (r *Registration) Encode(enc encoding.Encoding) ([]byte, error)

Encode returns an encoding of r in the specified encoding.

type Response

type Response struct {
	OPRFResponse
	Kex
}

Response is the Start corresponding response, usually from the server.

func (*Response) Encode

func (r *Response) Encode(enc encoding.Encoding) ([]byte, error)

Encode returns an encoding of r in the specified encoding.

type Start

type Start struct {
	OPRFInit
	Kex
}

Start message groups the OPRF and key exchange initiation, usually the first message from the client.

func (*Start) Encode

func (s *Start) Encode(enc encoding.Encoding) ([]byte, error)

Encode returns an encoding of s in the specified encoding.