# G-Merkle+, a hash based group signature scheme

This repository contains Python code for a hash based group signature scheme, as given by R. El Bansarkhani and R. Misoczki in the whitepaper **G-Merkle: A Hash-Based Group Signature Scheme From Standard Assumptions**. Scheme uses Merkle Signature Scheme along with Winternitz One Time Signature Scheme.

> [El Bansarkhani, R., Misoczki, R. _G-Merkle: A Hash-Based Group Signature Scheme From Standard Assumptions._ IACR Cryptology ePrint Archive. 2018.](https://eprint.iacr.org/2018/274 "Link to the whitepaper.")


## Requirements
Implementation was created using Python 3.9.11 and three external packages:
- [**pycryptodome**](https://www.pycryptodome.org/en/latest/)
    - for AES encryption of leaf indexes
- [**merkletools**](https://github.com/Tierion/pymerkletools)
    - for Merkle tree building, creating proofs and verifying proofs
- [**pysha3**](https://pypi.org/project/pysha3/)
    - for SHA3 hashing

Clone the repo and preferably install these packages within a virtual environment:
```
python3 -m venv venv
source venv/bin/activate
```
Install all requirements at once:
```
pip install -r requirements.txt
```
Or install packages one by one:
```
pip install pycryptodome
pip install merkletools
pip install pysha3
```

## Running the scheme

Currently there are two ways to run the scheme from the CLI:
### Example 1
Instantiate the scheme with default parameters, view possible scenarios and choose the one to be run:
```
python3 gmerkle_group_signature.py
```
Instantiate the scheme with default parameters and directly run one out of 6 premade scenarios:
```
python3 gmerkle_group_signature.py --scenario 1
python3 gmerkle_group_signature.py -s 1
```

### Example 2
Interactive mode for the group signature scheme. Simply run by:
```
python3 gmerkle_gss_interactive.py
```
This mode lets you choose the amount of group members and signatures per member, signing member id and a message. Verification and opening operations require a message to run as well. This way the outcomes of such operations carried out on wrong messages can be tested.

## Directory structure
The ```g-merkle``` folder contains 6 Python files:
- **[gmerkle_group_signature.py](g-merkle/gmerkle_group_signature.py)**
    - serves as a main file for example 1
- **[gmerkle_gss_interactive.py](g-merkle/gmerkle_gss_interactive.py)**
    - serves as a main file for example 2
- **[gmerkle.py](g-merkle/gmerkle.py)**
    - **group signature scheme class**
        - handles the scheme instantiation
        - creates the group manager entity
        - handles and delegates signing, verification and opening
- **[entities.py](g-merkle/entities.py)**
    - **group manager class**
        - joins members to the group
        - handles leaf shuffling
        - handles tree building
    - **group member class**
        - handles OTS keypairs generation
        - handles states
        - handles OTS message signing
        - returns leaves to group manager
- **[utils.py](g-merkle/utils.py)**
    - supporting functions (OTS sign, verify, hashing etc.)
- **[test_scenarios.py](g-merkle/test_scenarios.py)**
    - contains premade testing scenarios (used by example 1)
    - contains premade wrong testing variables

## Scheme operations syntax
Scheme can used just by importing ```gmerkle``` to your main file. Example usage as shown below.
```python
from gmerkle import g_merkle_GSS as GSS

members = 10                # assign number of group members
signatures = 10             # assign number of possible signatures per group member

# scheme instantiation
gmerkle_gs = GSS(members, signatures)
gpk = gmerkle_gs.gpk        # get Merkle root (group public key) of the scheme

id = 5                      # signing member id within the range of 1 - members

message = "Hello world"     # message to be signed

signature = gmerkle_gs.sign(id, message)
verification = gmerkle_gs.verify(signature, message, gpk)
open = gmerkle_gs.open(signature, message)

print(verification)         # Output:   True
print(open)                 # Output:   Signature was created by user 5.

```

<br>
<br>

### Author

Pavla Hlučková<br>
<xhluck01@vutbr.cz>
