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

charm/zkp_compiler/zkparser.py

@@ -0,0 +1,269 @@
+"""
+Zero-Knowledge Statement Parser.
+
+This module provides a parser for ZK proof statements using pyparsing.
+It converts statements like "h = g^x" or "(h = g^x) and (j = g^y)" into
+a binary tree representation for processing by the ZKP compiler.
+
+Supported Syntax:
+    - Single variable names: x, y, g, h (backwards compatible)
+    - Multi-character variable names: x1, x2, alpha, beta, gamma (NEW in v0.61)
+    - Exponentiation: g^x, g1^x1
+    - Equality: h = g^x
+    - Conjunction: (h = g^x) and (j = g^y)
+    - Disjunction: (h = g^x) or (j = g^y)
+
+Examples::
+
+    parser = ZKParser()
+    result = parser.parse("h = g^x")  # Single-char variables
+    result = parser.parse("h1 = g1^x1")  # Multi-char variables
+    result = parser.parse("commitment = generator^secret")  # Descriptive names
+"""
+from pyparsing import *
+from charm.toolbox.zknode import *
+import string
+import sys
+
+# Compatibility shim for pyparsing 3.x where upcaseTokens was moved to pyparsing_common
+try:
+    # pyparsing 2.x has upcaseTokens at module level
+    upcaseTokens
+except NameError:
+    # pyparsing 3.x moved it to pyparsing_common
+    try:
+        from pyparsing import pyparsing_common
+        upcaseTokens = pyparsing_common.upcase_tokens
+    except (ImportError, AttributeError):
+        # Fallback: define our own
+        def upcaseTokens(s, loc, toks):
+            return [t.upper() for t in toks]
+
+
+def _set_parse_action(element, action):
+    """Compatibility wrapper for setParseAction/set_parse_action."""
+    if hasattr(element, 'set_parse_action'):
+        return element.set_parse_action(action)
+    else:
+        return element.setParseAction(action)
+
+
+def _parse_string(parser, string):
+    """Compatibility wrapper for parseString/parse_string."""
+    if hasattr(parser, 'parse_string'):
+        return parser.parse_string(string)
+    else:
+        return parser.parseString(string)
+
+
+objStack = []
+
+
+def createNode(s, loc, toks):
+    """Create a BinNode from a parsed token."""
+    print('createNode => ', toks)
+    return BinNode(toks[0])
+
+
+# convert 'attr < value' to a binary tree based on 'or' and 'and'
+def parseNumConditional(s, loc, toks):
+    """Parse numeric conditional expressions."""
+    print("print: %s" % toks)
+    return BinNode(toks[0])
+
+
+def debug(s, loc, toks):
+    """Debug helper to print tokens."""
+    print("print: %s" % toks)
+    return toks
+
+
+def markPublic(s, loc, toks):
+    """Mark tokens as public variables."""
+    print("public: %s" % toks)
+    return toks
+
+
+def markSecret(s, loc, toks):
+    """Mark tokens as secret variables."""
+    print("secret: %s" % toks)
+    return toks
+
+
+def pushFirst(s, loc, toks):
+    """Push the first token onto the object stack."""
+    # print("Pushing first =>", toks[0])
+    objStack.append(toks[0])
+
+
+def createTree(op, node1, node2):
+    """
+    Create a binary tree node for an operator.
+
+    Args:
+        op: The operator string ("OR", "AND", "^", "=")
+        node1: Left child node
+        node2: Right child node
+
+    Returns:
+        BinNode with the operator type and children
+    """
+    if op == "OR":
+        node = BinNode(1)
+    elif op == "AND":
+        node = BinNode(2)
+    elif op == "^":
+        node = BinNode(3)
+    elif op == "=":
+        node = BinNode(4)
+    else:
+        return None
+    node.addSubNode(node1, node2)
+    return node
+
+
+class ZKParser:
+    """
+    Parser for Zero-Knowledge proof statements.
+
+    Converts ZK statements into binary tree representation for processing.
+
+    Supports both single-character variables (legacy) and multi-character
+    variable names (new in v0.61).
+
+    Examples::
+
+        parser = ZKParser()
+
+        # Single-character variables (legacy, still supported)
+        result = parser.parse("h = g^x")
+
+        # Multi-character variables (new in v0.61)
+        result = parser.parse("h1 = g1^x1")
+        result = parser.parse("commitment = generator^secret")
+
+        # Complex statements
+        result = parser.parse("(h = g^x) and (j = g^y)")
+        result = parser.parse("(pk1 = g^sk1) and (pk2 = g^sk2)")
+    """
+
+    def __init__(self, verbose=False):
+        """
+        Initialize the ZK parser.
+
+        Args:
+            verbose: If True, print debug information during parsing
+        """
+        self.finalPol = self.getBNF()
+        self.verbose = verbose
+
+    def getBNF(self):
+        """
+        Build the Backus-Naur Form grammar for ZK statements.
+
+        Returns:
+            pyparsing grammar object
+
+        Grammar supports:
+            - Variable names: alphanumeric starting with letter (e.g., x, x1, alpha)
+            - Operators: ^, =, AND, OR
+            - Parentheses for grouping
+        """
+        # supported operators => (OR, AND, <
+        OperatorOR = Literal("OR") | _set_parse_action(Literal("or"), upcaseTokens)
+        OperatorAND = Literal("AND") | _set_parse_action(Literal("and"), upcaseTokens)
+        lpar = Literal("(").suppress()
+        rpar = Literal(")").suppress()
+
+        ExpOp = Literal("^")
+        Equality = Literal("=")  # | Literal("==") | Word("<>", max=1)
+        Token = Equality | ExpOp
+        Operator = OperatorAND | OperatorOR | Token
+
+        # describes an individual leaf node
+        # UPDATED in v0.61: Support multi-character variable names
+        # Old: Word(alphas, max=1) - only single characters like x, y, g
+        # New: Word(alphas, alphanums) - alphanumeric starting with letter
+        #      Examples: x, x1, x2, alpha, beta, generator, secret
+        leafNode = _set_parse_action(Word(alphas, alphanums), createNode)
+        # describes expressions such as (attr < value)
+#        leafConditional = (Word(alphanums) + ExpOp + Word(nums)).setParseAction( parseNumConditional )
+
+        # describes the node concept
+        node = leafNode
+#        secret = variable.setParseAction( markSecret )
+#        public = variable.setParseAction( markPublic )
+
+#        expr = public + Equality + public + ExpOp + secret.setParseAction( pushFirst )
+        expr = Forward()
+        term = Forward()
+        factor = Forward()
+        atom = lpar + expr + rpar | _set_parse_action(leafNode, pushFirst)
+
+        # NEED TO UNDERSTAND THIS SEQUENCE AND WHY IT WORKS FOR PARSING ^ and = in logical order?!?
+        # Place more value on atom [ ^ factor}, so gets pushed on the stack before atom [ = factor], right?
+        # In other words, adds order of precedence to how we parse the string. This means we are parsing from right
+        # to left. a^b has precedence over b = c essentially
+        factor << atom + ZeroOrMore(_set_parse_action(ExpOp + factor, pushFirst))
+
+        term = atom + ZeroOrMore(_set_parse_action(Operator + factor, pushFirst))
+        # define placeholder set earlier with a 'term' + Operator + another term, where there can be
+        # more than zero or more of the latter. Once we find a term, we first push that into
+        # the stack, then if ther's an operand + term, then we first push the term, then the Operator.
+        # so on and so forth (follows post fix notation).
+        expr << term + ZeroOrMore(_set_parse_action(Operator + term, pushFirst))
+        # final bnf object
+        finalPol = expr#.setParseAction( debug )
+        return finalPol
+    
+    # method for evaluating stack assumes operators have two operands and pops them accordingly
+    def evalStack(self, stack):
+        op = stack.pop()
+#        print("op: %s" % op)
+        if op in ["AND","OR", "^", "="]: # == "AND" or op == "OR" or op == "^" or op == "=":
+            op2 = self.evalStack(stack)
+            op1 = self.evalStack(stack)
+            return createTree(op, op1, op2)
+#            print("debug tree => ", res)
+#            return res
+        else:
+            # Node value
+            return op
+    
+    # main loop for parser. 1) declare new stack, then parse the string (using defined BNF) to extract all
+    # the tokens from the string (not used for anything). 3) evaluate the stack which is in a post
+    # fix format so that we can pop an OR, AND, ^ or = nodes then pull 2 subsequent variables off the stack. Then,
+    # recursively evaluate those variables whether they are internal nodes or leaf nodes, etc.
+    def parse(self, str):
+        global objStack
+        del objStack[:]
+        tokens = _parse_string(self.finalPol, str)
+        print("stack =>", objStack)
+        return self.evalStack(objStack)
+   
+    # experimental - type checking 
+    def type_check(self, node, pk, sk):
+        if node.type == node.EXP:
+            print("public =>", node.getLeft(), "in pk?", pk.get(node.getLeft()))
+            print("secret =>", node.getRight(), "in sk?", sk.get(node.getRight()))
+            
+        elif node.type == node.EQ:
+            print("public =>", node.getLeft(), "in pk?", pk.get(node.getLeft()))
+            self.type_check(node.getRight(), pk, sk)
+        elif node.type == node.AND:
+            self.type_check(node.getLeft(), pk, sk)
+            self.type_check(node.getRight(), pk, sk)
+        else:
+            return None
+        return None
+    
+if __name__ == "__main__":
+    print(sys.argv[1:])
+    statement = sys.argv[1]
+
+    parser = ZKParser()
+    final = parser.parse(statement)
+    print("Final statement:  '%s'" % final)
+    pk = { 'g':1, 'h':2, 'j':3 }
+    sk = { 'x':4, 'y':5 }
+    parser.type_check(final, pk, sk)

charm_crypto_framework-0.61.1.dist-info/METADATA

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: charm-crypto-framework
+Version: 0.61.1
+Summary: Charm is a framework for rapid prototyping of cryptosystems
+Home-page: https://charm-crypto.io/
+Author: J. Ayo Akinyele
+Author-email: "J. Ayo Akinyele" <jakinye3@jhu.edu>
+Maintainer-email: "J. Ayo Akinyele" <jakinye3@jhu.edu>
+License: LGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/JHUISI/charm
+Project-URL: Documentation, https://jhuisi.github.io/charm/
+Project-URL: Repository, https://github.com/JHUISI/charm
+Project-URL: Issues, https://github.com/JHUISI/charm/issues
+Project-URL: Changelog, https://github.com/JHUISI/charm/blob/dev/CHANGELOG
+Keywords: cryptography,pairing-based cryptography,attribute-based encryption,identity-based encryption,digital signatures,elliptic curves,bilinear pairings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pyparsing<4.0,>=2.1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+
+Charm-Crypto
+============
+
+| Branch      | Status                                                                                                          |
+| ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `dev`       | ![Build Status](https://github.com/JHUISI/charm/actions/workflows/ci.yml/badge.svg?branch=dev) |
+
+Charm is a framework for rapidly prototyping advanced cryptosystems. Based on the Python language, it was designed from the ground up to minimize development time and code complexity while promoting the reuse of components.
+
+Charm uses a hybrid design: performance-intensive mathematical operations are implemented in native C modules, while cryptosystems themselves are written in a readable, high-level language. Charm additionally provides a number of new components to facilitate the rapid development of new schemes and protocols.
+
+## Features
+
+* **Mathematical Settings**: Integer rings/fields, bilinear (BN254) and non-bilinear Elliptic Curve groups
+* **Base Crypto Library**: Symmetric encryption, hash functions, PRNGs
+* **Standard APIs**: Digital signatures, encryption, commitments
+* **Protocol Engine**: Simplifies multi-party protocol implementation
+* **ZKP Compiler**: Production-ready compiler for interactive and non-interactive zero-knowledge proofs
+  - Discrete Log Equality (DLEQ) proofs
+  - Knowledge of Representation proofs
+  - AND/OR composition
+  - Range proofs
+  - Batch verification
+* **C/C++ Embed API**: Native applications can embed Charm via the Python C API
+* **Integrated Benchmarking**: Built-in performance measurement
+
+## Requirements
+
+| Component | Supported Versions |
+|-----------|-------------------|
+| **Python** | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 |
+| **Operating Systems** | Linux, macOS, Windows |
+| **OpenSSL** | 3.0+ |
+
+## Installation
+
+### Quick Install (pip)
+
+```bash
+pip install charm-crypto-framework
+```
+
+> **Note:** System libraries (GMP, PBC, OpenSSL) must be installed first. See [Prerequisites](#prerequisites) below.
+
+### Prerequisites
+
+Charm requires the following system libraries:
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| [GMP](http://gmplib.org/) | 5.0+ | Arbitrary precision arithmetic |
+| [PBC](http://crypto.stanford.edu/pbc/download.html) | 1.0.0 | Pairing-based cryptography |
+| [OpenSSL](http://www.openssl.org/source/) | 3.0+ | Cryptographic primitives |
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install libgmp-dev libssl-dev libpbc-dev flex bison
+```
+
+**macOS (Homebrew):**
+```bash
+brew install gmp openssl@3 pbc
+```
+
+**PBC from Source** (if not available via package manager):
+```bash
+wget https://crypto.stanford.edu/pbc/files/pbc-1.0.0.tar.gz
+tar xzf pbc-1.0.0.tar.gz
+cd pbc-1.0.0
+./configure && make && sudo make install
+```
+
+### From Source (Development)
+
+```bash
+git clone https://github.com/JHUISI/charm.git
+cd charm
+./configure.sh  # add --enable-darwin on macOS
+pip install -e ".[dev]"
+```
+
+### Verify Installation
+
+```bash
+python -c "from charm.toolbox.pairinggroup import PairingGroup; print('Charm installed successfully\!')"
+```
+
+## Testing
+
+Charm includes comprehensive test suites:
+
+```bash
+# Run all tests
+make test-all
+
+# Run specific test categories
+make test-unit       # Unit tests (toolbox, serialize, vectors)
+make test-schemes    # Cryptographic scheme tests
+make test-zkp        # ZKP compiler tests
+make test-adapters   # Adapter tests
+make test-embed      # C/C++ embed API tests
+
+# Threshold ECDSA (DKLS23) tests
+pytest charm/test/schemes/threshold_test.py -v
+
+# Run with coverage
+pytest --cov=charm charm/test/ -v
+```
+
+## Documentation
+
+* [Installation Guide](https://jhuisi.github.io/charm/install_source.html)
+* [Scheme Examples](https://jhuisi.github.io/charm/schemes.html)
+* [API Reference](https://jhuisi.github.io/charm/)
+* [C/C++ Embed API](embed/README.md)
+
+## Quick Examples
+
+### BLS Signatures (Pairing-Based)
+
+BLS signatures (Boneh-Lynn-Shacham) — standardized in [IETF RFC 9380](https://datatracker.ietf.org/doc/rfc9380/) and used in Ethereum 2.0:
+
+```python
+from charm.toolbox.pairinggroup import PairingGroup
+from charm.schemes.pksig.pksig_bls04 import BLS01
+
+# Initialize pairing group (BN254 curve, ~128-bit security)
+group = PairingGroup('BN254')
+bls = BLS01(group)
+
+# Ethereum 2.0 validator attestation
+attestation = {'slot': 1234, 'epoch': 38, 'beacon_block_root': '0xabc...'}
+
+(pk, sk) = bls.keygen()
+signature = bls.sign(sk['x'], attestation)
+assert bls.verify(pk, signature, attestation)
+```
+
+### ECDSA with secp256k1 (Bitcoin)
+
+ECDSA on secp256k1 — the curve used by Bitcoin ([SEC 2](https://www.secg.org/sec2-v2.pdf), [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)):
+
+```python
+import hashlib
+import json
+from charm.toolbox.ecgroup import ECGroup
+from charm.toolbox.eccurve import secp256k1
+from charm.schemes.pksig.pksig_ecdsa import ECDSA
+
+group = ECGroup(secp256k1)
+ecdsa = ECDSA(group)
+
+# Bitcoin transaction (simplified)
+tx = {
+    'inputs': [{'txid': 'a1b2c3...', 'vout': 0, 'address': '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'}],
+    'outputs': [{'address': '3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy', 'satoshis': 50000}],
+    'fee': 1000
+}
+
+# Serialize and double SHA-256 (SHA-256d) per Bitcoin protocol
+tx_bytes = json.dumps(tx, sort_keys=True).encode('utf-8')
+tx_hash = hashlib.sha256(hashlib.sha256(tx_bytes).digest()).hexdigest()
+
+(pk, sk) = ecdsa.keygen(0)
+signature = ecdsa.sign(pk, sk, tx_hash)
+assert ecdsa.verify(pk, signature, tx_hash)
+```
+
+> **Note:** Production Bitcoin implementations should use proper transaction serialization
+> per [Bitcoin Developer Documentation](https://developer.bitcoin.org/reference/transactions.html).
+
+### ECDSA with secp256k1 (XRPL)
+
+ECDSA on secp256k1 — also used by XRP Ledger ([SEC 2](https://www.secg.org/sec2-v2.pdf)):
+
+```python
+import hashlib
+import json
+from charm.toolbox.ecgroup import ECGroup
+from charm.toolbox.eccurve import secp256k1
+from charm.schemes.pksig.pksig_ecdsa import ECDSA
+
+group = ECGroup(secp256k1)
+ecdsa = ECDSA(group)
+
+# XRPL Payment transaction
+tx = {
+    'TransactionType': 'Payment',
+    'Account': 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh',
+    'Destination': 'rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe',
+    'Amount': '1000000',  # drops of XRP
+    'Sequence': 1
+}
+
+# Serialize and hash (XRPL uses canonical binary + SHA-512Half)
+tx_bytes = json.dumps(tx, sort_keys=True).encode('utf-8')
+tx_hash = hashlib.sha512(tx_bytes).hexdigest()[:64]  # SHA-512Half
+
+(pk, sk) = ecdsa.keygen(0)
+signature = ecdsa.sign(pk, sk, tx_hash)
+assert ecdsa.verify(pk, signature, tx_hash)
+```
+
+> **Note:** Production XRPL implementations should use canonical binary serialization
+> per [XRPL documentation](https://xrpl.org/serialization.html).
+
+### Threshold ECDSA (DKLS23) with XRPL testnet
+
+Charm also includes a threshold ECDSA scheme based on DKLS23, together with an XRPL
+testnet demo that shows how to use it end to end.
+
+```python
+from charm.toolbox.eccurve import secp256k1
+from charm.toolbox.ecgroup import ECGroup
+from charm.core.math.elliptic_curve import G
+from charm.schemes.threshold.dkls23_sign import DKLS23
+from charm.schemes.threshold.xrpl_wallet import (
+    XRPLThresholdWallet,
+    XRPLClient,
+    sign_xrpl_transaction,
+    create_payment_with_memo,
+    get_secp256k1_generator,
+)
+
+group = ECGroup(secp256k1)
+dkls = DKLS23(group, threshold=2, num_parties=3)
+g = get_secp256k1_generator(group)
+key_shares, public_key = dkls.distributed_keygen(g)
+wallet = XRPLThresholdWallet(group, public_key)
+client = XRPLClient(is_testnet=True)
+```
+
+See `examples/xrpl_memo_demo.py` for a complete XRPL testnet flow (fund account, create
+threshold wallet, send payment with memo).
+
+## Schemes
+
+Charm includes implementations of many cryptographic schemes:
+
+| Category | Examples |
+|----------|----------|
+| **ABE** | CP-ABE (BSW07), KP-ABE, FAME |
+| **IBE** | Waters05, BB04 |
+| **Signatures** | BLS, Waters, CL04 |
+| **Commitments** | Pedersen |
+| **Group Signatures** | BBS+, PS16 |
+
+See the [schemes directory](charm/schemes/) for all available implementations.
+
+## Contributing
+
+We welcome contributions\! Please note:
+
+* All schemes must include doctests for inclusion in `make test`
+* Follow the existing code style
+* Add tests for new functionality
+* Update documentation as needed
+
+## Security
+
+Charm uses the BN254 curve which provides approximately **128-bit security**. For production use:
+
+* Keep dependencies updated
+* Use the production-ready ZKP compiler (not the legacy `exec()`-based version)
+* Review scheme implementations for your specific security requirements
+
+## Support
+
+* **Issues**: [GitHub Issues](https://github.com/JHUISI/charm/issues)
+* **Email**: jakinye3@jhu.edu
+
+## License
+
+Charm is released under the **LGPL version 3** license. See [LICENSE.txt](LICENSE.txt) for details.
+
+## Citation
+
+If you use Charm in academic work, please cite:
+
+```bibtex
+@article{charm,
+  author = {Akinyele, Joseph A. and Garman, Christina and Miers, Ian and Pagano, Matthew W. and Rushanan, Michael and Green, Matthew and Rubin, Aviel D.},
+  title = {Charm: A Framework for Rapidly Prototyping Cryptosystems},
+  journal = {Journal of Cryptographic Engineering},
+  year = {2013}
+}
+```