policy

policy

Source:
Multi-factor key derivation policy

Methods

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

Source:
Since:
  • 0.16.0
Author:
Derive a policy-based multi-factor derived key
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}

Source:
Since:
  • 0.16.0
Author:
Evaluate a policy-based multi-factor derived key
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}

Source:
Since:
  • 0.16.0
Author:
Create a MFKDF factor based on OR of two MFKDF factors
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}

Source:
Since:
  • 0.16.0
Author:
Create a MFKDF factor based on AND of two MFKDF factors
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}

Source:
Since:
  • 0.16.0
Author:
Create a MFKDF factor based on ALL of the provided MFKDF factors
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}

Source:
Since:
  • 0.16.0
Author:
Create a MFKDF factor based on ANY of the provided MFKDF factors
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}

Source:
Since:
  • 0.16.0
Author:
Create a MFKDF factor based on at least some number of the provided MFKDF factors
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}

Source:
Since:
  • 0.16.0
Author:
Validate and setup a policy-based multi-factor derived key
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 <optional>
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>}

Source:
Since:
  • 0.16.0
Author:
Get all ids of multi-factor derived key factors (including factors of stacked keys)
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}

Source:
Since:
  • 0.16.0
Author:
Validate multi-factor derived key policy
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