From 02d4d0cd504ce3db38a578c0123744abcbe623b8 Mon Sep 17 00:00:00 2001 From: Russ Magee Date: Thu, 11 Jan 2018 13:44:11 -0800 Subject: [PATCH] Package documentation --- herradurakex.go | 17 +++++++++++++---- hkexchan.go | 5 ++++- hkexnet.go | 15 ++++++++++++--- 3 files changed, 29 insertions(+), 8 deletions(-) diff --git a/herradurakex.go b/herradurakex.go index c789e83..5312cca 100644 --- a/herradurakex.go +++ b/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, diff --git a/hkexchan.go b/hkexchan.go index 884e45c..54f1ad3 100644 --- a/hkexchan.go +++ b/hkexchan.go @@ -15,6 +15,7 @@ along with this program. If not, see . 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 ) diff --git a/hkexnet.go b/hkexnet.go index b6a24f3..ddacb61 100644 --- a/hkexnet.go +++ b/hkexnet.go @@ -15,12 +15,12 @@ along with this program. If not, see . 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 } +*/ +