auth

Documentation

Index

• Constants
• func VerifyOwnership(received, verified contact.Contact, e2e e2e.Handler) bool
• type Callbacks
• type Params
  • func GetDefaultParams() Params
  • func GetDefaultTemporaryParams() Params
  • func GetParameters(params string) (Params, error)
  • func (p Params) MarshalJSON() ([]byte, error)
  • func (p *Params) UnmarshalJSON(data []byte) error
• type State
  • func NewState(kv *versioned.KV, net cmix.Client, e2e e2e.Handler, ...) (State, error)
  • func NewStateLegacy(kv *versioned.KV, net cmix.Client, e2e e2e.Handler, ...) (State, error)

Constants

const (
	// ErrChannelExists is a message returned in state.Request when an
	// authenticated channel exists between the partner and me.
	ErrChannelExists = "Authenticated channel already established with partner"
)

Error constant strings. Any changes to these should go over usages of the affected messages in other applications (if applicable)

Functions

func VerifyOwnership

func VerifyOwnership(received, verified contact.Contact, e2e e2e.Handler) bool

VerifyOwnership calls the cAuth.VerifyOwnershipProof function to cryptographically prove the received ownership.

Types

type Callbacks

type Callbacks interface {
	Request(partner contact.Contact, receptionID receptionID.EphemeralIdentity,
		round rounds.Round)
	Confirm(partner contact.Contact, receptionID receptionID.EphemeralIdentity,
		round rounds.Round)
	Reset(partner contact.Contact, receptionID receptionID.EphemeralIdentity,
		round rounds.Round)
}

Callbacks is the interface for auth callback methods. TODO: Document this

type Params

type Params struct {
	ReplayRequests  bool
	RequestTag      string
	ConfirmTag      string
	ResetRequestTag string
	ResetConfirmTag string
}

Params is are the parameters for the auth package.

func GetDefaultParams

func GetDefaultParams() Params

GetDefaultParams returns a default set of Params.

func GetDefaultTemporaryParams

func GetDefaultTemporaryParams() Params

func GetParameters

func GetParameters(params string) (Params, error)

GetParameters Obtain default Params, or override with given parameters if set.

func (Params) MarshalJSON

func (p Params) MarshalJSON() ([]byte, error)

MarshalJSON adheres to the json.Marshaler interface.

func (*Params) UnmarshalJSON

func (p *Params) UnmarshalJSON(data []byte) error

UnmarshalJSON adheres to the json.Unmarshaler interface.

type State

type State interface {
	// Request sends a contact request from the user identity in the imported
	// e2e structure to the passed contact, as well as the passed facts (will
	// error if they are too long).
	// The other party must accept the request by calling Confirm in order to be
	// able to send messages using e2e.Handler.SendE2E. When the other party
	// does so, the "confirm" callback will get called.
	// The round the request is initially sent on will be returned, but the
	// request will be listed as a critical message, so the underlying cMix
	// client will auto resend it in the event of failure.
	// A request cannot be sent for a contact who has already received a request
	// or who is already a partner.
	// The request sends as a critical message, if the round send on fails, it
	// will be auto resent by the cMix client.
	Request(partner contact.Contact, myFacts fact.FactList) (id.Round, error)

	// Confirm sends a confirmation for a received request. It can only be
	// called once. This both sends keying material to the other party and
	// creates a channel in the e2e handler, after which e2e messages can be
	// sent to the partner using e2e.Handler.SendE2E.
	// The round the request is initially sent on will be returned, but the
	// request will be listed as a critical message, so the underlying cMix
	// client will auto resend it in the event of failure.
	// A confirm cannot be sent for a contact who has not sent a request or who
	// is already a partner. This can only be called once for a specific
	// contact.
	// The confirm sends as a critical message; if the round it sends on fails,
	// it will be auto resend by the cMix client.
	// If the confirm must be resent, use ReplayConfirm.
	Confirm(partner contact.Contact) (id.Round, error)

	// Reset sends a contact reset request from the user identity in the
	// imported e2e structure to the passed contact, as well as the passed facts
	// (it will error if they are too long).
	// This deletes all traces of the relationship with the partner from e2e and
	// create a new relationship from scratch.
	// The round the reset is initially sent on will be returned, but the
	// request will be listed as a critical message, so the underlying cMix
	// client will auto resend it in the event of failure.
	// A request cannot be sent for a contact who has already received a request
	// or who is already a partner.
	Reset(partner contact.Contact) (id.Round, error)

	// ReplayConfirm resends a confirm to the partner. It will fail to send if
	// the send relationship with the partner has already ratcheted.
	// The confirm sends as a critical message; if the round it sends on fails,
	// it will be auto resend by the cMix client.
	// This will not be useful if either side has ratcheted.
	ReplayConfirm(partner *id.ID) (id.Round, error)

	// CallAllReceivedRequests will iterate through all pending contact requests
	// and replay them on the callbacks.
	CallAllReceivedRequests()

	// DeleteRequest deletes sent or received requests for a specific partner ID.
	DeleteRequest(partnerID *id.ID) error

	// DeleteAllRequests clears all requests from client's auth storage.
	DeleteAllRequests() error

	// DeleteSentRequests clears all sent requests from client's auth storage.
	DeleteSentRequests() error

	// DeleteReceiveRequests clears all received requests from client's auth
	// storage.
	DeleteReceiveRequests() error

	// GetReceivedRequest returns a contact if there's a received request for it.
	GetReceivedRequest(partner *id.ID) (contact.Contact, error)

	// VerifyOwnership checks if the received ownership proof is valid.
	VerifyOwnership(received, verified contact.Contact, e2e e2e.Handler) bool

	// AddPartnerCallback adds a new callback that overrides the generic auth
	// callback for the given partner ID.
	AddPartnerCallback(partnerId *id.ID, cb Callbacks)

	// DeletePartnerCallback deletes the callback that overrides the generic
	// auth callback for the given partner ID.
	DeletePartnerCallback(partnerId *id.ID)

	// DeletePartner deletes the request and/or confirmation for the given
	// partner.
	DeletePartner(partner *id.ID) error

	// Closer stops listening to auth.
	io.Closer
}

func NewState

func NewState(kv *versioned.KV, net cmix.Client, e2e e2e.Handler,
	rng *fastRNG.StreamGenerator, event event.Reporter, authParams Params,
	sessParams session.Params, callbacks Callbacks,
	backupTrigger func(reason string)) (State, error)

NewState loads the auth state or creates new auth state if one cannot be found. Bases its reception identity and keys off of what is found in e2e. Uses this ID to modify the kv prefix for a unique storage path Parameters:

The params object passed in determines the services that will be used
to pick up requests and signal notifications. These are unique to an
identity, so multiple auth states with the same service tags with
different identities can run simultaneously.
Default parameters can be retrieved via GetDefaultParameters()

Temporary:

In some cases, for example client <-> server communications, connections
are treated as ephemeral. To do so in auth, pass in an ephemeral e2e (made
with a memory only versioned.KV) as well as a memory only versioned.KV for
NewState and use GetDefaultTemporaryParams() for the parameters

func NewStateLegacy

func NewStateLegacy(kv *versioned.KV, net cmix.Client, e2e e2e.Handler,
	rng *fastRNG.StreamGenerator, event event.Reporter, authParams Params,
	sessParams session.Params, callbacks Callbacks,
	backupTrigger func(reason string)) (State, error)

NewStateLegacy loads the auth state or creates new auth state if one cannot be found. Bases its reception identity and keys off of what is found in e2e. Does not modify the kv prefix for backwards compatibility. Otherwise, acts the same as NewState