From 678f627877c655496685ab4e0c54495714114cca Mon Sep 17 00:00:00 2001
From: Jono Wenger <jono@elixxir.io>
Date: Fri, 12 Aug 2022 11:54:48 -0700
Subject: [PATCH] Fix bindings comments
---
bindings/cmix.go | 21 +++++++++++++--------
bindings/e2e.go | 32 +++++++++++++++++++-------------
bindings/identity.go | 34 ++++++++++++++++++++++++----------
3 files changed, 56 insertions(+), 31 deletions(-)
diff --git a/bindings/cmix.go b/bindings/cmix.go
index 4b9d66cf3..71d5b1c64 100644
--- a/bindings/cmix.go
+++ b/bindings/cmix.go
@@ -35,10 +35,10 @@ type Cmix struct {
id int
}
-// NewCmix creates user storage, generates keys, connects, and registers
-// with the network. Note that this does not register a username/identity, but
-// merely creates a new cryptographic identity for adding such information
-// at a later date.
+// NewCmix creates user storage, generates keys, connects, and registers with
+// the network. Note that this does not register a username/identity, but merely
+// creates a new cryptographic identity for adding such information at a later
+// date.
//
// Users of this function should delete the storage directory on error.
func NewCmix(ndfJSON, storageDir string, password []byte, registrationCode string) error {
@@ -49,8 +49,9 @@ func NewCmix(ndfJSON, storageDir string, password []byte, registrationCode strin
return nil
}
-// LoadCmix will load an existing user storage from the storageDir using the password.
-// This will fail if the user storage does not exist or the password is incorrect.
+// LoadCmix will load an existing user storage from the storageDir using the
+// password. This will fail if the user storage does not exist or the password
+// is incorrect.
//
// The password is passed as a byte array so that it can be cleared from memory
// and stored as securely as possible using the MemGuard library.
@@ -82,6 +83,10 @@ func (c *Cmix) GetID() int {
return c.id
}
+////////////////////////////////////////////////////////////////////////////////
+// cMix Tracker //
+////////////////////////////////////////////////////////////////////////////////
+
// cmixTracker is a singleton used to keep track of extant Cmix objects,
// preventing race conditions created by passing it over the bindings.
type cmixTracker struct {
@@ -90,8 +95,8 @@ type cmixTracker struct {
mux sync.RWMutex
}
-// make creates a Cmix from a xxdk.Cmix, assigns it a unique ID,and adds it to
-// the cmixTracker.
+// make creates a Cmix from a [xxdk.Cmix], assigns it a unique ID, and adds it
+// to the cmixTracker.
func (ct *cmixTracker) make(c *xxdk.Cmix) *Cmix {
ct.mux.Lock()
defer ct.mux.Unlock()
diff --git a/bindings/e2e.go b/bindings/e2e.go
index 22438e73d..f9c302bcf 100644
--- a/bindings/e2e.go
+++ b/bindings/e2e.go
@@ -26,20 +26,20 @@ var e2eTrackerSingleton = &e2eTracker{
count: 0,
}
-// E2e wraps the xxdk.E2e, implementing additional functions
-// to support the bindings E2e interface.
+// E2e wraps the xxdk.E2e, implementing additional functions to support the
+// bindings E2e interface.
type E2e struct {
api *xxdk.E2e
id int
}
-// GetID returns the e2eTracker ID for the E2e object.
+// GetID returns the ID for this E2e in the e2eTracker.
func (e *E2e) GetID() int {
return e.id
}
// Login creates and returns a new E2e object and adds it to the
-// e2eTrackerSingleton. identity should be created via
+// e2eTrackerSingleton. Identity should be created via
// Cmix.MakeReceptionIdentity and passed in here. If callbacks is left nil, a
// default auth.Callbacks will be used.
func Login(cmixId int, callbacks AuthCallbacks, identity,
@@ -80,7 +80,7 @@ func Login(cmixId int, callbacks AuthCallbacks, identity,
}
// LoginEphemeral creates and returns a new ephemeral E2e object and adds it to
-// the e2eTrackerSingleton. identity should be created via
+// the e2eTrackerSingleton. Identity should be created via
// Cmix.MakeReceptionIdentity or Cmix.MakeLegacyReceptionIdentity and passed in
// here. If callbacks is left nil, a default auth.Callbacks will be used.
func LoginEphemeral(cmixId int, callbacks AuthCallbacks, identity,
@@ -126,13 +126,15 @@ func (e *E2e) GetContact() []byte {
return e.api.GetReceptionIdentity().GetContact().Marshal()
}
-// GetUdAddressFromNdf retrieve the User Discovery's network address fom the NDF.
+// GetUdAddressFromNdf retrieve the User Discovery's network address fom the
+// NDF.
func (e *E2e) GetUdAddressFromNdf() string {
return e.api.GetCmix().GetInstance().GetPartialNdf().
Get().UDB.Address
}
-// GetUdCertFromNdf retrieves the User Discovery's TLS certificate from the NDF.
+// GetUdCertFromNdf retrieves the User Discovery's TLS certificate (in PEM
+// format) from the NDF.
func (e *E2e) GetUdCertFromNdf() []byte {
return []byte(e.api.GetCmix().GetInstance().GetPartialNdf().Get().UDB.Cert)
}
@@ -178,11 +180,11 @@ type authCallback struct {
}
// convertAuthCallbacks turns an auth.Callbacks into an AuthCallbacks.
-func convertAuthCallbacks(requestor contact.Contact,
+func convertAuthCallbacks(requester contact.Contact,
receptionID receptionID.EphemeralIdentity, round rounds.Round) (
contact []byte, receptionId []byte, ephemeralId int64, roundId int64) {
- contact = requestor.Marshal()
+ contact = requester.Marshal()
receptionId = receptionID.Source.Marshal()
ephemeralId = int64(receptionID.EphId.UInt64())
roundId = int64(round.ID)
@@ -207,6 +209,10 @@ func (a *authCallback) Reset(partner contact.Contact,
a.bindingsCbs.Reset(convertAuthCallbacks(partner, receptionID, round))
}
+////////////////////////////////////////////////////////////////////////////////
+// E2E Tracker //
+////////////////////////////////////////////////////////////////////////////////
+
// e2eTracker is a singleton used to keep track of extant E2e objects,
// preventing race conditions created by passing it over the bindings.
type e2eTracker struct {
@@ -222,15 +228,15 @@ func (ct *e2eTracker) make(c *xxdk.E2e) *E2e {
ct.mux.Lock()
defer ct.mux.Unlock()
- id := ct.count
+ e2eID := ct.count
ct.count++
- ct.tracked[id] = &E2e{
+ ct.tracked[e2eID] = &E2e{
api: c,
- id: id,
+ id: e2eID,
}
- return ct.tracked[id]
+ return ct.tracked[e2eID]
}
// get an E2e from the e2eTracker given its ID.
diff --git a/bindings/identity.go b/bindings/identity.go
index 9b45a9527..b55ee1834 100644
--- a/bindings/identity.go
+++ b/bindings/identity.go
@@ -35,7 +35,7 @@ type ReceptionIdentity struct {
}
// StoreReceptionIdentity stores the given identity in Cmix storage with the
-// given key. This is the ideal way to securely store identities, as the caller
+// given key. This is the ideal way to securely store identities, as the caller
// of this function is only required to store the given key separately rather
// than the keying material.
func StoreReceptionIdentity(key string, identity []byte, cmixId int) error {
@@ -97,8 +97,13 @@ func (c *Cmix) GetReceptionRegistrationValidationSignature() []byte {
// Contact Functions //
////////////////////////////////////////////////////////////////////////////////
-// GetIDFromContact accepts a marshalled contact.Contact object and returns a
-// marshalled id.ID object.
+// GetIDFromContact returns the ID in the [contact.Contact] object.
+//
+// Parameters:
+// - marshaledContact - JSON marshalled bytes of [contact.Contact]
+//
+// Returns:
+// - []byte - bytes of the [id.ID] object
func GetIDFromContact(marshaledContact []byte) ([]byte, error) {
cnt, err := contact.Unmarshal(marshaledContact)
if err != nil {
@@ -108,8 +113,14 @@ func GetIDFromContact(marshaledContact []byte) ([]byte, error) {
return cnt.ID.Marshal(), nil
}
-// GetPubkeyFromContact accepts a marshalled contact.Contact object and returns
-// a JSON marshalled large.Int DH public key.
+// GetPubkeyFromContact returns the DH public key in the [contact.Contact]
+// object.
+//
+// Parameters:
+// - marshaledContact - JSON marshalled bytes of [contact.Contact]
+//
+// Returns:
+// - []byte - JSON marshalled bytes of the [cyclic.Int] object
func GetPubkeyFromContact(marshaledContact []byte) ([]byte, error) {
cnt, err := contact.Unmarshal(marshaledContact)
if err != nil {
@@ -127,8 +138,11 @@ func GetPubkeyFromContact(marshaledContact []byte) ([]byte, error) {
// pass in empty facts in order to clear the facts.
//
// Parameters:
-// - marshaledContact - the JSON marshalled bytes of contact.Contact object.
-// - factListJSON - the JSON marshalled bytes of [fact.FactList].
+// - marshaledContact - the JSON marshalled bytes of [contact.Contact]
+// - factListJSON - the JSON marshalled bytes of [fact.FactList]
+//
+// Returns:
+// - []byte - marshalled bytes of the modified [contact.Contact]
func SetFactsOnContact(marshaledContact []byte, factListJSON []byte) ([]byte, error) {
cnt, err := contact.Unmarshal(marshaledContact)
if err != nil {
@@ -146,13 +160,13 @@ func SetFactsOnContact(marshaledContact []byte, factListJSON []byte) ([]byte, er
return cnt.Marshal(), nil
}
-// GetFactsFromContact returns the fact list in the contact.Contact object.
+// GetFactsFromContact returns the fact list in the [contact.Contact] object.
//
// Parameters:
-// - marshaledContact - the JSON marshalled bytes by of contact.Contact object.
+// - marshaledContact - the JSON marshalled bytes of [contact.Contact]
//
// Returns:
-// - []byte - the JSON marshalled bytes of [fact.FactList].
+// - []byte - the JSON marshalled bytes of [fact.FactList]
func GetFactsFromContact(marshaledContact []byte) ([]byte, error) {
cnt, err := contact.Unmarshal(marshaledContact)
if err != nil {
--
GitLab