MFKDFDerivedKey

MFKDFDerivedKey

Class representing a multi-factor derived key

Constructor

new MFKDFDerivedKey(policy, key, secret, shares, outputs)

Description:
  • Create a MFKDFDerivedKey object
Source:
Since:
  • 0.8.0
Author:
Parameters:
Name Type Description
policy Object The policy for deriving this key
key Buffer The value of this derived key
secret Buffer The secret (pre-KDF) value of this derived key
shares Array.<Buffer> The shares corresponding to the factors of this key
outputs Array.<Object> The outputs corresponding to the factors of this key

Methods

(async, static) ISO97982PassUnilateralAuthSymmetric(challenge, identity) → {Buffer}

Description:
  • ISO 9798-2 2-Pass Unilateral Authentication
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])
// challenger: create random challenge
const challenge = crypto.randomBytes(32)
const identity = Buffer.from('Challenger')
// responder: generate response
const response = await key.ISO97982PassUnilateralAuthSymmetric(challenge, identity)
// verifier: verify response
const authKey = await key.ISO9798SymmetricKey()
const valid = await mfkdf.auth.VerifyISO97982PassUnilateralAuthSymmetric(challenge, identity, response, authKey) // -> true
Parameters:
Name Type Description
challenge Buffer The nonce value provided by the challenger
identity Buffer The identity of the challenger
Returns:
The response value
Type
Buffer

(async, static) ISO97982PassUnilateralAuthAsymmetric(challenge, identity) → {Buffer}

Description:
  • ISO 9798-2 Public Key 2-Pass Unilateral Authentication
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// challenger: create random challenge
const challenge = crypto.randomBytes(32)
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97982PassUnilateralAuthAsymmetric(challenge, identity)

// verifier: verify response
const authKey = await key.ISO9798AsymmetricKey()
const valid = await mfkdf.auth.VerifyISO97982PassUnilateralAuthAsymmetric(challenge, identity, response, authKey) // -> true
Parameters:
Name Type Description
challenge Buffer The nonce value provided by the challenger
identity Buffer The identity of the challenger
Returns:
The response value
Type
Buffer

(async, static) ISO97982PassUnilateralAuthCCF(challenge, identity) → {Buffer}

Description:
  • ISO 9798-2 2-Pass Unilateral Authentication over CCF
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// challenger: create random challenge
const challenge = crypto.randomBytes(32)
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97982PassUnilateralAuthCCF(challenge, identity)

// verifier: verify response
const authKey = await key.ISO9798CCFKey()
const valid = await mfkdf.auth.VerifyISO97982PassUnilateralAuthCCF(challenge, identity, response, authKey) // -> true
Parameters:
Name Type Description
challenge Buffer The nonce value provided by the challenger
identity Buffer The identity of the challenger
Returns:
The response value
Type
Buffer

(async, static) ISO97981PassUnilateralAuthSymmetric(identity) → {Buffer}

Description:
  • ISO 9798-2 1-Pass Unilateral Authentication
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97981PassUnilateralAuthSymmetric(identity)

// verifier: verify response
const authKey = await key.ISO9798SymmetricKey()
const valid = await mfkdf.auth.VerifyISO97981PassUnilateralAuthSymmetric(identity, response, authKey) // -> true
Parameters:
Name Type Description
identity Buffer The identity of the challenger
Returns:
The response value
Type
Buffer

(async, static) ISO97981PassUnilateralAuthAsymmetric(identity) → {Buffer}

Description:
  • ISO 9798-2 Public Key 1-Pass Unilateral Authentication
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97981PassUnilateralAuthAsymmetric(identity)

// verifier: verify response
const authKey = await key.ISO9798AsymmetricKey()
const valid = await mfkdf.auth.VerifyISO97981PassUnilateralAuthAsymmetric(identity, response, authKey) // -> true
Parameters:
Name Type Description
identity Buffer The identity of the challenger
Returns:
The response value
Type
Buffer

(async, static) ISO97981PassUnilateralAuthCCF(identity) → {Buffer}

Description:
  • ISO 9798-2 1-Pass Unilateral Authentication over CCF
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97981PassUnilateralAuthCCF(identity)

// verifier: verify response
const authKey = await key.ISO9798CCFKey()
const valid = await mfkdf.auth.VerifyISO97981PassUnilateralAuthCCF(identity, response, authKey) // -> true
Parameters:
Name Type Description
identity Buffer The identity of the challenger
Returns:
The response value
Type
Buffer

(async, static) ISO9798SymmetricKey() → {Buffer}

Description:
  • Get the symmetric key used for ISO 9798-2 Unilateral Authentication
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])
// challenger: create random challenge
const challenge = crypto.randomBytes(32)
const identity = Buffer.from('Challenger')
// responder: generate response
const response = await key.ISO97982PassUnilateralAuthSymmetric(challenge, identity)
// verifier: verify response
const authKey = await key.ISO9798SymmetricKey()
const valid = await mfkdf.auth.VerifyISO97982PassUnilateralAuthSymmetric(challenge, identity, response, authKey) // -> true
Returns:
Symmetric key
Type
Buffer

(async, static) ISO9798AsymmetricKey() → {Buffer}

Description:
  • Get the public key used for ISO 9798-2 Public Key Unilateral Authentication
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// challenger: create random challenge
const challenge = crypto.randomBytes(32)
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97982PassUnilateralAuthAsymmetric(challenge, identity)

// verifier: verify response
const authKey = await key.ISO9798AsymmetricKey()
const valid = await mfkdf.auth.VerifyISO97982PassUnilateralAuthAsymmetric(challenge, identity, response, authKey) // -> true
Returns:
Public key (spki-der encoded)
Type
Buffer

(async, static) ISO9798CCFKey() → {Buffer}

Description:
  • Get the CCF key used for ISO 9798-2 Unilateral Authentication over CCF
Source:
Since:
  • 0.17.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// challenger: create random challenge
const challenge = crypto.randomBytes(32)
const identity = Buffer.from('Challenger')

// responder: generate response
const response = await key.ISO97982PassUnilateralAuthCCF(challenge, identity)

// verifier: verify response
const authKey = await key.ISO9798CCFKey()
const valid = await mfkdf.auth.VerifyISO97982PassUnilateralAuthCCF(challenge, identity, response, authKey) // -> true
Returns:
CCF key
Type
Buffer

(async, static) getSubkey(sizeopt, purposeopt, digestopt) → {Buffer}

Description:
  • Create a sub-key of specified size and purpose using HKDF
Source:
Since:
  • 0.10.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// get 16-byte sub-key for "eth" using hkdf/sha256
const subkey = await key.getSubkey(16, 'eth', 'sha256')
subkey.toString('hex') // -> 54ad9e5acbc1c33b08a15dd79126e9c9
Parameters:
Name Type Attributes Default Description
size number <optional>
The size of sub-key to derive in bytes; same as base key by default
purpose string <optional>
'' Factors used to derive this key
digest string <optional>
'sha512' HKDF digest to use; sha1, sha256, sha384, or sha512
Returns:
Derived sub-key
Type
Buffer

(async, static) getSymmetricKey(typeopt, authopt) → {Buffer}

Description:
  • Create a symmetric sub-key of specified type
Source:
Since:
  • 0.10.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// get 16-byte AES128 sub-key
const subkey = await key.getSymmetricKey('aes128')
subkey.toString('hex') // -> c985454e008e5ecc695e865d339cb2be
Parameters:
Name Type Attributes Default Description
type string <optional>
'aes256' Type of key to generate; des, 3des, aes128, aes192, or aes256
auth boolean <optional>
false Whether this is being used for authentication
Returns:
Derived sub-key as a Buffer
Type
Buffer

(async, static) getAsymmetricKeyPair(typeopt, authopt) → {Object}

Description:
  • Create an asymmetric sub-key pair of specified type
Source:
Since:
  • 0.11.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// get 16-byte RSA1024 sub-key
const subkey = await key.getAsymmetricKeyPair('rsa1024') // -> { privateKey: Uint8Array, publicKey: Uint8Array }
Parameters:
Name Type Attributes Default Description
type string <optional>
'rsa3072' Type of key to generate; ed25519, rsa1024, rsa2048, or rsa3072
auth boolean <optional>
false Whether this is being used for authentication
Returns:
Public key (spki-der encoded) and private key (pkcs8-der encoded)
Type
Object

(async, static) sign(message, methodopt, authopt) → {Buffer}

Description:
  • Sign a message with this key
Source:
Since:
  • 0.11.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// sign message using RSA-1024
const signature = await key.sign('hello world', 'rsa1024')

// verify signature using RSA-1024
const valid = await key.verify('hello world', signature, 'rsa1024') // -> true
Parameters:
Name Type Attributes Default Description
message string | Buffer The message to sign
method string <optional>
'rsa3072' Signature method to use; rsa1024, rsa2048, or rsa3072
auth boolean <optional>
false Whether this is being used for authentication
Returns:
The signed message
Type
Buffer

(async, static) verify(message, signature, methodopt) → {boolean}

Description:
  • Verify a message signed with this key
Source:
Since:
  • 0.11.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// sign message using RSA-1024
const signature = await key.sign('hello world', 'rsa1024')

// verify signature using RSA-1024
const valid = await key.verify('hello world', signature, 'rsa1024') // -> true
Parameters:
Name Type Attributes Default Description
message string | Buffer The message this signature corresponds to
signature Buffer The signature to verify
method string <optional>
'rsa3072' Signature method to use; rsa1024, rsa2048, or rsa3072
Returns:
Whether the signature is valid
Type
boolean

(async, static) encrypt(message, methodopt, modeopt, authopt) → {Buffer}

Description:
  • Encrypt a message with this key Note: DES is not supported on Node.js v18 and later
Source:
Since:
  • 0.10.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// encrypt message using 3DES
const encrypted = await key.encrypt('hello world', '3des')

// decrypt message using 3DES
const decrypted = await key.decrypt(encrypted, '3des')
decrypted.toString() // -> hello world
Parameters:
Name Type Attributes Default Description
message string | Buffer The message to encrypt
method string <optional>
'aes256' Encryption method to use; rsa1024, rsa2048, des, 3des, aes128, aes192, or aes256
mode string <optional>
'CBC' Encryption mode to use; ECB, CFB, OFB, GCM, CTR, or CBC
auth boolean <optional>
false Whether this is being used for authentication
Returns:
The encrypted message
Type
Buffer

(async, static) decrypt(message, methodopt, modeopt) → {Buffer}

Description:
  • Decrypt a message with this key Note: DES is not supported on Node.js v18 and later
Source:
Since:
  • 0.10.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// encrypt message using 3DES
const encrypted = await key.encrypt('hello world', '3des')

// decrypt message using 3DES
const decrypted = await key.decrypt(encrypted, '3des')
decrypted.toString() // -> hello world
Parameters:
Name Type Attributes Default Description
message Buffer The message to decrypt
method string <optional>
'aes256' Decryption method to use; des, 3des, aes128, aes192, or aes256
mode string <optional>
'CBC' Decryption mode to use; ECB, CFB, OFB, GCM, CTR, or CBC
Returns:
The decrypted message
Type
Buffer

(async, static) addEnvelopedSecret(id, value, typeopt)

Description:
  • Add enveloped secret to a multi-factor derived key
Source:
Since:
  • 0.20.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// add enveloped secret to key
await key.addEnvelopedSecret('mySecret', Buffer.from('hello world'))

// later... derive key
const derived = await mfkdf.derive.key(key.policy, { password: mfkdf.derive.factors.password('password') })

// retrieve secret
const secret = await derived.getEnvelopedSecret('mySecret')
secret.toString() // -> hello world
Parameters:
Name Type Attributes Default Description
id string String which uniquely identifies the enveloped secret to add
value Buffer The plaintext secret value to be encrypted with this key
type string <optional>
'raw' The type of the enveloped secret to add

(static) hasEnvelopedSecret(id) → {boolean}

Description:
  • Check if multi-factor derived key has enveloped secret with id
Source:
Since:
  • 0.20.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// add enveloped secret to key
await key.addEnvelopedSecret('mySecret', Buffer.from('hello world'))

// later... derive key
const derived = await mfkdf.derive.key(key.policy, { password: mfkdf.derive.factors.password('password') })

// check secret
const check1 = derived.hasEnvelopedSecret('mySecret') // -> true

// remove secret
derived.removeEnvelopedSecret('mySecret')

// check secret
const check2 = derived.hasEnvelopedSecret('mySecret') // -> false
Parameters:
Name Type Description
id string String which uniquely identifies the enveloped secret
Returns:
- Whether the key has enveloped secret with given id
Type
boolean

(static) removeEnvelopedSecret(id)

Description:
  • Remove enveloped secret from a multi-factor derived key
Source:
Since:
  • 0.20.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// add enveloped secret to key
await key.addEnvelopedSecret('mySecret', Buffer.from('hello world'))

// later... derive key
const derived = await mfkdf.derive.key(key.policy, { password: mfkdf.derive.factors.password('password') })

// check secret
const check1 = derived.hasEnvelopedSecret('mySecret') // -> true

// remove secret
derived.removeEnvelopedSecret('mySecret')

// check secret
const check2 = derived.hasEnvelopedSecret('mySecret') // -> false
Parameters:
Name Type Description
id string ID of the enveloped secret to remove

(async, static) addEnvelopedKey(id, typeopt)

Description:
  • Add enveloped key to a multi-factor derived key
Source:
Since:
  • 0.20.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// add enveloped rsa1024 key
await key.addEnvelopedKey('myKey', 'rsa1024')

// later... derive key
const derived = await mfkdf.derive.key(key.policy, { password: mfkdf.derive.factors.password('password') })

// retrieve enveloped key
const enveloped = await derived.getEnvelopedKey('myKey') // -> PrivateKeyObject
Parameters:
Name Type Attributes Default Description
id string String which uniquely identifies the enveloped key to add
type string <optional>
'rsa1024' The type of the enveloped key to add; rsa1024, rsa2048, or ed25519

(async, static) getEnvelopedSecret(id) → {Buffer}

Description:
  • Get enveloped secret from a multi-factor derived key
Source:
Since:
  • 0.20.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// add enveloped secret to key
await key.addEnvelopedSecret('mySecret', Buffer.from('hello world'))

// later... derive key
const derived = await mfkdf.derive.key(key.policy, { password: mfkdf.derive.factors.password('password') })

// retrieve secret
const secret = await derived.getEnvelopedSecret('mySecret')
secret.toString() // -> hello world
Parameters:
Name Type Description
id string ID of the enveloped secret to get
Returns:
The retrieved plaintext secret value
Type
Buffer

(async, static) getEnvelopedKey(id) → {PrivateKeyObject}

Description:
  • Get enveloped secret from a multi-factor derived key
Source:
Since:
  • 0.20.0
Author:
Example
// setup multi-factor derived key
const key = await mfkdf.setup.key([ await mfkdf.setup.factors.password('password') ])

// add enveloped rsa1024 key
await key.addEnvelopedKey('myKey', 'rsa1024')

// later... derive key
const derived = await mfkdf.derive.key(key.policy, { password: mfkdf.derive.factors.password('password') })

// retrieve enveloped key
const enveloped = await derived.getEnvelopedKey('myKey') // -> PrivateKeyObject
Parameters:
Name Type Description
id string ID of the enveloped key to get
Returns:
The retrieved enveloped key
Type
PrivateKeyObject

(static) persistFactor(id) → {Buffer}

Description:
  • Persist material from an MFKDF factor to bypass it in future derivation
Source:
Since:
  • 0.18.0
Author:
Example
// setup 3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8})

// persist one of the factors
const factor2 = setup.persistFactor('password2')

// derive key with 2 factors
const derived = await mfkdf.derive.key(setup.policy, {
 password1: mfkdf.derive.factors.password('password1'),
 password2: mfkdf.derive.factors.persisted(factor2),
 password3: mfkdf.derive.factors.password('password3')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
id string ID of the factor to persist
Returns:
- The share which can be used to bypass the factor
Type
Buffer

(async, static) setThreshold(threshold)

Description:
  • Change the threshold of factors needed to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8})

// change threshold to 2/3
await setup.setThreshold(2)

// derive key with 2 factors
const derived = await mfkdf.derive.key(setup.policy, {
 password1: mfkdf.derive.factors.password('password1'),
 password3: mfkdf.derive.factors.password('password3')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
threshold number New threshold for key derivation

(async, static) removeFactor(id)

Description:
  • Remove a factor used to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 2-of-3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8, threshold: 2})

// remove one of the factors
await setup.removeFactor('password2')

// derive key with remaining 2 factors
const derived = await mfkdf.derive.key(setup.policy, {
 password1: mfkdf.derive.factors.password('password1'),
 password3: mfkdf.derive.factors.password('password3')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
id string ID of existing factor to remove

(async, static) removeFactors(ids)

Description:
  • Remove factors used to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 1-of-3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8, threshold: 1})

// remove two factors
await setup.removeFactors(['password1', 'password2'])

// derive key with remaining factor
const derived = await mfkdf.derive.key(setup.policy, {
 password3: mfkdf.derive.factors.password('password3')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
ids Array.<string> Array of IDs of existing factors to remove

(async, static) addFactor(factor)

Description:
  • Add a factor used to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 2-of-3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8, threshold: 2})

// add fourth factor
await setup.addFactor(
 await mfkdf.setup.factors.password('password4', { id: 'password4' })
)

// derive key with any 2 factors
const derived = await mfkdf.derive.key(setup.policy, {
 password2: mfkdf.derive.factors.password('password2'),
 password4: mfkdf.derive.factors.password('password4')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
factor MFKDFFactor Factor to add

(async, static) addFactors(factors)

Description:
  • Add new factors to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 2-of-3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.password('password1', { id: 'password1' }),
  await mfkdf.setup.factors.password('password2', { id: 'password2' }),
  await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8, threshold: 2})

// add two more factors
await setup.addFactors([
  await mfkdf.setup.factors.password('password4', { id: 'password4' }),
  await mfkdf.setup.factors.password('password5', { id: 'password5' })
])

// derive key with any 2 factors
const derived = await mfkdf.derive.key(setup.policy, {
  password3: mfkdf.derive.factors.password('password3'),
  password5: mfkdf.derive.factors.password('password5')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
factors Array.<MFKDFFactor> Array of factors to add

(async, static) recoverFactor(factor)

Description:
  • Update a factor used to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8})

// change the 2nd factor
await setup.recoverFactor(
 await mfkdf.setup.factors.password('newPassword2', { id: 'password2' })
)

// derive key with new factors
const derived = await mfkdf.derive.key(setup.policy, {
 password1: mfkdf.derive.factors.password('password1'),
 password2: mfkdf.derive.factors.password('newPassword2'),
 password3: mfkdf.derive.factors.password('password3')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
factor MFKDFFactor Factor to replace

(async, static) recoverFactors(factors)

Description:
  • Update the factors used to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
 await mfkdf.setup.factors.password('password1', { id: 'password1' }),
 await mfkdf.setup.factors.password('password2', { id: 'password2' }),
 await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8})

// change 2 factors
await setup.recoverFactors([
 await mfkdf.setup.factors.password('newPassword2', { id: 'password2' }),
 await mfkdf.setup.factors.password('newPassword3', { id: 'password3' })
])

// derive key with new factors
const derived = await mfkdf.derive.key(setup.policy, {
 password1: mfkdf.derive.factors.password('password1'),
 password2: mfkdf.derive.factors.password('newPassword2'),
 password3: mfkdf.derive.factors.password('newPassword3')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Description
factors Array.<MFKDFFactor> Array of factors to replace

(async, static) reconstitute(removeFactorsopt, addFactorsopt, thresholdopt)

Description:
  • Reconstitute the factors used to derive a multi-factor derived key
Source:
Since:
  • 0.14.0
Author:
Example
// setup 2-of-3-factor multi-factor derived key
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.password('password1', { id: 'password1' }),
  await mfkdf.setup.factors.password('password2', { id: 'password2' }),
  await mfkdf.setup.factors.password('password3', { id: 'password3' })
], {size: 8, threshold: 2})

// remove 1 factor and add 1 new factor
await setup.reconstitute(
  ['password1'], // remove
  [ await mfkdf.setup.factors.password('password4', { id: 'password4' }) ] // add
)

// derive key with new factors
const derived = await mfkdf.derive.key(setup.policy, {
  password3: mfkdf.derive.factors.password('password3'),
  password4: mfkdf.derive.factors.password('password4')
})

setup.key.toString('hex') // -> 64587f2a0e65dc3c
derived.key.toString('hex') // -> 64587f2a0e65dc3c
Parameters:
Name Type Attributes Description
removeFactors Array.<string> <optional>
Array of IDs of existing factors to remove
addFactors Array.<MFKDFFactor> <optional>
Array of factors to add or replace
threshold number <optional>
New threshold for key derivation; same as current by default