factors

setup. Namespace

factors

Description:
  • Multi-factor key derivation factor setup
Source:

Methods

(async, static) hmacsha1(optionsopt) → {MFKDFFactor}

Description:
  • Setup a YubiKey-compatible MFKDF HMAC-SHA1 challenge-response factor
Source:
Since:
  • 0.21.0
Author:
Example
// setup key with hmacsha1 factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.hmacsha1()
], {size: 8})

// calculate response; could be done using hardware device
const secret = setup.outputs.hmacsha1.secret
const challenge = Buffer.from(setup.policy.factors[0].params.challenge, 'hex')
const response = crypto.createHmac('sha1', secret).update(challenge).digest()

// derive key with hmacsha1 factor
const derive = await mfkdf.derive.key(setup.policy, {
  hmacsha1: mfkdf.derive.factors.hmacsha1(response)
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
id string <optional>
 'hmacsha1' Unique identifier for this factor
secret Buffer <optional>
 HMAC secret to use; randomly generated by default
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) hotp(optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF HOTP factor
Source:
Since:
  • 0.12.0
Author:
Example
// setup key with hotp factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.hotp({ secret: Buffer.from('hello world') })
], {size: 8})

// derive key with hotp factor
const derive = await mfkdf.derive.key(setup.policy, {
  hotp: mfkdf.derive.factors.hotp(365287)
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
id string <optional>
 'hotp' Unique identifier for this factor
hash string <optional>
 'sha1' Hash algorithm to use; sha512, sha256, or sha1
digits number <optional>
 6 Number of digits to use
secret Buffer <optional>
 HOTP secret to use; randomly generated by default
issuer Buffer <optional>
 'MFKDF' OTPAuth issuer string
label Buffer <optional>
 'mfkdf.com' OTPAuth label string
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) ooba(optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF Out-of-Band Authentication (OOBA) factor
Source:
Since:
  • 1.1.0
Author:
Example
// setup RSA key pair (on out-of-band server)
const keyPair = await crypto.webcrypto.subtle.generateKey({hash: 'SHA-256', modulusLength: 2048, name: 'RSA-OAEP', publicExponent: new Uint8Array([1, 0, 1])}, true, ['encrypt', 'decrypt'])

// setup key with out-of-band authentication factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.ooba({
    key: keyPair.publicKey, params: { email: '[email protected]' }
  })
])

// decrypt and send code (on out-of-band server)
const next = setup.policy.factors[0].params.next
const decrypted = await crypto.webcrypto.subtle.decrypt({name: 'RSA-OAEP'}, keyPair.privateKey, Buffer.from(next, 'hex'))
const code = JSON.parse(Buffer.from(decrypted).toString()).code;

// derive key with out-of-band factor
const derive = await mfkdf.derive.key(setup.policy, {
  ooba: mfkdf.derive.factors.ooba(code)
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
id string <optional>
 'ooba' Unique identifier for this factor
length number <optional>
 6 Number of characters to use in one-time codes
key CryptoKey Public key of out-of-band channel
params Object Parameters to provide out-of-band channel
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) password(password, optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF password factor
Source:
Since:
  • 0.8.0
Author:
Example
// setup key with password factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.password('password')
], {size: 8})

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

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
password string The password from which to derive an MFKDF factor
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
id string <optional>
 'password' Unique identifier for this factor
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) question(answer, optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF Security Question factor
Source:
Since:
  • 1.0.0
Author:
Example
// setup key with security question factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.question('Fido')
], {size: 8})

// derive key with security question factor
const derive = await mfkdf.derive.key(setup.policy, {
  question: mfkdf.derive.factors.question('Fido')
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
answer string The answer from which to derive an MFKDF factor
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
question string <optional>
 Security question corresponding to this factor
id string <optional>
 'question' Unique identifier for this factor
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) stack(factors, optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF stacked key factor
Source:
Since:
  • 0.15.0
Author:
Example
// setup key with hmacsha1 factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.hmacsha1()
], {size: 8})

// calculate response; could be done using hardware device
const secret = setup.outputs.hmacsha1.secret
const challenge = Buffer.from(setup.policy.factors[0].params.challenge, 'hex')
const response = crypto.createHmac('sha1', secret).update(challenge).digest()

// derive key with hmacsha1 factor
const derive = await mfkdf.derive.key(setup.policy, {
  hmacsha1: mfkdf.derive.factors.hmacsha1(response)
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
factors Array.<MFKDFFactor> Array of factors used to derive this key
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
id string <optional>
 'stack' Unique identifier for this factor
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>
 'pbkdf2' KDF algorithm to use; pbkdf2, bcrypt, scrypt, argon2i, argon2d, or argon2id
pbkdf2rounds number <optional>
 1 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 Mmemory to use if using argon2
argon2parallelism number <optional>
 1 Parallelism to use if using argon2
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) totp(optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF TOTP factor
Source:
Since:
  • 0.13.0
Author:
Example
// setup key with totp factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.totp({
    secret: Buffer.from('hello world'),
    time: 1650430806597
  })
], {size: 8})

// derive key with totp factor
const derive = await mfkdf.derive.key(setup.policy, {
  totp: mfkdf.derive.factors.totp(528258, { time: 1650430943604 })
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
id string <optional>
 'totp' Unique identifier for this factor
hash string <optional>
 'sha1' Hash algorithm to use; sha512, sha256, or sha1
digits number <optional>
 6 Number of digits to use
secret Buffer <optional>
 TOTP secret to use; randomly generated by default
issuer Buffer <optional>
 'MFKDF' OTPAuth issuer string
label Buffer <optional>
 'mfkdf.com' OTPAuth label string
time number <optional>
 Current time for TOTP; defaults to Date.now()
window number <optional>
 87600 Maximum window between logins, in number of steps (1 month by default)
step number <optional>
 30 TOTP step size
Returns:
MFKDF factor information
Type
MFKDFFactor

(async, static) uuid(optionsopt) → {MFKDFFactor}

Description:
  • Setup an MFKDF UUID factor
Source:
Since:
  • 0.9.0
Author:
Example
// setup key with uuid factor
const setup = await mfkdf.setup.key([
  await mfkdf.setup.factors.uuid({ uuid: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' })
], {size: 8})

// derive key with uuid factor
const derive = await mfkdf.derive.key(setup.policy, {
  uuid: mfkdf.derive.factors.uuid('9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d')
})

setup.key.toString('hex') // -> 01d0c7236adf2516
derive.key.toString('hex') // -> 01d0c7236adf2516
Parameters:
Name Type Attributes Description
options Object <optional>
 Configuration options
Properties
Name Type Attributes Default Description
uuid string <optional>
 UUID to use for this factor; random v4 uuid default
id string <optional>
 'uuid' Unique identifier for this factor
Returns:
MFKDF factor information
Type
MFKDFFactor