policy

Description:

Multi-factor key derivation policy

Source:

policy/index.js, line 1

Methods

(async, static) derive(policy, factors) → {MFKDFDerivedKey}

Description:

Derive a policy-based multi-factor derived key

Source:

policy/derive.js, line 67

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  ), { size: 8 }
)

// derive key with passwordA and passwordC (or passwordA and passwordB)
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordA: mfkdf.derive.factors.password('passwordA'),
  passwordC: mfkdf.derive.factors.password('passwordC'),
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name	Type	Description
`policy`	Object	The key policy for the key being derived
`factors`	Object.<string, MFKDFFactor>	Factors used to derive this key

Returns:

A multi-factor derived key object

Type: MFKDFDerivedKey

(static) evaluate(policy, factors) → {boolean}

Description:

Evaluate a policy-based multi-factor derived key

Source:

policy/evaluate.js, line 39

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  )
)

// check if key can be derived with passwordA and passwordC
const valid1 = await mfkdf.policy.evaluate(setup.policy, ['passwordA', 'passwordC']) // -> true

// check if key can be derived with passwordB and passwordC
const valid2 = await mfkdf.policy.evaluate(setup.policy, ['passwordB', 'passwordC']) // -> false

Parameters:

Name	Type	Description
`policy`	Object	The key policy for the key being derived
`factors`	Array.<string>	Array of factor ids used to derive this key

Returns:

Whether the key can be derived with given factor ids

Type: boolean

(async, static) or(factor1, factor2) → {MFKDFFactor}

Description:

Create a MFKDF factor based on OR of two MFKDF factors

Source:

policy/logic.js, line 46

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  ), { size: 8 }
)

// derive key with passwordA and passwordC (or passwordA and passwordB)
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordA: mfkdf.derive.factors.password('passwordA'),
  passwordC: mfkdf.derive.factors.password('passwordC'),
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name	Type	Description
`factor1`	MFKDFFactor	The first factor input to the OR policy
`factor2`	MFKDFFactor	The second factor input to the OR policy

Returns:

Factor that can be derived with either factor

Type: MFKDFFactor

(async, static) and(factor1, factor2) → {MFKDFFactor}

Description:

Create a MFKDF factor based on AND of two MFKDF factors

Source:

policy/logic.js, line 83

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  ), { size: 8 }
)

// derive key with passwordA and passwordC (or passwordA and passwordB)
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordA: mfkdf.derive.factors.password('passwordA'),
  passwordC: mfkdf.derive.factors.password('passwordC'),
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name	Type	Description
`factor1`	MFKDFFactor	The first factor input to the AND policy
`factor2`	MFKDFFactor	The second factor input to the AND policy

Returns:

Factor that can be derived with both factors

Type: MFKDFFactor

(async, static) all(factors) → {MFKDFFactor}

Description:

Create a MFKDF factor based on ALL of the provided MFKDF factors

Source:

policy/logic.js, line 118

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND passwordB AND passwordC
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.all([
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
    await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
  ]), { size: 8 }
)

// derive key with passwordA and passwordB and passwordC
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordA: mfkdf.derive.factors.password('passwordA'),
  passwordB: mfkdf.derive.factors.password('passwordB'),
  passwordC: mfkdf.derive.factors.password('passwordC'),
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name	Type	Description
`factors`	Array.<MFKDFFactor>	The factor inputs to the ALL policy

Returns:

Factor that can be derived with all factors

Type: MFKDFFactor

(async, static) any(factors) → {MFKDFFactor}

Description:

Create a MFKDF factor based on ANY of the provided MFKDF factors

Source:

policy/logic.js, line 151

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA OR passwordB OR passwordC
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.any([
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
    await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
  ]), { size: 8 }
)

// derive key with passwordA (or passwordB or passwordC)
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordB: mfkdf.derive.factors.password('passwordB')
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name	Type	Description
`factors`	Array.<MFKDFFactor>	The factor inputs to the ANY policy

Returns:

Factor that can be derived with any factor

Type: MFKDFFactor

(async, static) atLeast(n, factors) → {MFKDFFactor}

Description:

Create a MFKDF factor based on at least some number of the provided MFKDF factors

Source:

policy/logic.js, line 186

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from at least 2 of (passwordA, passwordB, passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.any([
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
    await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
  ]), { size: 8 }
)

// derive key with passwordA and passwordB (or passwordA and passwordC, or passwordB and passwordC)
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordA: mfkdf.derive.factors.password('passwordA'),
  passwordB: mfkdf.derive.factors.password('passwordB')
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name	Type	Description
`n`	number	The number of factors to be required
`factors`	Array.<MFKDFFactor>	The factor inputs to the atLeast(#) policy

Returns:

Factor that can be derived with at least n of the given factors

Type: MFKDFFactor

(async, static) setup(factor, optionsopt) → {MFKDFDerivedKey}

Description:

Validate and setup a policy-based multi-factor derived key

Source:

policy/setup.js, line 59

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  ), { size: 8 }
)

// derive key with passwordA and passwordC (or passwordA and passwordB)
const derive = await mfkdf.policy.derive(setup.policy, {
  passwordA: mfkdf.derive.factors.password('passwordA'),
  passwordC: mfkdf.derive.factors.password('passwordC'),
})

setup.key.toString('hex') // -> e16a227944a65263
derive.key.toString('hex') // -> e16a227944a65263

Parameters:

Name Type Attributes Description

factor MFKDFFactor Base factor used to derive this key

options

Object

Configuration options

Properties

Name	Type	Attributes	Default	Description
`id`	string	<optional>		Unique identifier for this key; random UUIDv4 generated by default
`size`	number	<optional>	`32`	Size of derived key, in bytes
`threshold`	number	<optional>		Number of factors required to derive key; factors.length by default (all required)
`salt`	Buffer	<optional>		Cryptographic salt; generated via secure PRG by default (recommended)
`kdf`	string	<optional>	`'argon2id'`	KDF algorithm to use; pbkdf2, bcrypt, scrypt, argon2i, argon2d, or argon2id
`pbkdf2rounds`	number	<optional>	`310000`	Number of rounds to use if using pbkdf2
`pbkdf2digest`	string	<optional>	`'sha256'`	Hash function to use if using pbkdf2; sha1, sha256, sha384, or sha512
`bcryptrounds`	number	<optional>	`10`	Number of rounds to use if using bcrypt
`scryptcost`	number	<optional>	`16384`	Iterations count (N) to use if using scrypt
`scryptblocksize`	number	<optional>	`8`	Block size (r) to use if using scrypt
`scryptparallelism`	number	<optional>	`1`	Parallelism factor (p) to use if using scrypt
`argon2time`	number	<optional>	`2`	Iterations to use if using argon2
`argon2mem`	number	<optional>	`24576`	Memory to use if using argon2
`argon2parallelism`	number	<optional>	`1`	Parallelism to use if using argon2

Returns:

A multi-factor derived key object

Type: MFKDFDerivedKey

(static) ids(policy) → {Array.<string>}

Description:

Get all ids of multi-factor derived key factors (including factors of stacked keys)

Source:

policy/validate.js, line 35

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  )
)

// get list of ids
const ids = mfkdf.policy.ids(setup.policy) // -> ['passwordA', 'passwordB', 'passwordC', ...]

Parameters:

Name	Type	Description
`policy`	Object	Policy used to derive a key

Returns:

The ids of the provided factors

Type: Array.<string>

(static) validate(policy) → {boolean}

Description:

Validate multi-factor derived key policy

Source:

policy/validate.js, line 69

Since:

0.16.0

Author:

Vivek Nair (https://nair.me) <[email protected]>

Example

// setup key that can be derived from passwordA AND (passwordB OR passwordC)
const setup = await mfkdf.policy.setup(
  await mfkdf.policy.and(
    await mfkdf.setup.factors.password('passwordA', { id: 'passwordA' }),
    await mfkdf.policy.or(
      await mfkdf.setup.factors.password('passwordB', { id: 'passwordB' }),
      await mfkdf.setup.factors.password('passwordC', { id: 'passwordC' })
    )
  )
)

// validate policy
const valid = mfkdf.policy.validate(setup.policy) // -> true

Parameters:

Name	Type	Description
`policy`	Object	Policy used to derive a key

Returns:

Whether the policy is valid

Type: boolean