clean up comments

e2e/interface.go

@@ -107,11 +107,9 @@ type Handler interface {
 
 	// AddPartner adds a partner. Automatically creates both send
 	// and receive sessions using the passed cryptographic data
-	// and per the parameters sent If an alternate ID public key
+	// and per the parameters sent. If an alternate ID public key
 	// are to be used for this relationship, then pass them in,
-	// otherwise, leave myID and myPrivateKey nil If temporary is
-	// true, an alternate ram kv will be used for storage and the
-	// relationship will not survive a reset
+	// otherwise, leave myID and myPrivateKey nil
 	AddPartner(partnerID *id.ID,
 		partnerPubKey, myPrivKey *cyclic.Int,
 		partnerSIDHPubKey *sidh.PublicKey,
@@ -119,12 +117,12 @@ type Handler interface {
 		receiveParams session.Params) (partner.Manager, error)
 
 	// GetPartner returns the partner per its ID, if it exists
-	// myID is your ID in the relationship, if left blank, it will
+	// myID is your ID in the relationship. If left blank, it will
 	// assume to be your defaultID
 	GetPartner(partnerID *id.ID) (partner.Manager, error)
 
 	// DeletePartner removes the associated contact from the E2E store
-	// myID is your ID in the relationship, if left blank, it will
+	// myID is your ID in the relationship. If left blank, it will
 	// assume to be your defaultID
 	DeletePartner(partnerId *id.ID) error
 

e2e/ratchet/partner/interface.go

@@ -9,40 +9,63 @@ import (
 	"gitlab.com/xx_network/primitives/id"
 )
 
+// Manager create and manages both E2E send and receive sessions using the passed cryptographic data
 type Manager interface {
-	//accessors
+	// GetPartnerID returns the ID of the E2E partner
 	GetPartnerID() *id.ID
+	// GetMyID returns my ID used for the E2E relationship
 	GetMyID() *id.ID
+	// GetMyOriginPrivateKey returns my private key
 	GetMyOriginPrivateKey() *cyclic.Int
+	// GetPartnerOriginPublicKey returns the partner's public key
 	GetPartnerOriginPublicKey() *cyclic.Int
-
+	// GetSendRelationshipFingerprint returns the fingerprint of the send session
 	GetSendRelationshipFingerprint() []byte
+	// GetReceiveRelationshipFingerprint returns the fingerprint of the receive session
 	GetReceiveRelationshipFingerprint() []byte
-
+	// GetConnectionFingerprintBytes returns a unique fingerprint for an E2E relationship in bytes format
 	GetConnectionFingerprintBytes() []byte
+	// GetConnectionFingerprint returns a unique fingerprint for an E2E relationship in string format
 	GetConnectionFingerprint() string
+	// GetContact returns the contact of the E2E partner
 	GetContact() contact.Contact
 
-	//sending and receving
+	// PopSendCypher returns the key which is most likely to be successful for sending
 	PopSendCypher() (*session.Cypher, error)
+	// PopRekeyCypher returns a key which should be used for rekeying
 	PopRekeyCypher() (*session.Cypher, error)
 
-	//Ratcheting
+	// NewReceiveSession creates a new Receive session using the latest private key
+	// this user has sent and the new public key received from the partner. If the
+	// session already exists, then it will not be overwritten and the extant
+	// session will be returned with the bool set to true denoting a duplicate. This
+	// allows for support of duplicate key exchange triggering.
 	NewReceiveSession(partnerPubKey *cyclic.Int,
 		partnerSIDHPubKey *sidh.PublicKey, e2eParams session.Params,
 		source *session.Session) (*session.Session, bool)
+	// NewSendSession creates a new Send session using the latest public key
+	// received from the partner and a new private key for the user. Passing in a
+	// private key is optional. A private key will be generated if none is passed.
 	NewSendSession(myDHPrivKey *cyclic.Int, mySIDHPrivateKey *sidh.PrivateKey,
 		e2eParams session.Params, source *session.Session) *session.Session
+	// GetSendSession gets the Send session of the passed ID. Returns nil if no session is found.
 	GetSendSession(sid session.SessionID) *session.Session
-
-	//state machine
+	//GetReceiveSession gets the Receive session of the passed ID. Returns nil if no session is found.
 	GetReceiveSession(sid session.SessionID) *session.Session
+
+	// Confirm sets the passed session ID as confirmed and cleans up old sessions
 	Confirm(sid session.SessionID) error
+
+	// TriggerNegotiations returns a list of session that need rekeys
 	TriggerNegotiations() []*session.Session
 
-	//services
+	// MakeService Returns a service interface with the
+	// appropriate identifier for who is being sent to. Will populate
+	// the metadata with the partner
 	MakeService(tag string) message.Service
 
-	//storage
+	// Delete removes the relationship between the partner
+	// and deletes the Send and Receive sessions. This includes the
+	// sessions and the key vectors
 	Delete() error
 }

e2e/ratchet/partner/manager.go

@@ -30,6 +30,7 @@ const managerPrefix = "Manager{partner:%s}"
 const originMyPrivKeyKey = "originMyPrivKey"
 const originPartnerPubKey = "originPartnerPubKey"
 
+// Implements the partner.Manager interface
 type manager struct {
 	kv *versioned.KV
 
@@ -231,14 +232,12 @@ func (m *manager) NewSendSession(myPrivKey *cyclic.Int,
 		sourceSession.GetID(), session.Sending, e2eParams)
 }
 
-// PopSendCypher gets the correct session to Send with depending on the type
-// of Send.
+// PopSendCypher returns the key which is most likely to be successful for sending
 func (m *manager) PopSendCypher() (*session.Cypher, error) {
 	return m.send.getKeyForSending()
 }
 
-// PopRekeyCypher gets the correct session to Send with depending on the type
-// of Send.
+// PopRekeyCypher returns a key which should be used for rekeying
 func (m *manager) PopRekeyCypher() (*session.Cypher, error) {
 	return m.send.getKeyForRekey()
 
@@ -266,14 +265,12 @@ func (m *manager) GetReceiveSession(sid session.SessionID) *session.Session {
 	return m.receive.GetByID(sid)
 }
 
-// GetSendRelationshipFingerprint gets the Send session of the passed ID. Returns nil if no
-// session is found.
+// GetSendRelationshipFingerprint
 func (m *manager) GetSendRelationshipFingerprint() []byte {
 	return m.send.fingerprint
 }
 
-// GetReceiveRelationshipFingerprint gets the receive session of the passed ID.
-// Returns nil if no session is found.
+// GetReceiveRelationshipFingerprint
 func (m *manager) GetReceiveRelationshipFingerprint() []byte {
 	return m.receive.fingerprint
 }
@@ -283,8 +280,7 @@ func (m *manager) Confirm(sid session.SessionID) error {
 	return m.send.Confirm(sid)
 }
 
-// TriggerNegotiations returns a list of key exchange operations if any are
-// necessary.
+// TriggerNegotiations returns a list of key exchange operations if any are necessary.
 func (m *manager) TriggerNegotiations() []*session.Session {
 	return m.send.TriggerNegotiation()
 }
@@ -299,8 +295,8 @@ func (m *manager) GetPartnerOriginPublicKey() *cyclic.Int {
 
 const relationshipFpLength = 15
 
-// GetRelationshipFingerprint returns a unique fingerprint for an E2E
-// relationship. The fingerprint is a base 64 encoded hash of of the two
+// GetConnectionFingerprint returns a unique fingerprint for an E2E
+// relationship. The fingerprint is a base 64 encoded hash of the two
 // relationship fingerprints truncated to 15 characters.
 func (m *manager) GetConnectionFingerprint() string {
 
@@ -309,8 +305,8 @@ func (m *manager) GetConnectionFingerprint() string {
 		m.GetConnectionFingerprintBytes())[:relationshipFpLength]
 }
 
-// GetRelationshipFingerprintBytes returns a unique fingerprint for an E2E
-// relationship. used for the e2e preimage.
+// GetConnectionFingerprintBytes returns a unique fingerprint for an E2E
+// relationship used for the e2e preimage.
 func (m *manager) GetConnectionFingerprintBytes() []byte {
 	// Sort fingerprints
 	var fps [][]byte

e2e/ratchet/partner/relationship.go

@@ -311,11 +311,9 @@ func (r *relationship) getSessionForSending() *session.Session {
 	return nil
 }
 
-// todo - doscstring
-// returns a list of session that need rekeys. Nil instances mean a new rekey
-// from scratch
+// TriggerNegotiation returns a list of session that need rekeys. Nil instances mean a new rekey from scratch
 func (r *relationship) TriggerNegotiation() []*session.Session {
-	//dont need to take the lock due to the use of a copy of the buffer
+	// Don't need to take the lock due to the use of a copy of the buffer
 	sessions := r.getInternalBufferShallowCopy()
 	var instructions []*session.Session
 	for _, ses := range sessions {
@@ -379,10 +377,7 @@ func (r *relationship) GetByID(id session.SessionID) *session.Session {
 	return r.sessionByID[id]
 }
 
-// todo - doscstring
-// sets the passed session ID as confirmed. Call "GetSessionRotation" after
-// to get any sessions that are to be deleted and then "DeleteSession" to
-// remove them
+// Confirm sets the passed session ID as confirmed and cleans up old sessions
 func (r *relationship) Confirm(id session.SessionID) error {
 	r.mux.Lock()
 	defer r.mux.Unlock()
@@ -409,7 +404,7 @@ func (r *relationship) getInternalBufferShallowCopy() []*session.Session {
 	return r.sessions
 }
 
-// todo - doscstring
+// clean deletes old confirmed sessions
 func (r *relationship) clean() {
 
 	numConfirmed := uint(0)
@@ -432,7 +427,7 @@ func (r *relationship) clean() {
 		newSessions = append(newSessions, s)
 	}
 
-	//only do the update and save if changes occured
+	//only do the update and save if changes occurred
 	if editsMade {
 		r.sessions = newSessions
 

e2e/ratchet/partner/session/session.go

@@ -515,7 +515,6 @@ func (s *Session) NegotiationStatus() Negotiation {
 // IsConfirmed checks if the session has been confirmed
 func (s *Session) IsConfirmed() bool {
 	c := s.NegotiationStatus()
-	//fmt.Println(c)
 	return c >= Confirmed
 }