Multisig scheme for HMAC authentication
Work in progress
Many APIs use symmetric "signatures", through HMACs, of a nonce and the data to be processed by a remote server. You always trust the receiving party to process the data, as they are the trusted 3rd party with access to all keys, however the external party, making the call to be processed, only has power over their own keys. As an external party you might want to secure high sensitivity calls with additional checks such as allowed IP ranges. Another check is that multiple parties on the issuing side co-sign the request.
Imagine a withdrawal action on a bank or exchange or a delete call on a
cloud provider, which are both highly sensitive, "destructive" actions.
Using this multisig scheme, several separate entities on the calling party,
will have to agree to perform the action. This could be multiple servers or
people storing their own personal credentials.
This scheme takes each separate signature and a bitfield indicating the keys used, which are combinable in an any order, allowing for simple threshold schemes, or more advanced authentication flows.
Signatures made with this scheme are the same size as standard HMACs, with keys being the same size. This module supports the SHA-2 suite of algorithms for HMAC making it backwards compatible, in sizes, with existing HMAC authentication. Implementing this scheme only requires storing the threshold for actions that are multisig enabled.
Key managment can happen in either of two modes, either by storing every of the component keys, or by storing a single master seed and using that to derive keys ad hoc.
Using stored keys:
const MultisigHMAC = require('multisig-hmac')
const multisigHmac = new MultisigHMAC()
// generate keys, which need to be stored securely
// and need to be shared securely with each party
const k1 = multisigHmac.keygen(1)
const k2 = multisigHmac.keygen(2)
const k3 = multisigHmac.keygen(3)
// Sign by each client with 2-of-3
const data = Buffer.from('Hello world')
// Notice no mention of nonce here. The data can follow whatever format you
// desire, but should include a nonce
const s1 = multisigHmac.sign(k1, data)
const s3 = multisigHmac.sign(k3, data)
const signature = multisigHmac.combine([s1, s3])
// Verify on the server
const threshold = 2
const keys = [k1, k2, k3]
const verified = multisigHmac.verify(keys, signature, data, threshold)
console.log(verified)Using a derived master key:
const MultisigHMAC = require('multisig-hmac')
const multisigHmac = new MultisigHMAC()
// Generate a master seed, which needs to be stored securely
// This seed must NOT be shared with any other party
const seed = multisigHmac.seedgen()
const k1 = multisigHmac.deriveKey(seed, 1)
const k2 = multisigHmac.deriveKey(seed, 2)
const k3 = multisigHmac.deriveKey(seed, 3)
// Sign by each client with 2-of-3
const data = Buffer.from('Hello world')
// Notice no mention of nonce here. The data can follow whatever format you
// desire, but should include a nonce
const s1 = multisigHmac.sign(k1, data)
const s3 = multisigHmac.sign(k3, data)
const signature = multisigHmac.combine([s1, s3])
// Verify on the server, but now keys are dynamically derived
const threshold = 2
const verified = multisigHmac.verifyDerived(seed, signature, data, threshold)
console.log(verified)MultisigHMAC.BYTESsignature length in bytes (default)MultisigHMAC.KEYBYTESkey length in bytes (default)MultisigHMAC.PRIMITIVEissha256(default)
Specific algorithms (support depends on your OpenSSL version):
MultisigHMAC.SHA256_BYTESsignature length in bytesMultisigHMAC.SHA256_KEYBYTESkey length in bytesMultisigHMAC.SHA256_PRIMITIVEissha256MultisigHMAC.SHA384_BYTESsignature length in bytesMultisigHMAC.SHA384_KEYBYTESkey length in bytesMultisigHMAC.SHA384_PRIMITIVEissha384MultisigHMAC.SHA512_BYTESsignature length in bytesMultisigHMAC.SHA512_KEYBYTESkey length in bytesMultisigHMAC.SHA512_PRIMITIVEissha512MultisigHMAC.SHA512_256_BYTESsignature length in bytesMultisigHMAC.SHA512_256_KEYBYTESkey length in bytesMultisigHMAC.SHA512_256_PRIMITIVEissha512_256(also knowns as SHA512/256)
Returns the number of keys (ie. high bits) in bitfield. bitfield must be a
uint32.
Example: assert(MultisigHMAC.keyIndexes(0b101), 2)
Returns the indexes of the keys (ie. high bits) in bitfield as an array.
bitfield must be a uint32.
Example: assert(MultisigHMAC.keyIndexes(0b101), [0, 2])
Create a new instance of MultisigHMAC, which can be used as a global
singleton. Just sets the algorithm to be used for subsequent methods and
associated constants.
Generate a new cryptographically random key. Optionally pass a Buffer of
length KEYBYTES that the key will be written to. This will then be the same
Buffer in key.key.
Returns { index: uint32, key: Buffer }.
Note: index should be counted from 0
Generate a new cryptographically random master seed. Optionally pass a Buffer
of length KEYBYTES that the seed will be written to. This will then be the same
Buffer returned.
Derive a new sub key from a master seed. index must be a uint32, but in
practice you want to keep a much lower number, as the bitfield used with the
signature has as many bits as the largest index. A simple counter suffices.
Optionally pass a Buffer of length KEYBYTES that the key will be written to.
This will then be the same Buffer in key.key. Returns
{ index: uint32, key: Buffer }
Note: index should be counted from 0
Keys are derived using a KDF based on HMAC:
b[0...BYTES] = HMAC(Key = masterSeed, data = 'derive' || U32LE(index) || 0x00)
b[BYTES...] = HMAC(Key = masterSeed, b[0...BYTES] || 0x01)
Independently sign Buffer data with key, using the optional buf to store
the signature. buf must be at least BYTES long. Returns
{ bitfield: uint32, signature: Buffer }.
This object can be passed to combine()
Combine a list of signatures, which have all been signed independently. Only
include each signature once or they will cancel out. Optionally pass buf,
which will store the aggregate signature. This must be a Buffer of BYTES.
Signatures can be combined in any order and over several passes for more
advanced aggregation schemes. Returns { bitfield: uint32, signature: Buffer }
Verify a signature of data against a list of keys, over a given
threshold. keys must be an Array of keys, from which the
signature.bitfield defines which must be verified. Optionally pass
sigScratchBuf which will be used for intermediate signature verification. This
Buffer must be BYTES long. Returns a Boolean for success.
const valid = multisigHmac.verifyDerived(masterSeed, signature, data, threshold, [keyScratchBuf], [sigScratchBuf])
Verify a signature of data against dynamically derived keys from
masterSeed, over a given threshold. masterSeed must be an Buffer of
length KEYBYTES, from which the signature.bitfield defines which must be
derived and verified. Optionally pass keyScratchBuf for which the intermediate
keys are derived into and sigScratchBuf which will be used for intermediate
signature verification. These Buffers must be KEYBYTES and BYTES long,
respectively. Returns a Boolean for success.
npm install multisig-hmac