Merge branch 'XX-3954/e2eBindings' into 'release'

XX-3954 / e2e Bindings

See merge request !239

auth/interface.go

@@ -24,85 +24,83 @@ type State interface {
 	// 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
+	// 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
+	// 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.
+	// 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)
+	// 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.
+	// 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
+	// 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
+	// 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 send on fails, it
-	// will be auto resent by the cmix client
-	// If the confirm must be resent, use ReplayConfirm
+	// 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 (will error if they are too long).
-	// This delete all traces of the relationship with the partner from e2e and
+	// 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.
+	// 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.
-	// will fail to send if the send relationship with the partner has already
-	// ratcheted
-	// The confirm sends as a critical message, if the round send on fails, it
-	// will be auto resent by the cmix client
-	// This will not be useful if either side has ratcheted
+	// 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 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 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 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 checks if the received ownership proof is valid.
 	VerifyOwnership(received, verified contact.Contact, e2e e2e.Handler) bool
 
-	// AddPartnerCallback that overrides the generic auth callback for the given partnerId
+	// AddPartnerCallback adds a new callback that overrides the generic auth
+	// callback for the given partner ID.
 	AddPartnerCallback(partnerId *id.ID, cb Callbacks)
 
-	// DeletePartnerCallback that overrides the generic auth callback for the given partnerId
+	// DeletePartnerCallback deletes the callback that overrides the generic
+	// auth callback for the given partner ID.
 	DeletePartnerCallback(partnerId *id.ID)
 
-	//Closer stops listening to auth
+	// Closer stops listening to auth.
 	io.Closer
 }
 

bindings/README.md

+# xx network Client Bindings
+
+## Allowed Types
+
+> At present, only a subset of Go types are supported.
+> 
+> All exported symbols in the package must have types that are supported. Supported types include:
+> 
+> - Signed integer and floating point types.
+> - String and boolean types.
+> - Byte slice types. Note that byte slices are passed by reference, and support mutation.
+> - Any function type all of whose parameters and results have supported types. Functions must return either no results, one result, or two results where the type of the second is the built-in 'error' type.
+> - Any interface type, all of whose exported methods have supported function types.
+> - Any struct type, all of whose exported methods have supported function types and all of whose exported fields have supported types. Unexported symbols have no effect on the cross-language interface, and as such are not restricted.
+> 
+> The set of supported types will eventually be expanded to cover more Go types, but this is a work in progress.
+> 
+> Exceptions and panics are not yet supported. If either pass a language boundary, the program will exit.
+
+**Source:** https://pkg.go.dev/golang.org/x/mobile/cmd/gobind under *Type restrictions* heading
\ No newline at end of file

bindings/e2eAuth.go

+////////////////////////////////////////////////////////////////////////////////
+// Copyright © 2020 xx network SEZC                                           //
+//                                                                            //
+// Use of this source code is governed by a license that can be found in the  //
+// LICENSE file                                                               //
+////////////////////////////////////////////////////////////////////////////////
+
+package bindings
+
+import (
+	"gitlab.com/elixxir/client/auth"
+	"gitlab.com/elixxir/crypto/contact"
+	"gitlab.com/elixxir/primitives/fact"
+	"gitlab.com/xx_network/primitives/id"
+)
+
+// 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.
+//
+// Parameters:
+//  - partnerContact - the marshalled bytes of the contact.Contact object.
+//  - myFacts - stringified list of fact.FactList.
+// Returns:
+//  - int64 - ID of the round (convert to uint64)
+func (e *E2e) Request(partnerContact []byte, myFactsString string) (int64, error) {
+	partner, err := contact.Unmarshal(partnerContact)
+	if err != nil {
+		return 0, err
+	}
+
+	myFacts, _, err := fact.UnstringifyFactList(myFactsString)
+	if err != nil {
+		return 0, err
+	}
+
+	roundID, err := e.api.GetAuth().Request(partner, myFacts)
+
+	return int64(roundID), err
+}
+
+// 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.
+//
+// Parameters:
+//  - partnerContact - the marshalled bytes of the contact.Contact object.
+// Returns:
+//  - int64 - ID of the round (convert to uint64)
+func (e *E2e) Confirm(partnerContact []byte) (int64, error) {
+	partner, err := contact.Unmarshal(partnerContact)
+	if err != nil {
+		return 0, err
+	}
+
+	roundID, err := e.api.GetAuth().Confirm(partner)
+
+	return int64(roundID), err
+}
+
+// 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.
+//
+// Parameters:
+//  - partnerContact - the marshalled bytes of the contact.Contact object.
+// Returns:
+//  - int64 - ID of the round (convert to uint64)
+func (e *E2e) Reset(partnerContact []byte) (int64, error) {
+	partner, err := contact.Unmarshal(partnerContact)
+	if err != nil {
+		return 0, err
+	}
+
+	roundID, err := e.api.GetAuth().Reset(partner)
+
+	return int64(roundID), err
+}
+
+// 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.
+//
+// Parameters:
+//  - partnerID - the marshalled bytes of the id.ID object.
+// Returns:
+//  - int64 - ID of the round (convert to uint64)
+func (e *E2e) ReplayConfirm(partnerID []byte) (int64, error) {
+	partner, err := id.Unmarshal(partnerID)
+	if err != nil {
+		return 0, err
+	}
+
+	roundID, err := e.api.GetAuth().ReplayConfirm(partner)
+
+	return int64(roundID), err
+}
+
+// CallAllReceivedRequests will iterate through all pending contact requests and
+// replay them on the callbacks.
+func (e *E2e) CallAllReceivedRequests() {
+	e.api.GetAuth().CallAllReceivedRequests()
+}
+
+// DeleteRequest deletes sent or received requests for a specific partner ID.
+//
+// Parameters:
+//  - partnerID - the marshalled bytes of the id.ID object.
+func (e *E2e) DeleteRequest(partnerID []byte) error {
+	partner, err := id.Unmarshal(partnerID)
+	if err != nil {
+		return err
+	}
+
+	return e.api.GetAuth().DeleteRequest(partner)
+}
+
+// DeleteAllRequests clears all requests from client's auth storage.
+func (e *E2e) DeleteAllRequests() error {
+	return e.api.GetAuth().DeleteAllRequests()
+}
+
+// DeleteSentRequests clears all sent requests from client's auth storage.
+func (e *E2e) DeleteSentRequests() error {
+	return e.api.GetAuth().DeleteSentRequests()
+}
+
+// DeleteReceiveRequests clears all received requests from client's auth storage.
+func (e *E2e) DeleteReceiveRequests() error {
+	return e.api.GetAuth().DeleteReceiveRequests()
+}
+
+// GetReceivedRequest returns a contact if there's a received request for it.
+//
+// Parameters:
+//  - partnerID - the marshalled bytes of the id.ID object.
+// Returns:
+//  - []byte - the marshalled bytes of the contact.Contact object.
+func (e *E2e) GetReceivedRequest(partnerID []byte) ([]byte, error) {
+	partner, err := id.Unmarshal(partnerID)
+	if err != nil {
+		return nil, err
+	}
+
+	c, err := e.api.GetAuth().GetReceivedRequest(partner)
+	if err != nil {
+		return nil, err
+	}
+
+	return c.Marshal(), nil
+}
+
+// VerifyOwnership checks if the received ownership proof is valid.
+//
+// Parameters:
+//  - receivedContact, verifiedContact - the marshalled bytes of the
+//      contact.Contact object.
+//  - e2eId - ID of the e2e handler
+func (e *E2e) VerifyOwnership(
+	receivedContact, verifiedContact []byte, e2eId int) (bool, error) {
+	received, err := contact.Unmarshal(receivedContact)
+	if err != nil {
+		return false, err
+	}
+
+	verified, err := contact.Unmarshal(verifiedContact)
+	if err != nil {
+		return false, err
+	}
+
+	e2eClient, err := e2eTrackerSingleton.get(e2eId)
+	if err != nil {
+		return false, err
+	}
+
+	return e.api.GetAuth().VerifyOwnership(
+		received, verified, e2eClient.api.GetE2E()), nil
+}
+
+// AddPartnerCallback adds a new callback that overrides the generic auth
+// callback for the given partner ID.
+//
+// Parameters:
+//  - partnerID - the marshalled bytes of the id.ID object.
+func (e *E2e) AddPartnerCallback(partnerID []byte, cb AuthCallbacks) error {
+	partnerId, err := id.Unmarshal(partnerID)
+	if err != nil {
+		return err
+	}
+
+	var authCallbacks auth.Callbacks
+	if cb == nil {
+		authCallbacks = auth.DefaultAuthCallbacks{}
+	} else {
+		authCallbacks = &authCallback{bindingsCbs: cb}
+	}
+
+	e.api.GetAuth().AddPartnerCallback(partnerId, authCallbacks)
+
+	return nil
+}
+
+// DeletePartnerCallback deletes the callback that overrides the generic
+// auth callback for the given partner ID.
+//
+// Parameters:
+//  - partnerID - the marshalled bytes of the id.ID object.
+func (e *E2e) DeletePartnerCallback(partnerID []byte) error {
+	partnerId, err := id.Unmarshal(partnerID)
+	if err != nil {
+		return err
+	}
+
+	e.api.GetAuth().DeletePartnerCallback(partnerId)
+
+	return nil
+}