Package documentation

This commit is contained in:
Russ Magee 2018-01-11 13:44:11 -08:00
parent d4c9a1e456
commit 02d4d0cd50
3 changed files with 29 additions and 8 deletions

View File

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

View File

@ -15,6 +15,7 @@
along with this program. If not, see <https://www.gnu.org/licenses/>. along with this program. If not, see <https://www.gnu.org/licenses/>.
golang implementation by Russ Magee (rmagee_at_gmail.com) */ golang implementation by Russ Magee (rmagee_at_gmail.com) */
package herradurakex package herradurakex
/* Support functions to set up encryption once an HKEx Conn has been /* Support functions to set up encryption once an HKEx Conn has been
@ -28,10 +29,12 @@ import (
"os" "os"
) )
// Available ciphers for hkex.Conn
const ( 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 ( const (
H_SHA256 = 0 H_SHA256 = 0
) )

View File

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