charm-crypto-framework 0.61.1__cp313-cp313-macosx_10_13_universal2.whl

charm/toolbox/broadcast.py

@@ -0,0 +1,220 @@
+'''
+Echo Broadcast Protocol Implementation
+
+Implements Bracha's reliable broadcast protocol for Byzantine fault tolerance.
+Ensures all honest parties receive the same message from each sender.
+
+| Based on: Bracha's Reliable Broadcast (1987)
+| Reference: "Asynchronous Byzantine Agreement Protocols" - Gabriel Bracha
+|
+| Used in: DKLS23 Threshold ECDSA DKG for broadcast consistency verification
+
+:Authors: Elton de Souza
+:Date:    01/2026
+'''
+
+import hashlib
+import json
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple, Union
+
+PartyId = int
+
+# Module logger
+logger = logging.getLogger(__name__)
+
+
+class EchoBroadcast:
+    """
+    Echo broadcast protocol for Byzantine fault tolerant message delivery.
+
+    Ensures that if any honest party accepts a message from a sender,
+    all honest parties accept the same message (consistency).
+
+    This implements echo broadcast verification as used in distributed
+    key generation (DKG) protocols to prevent equivocation attacks where
+    a malicious sender sends different messages to different recipients.
+
+    Attributes:
+        n: Number of parties in the protocol
+        f: Byzantine fault threshold (default: (n-1)//3)
+
+    Example:
+        >>> broadcast = EchoBroadcast(num_parties=5)
+        >>> msg = broadcast.create_broadcast_message(1, {'value': 42})
+        >>> 'sender_id' in msg and 'hash' in msg
+        True
+    """
+
+    def __init__(self, num_parties: int, fault_threshold: Optional[int] = None):
+        """
+        Initialize echo broadcast with party count and fault threshold.
+
+        Parameters
+        ----------
+        num_parties : int
+            Total number of parties in the protocol
+        fault_threshold : int, optional
+            Maximum number of Byzantine (faulty) parties tolerated.
+            Defaults to (num_parties - 1) // 3 for optimal Byzantine tolerance.
+        """
+        if num_parties < 1:
+            raise ValueError("num_parties must be at least 1")
+
+        self.n = num_parties
+        self.f = fault_threshold if fault_threshold is not None else (num_parties - 1) // 3
+
+        if self.f < 0:
+            raise ValueError("fault_threshold must be non-negative")
+
+    def compute_message_hash(self, message: Any) -> bytes:
+        """
+        Compute hash of a message for echo comparison.
+
+        Parameters
+        ----------
+        message : Any
+            The message to hash. Can be bytes, dict, or any serializable type.
+
+        Returns
+        -------
+        bytes
+            SHA-256 hash of the message
+        """
+        if isinstance(message, bytes):
+            data = message
+        elif isinstance(message, dict):
+            # Serialize dict to bytes deterministically
+            data = json.dumps(message, sort_keys=True, default=str).encode()
+        else:
+            data = str(message).encode()
+
+        return hashlib.sha256(data).digest()
+
+    def create_broadcast_message(self, party_id: int, message: Any) -> Dict[str, Any]:
+        """
+        Create a broadcast message with its hash for echo verification.
+
+        Parameters
+        ----------
+        party_id : int
+            The sender's party identifier
+        message : Any
+            The message content to broadcast
+
+        Returns
+        -------
+        dict
+            Broadcast message containing:
+            - sender_id: The sender's party ID
+            - message: The original message content
+            - hash: SHA-256 hash of the message
+        """
+        msg_hash = self.compute_message_hash(message)
+        return {
+            'sender_id': party_id,
+            'message': message,
+            'hash': msg_hash
+        }
+
+    def process_echo(
+        self,
+        verifier_id: int,
+        sender_id: int,
+        msg_hash: bytes,
+        echo_state: Optional[Dict[int, Dict[int, bytes]]] = None
+    ) -> Dict[int, Dict[int, bytes]]:
+        """
+        Process an echo from another party.
+
+        Records what message hash a verifier claims to have received from a sender.
+
+        Parameters
+        ----------
+        verifier_id : int
+            ID of the party reporting what they received
+        sender_id : int
+            ID of the original sender
+        msg_hash : bytes
+            Hash of the message the verifier claims to have received
+        echo_state : dict, optional
+            Current echo state to update. If None, creates new state.
+
+        Returns
+        -------
+        dict
+            Updated echo state: {verifier_id: {sender_id: msg_hash}}
+        """
+        if echo_state is None:
+            echo_state = {}
+        if verifier_id not in echo_state:
+            echo_state[verifier_id] = {}
+        echo_state[verifier_id][sender_id] = msg_hash
+        return echo_state
+
+    def verify_consistency(self, echo_msgs: Dict[int, Dict[int, bytes]]) -> bool:
+        """
+        Verify all parties received consistent messages from each sender.
+
+        Checks that for each sender, all verifiers report the same message hash.
+        If any sender sent different messages to different recipients (equivocation),
+        raises ValueError with details about the inconsistency.
+
+        Parameters
+        ----------
+        echo_msgs : dict
+            Echo state mapping {verifier_id: {sender_id: msg_hash}}
+
+        Returns
+        -------
+        bool
+            True if all messages are consistent
+
+        Raises
+        ------
+        ValueError
+            If broadcast inconsistency is detected, with details about which
+            sender sent different messages to different recipients
+
+        Example:
+            >>> broadcast = EchoBroadcast(num_parties=3)
+            >>> # All parties received same hash from sender 1
+            >>> echo_msgs = {1: {1: b'hash1'}, 2: {1: b'hash1'}, 3: {1: b'hash1'}}
+            >>> broadcast.verify_consistency(echo_msgs)
+            True
+        """
+        if not echo_msgs:
+            return True
+
+        # Build a map: sender_id -> {hash -> set of receivers who got that hash}
+        sender_to_hashes: Dict[int, Dict[bytes, Set[int]]] = {}
+
+        for verifier_id, received_hashes in echo_msgs.items():
+            for sender_id, msg_hash in received_hashes.items():
+                if sender_id not in sender_to_hashes:
+                    sender_to_hashes[sender_id] = {}
+
+                # Convert hash to bytes if needed
+                hash_key = msg_hash if isinstance(msg_hash, bytes) else bytes(msg_hash)
+
+                if hash_key not in sender_to_hashes[sender_id]:
+                    sender_to_hashes[sender_id][hash_key] = set()
+                sender_to_hashes[sender_id][hash_key].add(verifier_id)
+
+        # Check consistency: each sender should have only one unique hash
+        for sender_id, hash_to_receivers in sender_to_hashes.items():
+            if len(hash_to_receivers) > 1:
+                # Found inconsistency - sender sent different messages
+                receivers_by_hash = [
+                    f"hash {i+1}: receivers {sorted(receivers)}"
+                    for i, (_, receivers) in enumerate(hash_to_receivers.items())
+                ]
+                raise ValueError(
+                    f"Broadcast inconsistency detected: Party {sender_id} sent "
+                    f"different messages to different receivers. "
+                    f"{'; '.join(receivers_by_hash)}"
+                )
+
+        logger.debug("Broadcast consistency verified for %d senders", len(sender_to_hashes))
+        return True
+

charm/toolbox/conversion.py

@@ -0,0 +1,100 @@
+'''
+:Date: Jul 5, 2011
+:Authors: Gary Belvin
+
+This class facilitates conversion between domain spaces
+'''
+from charm.core.math.integer import integer
+from charm.toolbox.bitstring import Bytes,py3
+import math
+
+class Conversion(object):
+    '''
+    The goal is to convert arbitrarily between any of the following types
+    
+    Input types:
+    
+    * bytes
+    * Bytes
+    * int
+    * Integer Element
+    * Modular Integer Element
+    
+    Output types:
+    
+    * int
+    * Group element
+    * Integer element
+    * Integer element mod N
+    '''
+
+    @classmethod
+    def bytes2element(self, bytestr):
+        '''Converts a byte string to a group element'''
+        pass
+    @classmethod
+    def bytes2integer(self, bytestr):
+        '''Converts a bytes string to an integer object'''
+        return integer(bytestr)
+    @classmethod
+    def str2bytes(self, strobj):
+        return Bytes(strobj, 'utf-8')
+    @classmethod
+    def bytes2str(self, byteobj):
+        return Bytes.decode(byteobj, 'utf-8')
+    
+    @classmethod
+    def int2bin(self, intobj):
+        _str = bin(int(intobj))
+        _array = []
+        for i in range(2, len(_str)):
+            _array.append(int(_str[i])) 
+        return _array
+        
+    @classmethod    
+    def OS2IP(self, bytestr, element = False):
+        '''
+        :Return: A python ``int`` if element is False. An ``integer.Element`` if element is True
+        
+        Converts a byte string to an integer
+        '''
+        val = 0 
+        for i in range(len(bytestr)):
+            byt = bytestr[len(bytestr)-1-i]
+            if not py3: byt = ord(byt)
+            val += byt << (8 *i)
+
+        #These lines convert val into a binary string of 1's and 0's 
+        #bstr = bin(val)[2:]   #cut out the 0b header
+        #val = int(bstr, 2)
+        #return val
+        if element:
+            return integer(val)
+        else:
+            return val
+    @classmethod    
+    def IP2OS(self, number, xLen=None):
+        '''
+        :Parameters:
+          - ``number``: is a normal integer, not modular
+          - ``xLen``: is the intended length of the resulting octet string
+        
+        Converts an integer into a byte string'''
+        
+        ba = bytearray()
+        x = 0
+        if type(number) == integer:
+            x = int(number)
+        elif type(number) == int:
+            x = number
+        elif not py3 and type(number) == long:
+            x = number  
+
+        if xLen == None:
+            xLen = int(math.ceil(math.log(x, 2) / 8.0))
+            
+        for i in range(xLen):
+            ba.append(x % 256)
+            x = x >> 8
+        ba.reverse()
+        return Bytes(ba)

charm/toolbox/eccurve.py

@@ -0,0 +1,149 @@
+
+""" Openssl Elliptic Curve Parameters
+Run ``openssl ecparam -list_curves`` to show all of the curve identifiers supported in OpenSSL.
+
+import the ``charm.toolbox.eccurve`` module for the full listing from Charm.
+"""
+
+prime192v1 = 409
+prime192v2 = 410
+prime192v3 = 411
+prime239v1 = 412
+prime239v2 = 413
+prime239v3 = 414
+prime256v1 = 415
+
+c2pnb163v1 = 684
+c2pnb163v2 = 685
+c2pnb163v3 = 686
+c2pnb176v1 = 687
+c2tnb191v1 = 688
+c2tnb191v2 = 689
+c2tnb191v3 = 690
+c2onb191v4 = 691
+c2onb191v5 = 692
+c2pnb208w1 = 693
+
+c2tnb239v1 = 694
+c2tnb239v2 = 695
+c2tnb239v3 = 696
+c2onb239v4 = 697
+c2onb239v5 = 698
+
+c2pnb272w1 = 699
+c2pnb304w1 = 700
+c2tnb359v1 = 701
+c2pnb368w1 = 702
+c2tnb431r1 = 703
+
+secp112r1 = 704
+secp112r2 = 705
+secp128r1 = 706
+secp128r2 = 707
+secp160k1 = 708
+secp160r1 = 709
+secp160r2 = 710
+secp192k1 = 711
+secp224k1 = 712
+secp224r1 = 713
+secp256k1 = 714
+secp384r1 = 715
+secp521r1 = 716
+sect113r1 = 717
+sect113r2 = 718
+sect131r1 = 719
+sect131r2 = 720
+sect163k1 = 721
+sect163r1 = 722
+sect163r2 = 723
+sect193r1 = 724
+sect193r2 = 725
+sect233k1 = 726
+sect233r1 = 727
+sect239k1 = 728
+sect283k1 = 729
+sect283r1 = 730
+sect409k1 = 731
+sect409r1 = 732
+sect571k1 = 733
+sect571r1 = 734
+
+ecid_wtls1 = 735
+ecid_wtls3 = 736
+ecid_wtls4 = 737
+ecid_wtls5 = 738
+ecid_wtls6 = 739
+ecid_wtls7 = 740
+ecid_wtls8 = 741
+ecid_wtls9 = 742
+ecid_wtls10 = 743
+ecid_wtls11 = 744
+ecid_wtls12 = 745
+
+curve_description = {  
+  secp112r1 : 'SECG/WTLS curve over a 112 bit prime field',
+  secp112r2 : 'SECG curve over a 112 bit prime field',
+  secp128r1 : 'SECG curve over a 128 bit prime field',
+  secp128r2 : 'SECG curve over a 128 bit prime field',
+  secp160k1 : 'SECG curve over a 160 bit prime field',
+  secp160r1 : 'SECG curve over a 160 bit prime field',
+  secp160r2 : 'SECG/WTLS curve over a 160 bit prime field',
+  secp192k1 : 'SECG curve over a 192 bit prime field',
+  secp224k1 : 'SECG curve over a 224 bit prime field',
+  secp224r1 : 'NIST/SECG curve over a 224 bit prime field',
+  secp256k1 : 'SECG curve over a 256 bit prime field',
+  secp384r1 : 'NIST/SECG curve over a 384 bit prime field',
+  secp521r1 : 'NIST/SECG curve over a 521 bit prime field',
+  prime192v1: 'NIST/X9.62/SECG curve over a 192 bit prime field',
+  prime192v2: 'X9.62 curve over a 192 bit prime field',
+  prime192v3: 'X9.62 curve over a 192 bit prime field',
+  prime239v1: 'X9.62 curve over a 239 bit prime field',
+  prime239v2: 'X9.62 curve over a 239 bit prime field',
+  prime239v3: 'X9.62 curve over a 239 bit prime field',
+  prime256v1: 'X9.62/SECG curve over a 256 bit prime field',
+  sect113r1 : 'SECG curve over a 113 bit binary field',
+  sect113r2 : 'SECG curve over a 113 bit binary field',
+  sect131r1 : 'SECG/WTLS curve over a 131 bit binary field',
+  sect131r2 : 'SECG curve over a 131 bit binary field',
+  sect163k1 : 'NIST/SECG/WTLS curve over a 163 bit binary field',
+  sect163r1 : 'SECG curve over a 163 bit binary field',
+  sect163r2 : 'NIST/SECG curve over a 163 bit binary field',
+  sect193r1 : 'SECG curve over a 193 bit binary field',
+  sect193r2 : 'SECG curve over a 193 bit binary field',
+  sect233k1 : 'NIST/SECG/WTLS curve over a 233 bit binary field',
+  sect233r1 : 'NIST/SECG/WTLS curve over a 233 bit binary field',
+  sect239k1 : 'SECG curve over a 239 bit binary field',
+  sect283k1 : 'NIST/SECG curve over a 283 bit binary field',
+  sect283r1 : 'NIST/SECG curve over a 283 bit binary field',
+  sect409k1 : 'NIST/SECG curve over a 409 bit binary field',
+  sect409r1 : 'NIST/SECG curve over a 409 bit binary field',
+  sect571k1 : 'NIST/SECG curve over a 571 bit binary field',
+  sect571r1 : 'NIST/SECG curve over a 571 bit binary field',
+  c2pnb163v1: 'X9.62 curve over a 163 bit binary field',
+  c2pnb163v2: 'X9.62 curve over a 163 bit binary field',
+  c2pnb163v3: 'X9.62 curve over a 163 bit binary field',
+  c2pnb176v1: 'X9.62 curve over a 176 bit binary field',
+  c2tnb191v1: 'X9.62 curve over a 191 bit binary field',
+  c2tnb191v2: 'X9.62 curve over a 191 bit binary field',
+  c2tnb191v3: 'X9.62 curve over a 191 bit binary field',
+  c2pnb208w1: 'X9.62 curve over a 208 bit binary field',
+  c2tnb239v1: 'X9.62 curve over a 239 bit binary field',
+  c2tnb239v2: 'X9.62 curve over a 239 bit binary field',
+  c2tnb239v3: 'X9.62 curve over a 239 bit binary field',
+  c2pnb272w1: 'X9.62 curve over a 272 bit binary field',
+  c2pnb304w1: 'X9.62 curve over a 304 bit binary field',
+  c2tnb359v1: 'X9.62 curve over a 359 bit binary field',
+  c2pnb368w1: 'X9.62 curve over a 368 bit binary field',
+  c2tnb431r1: 'X9.62 curve over a 431 bit binary field',
+  ecid_wtls1: 'WTLS curve over a 113 bit binary field',
+  ecid_wtls3: 'NIST/SECG/WTLS curve over a 163 bit binary field',
+  ecid_wtls4: 'SECG curve over a 113 bit binary field',
+  ecid_wtls5: 'X9.62 curve over a 163 bit binary field',
+  ecid_wtls6: 'SECG/WTLS curve over a 112 bit prime field',
+  ecid_wtls7: 'SECG/WTLS curve over a 160 bit prime field',
+  ecid_wtls8: 'WTLS curve over a 112 bit prime field',
+  ecid_wtls9: 'WTLS curve over a 160 bit prime field',
+  ecid_wtls10:'NIST/SECG/WTLS curve over a 233 bit binary field',
+  ecid_wtls11:'NIST/SECG/WTLS curve over a 233 bit binary field',
+  ecid_wtls12:'WTLS curvs over a 224 bit prime field',
+}

charm/toolbox/ecgroup.py

@@ -0,0 +1,143 @@
+try:
+   from charm.core.math.elliptic_curve import elliptic_curve,ec_element,ZR,G,init,random,order,getGenerator,bitsize,serialize,deserialize,hashEC,encode,decode,getXY
+   import charm.core.math.elliptic_curve as ecc
+except Exception as err:
+   raise ImportError("Cannot import elliptic_curve module. Ensure Charm crypto C extensions are compiled: %s" % err)
+
+class ECGroup():
+    def __init__(self, builtin_cv):
+        self.ec_group = elliptic_curve(nid=builtin_cv)
+        self.param = builtin_cv
+        self._verbose = True
+
+    def __str__(self):
+        return str(self.ec_group)
+
+    def order(self):
+        """returns the order of the group"""
+        return order(self.ec_group)
+
+    def bitsize(self):
+        """returns the bitsize for encoding messages in the group"""
+        return bitsize(self.ec_group)
+    
+    def paramgen(self, secparam):
+        return None
+
+    def groupSetting(self):
+        return 'elliptic_curve'
+
+    def groupType(self): 
+        return self.param
+
+    def init(self, _type=ZR, value=None):
+        """initializes an object with a specified type and value"""
+        if value is not None:
+            return init(self.ec_group, _type, value)
+        return init(self.ec_group, _type)
+    
+    def random(self, _type=ZR):
+        """selects a random element in ZR or G"""        
+        if _type == ZR or _type == G:
+            return random(self.ec_group, _type)
+        return None
+    
+    def encode(self, message, include_ctr=False):
+        """encode arbitrary string as a group element. Max size is dependent on the EC group order"""
+        return encode(self.ec_group, message, include_ctr)
+    
+    def decode(self, msg_bytes, include_ctr=False):
+        """decode a group element into a string"""
+        return decode(self.ec_group, msg_bytes, include_ctr)
+    
+    def serialize(self, object):
+        """serializes a pairing object into bytes"""        
+        return serialize(object)
+    
+    def deserialize(self, bytes_object):
+        """deserializes into a pairing object"""        
+        return deserialize(self.ec_group, bytes_object)
+
+    def hash(self, args, target_type=ZR):
+        """hashes objects into ZR or G
+
+        Different object types may hash to the same element, e.g., the ASCII
+        string 'str' and the byte string b'str' map to the same element."""
+        def hash_encode(arg):
+            """encode a data type to bytes"""
+            if type(arg) is bytes:
+                s = arg
+            elif type(arg) is ec_element:
+                s = serialize(arg)
+            elif type(arg) is str:
+                s = arg.encode('utf-8')
+            elif type(arg) is int:
+                s = arg.to_bytes((arg.bit_length() + 7) // 8, 'little')
+            elif isinstance(args, tuple):
+                # based on TupleHash (see NIST SP 800-185)
+                def left_encode(x):
+                    # This implictly checks for validity conditions:
+                    # An exception is raised if n > 255, i.e., if len(x) > 2**2040
+                    n = (x.bit_length() + 7 ) // 8
+                    return n.to_bytes(1, 'little') + x.to_bytes(n, 'little')
+
+                s = b''
+                for arg in args:
+                    z = hash_encode(arg)
+                    # concat with encode_string(z)
+                    s += left_encode(len(z)) + z
+            else:
+                raise ValueError("unexpected type to hash: {}".format(type(arg)))
+
+            return s
+
+        return hashEC(self.ec_group, hash_encode(args), target_type)
+
+    def zr(self, point):
+        """get the X coordinate only"""
+        if type(point) == ec_element:
+            return getXY(self.ec_group, point, False)
+        return None
+
+    def coordinates(self, point):
+        """get the X and Y coordinates of an EC point"""
+        if type(point) == ec_element:
+            return getXY(self.ec_group, point, True)
+        
+    def debug(self, data, prefix=None):
+        if type(data) == dict and self._verbose:
+           for k,v in data.items():
+               print(k,v)
+        elif type(data) == list and self._verbose:
+           for i in range(0, len(data)):
+               print(prefix, (i+1),':',data[i])            
+           print('')
+        elif type(data) == str and self._verbose:
+           print(data)
+        return None
+
+    def InitBenchmark(self):
+        """initiates the benchmark state"""        
+        return ecc.InitBenchmark(self.ec_group)
+    
+    def StartBenchmark(self, options):
+        """starts the benchmark with any of these options: 
+        RealTime, CpuTime, Mul, Div, Add, Sub, Exp, Granular"""        
+        return ecc.StartBenchmark(self.ec_group, options)
+    
+    def EndBenchmark(self):
+        """ends an ongoing benchmark"""        
+        return ecc.EndBenchmark(self.ec_group)
+        
+    def GetGeneralBenchmarks(self):
+        """retrieves benchmark count for all group operations"""
+        return ecc.GetGeneralBenchmarks(self.ec_group)
+    
+    def GetGranularBenchmarks(self):
+        """retrieves group operation count per type: ZR and G"""        
+        return ecc.GetGranularBenchmarks(self.ec_group)
+    
+    def GetBenchmark(self, option):
+        """retrieves benchmark results for any of these options: 
+        RealTime, CpuTime, Mul, Div, Add, Sub, Exp, Granular"""        
+        return ecc.GetBenchmark(self.ec_group, option)

charm/toolbox/enum.py

@@ -0,0 +1,60 @@
+# code adapted from active state code recipes for enumeration
+def Enum(*names):
+      class EnumClass(object):
+         __slots__ = names
+         def __iter__(self):        return iter(constants)
+         def __len__(self):         return len(constants)
+         def __getitem__(self, i):  
+             if type(i) == int: return constants[i]
+             elif type(i) == str: 
+                 index = lookup.get(i) 
+                 if index != None: return constants[index]
+                 else: return None
+             else: assert False, "Invalid input type."
+         def __repr__(self):        return 'Enum' + str(names)
+         def __str__(self):         return 'enum ' + str(constants)
+         def getList(self):         return list(names)
+
+      class EnumValue(object):
+         #__slots__ = ('__value')
+         def __init__(self, value): self.__value = value
+         Value = property(lambda self: self.__value)
+         EnumType = property(lambda self: EnumType)
+         def __hash__(self):        return hash(self.__value)
+         def __lt__(self, other): 
+             return (self.__value < other.__value)
+         def __gt__(self, other): 
+             return (self.__value > other.__value)
+         def __le__(self, other): 
+             return (self.__value <= other.__value)
+         def __ge__(self, other): 
+             return (self.__value >= other.__value)
+         def __eq__(self, other): 
+             if type(self) == int: lhs = self
+             else: lhs = self.__value
+             if type(other) == int: rhs = other
+             else: rhs = other.__value
+             return (lhs == rhs)
+         def __ne__(self, other): 
+             if type(self) == int: lhs = self
+             else: lhs = self.__value
+             if type(other) == int: rhs = other
+             else: rhs = other.__value
+             return (lhs != rhs)
+         def __invert__(self):      return constants[maximum - self.__value]
+         def __nonzero__(self):     return bool(self.__value)
+         def __repr__(self):        return str(names[self.__value])
+
+      maximum = len(names) - 1
+      constants = [None] * len(names)
+      lookup = {}
+      for i, each in enumerate(names):
+          val = EnumValue(i)
+          setattr(EnumClass, each, val)
+          # create list of int => 'str'
+          constants[i] = val
+          # create reverse lookup 
+          lookup[str(val)] = i
+      constants = tuple(constants)
+      EnumType = EnumClass()
+      return EnumType