hash-zig

A pure Zig implementation of hash-based signatures using Poseidon2 and SHA3 hash functions with incomparable encodings. This library implements XMSS-like signatures based on the framework from this paper.

🌟 Features

• Multiple Hash Functions: Support for both Poseidon2 (ZK-optimized) and SHA3 (NIST standard)
• Poseidon2 Hash Function: Efficient arithmetic hash optimized for zero-knowledge proof systems
• SHA3 Hash Function: NIST-standardized cryptographic hash (SHA3-256, SHA3-384, SHA3-512)
• Multiple Security Levels: 128-bit, 192-bit, and 256-bit security
• Flexible Key Lifetimes: Support from 2^10 to 2^32 signatures per keypair
• Incomparable Encodings: Binary, ternary, and quaternary encoding schemes
• Hypertree Optimization: Efficient handling of large signature trees
• Pure Zig: Minimal dependencies, fully type-safe
• Well-Tested: Comprehensive unit and integration tests

📋 Table of Contents

• Installation
• Quick Start
• Usage
• Configuration
• Architecture
• Performance
• Security Considerations
• API Reference
• Testing
• Contributing
• License

🚀 Installation

Using Zig Package Manager

Add to your build.zig.zon:

.{
    .name = .my_project,
    .version = "0.1.0",
    .dependencies = .{
        .@"hash-zig" = .{
            .url = "https://github.com/ch4r10t33r/hash-zig/archive/refs/tags/v0.1.0.tar.gz",
            .hash = "1220...", // Will be generated by zig build
        },
    },
}

In your build.zig:

const hash_zig_dep = b.dependency("hash-zig", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("hash-zig", hash_zig_dep.module("hash-zig"));

Manual Installation

git clone https://github.com/ch4r10t33r/hash-zig.git
cd hash-zig
zig build test

⚡ Quick Start

const std = @import("std");
const hash_zig = @import("hash-zig");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Initialize with 128-bit security and medium lifetime (2^16 signatures)
    const params = hash_zig.Parameters.init(.level_128, .lifetime_2_16);
    var sig_scheme = try hash_zig.HashSignature.init(allocator, params);
    defer sig_scheme.deinit();

    // Generate keypair
    var keypair = try sig_scheme.generateKeyPair(allocator);
    defer keypair.deinit(allocator);

    // Sign a message
    const message = "Hello, hash-based signatures!";
    var signature = try sig_scheme.sign(allocator, message, keypair.secret_key, 0);
    defer signature.deinit(allocator);

    // Verify signature
    const is_valid = try sig_scheme.verify(allocator, message, signature, keypair.public_key);
    std.debug.print("Signature valid: {}\n", .{is_valid});
}

📖 Usage

Basic Signing and Verification

const hash_zig = @import("hash-zig");

// Configure parameters with Poseidon2 (default)
const params = hash_zig.Parameters.init(.level_128, .lifetime_2_16);
var sig = try hash_zig.HashSignature.init(allocator, params);
defer sig.deinit();

// Generate keys
var keypair = try sig.generateKeyPair(allocator);
defer keypair.deinit(allocator);

// Sign
var signature = try sig.sign(allocator, "message", keypair.secret_key, 0);
defer signature.deinit(allocator);

// Verify
const valid = try sig.verify(allocator, "message", signature, keypair.public_key);

Using SHA3 Hash Function

// Initialize with SHA3-256 instead of Poseidon2
const params = hash_zig.Parameters.initWithSha3(.level_128, .lifetime_2_16);

// Everything else works the same way
var sig = try hash_zig.HashSignature.init(allocator, params);
defer sig.deinit();

Different Security Levels

// 128-bit security with Poseidon2
const params_128 = hash_zig.Parameters.init(.level_128, .lifetime_2_16);

// 192-bit security with Poseidon2
const params_192 = hash_zig.Parameters.init(.level_192, .lifetime_2_16);

// 256-bit security with Poseidon2
const params_256 = hash_zig.Parameters.init(.level_256, .lifetime_2_16);

// Or use SHA3
const params_sha3 = hash_zig.Parameters.initWithSha3(.level_128, .lifetime_2_16);

Different Key Lifetimes

// lifetime_2_10: 2^10 = 1,024 signatures
const params_short = hash_zig.Parameters.init(.level_128, .lifetime_2_10);

// lifetime_2_16: 2^16 = 65,536 signatures (default)
const params_medium = hash_zig.Parameters.init(.level_128, .lifetime_2_16);

// lifetime_2_20: 2^20 = 1,048,576 signatures
const params_long = hash_zig.Parameters.init(.level_128, .lifetime_2_20);

// lifetime_2_28: 2^28 = 268,435,456 signatures
const params_very_long = hash_zig.Parameters.init(.level_128, .lifetime_2_28);

// lifetime_2_32: 2^32 = 4,294,967,296 signatures
const params_extreme = hash_zig.Parameters.init(.level_128, .lifetime_2_32);

⚙️ Configuration

Security Levels

Level	Hash Output	Encoding	Security Bits
level_128	32 bytes	binary	128-bit
level_192	48 bytes	ternary	192-bit
level_256	64 bytes	quaternary	256-bit

Hash Functions

Function	Security	Output Size	Use Case
poseidon2_128	128-bit	32 bytes	ZK proofs, arithmetic circuits
poseidon2_192	192-bit	48 bytes	ZK proofs, arithmetic circuits
poseidon2_256	256-bit	64 bytes	ZK proofs, arithmetic circuits
sha3_256	128-bit	32 bytes	NIST standard, general crypto
sha3_384	192-bit	48 bytes	NIST standard, general crypto
sha3_512	256-bit	64 bytes	NIST standard, general crypto

Key Lifetimes

Lifetime	Tree Height	Max Signatures	Memory Required*
lifetime_2_10	10	1,024	~32 KB
lifetime_2_16	16	65,536	~2 MB
lifetime_2_20	20	1,048,576	~33 MB
lifetime_2_28	28	268,435,456	~8.6 GB
lifetime_2_32	32	4,294,967,296	~137 GB

*Memory estimates based on 32-byte hashes. For large lifetimes, hypertree optimization is automatically used.

🏗️ Architecture

hash-zig/
├── src/
│   ├── root.zig              # Main module entry point
│   ├── params.zig            # Configuration and parameters
│   ├── poseidon2/
│   │   ├── field.zig         # BN254 field arithmetic
│   │   └── hash.zig          # Poseidon2 implementation
│   ├── sha3.zig              # SHA3 hash implementation
│   ├── encoding.zig          # Incomparable encodings
│   ├── tweakable_hash.zig    # Domain-separated hashing
│   ├── winternitz.zig        # Winternitz OTS
│   ├── merkle.zig            # Merkle tree construction
│   └── signature.zig         # Main signature scheme
├── examples/
│   └── basic_usage.zig
├── test/
│   └── integration_test.zig
└── build.zig

Key Components

• Poseidon2: Arithmetic hash over BN254 scalar field, optimized for ZK proofs
• SHA3: NIST-standardized Keccak-based hash for general-purpose cryptography
• Winternitz OTS: Efficient one-time signature scheme with configurable chain length
• Merkle Tree: Single tree for small lifetimes, automatic hypertree for large ones
• Incomparable Encodings: Binary, ternary, and quaternary encoding schemes

📊 Performance

⚠️ Benchmarks pending: Performance measurements have not been conducted yet. Values will vary based on hardware, hash function choice, and implementation optimizations.

Theoretical Estimates

Operation	Estimated
Key Generation (2^10)	TBD
Sign	TBD
Verify	TBD
Public Key Size	32-64 bytes
Signature Size	~2-4 KB

Optimization Tips

1. Use appropriate lifetime for your use case
2. Choose hash function based on requirements:
   • Poseidon2 for ZK-proof systems
   • SHA3 for NIST compliance and interoperability
3. Batch key generation offline when possible
4. Always persist signature state
5. Use hypertree for lifetimes > 2^20

🔒 Security Considerations

⚠️ Critical Rules

1. NEVER reuse a signature index - Each index must be used only once
2. Protect the secret key - Use secure storage (encrypted, HSM, etc.)
3. Verify signatures properly - Always check return values
4. Plan key rotation - Generate new keypair before exhausting signatures

Security Properties

• Post-quantum secure: Resistant to quantum attacks
• Stateful: Requires tracking used indices
• Forward secure: Old signatures valid even if key compromised
• One-time per index: Each tree index used once only

📚 API Reference

Parameters

// Poseidon2 (default)
const params = hash_zig.Parameters.init(.level_128, .lifetime_2_16);

// SHA3
const params_sha3 = hash_zig.Parameters.initWithSha3(.level_128, .lifetime_2_16);

// Default (Poseidon2, lifetime_2_16)
const params_default = hash_zig.Parameters.initDefault(.level_128);

Enums

pub const SecurityLevel = enum { level_128, level_192, level_256 };
pub const HashFunction = enum { 
    poseidon2_128, poseidon2_192, poseidon2_256,
    sha3_256, sha3_384, sha3_512
};
pub const KeyLifetime = enum { 
    lifetime_2_10,   // 1,024 signatures
    lifetime_2_16,   // 65,536 signatures
    lifetime_2_20,   // 1,048,576 signatures
    lifetime_2_28,   // 268,435,456 signatures
    lifetime_2_32    // 4,294,967,296 signatures
};
pub const EncodingType = enum { binary, ternary, quaternary };

🧪 Testing

Run All Tests

zig build test

Run Linter

zig build lint

Build Library

zig build

Run Example

zig build example

Generate Documentation

zig build docs

This will generate HTML documentation in zig-out/docs/. Open zig-out/docs/index.html in your browser to view the API documentation.

Test Examples

Poseidon2:

test "poseidon2 hashing" {
    const allocator = std.testing.allocator;
    const params = hash_zig.Parameters.init(.level_128, .lifetime_2_16);
    
    var hash = try hash_zig.TweakableHash.init(allocator, params);
    defer hash.deinit();
    
    const result = try hash.hash(allocator, "test data", 0);
    defer allocator.free(result);
    
    try std.testing.expect(result.len == 32);
}

SHA3:

test "sha3 hashing" {
    const allocator = std.testing.allocator;
    const params = hash_zig.Parameters.initWithSha3(.level_128, .lifetime_2_16);
    
    var hash = try hash_zig.TweakableHash.init(allocator, params);
    defer hash.deinit();
    
    const result = try hash.hash(allocator, "test data", 0);
    defer allocator.free(result);
    
    try std.testing.expect(result.len == 32); // SHA3-256
}

Comparison:

test "compare hash functions" {
    const allocator = std.testing.allocator;
    
    // Poseidon2
    const params_p2 = hash_zig.Parameters.init(.level_128, .lifetime_2_16);
    var hash_p2 = try hash_zig.TweakableHash.init(allocator, params_p2);
    defer hash_p2.deinit();
    
    // SHA3
    const params_sha3 = hash_zig.Parameters.initWithSha3(.level_128, .lifetime_2_16);
    var hash_sha3 = try hash_zig.TweakableHash.init(allocator, params_sha3);
    defer hash_sha3.deinit();
    
    const data = "test";
    const h1 = try hash_p2.hash(allocator, data, 0);
    defer allocator.free(h1);
    const h2 = try hash_sha3.hash(allocator, data, 0);
    defer allocator.free(h2);
    
    // Different hash functions produce different outputs
    try std.testing.expect(!std.mem.eql(u8, h1, h2));
}

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for changes
4. Ensure tests pass (zig build test)
5. Run linter (zig build lint)
6. Open a Pull Request

CI/CD

GitHub Actions automatically runs on pushes/PRs to main, master, or develop:

• Linting using zlinter
• Tests on Ubuntu, macOS, Windows
• Uses Zig 0.14.1 (required for zlinter compatibility)

See .github/workflows/ci.yml for details.

Note: The project currently requires Zig 0.14.1 because zlinter only supports the 0.14.x branch. Once zlinter adds support for Zig 0.15+, we'll update to the latest version.

🐛 Known Issues

• Signature verification not fully implemented: The verify function is a placeholder. Full XMSS verification requires Merkle authentication paths which are not yet implemented
• Hypertree authentication paths not yet implemented
• State persistence needs implementation
• Large tree generation (2^28+) requires significant resources

⚠️ Important: This is a research/prototype implementation. The signature verification currently does not perform full Merkle tree validation and should NOT be used in production.

📄 License

Apache License 2.0 - see LICENSE file.

🙏 Acknowledgments

• Inspired by Rust implementation
• Framework from hash-sig paper
• Poseidon2 spec from Poseidon2 paper

📧 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⚠️ IMPORTANT DISCLAIMER: This is a prototype implementation for research and experimentation. The signature verification is incomplete (Merkle authentication paths not implemented). This code has NOT been audited and should NOT be used in production systems.