Added documentation and adjusted API

Author: gschier

Diff for: client.go

@@ -7,34 +7,29 @@ import (
 )
 
 type SRPClient struct {
-	// Set in constructor
 	Params     *SRPParams
 	Secret1    *big.Int
 	Multiplier *big.Int
 	A          *big.Int
 	X          *big.Int
-
-	// Set in SetB
-	M1 []byte
-	M2 []byte
-	K  []byte
-
-	// Private (for tests)
-	U *big.Int
-	S *big.Int
+	M1         []byte
+	M2         []byte
+	K          []byte
+	u          *big.Int
+	s          *big.Int
 }
 
-func NewClient(params *SRPParams, salt, identity, password, S1b []byte) *SRPClient {
+func NewClient(params *SRPParams, salt, identity, password, secret1 []byte) *SRPClient {
 	multiplier := getMultiplier(params)
-	secret1 := intFromBytes(S1b)
-	Ab := getA(params, secret1)
+	secret1Int := intFromBytes(secret1)
+	Ab := getA(params, secret1Int)
 	A := intFromBytes(Ab)
 	x := getx(params, salt, identity, password)
 
 	return &SRPClient{
 		Params:     params,
 		Multiplier: multiplier,
-		Secret1:    secret1,
+		Secret1:    secret1Int,
 		A:          A,
 		X:          x,
 	}
@@ -44,6 +39,16 @@ func (c *SRPClient) ComputeA() []byte {
 	return intToBytes(c.A)
 }
 
+// ComputeVerifier returns a verifier that is calculated as described in
+// Section 3 of [SRP-RFC]
+func ComputeVerifier(params *SRPParams, salt, I, P []byte) []byte {
+	x := getx(params, salt, I, P)
+	vNum := new(big.Int)
+	vNum.Exp(params.G, x, params.N)
+
+	return padToN(vNum, params)
+}
+
 func (c *SRPClient) SetB(Bb []byte) {
 	B := intFromBytes(Bb)
 	u := getu(c.Params, c.A, B)
@@ -53,8 +58,8 @@ func (c *SRPClient) SetB(Bb []byte) {
 	c.M1 = getM1(c.Params, intToBytes(c.A), Bb, S)
 	c.M2 = getM2(c.Params, intToBytes(c.A), c.M1, c.K)
 
-	c.U = u               // Only for tests
-	c.S = intFromBytes(S) // Only for tests
+	c.u = u               // Only for tests
+	c.s = intFromBytes(S) // Only for tests
 }
 
 func (c *SRPClient) ComputeM1() []byte {
@@ -129,11 +134,3 @@ func getx(params *SRPParams, salt, I, P []byte) *big.Int {
 
 	return hashToInt(hashX)
 }
-
-func ComputeVerifier(params *SRPParams, salt, I, P []byte) []byte {
-	x := getx(params, salt, I, P)
-	vNum := new(big.Int)
-	vNum.Exp(params.G, x, params.N)
-
-	return padToN(vNum, params)
-}

Diff for: params.go

@@ -29,7 +29,7 @@ func createParams(G int64, nBitLength int, hash crypto.Hash, NHex string) *SRPPa
 	return &p
 }
 
-func Params(G int) *SRPParams {
+func GetParams(G int) *SRPParams {
 	params := knownGroups[G]
 	if params == nil {
 		panic(fmt.Sprintf("Params don't exist for %v", G))

Diff for: server.go

@@ -7,20 +7,15 @@ import (
 )
 
 type SRPServer struct {
-	// Set in constructor
 	Params   *SRPParams
 	Verifier *big.Int
 	Secret2  *big.Int
 	B        *big.Int
-
-	// Set in SetA
-	M1 []byte
-	M2 []byte
-	K  []byte
-
-	// Private (for tests)
-	U *big.Int
-	S *big.Int
+	M1       []byte
+	M2       []byte
+	K        []byte
+	u        *big.Int
+	s        *big.Int
 }
 
 func NewServer(params *SRPParams, Vb []byte, S2b []byte) *SRPServer {
@@ -52,8 +47,8 @@ func (s *SRPServer) SetA(A []byte) {
 	s.M1 = getM1(s.Params, A, intToBytes(s.B), S)
 	s.M2 = getM2(s.Params, A, s.M1, s.K)
 
-	s.U = U               // only for tests
-	s.S = intFromBytes(S) // only for tests
+	s.u = U               // only for tests
+	s.s = intFromBytes(S) // only for tests
 }
 
 func (s *SRPServer) CheckM1(M1 []byte) ([]byte, error) {

Diff for: srp.go

@@ -1,3 +1,46 @@
+// Package srp is port of node-srp to Go.
+//
+//
+// To use SRP, first decide on they parameters you will use. Both client and server must
+// use the same set.
+//  params := srp.GetParams(4096)
+//
+// From the client... generate a new secret key, initialize the client, and compute A.
+// Once you have A, you can send A to the server.
+//  secret1 := srp.GenKey()
+//  client := NewClient(params, salt, identity, secret, a)
+//  srpA := client.computeA()
+//
+//  sendToServer(srpA)
+//
+// From the server... generate another secret key, initialize the server, and compute B.
+// Once you have B, you can send B to the client.
+//  secret2 := srp.GenKey()
+//  server := NewServer(params, verifier, secret2)
+//  srpB := client.computeB()
+//
+//  sendToClient(srpB)
+//
+// Once the client received B from the server, it can compute M1 based on A and B.
+// Once you have M1, send M1 to the server.
+//  client.setB(srpB)
+//  srpM1 := client.ComputeM1()
+//  sendM1ToServer(srpM1)
+//
+// Once the server receives M1, it can verify that it is correct. If checkM1() returns
+// an error, authentication failed. If it succeeds it should be sent to the client.
+//  srpM2, err := server.checkM1(srpM1)
+//
+// Once the client receives M2, it can verify that it is correct, and know that authentication
+// was successful.
+//  err = client.CheckM2(serverM2)
+//
+// Now that both client and server have completed a successful authentication, they can
+// both compute K independently. K can now be used as either a key to encrypt communication
+// or as a session ID.
+//  clientK := client.ComputeK()
+//  serverK := server.ComputeK()
+//
 package srp
 
 import (
@@ -6,8 +49,8 @@ import (
 	"math/big"
 )
 
-func GenKey(numBytes int) []byte {
-	bytes := make([]byte, numBytes)
+func GenKey() []byte {
+	bytes := make([]byte, 32)
 	_, err := io.ReadFull(rand.Reader, bytes)
 	if err != nil {
 		panic("Random source is broken!")

Diff for: srp_test.go

@@ -11,8 +11,8 @@ var identity = []byte("alice")
 var password = []byte("password123")
 
 func getAAndB() ([]byte, []byte) {
-	a := GenKey(64)
-	b := GenKey(32)
+	a := GenKey()
+	b := GenKey()
 	return a, b
 }
 
@@ -41,13 +41,13 @@ func getVerifier() []byte {
 }
 
 func TestCreateVerifier(t *testing.T) {
-	verifier := ComputeVerifier(Params(4096), salt, identity, password)
+	verifier := ComputeVerifier(GetParams(4096), salt, identity, password)
 	expected := getVerifier()
 	assert.Equal(t, expected, verifier, "Verifier did not match")
 }
 
 func TestUseAAndB(t *testing.T) {
-	params := Params(4096)
+	params := GetParams(4096)
 	a, b := getAAndB()
 
 	// Create client
@@ -91,7 +91,7 @@ func TestUseAAndB(t *testing.T) {
 
 func TestServerRejectsWrongM1(t *testing.T) {
 	a, b := getAAndB()
-	params := Params(4096)
+	params := GetParams(4096)
 	badClient := NewClient(params, salt, identity, []byte("Bad"), a)
 	server := NewServer(params, getVerifier(), b)
 	badClient.SetB(server.ComputeB())
@@ -105,7 +105,7 @@ func TestServerRejectsBadA(t *testing.T) {
 	// number itself is examined.
 
 	_, b := getAAndB()
-	params := Params(4096)
+	params := GetParams(4096)
 	server := NewServer(params, getVerifier(), b)
 
 	assert.Panics(t, func() {
@@ -126,7 +126,7 @@ func TestServerRejectsBadA(t *testing.T) {
 func TestClientRejectsBadB(t *testing.T) {
 	// server's "B" must be 1..N-1 . Reject 0 and N and N+1
 	a, _ := getAAndB()
-	params := Params(4096)
+	params := GetParams(4096)
 	client := NewClient(params, salt, identity, password, a)
 
 	assert.Panics(t, func() {
@@ -146,7 +146,7 @@ func TestClientRejectsBadB(t *testing.T) {
 
 func TestClientRejectsBadM2(t *testing.T) {
 	a, b := getAAndB()
-	params := Params(4096)
+	params := GetParams(4096)
 	client := NewClient(params, salt, identity, password, a)
 
 	// Client produces A
@@ -183,7 +183,7 @@ func TestClientRejectsBadM2(t *testing.T) {
 }
 
 func TestRFC5054(t *testing.T) {
-	params := Params(1024)
+	params := GetParams(1024)
 	I := []byte("alice")
 	P := []byte("password123")
 	s := bytesFromHexString("beb25379d1a8581eb5a727673a2441ee")
@@ -238,10 +238,10 @@ func TestRFC5054(t *testing.T) {
 
 	// u and S client
 	client.SetB(BExpected)
-	assert.Equal(t, uExpected, intToBytes(client.U), "u should match")
-	assert.Equal(t, SExpected, intToBytes(client.S), "S should match")
+	assert.Equal(t, uExpected, intToBytes(client.u), "u should match")
+	assert.Equal(t, SExpected, intToBytes(client.s), "S should match")
 
 	// S server
 	server.SetA(AExpected)
-	assert.Equal(t, SExpected, intToBytes(server.S), "S should match")
+	assert.Equal(t, SExpected, intToBytes(server.s), "S should match")
 }