Package documentation

herradurakex.go

@@ -28,7 +28,7 @@ import (
 	"time"
 )
 
-// This type holds the session state for a key exchange
+// HerraduraKEx holds the session state for a key exchange.
 type HerraduraKEx struct {
 	intSz, pubSz int
 	randctx      *rand.Rand
@@ -43,7 +43,12 @@ type HerraduraKEx struct {
 //	return New(256, 64)
 //}
 
-// Returns a new HerraduraKEx struct
+// Return a new HerraduraKEx struct.
+//   i - internal (private) random nonce
+//   p - public (exchanged) random nonce (typically 1/4 bitsize of i)
+//
+//   If i or p are passed as zero, they will default to 256 and 64,
+//   respectively.
 func New(i int, p int) (h *HerraduraKEx) {
 	h = new(HerraduraKEx)
 
@@ -117,8 +122,8 @@ func (h *HerraduraKEx) fscx(up, down *big.Int) (result *big.Int) {
 	return result
 }
 
-// This is the iteration function using the result of the previous iteration as the first
-// parameter and the second parameter of the first iteration
+// This is the iteration function using the result of the previous iteration
+// as the first parameter and the second parameter of the first iteration.
 func (h *HerraduraKEx) fscxRevolve(x, y *big.Int, passes int) (result *big.Int) {
 	result = big.NewInt(0)
 
@@ -129,15 +134,19 @@ func (h *HerraduraKEx) fscxRevolve(x, y *big.Int, passes int) (result *big.Int)
 	return result
 }
 
+// Return the D (FSCX Revolved) value, input to generate FA
+// (the value for peer KEx)
 func (h *HerraduraKEx) D() *big.Int {
 	return h.d
 }
 
+// Return the FA value, which must be sent to peer for KEx.
 func (h *HerraduraKEx) FA() {
 	h.fa = h.fscxRevolve(h.PeerD, h.b, h.intSz-h.pubSz)
 	h.fa.Xor(h.fa, h.a)
 }
 
+// Output HerraduraKEx type value as a string. Implements Stringer interface.
 func (h *HerraduraKEx) String() string {
 	return fmt.Sprintf("s:%d p:%d\na:%s\nb:%s\nd:->%s\n<-PeerD:%s\nfa:%s",
 		h.intSz, h.pubSz,

hkexchan.go

@@ -15,6 +15,7 @@
     along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
     golang implementation by Russ Magee (rmagee_at_gmail.com) */
+
 package herradurakex
 
 /* Support functions to set up encryption once an HKEx Conn has been
@@ -28,10 +29,12 @@ import (
 	"os"
 )
 
+// Available ciphers for hkex.Conn
 const (
-	C_AES_256 = 0
+	C_AES_256 = 0  // (TODO: config or pass during KEx Dial()/Accept())  AES-256 cipher
 )
 
+// Available HMACs for hkex.Conn (TODO: not currently used)
 const (
 	H_SHA256 = 0
 )

hkexnet.go

@@ -15,12 +15,12 @@
     along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
     golang implementation by Russ Magee (rmagee_at_gmail.com) */
+
 package herradurakex
 
 // Implementation of HKEx-wrapped versions of the golang standard
 // net package interfaces, allowing clients and servers to simply replace
-// 'net.Dial', 'net.Listen' etc. with 'hkex.Dial', 'hkex.Listen' and so
-// forth.
+// 'net.Dial' and 'net.Listen' with 'hkex.Dial' and 'hkex.Listen'.
 import (
 	"bytes"
 	"crypto/cipher"
@@ -31,6 +31,7 @@ import (
 
 /*---------------------------------------------------------------------*/
 
+// A HKex connection - drop-in replacement for net.Conn
 type Conn struct {
 	c net.Conn // which also implements io.Reader, io.Writer, ...
 	h *HerraduraKEx
@@ -64,6 +65,7 @@ func Dial(protocol string, ipport string) (hc *Conn, err error) {
 	return
 }
 
+// Close a hkex.Conn
 func (hc *Conn) Close() (err error) {
 	err = hc.c.Close()
 	fmt.Println("[Conn Closing]")
@@ -72,10 +74,12 @@ func (hc *Conn) Close() (err error) {
 
 /*---------------------------------------------------------------------*/
 
+// A hkex Listener, conforming to net.Listener - returns a hkex.Conn
 type HKExListener struct {
 	l net.Listener
 }
 
+// hkex.Listen, a drop-in replacement for net.Conn.Listen
 func Listen(protocol string, ipport string) (hl HKExListener, e error) {
 	l, err := net.Listen(protocol, ipport)
 	if err != nil {
@@ -86,11 +90,13 @@ func Listen(protocol string, ipport string) (hl HKExListener, e error) {
 	return
 }
 
+// Close a hkex Listener
 func (hl *HKExListener) Close() {
 	hl.l.Close()
 	fmt.Println("[Listener Closed]")
 }
 
+// Accept a client connection, conforming to net.Listener.Accept()
 func (hl *HKExListener) Accept() (hc Conn, err error) {
 	c, err := hl.l.Accept()
 
@@ -153,7 +159,8 @@ func (hc Conn) Write(b []byte) (n int, err error) {
 // Return c coerced into a HKEx Conn (which implements interface net.Conn)
 //   Only useful if one wants to convert an open connection later to HKEx
 //   (Use Dial() instead to start with HKEx automatically.)
-func NewHKExConn(c *net.Conn) (hc *Conn) {
+/*
+ func NewHKExConn(c *net.Conn) (hc *Conn) {
 	hc = new(Conn)
 
 	hc.c = *c
@@ -168,3 +175,5 @@ func NewHKExConn(c *net.Conn) (hc *Conn) {
 	fmt.Printf("** peerD:%s\n", hc.h.PeerD.Text(16))
 	return
 }
+*/
+