sqisign-lvl3 0.1.1

# sqisign-rs

Rust bindings for the [SQIsign](https://sqisign.org/) post-quantum signature scheme.

SQIsign (Short Quaternion and Isogeny Signature) is a post-quantum digital signature scheme based on isogenies between supersingular elliptic curves. It was submitted to NIST's Post-Quantum Cryptography Standardization Process and features the most compact signatures among all candidates.

## Crates

This workspace provides separate crates for each security level:

| Crate | Security Level | Public Key | Secret Key | Signature |
|-------|----------------|------------|------------|-----------|
| [`sqisign-lvl1`](crates/sqisign-lvl1) | NIST Level 1 (AES-128) | 65 bytes | 353 bytes | 148 bytes |
| [`sqisign-lvl3`](crates/sqisign-lvl3) | NIST Level 3 (AES-192) | 97 bytes | 529 bytes | 224 bytes |
| [`sqisign-lvl5`](crates/sqisign-lvl5) | NIST Level 5 (AES-256) | 129 bytes | 701 bytes | 292 bytes |

The [`sqisign-core`](crates/sqisign-core) crate provides shared types and traits for writing generic code.

## Features

- **Post-quantum security**: Resistant to attacks by quantum computers
- **Compact signatures**: Smallest signatures among NIST PQC candidates
- **Multiple security levels**: Choose the level appropriate for your use case
- **Safe Rust API**: Memory-safe wrappers around the C implementation
- **Automatic stack management**: Handles large stack requirements transparently
- **Clean ergonomics**: No type parameters needed for single-level usage

## Performance

Benchmarks on Apple M4 Mini Pro (Level 1):

| Operation | Time |
|-----------|------|
| Keygen | 10.97 ms |
| Sign | 24.56 ms |
| Verify | 1.65 ms |

Run benchmarks yourself: `cargo bench -p sqisign-lvl1`

## Installation

Add the crate for your desired security level to your `Cargo.toml`:

```toml
[dependencies]
# Choose one:
sqisign-lvl1 = "0.1"  # NIST Level 1 (fastest, smallest)
sqisign-lvl3 = "0.1"  # NIST Level 3 (medium)
sqisign-lvl5 = "0.1"  # NIST Level 5 (highest security)
```

**Minimum Rust version**: 1.88+

## System Requirements

Building these crates requires several system dependencies. The build script will automatically fetch and compile the SQIsign C library, but you need:

### Linux (Debian/Ubuntu)

```bash
sudo apt update
sudo apt install build-essential cmake git libgmp-dev
```

### Linux (Fedora/RHEL/CentOS)

```bash
sudo dnf install gcc gcc-c++ cmake git gmp-devel
```

### macOS

```bash
xcode-select --install
brew install cmake gmp
```

### Windows

Windows is not currently supported. Consider using WSL2.

## Usage

### Basic Example

```rust
use sqisign_lvl1::KeyPair;

fn main() {
    // Generate a keypair
    let keypair = KeyPair::generate().expect("keypair generation failed");

    // Sign a message
    let message = b"Hello, quantum-resistant world!";
    let signature = keypair.sign(message).expect("signing failed");

    // Verify the signature
    assert!(keypair.verify(message, &signature).expect("verification failed"));
    
    println!("Signature verified successfully!");
}
```

### Serialization

```rust
use sqisign_lvl1::{KeyPair, PublicKey, SecretKey};

fn main() {
    let keypair = KeyPair::generate().unwrap();
    
    // Serialize
    let pk_bytes = keypair.public_key.to_bytes();
    let sk_bytes = keypair.secret_key.to_bytes();
    
    // Deserialize
    let pk = PublicKey::from_bytes(&pk_bytes).unwrap();
    let sk = SecretKey::from_bytes(&sk_bytes).unwrap();
    
    // Use restored keys
    let sig = sk.sign(b"test").unwrap();
    assert!(pk.verify(b"test", &sig).unwrap());
}
```

### Constants

Each crate exports size constants:

```rust
use sqisign_lvl1::{PUBLIC_KEY_SIZE, SECRET_KEY_SIZE, SIGNATURE_SIZE};

let buffer = vec![0u8; SIGNATURE_SIZE];
```

### Generic Code Across Levels

Use `sqisign-core` to write code that works with any security level:

```rust
use sqisign_core::{SecurityLevel, KeyPair, Signature};

fn sign_message<L: SecurityLevel>(message: &[u8]) -> (KeyPair<L>, Signature<L>) {
    let keypair = KeyPair::<L>::generate().unwrap();
    let signature = keypair.sign(message).unwrap();
    (keypair, signature)
}

// Usage:
// use sqisign_lvl1::Level1;
// let (kp, sig) = sign_message::<Level1>(b"test");
```

## Build from Source

```bash
git clone https://github.com/SQISign/sqisign-rs.git
cd sqisign-rs

# Build all crates
cargo build --release

# Run all tests
cargo test

# Test a specific level
cargo test -p sqisign-lvl1
```

## Troubleshooting

### CMake not found

```bash
cmake --version  # Check if installed
# Install: apt install cmake (Linux) or brew install cmake (macOS)
```

### GMP library not found

```bash
# Debian/Ubuntu
sudo apt install libgmp-dev

# macOS
brew install gmp
```

## How It Works

Each level crate's build process:

1. **Fetch**: Downloads SQIsign C library from GitHub (pinned commit)
2. **Configure**: Uses CMake to configure for your system
3. **Compile**: Builds a monolithic static library for that level
4. **Link**: Links the static library and GMP into your Rust binary

## License

This project is dual-licensed under MIT and Apache-2.0.

The underlying SQIsign C library has its own license - see the [SQIsign repository](https://github.com/SQISign/the-sqisign).

## References

- [SQIsign Official Website](https://sqisign.org/)
- [SQIsign NIST Submission](https://csrc.nist.gov/Projects/post-quantum-cryptography)
- [SQIsign GitHub Repository](https://github.com/SQISign/the-sqisign)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

## Signed with SQIsign

This README is signed using SQIsign Level 1:

**Public Key** (65 bytes):
```
42ef6c6eaea747bd7da163d2ee62a2f438de80a2873caa8bc21d894a28b3d901
c290f39cb88b3805be62cd2633391cf6c2c10601abf8935a80eb4a251558bd02
02
```

**Signature** (148 bytes):
```
1ade5aca6e6523ebcf3837231ced10ef5e74dcec146f823d9bd221926d113500
9012aa2c7dcb885a4c6990f59e53ca269a757efd8e72a2ff751d38ae5c90b004
00001967c1a5731fe6ad67782f9e014666037ad5b260a2629c4e915d7559c0fb
0d3640f860c25435d11d2b56590b6ea65bb6f583fbdee32409f58c0cbe1641bc
e0c1e06de9d8186ff277daefa869c3b47a012104
```

Verify with: `cargo run --example verify_readme -p sqisign-lvl1`