MFKDF

derive/key.js

  1. /**
  2.  * @file Multi-factor Key Derivation
  3.  * @copyright Multifactor 2022 All Rights Reserved
  4.  *
  5.  * @description
  6.  * Derive a multi-factor derived key
  7.  *
  8.  * @author Vivek Nair (https://nair.me) <vivek@nair.me>
  9.  */
  11. const Ajv = require('ajv')
  12. const policySchema = require('./policy.json')
  13. const combine = require('../secrets/combine').combine
  14. const recover = require('../secrets/recover').recover
  15. const kdf = require('../kdf').kdf
  16. const { hkdf } = require('@panva/hkdf')
  17. const xor = require('buffer-xor')
  18. const MFKDFDerivedKey = require('../classes/MFKDFDerivedKey')
  20. /**
  21.  * Derive a key from multiple factors of input
  22.  *
  23.  * @example
  24.  * // setup 16 byte 2-of-3-factor multi-factor derived key with a password, HOTP code, and UUID recovery code
  25.  * const setup = await mfkdf.setup.key([
  26.  *   await mfkdf.setup.factors.password('password'),
  27.  *   await mfkdf.setup.factors.hotp({ secret: Buffer.from('hello world') }),
  28.  *   await mfkdf.setup.factors.uuid({ id: 'recovery', uuid: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' })
  29.  * ], {threshold: 2, size: 16})
  30.  *
  31.  * // derive key using 2 of the 3 factors
  32.  * const derive = await mfkdf.derive.key(setup.policy, {
  33.  *   password: mfkdf.derive.factors.password('password'),
  34.  *   hotp: mfkdf.derive.factors.hotp(365287)
  35.  * })
  36.  *
  37.  * setup.key.toString('hex') // -> 34d20ced439ec2f871c96ca377f25771
  38.  * derive.key.toString('hex') // -> 34d20ced439ec2f871c96ca377f25771
  39.  *
  40.  * @param {Object} policy - The key policy for the key being derived
  41.  * @param {Object.<string, MFKDFFactor>} factors - Factors used to derive this key
  42.  * @returns {MFKDFDerivedKey} A multi-factor derived key object
  43.  * @author Vivek Nair (https://nair.me) <vivek@nair.me>
  44.  * @since 0.9.0
  45.  * @async
  46.  * @memberOf derive
  47.  */
  48. async function key (policy, factors) {
  49.   const ajv = new Ajv()
  50.   const valid = ajv.validate(policySchema, policy)
  51.   if (!valid) throw new TypeError('invalid key policy', ajv.errors)
  52.   if (Object.keys(factors).length < policy.threshold) throw new RangeError('insufficient factors provided to derive key')
  54.   const shares = []
  55.   const newFactors = []
  56.   const outputs = {}
  58.   for (const factor of policy.factors) {
  59.     if (factors[factor.id] && typeof factors[factor.id] === 'function') {
  60.       const material = await factors[factor.id](factor.params)
  61.       let share
  63.       if (material.type === 'persisted') {
  64.         share = material.data
  65.       } else {
  66.         if (material.type !== factor.type) throw new TypeError('wrong factor material function used for this factor type')
  68.         const pad = Buffer.from(factor.pad, 'base64')
  69.         let stretched = Buffer.from(await hkdf('sha512', material.data, '', '', policy.size))
  70.         if (Buffer.byteLength(pad) > policy.size) stretched = Buffer.concat([Buffer.alloc(Buffer.byteLength(pad) - policy.size), stretched])
  72.         share = xor(pad, stretched)
  73.       }
  75.       shares.push(share)
  76.       if (material.output) outputs[factor.id] = await material.output()
  77.       newFactors.push(material.params)
  78.     } else {
  79.       shares.push(null)
  80.       newFactors.push(null)
  81.     }
  82.   }
  84.   if (shares.filter(x => Buffer.isBuffer(x)).length < policy.threshold) throw new RangeError('insufficient factors provided to derive key')
  86.   const secret = combine(shares, policy.threshold, policy.factors.length)
  87.   const key = await kdf(secret, Buffer.from(policy.salt, 'base64'), policy.size, policy.kdf)
  89.   const newPolicy = JSON.parse(JSON.stringify(policy))
  91.   for (const [index, factor] of newFactors.entries()) {
  92.     if (typeof factor === 'function') {
  93.       newPolicy.factors[index].params = await factor({ key })
  94.     }
  95.   }
  97.   const originalShares = recover(shares, policy.threshold, policy.factors.length)
  99.   return new MFKDFDerivedKey(newPolicy, key, secret, originalShares, outputs)
  100. }
  101. module.exports.key = key