multisig-hmac
Multisig scheme for HMAC authentication. Python implementation of multisig-hmac.
Usage
Key management 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.
The following two examples return true
when they are executed, for example inside a virtual environment.
Using stored keys:
import multisig_hmac
from multisig_hmac.multisig_hmac import MultisigHMAC
import base64
m = MultisigHMAC()
# generate keys which need to be stored securely and need to be shared securely with each party
k0 = m.keygen(0)
k1 = m.keygen(1)
k2 = m.keygen(2)
# sign by each client
data = b'hello world'
s0 = m.sign(k0, data)
s2 = m.sign(k2, data)
# combine the used signatures
out = m.combine([s0, s2])
sent = (out[0], base64.urlsafe_b64encode(out[1]))
# --- network ---
received = (sent[0], base64.urlsafe_b64decode(sent[1]))
# verify on the server
threshold = 2
keys = [k0, k1, k2]
signature = received
print(m.verify(keys, signature, data, threshold))
Using a derived master key:
import multisig_hmac
from multisig_hmac.multisig_hmac import MultisigHMAC
import base64
m = MultisigHMAC()
# generate a master seed which needs to be stored securely
# this seed must NOT be shared with any other party
seed = m.seedgen()
k0 = m.deriveKey(seed, 0)
k1 = m.deriveKey(seed, 1)
k2 = m.deriveKey(seed, 2)
# sign by each client
data = b'hello world'
s0 = m.sign(k0, data)
s2 = m.sign(k2, data)
# combine the used signatures
out = m.combine([s0, s2])
sent = (out[0], base64.urlsafe_b64encode(out[1]))
# --- network ---
received = (sent[0], base64.urlsafe_b64decode(sent[1]))
# verify on the server, but now keys are dynamically derived
threshold = 2
signature = received
print(m.verifyDerived(seed, signature, data, threshold))
API
Constants
-
MultisigHMAC.BYTES
signature length in bytes (default) -
MultisigHMAC.KEYBYTES
key length in bytes (default) -
MultisigHMAC.PRIMITIVE
issha256
(default)
So far, the implementation supports the following specific algorithms:
-
MultisigHMAC.SHA256_BYTES
signature length in bytes -
MultisigHMAC.SHA256_KEYBYTES
key length in bytes -
MultisigHMAC.SHA256_PRIMITIVE
issha256
-
MultisigHMAC.SHA512_BYTES
signature length in bytes -
MultisigHMAC.SHA512_KEYBYTES
key length in bytes -
MultisigHMAC.SHA512_PRIMITIVE
issha512
-
MultisigHMAC.SHA384_BYTES
signature length in bytes -
MultisigHMAC.SHA384_KEYBYTES
key length in bytes -
MultisigHMAC.SHA384_PRIMITIVE
issha384
n = MultisigHMAC.popcount(bitfield)
Returns the number of keys (i.e. high bits) in bitfield
. bitfield
must be a 32-bit unsigned integer. Example:
assert MultisigHMAC.popcount(5) == 2
xs = MultisigHMAC.keyIndexes(bitfield)
Returns the indexes of the keys (i.e. high bits) in bitfield
as a list. bitfield
must be a 32-bit unsigned integer. Example:
assert MultisigHMAC.keyIndexes(5) == [0,2]
m = MultisigHMAC([alg = MultisigHMAC.PRIMITIVE])
Creates 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. Example:
m = MultisigHMAC()
assert (m.popcount(5) == 2 and m.keyIndexes(5) == [0,2])
key = MultisigHMAC.keygen(index)
Generates a new cryptographically random key. The function returns { index: 32-bit unsigned integer, key: bytes of length KEYBYTES }
.
Note: index
should be counted from 0.
masterSeed = MultisigHMAC.seedgen()
Generates a new cryptographically random master seed.
key = MultisigHMAC.deriveKey(masterSeed, index)
Derives a new subkey from a master seed. index
must be a 32-bit unsigned integer, 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. The function returns { index: 32-bit unsigned integer, key: bytes of length KEYBYTES }
.
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)
signature = MultisigHMAC.sign(key, data)
Independently signs data
with key
. The function returns { bitfield: 32-bit unsigned integer, signature: bytes of length BYTES }
. This object can be passed to the combine()
function explained below.
signature = MultisigHMAC.combine([signatures...])
Combines a list of signatures which have all been signed independently. Only include each signature once, otherwise they will cancel out. Signatures can be combined in any order. The function returns { bitfield: 32-bit unsigned integer, signature: bytearray of length BYTES }
.
valid = MultisigHMAC.verify(keys, signature, data, threshold)
Verifies a signature
of data
against a list of keys
, over a given threshold
. keys
must be an array of keys. The function returns True
or False
.
valid = MultisigHMAC.verifyDerived(masterSeed, signature, data, threshold)
Verifies a signature
of data
against dynamically derived keys from masterSeed
, over a given threshold
. masterSeed
must be bytes of length KEYBYTES
. The function returns True
or False
.
Installation
$ pip install multisig-hmac
Running tests
$ pip install -U pytest
$ py.test