Use hash size as KSF output size, expose KSF parameters & salt in configuration

client.go

@@ -67,7 +67,7 @@ func (c *Client) GetConf() *internal.Configuration {
 // buildPRK derives the randomized password from the OPRF output.
 func (c *Client) buildPRK(evaluation *group.Element) []byte {
 	output := c.OPRF.Finalize(evaluation)
-	stretched := c.conf.KSF.Harden(output, nil, c.conf.OPRF.Group().ElementLength())
+	stretched := c.conf.KSF.Harden(output, c.conf.KSFSalt, c.conf.Hash.Size())
 
 	return c.conf.KDF.Extract(nil, encoding.Concat(output, stretched))
 }

examples_test.go

@@ -31,7 +31,7 @@ func isSameConf(a, b *opaque.Configuration) bool {
 		a.KDF != b.KDF ||
 		a.MAC != b.MAC ||
 		a.Hash != b.Hash ||
-		a.KSF != b.KSF ||
+		!reflect.DeepEqual(a.KSF, b.KSF) ||
 		a.AKE != b.AKE {
 		return false
 	}
@@ -48,11 +48,13 @@ func Example_configuration() {
 	defaultConf := opaque.DefaultConfiguration()
 
 	customConf := &opaque.Configuration{
-		OPRF:    opaque.RistrettoSha512,
-		KDF:     crypto.SHA512,
-		MAC:     crypto.SHA512,
-		Hash:    crypto.SHA512,
-		KSF:     ksf.Argon2id,
+		OPRF: opaque.RistrettoSha512,
+		KDF:  crypto.SHA512,
+		MAC:  crypto.SHA512,
+		Hash: crypto.SHA512,
+		KSF: opaque.KSFConfiguration{
+			Identifier: ksf.Argon2id,
+		},
 		AKE:     opaque.RistrettoSha512,
 		Context: nil,
 	}
@@ -79,7 +81,7 @@ func Example_configuration() {
 
 	fmt.Println("OPAQUE configuration is easy!")
 
-	// Output: Encoded Configuration: 0107070701010000
+	// Output: Encoded Configuration: 010707070101000000000000
 	// OPAQUE configuration is easy!
 }
 

internal/configuration.go

@@ -36,6 +36,7 @@ type Configuration struct {
 	MAC          *Mac
 	Hash         *Hash
 	KSF          *KSF
+	KSFSalt      []byte
 	OPRF         oprf.Identifier
 	Context      []byte
 	NonceLen     int

internal/hash.go

@@ -108,6 +108,7 @@ type KSF struct {
 type ksfInterface interface {
 	// Harden uses default parameters for the key derivation function over the input password and salt.
 	Harden(password, salt []byte, length int) []byte
+	Parameterize(parameters ...int)
 }
 
 // IdentityKSF represents a KSF with no operations.
@@ -117,3 +118,5 @@ type IdentityKSF struct{}
 func (i IdentityKSF) Harden(password, _ []byte, _ int) []byte {
 	return password
 }
+
+func (i IdentityKSF) Parameterize(parameters ...int) {}

opaque.go

@@ -67,7 +67,7 @@ func (g Group) Group() group.Group {
 	return group.Group(g)
 }
 
-const confLength = 6
+const confIdsLength = 6
 
 var (
 	errInvalidOPRFid = errors.New("invalid OPRF group id")
@@ -78,26 +78,34 @@ var (
 	errInvalidAKEid  = errors.New("invalid AKE group id")
 )
 
+type KSFConfiguration struct {
+	Identifier ksf.Identifier `json:"identifier"`
+	Parameters []int          `json:"parameters"`
+	Salt       []byte         `json:"salt"`
+}
+
 // Configuration represents an OPAQUE configuration. Note that OprfGroup and AKEGroup are recommended to be the same,
 // as well as KDF, MAC, Hash should be the same.
 type Configuration struct {
 	Context []byte
-	KDF     crypto.Hash    `json:"kdf"`
-	MAC     crypto.Hash    `json:"mac"`
-	Hash    crypto.Hash    `json:"hash"`
-	OPRF    Group          `json:"oprf"`
-	KSF     ksf.Identifier `json:"ksf"`
-	AKE     Group          `json:"group"`
+	KDF     crypto.Hash      `json:"kdf"`
+	MAC     crypto.Hash      `json:"mac"`
+	Hash    crypto.Hash      `json:"hash"`
+	OPRF    Group            `json:"oprf"`
+	KSF     KSFConfiguration `json:"ksf"`
+	AKE     Group            `json:"group"`
 }
 
 // DefaultConfiguration returns a default configuration with strong parameters.
 func DefaultConfiguration() *Configuration {
 	return &Configuration{
-		OPRF:    RistrettoSha512,
-		KDF:     crypto.SHA512,
-		MAC:     crypto.SHA512,
-		Hash:    crypto.SHA512,
-		KSF:     ksf.Argon2id,
+		OPRF: RistrettoSha512,
+		KDF:  crypto.SHA512,
+		MAC:  crypto.SHA512,
+		Hash: crypto.SHA512,
+		KSF: KSFConfiguration{
+			Identifier: ksf.Argon2id,
+		},
 		AKE:     RistrettoSha512,
 		Context: nil,
 	}
@@ -145,7 +153,7 @@ func (c *Configuration) verify() error {
 		return errInvalidHASHid
 	}
 
-	if c.KSF != 0 && !c.KSF.Available() {
+	if c.KSF.Identifier != 0 && !c.KSF.Identifier.Available() {
 		return errInvalidKSFid
 	}
 
@@ -166,13 +174,18 @@ func (c *Configuration) toInternal() (*internal.Configuration, error) {
 		KDF:          internal.NewKDF(c.KDF),
 		MAC:          mac,
 		Hash:         internal.NewHash(c.Hash),
-		KSF:          internal.NewKSF(c.KSF),
+		KSF:          internal.NewKSF(c.KSF.Identifier),
+		KSFSalt:      c.KSF.Salt,
 		NonceLen:     internal.NonceLength,
 		EnvelopeSize: internal.NonceLength + mac.Size(),
 		Group:        g,
 		Context:      c.Context,
 	}
 
+	if c.KSF.Parameters != nil {
+		ip.KSF.Parameterize(c.KSF.Parameters...)
+	}
+
 	return ip, nil
 }
 
@@ -189,16 +202,23 @@ func (c *Configuration) Deserializer() (*Deserializer, error) {
 
 // Serialize returns the byte encoding of the Configuration structure.
 func (c *Configuration) Serialize() []byte {
-	b := []byte{
+	ids := []byte{
 		byte(c.OPRF),
 		byte(c.KDF),
 		byte(c.MAC),
 		byte(c.Hash),
-		byte(c.KSF),
+		byte(c.KSF.Identifier),
 		byte(c.AKE),
 	}
 
-	return encoding.Concat(b, encoding.EncodeVector(c.Context))
+	var ksfEncodedParams []byte
+	for _, param := range c.KSF.Parameters {
+		ksfEncodedParams = append(ksfEncodedParams, encoding.I2OSP(param, 4)...)
+	}
+	ksfEncodedParams = encoding.EncodeVector(ksfEncodedParams)
+	ksfEncodedSalt := encoding.EncodeVector(c.KSF.Salt)
+
+	return encoding.Concatenate(ids, encoding.EncodeVector(c.Context), ksfEncodedParams, ksfEncodedSalt)
 }
 
 // GetFakeRecord creates a fake Client record to be used when no existing client record exists,
@@ -228,21 +248,50 @@ func (c *Configuration) GetFakeRecord(credentialIdentifier []byte) (*ClientRecor
 
 // DeserializeConfiguration decodes the input and returns a Parameter structure.
 func DeserializeConfiguration(encoded []byte) (*Configuration, error) {
-	if len(encoded) < confLength+2 { // corresponds to the configuration length + 2-byte encoding of empty context
+	if len(encoded) < confIdsLength+2 { // corresponds to the configuration length + 2-byte encoding of empty context
 		return nil, internal.ErrConfigurationInvalidLength
 	}
 
-	ctx, _, err := encoding.DecodeVector(encoded[confLength:])
+	ctx, _, err := encoding.DecodeVector(encoded[confIdsLength:])
 	if err != nil {
 		return nil, fmt.Errorf("decoding the configuration context: %w", err)
 	}
 
+	var ksfParams []int
+	ksfParamOffset := confIdsLength + 2 + len(ctx)
+
+	if len(encoded) >= ksfParamOffset+2 {
+		ksfEncodedParams, _, err := encoding.DecodeVector(encoded[ksfParamOffset:])
+		if err != nil {
+			return nil, fmt.Errorf("decoding the ksf configuration parameters: %w", err)
+		}
+		for i := 0; i < len(ksfEncodedParams); i += 4 {
+			ksfParams = append(ksfParams, encoding.OS2IP(ksfEncodedParams[i:i+4]))
+		}
+	}
+
+	var ksfSalt []byte
+	ksfSaltOffset := ksfParamOffset + 2 + (len(ksfParams) * 4)
+	if len(encoded) >= ksfSaltOffset+2 {
+		ksfSalt, _, err = encoding.DecodeVector(encoded[ksfSaltOffset:])
+		if err != nil {
+			return nil, fmt.Errorf("decoding the ksf salt: %w", err)
+		}
+		if len(ksfSalt) == 0 {
+			ksfSalt = nil
+		}
+	}
+
 	c := &Configuration{
-		OPRF:    Group(encoded[0]),
-		KDF:     crypto.Hash(encoded[1]),
-		MAC:     crypto.Hash(encoded[2]),
-		Hash:    crypto.Hash(encoded[3]),
-		KSF:     ksf.Identifier(encoded[4]),
+		OPRF: Group(encoded[0]),
+		KDF:  crypto.Hash(encoded[1]),
+		MAC:  crypto.Hash(encoded[2]),
+		Hash: crypto.Hash(encoded[3]),
+		KSF: KSFConfiguration{
+			Identifier: ksf.Identifier(encoded[4]),
+			Parameters: ksfParams,
+			Salt:       ksfSalt,
+		},
 		AKE:     Group(encoded[5]),
 		Context: ctx,
 	}

tests/deserializer_test.go

@@ -38,11 +38,13 @@ func TestDeserializer(t *testing.T) {
 
 	// Test for an invalid configuration.
 	conf := &opaque.Configuration{
-		OPRF:    0,
-		KDF:     0,
-		MAC:     0,
-		Hash:    0,
-		KSF:     0,
+		OPRF: 0,
+		KDF:  0,
+		MAC:  0,
+		Hash: 0,
+		KSF: opaque.KSFConfiguration{
+			Identifier: 0,
+		},
 		AKE:     0,
 		Context: nil,
 	}

tests/fuzz_test.go

@@ -52,7 +52,7 @@ func fuzzTestConfigurationError(t *testing.T, c *opaque.Configuration, err error
 		{errors.New("invalid KDF id"), c.KDF, hash.Hash(c.KDF).Available()},
 		{errors.New("invalid MAC id"), c.MAC, hash.Hash(c.MAC).Available()},
 		{errors.New("invalid Hash id"), c.Hash, hash.Hash(c.Hash).Available()},
-		{errors.New("invalid KSF id"), c.KSF, c.KSF == 0 && c.KSF.Available()},
+		{errors.New("invalid KSF id"), c.KSF.Identifier, c.KSF.Identifier == 0 && c.KSF.Identifier.Available()},
 		{errors.New("invalid OPRF group id"), c.OPRF, c.OPRF.Available() && c.OPRF.OPRF().Available()},
 		{errors.New("invalid AKE group id"), c.AKE, c.AKE.Available() && c.AKE.Group().Available()},
 	}
@@ -202,8 +202,10 @@ func inputToConfig(context []byte, kdf, mac, h uint, o []byte, ksfID, ake byte)
 		MAC:     crypto.Hash(mac),
 		Hash:    crypto.Hash(h),
 		OPRF:    oprfToGroup(oprf.Identifier(o)),
-		KSF:     ksf.Identifier(ksfID),
-		AKE:     opaque.Group(ake),
+		KSF: opaque.KSFConfiguration{
+			Identifier: ksf.Identifier(ksfID),
+		},
+		AKE: opaque.Group(ake),
 	}
 }
 

tests/helper_test.go

@@ -54,8 +54,10 @@ var configurationTable = []configuration{
 			KDF:  crypto.SHA256,
 			MAC:  crypto.SHA256,
 			Hash: crypto.SHA256,
-			KSF:  ksf.Scrypt,
-			AKE:  opaque.P256Sha256,
+			KSF: opaque.KSFConfiguration{
+				Identifier: ksf.Scrypt,
+			},
+			AKE: opaque.P256Sha256,
 		},
 		curve: elliptic.P256(),
 	},
@@ -66,8 +68,10 @@ var configurationTable = []configuration{
 			KDF:  crypto.SHA512,
 			MAC:  crypto.SHA512,
 			Hash: crypto.SHA512,
-			KSF:  ksf.Scrypt,
-			AKE:  opaque.P384Sha512,
+			KSF: opaque.KSFConfiguration{
+				Identifier: ksf.Scrypt,
+			},
+			AKE: opaque.P384Sha512,
 		},
 		curve: elliptic.P384(),
 	},
@@ -78,8 +82,10 @@ var configurationTable = []configuration{
 			KDF:  crypto.SHA512,
 			MAC:  crypto.SHA512,
 			Hash: crypto.SHA512,
-			KSF:  ksf.Scrypt,
-			AKE:  opaque.P521Sha512,
+			KSF: opaque.KSFConfiguration{
+				Identifier: ksf.Scrypt,
+			},
+			AKE: opaque.P521Sha512,
 		},
 		curve: elliptic.P521(),
 	},