# Hybrid Cryptography

[![Crates.io](https://img.shields.io/crates/v/dcrypt-hybrid.svg)](https://crates.io/crates/dcrypt-hybrid)
[![Docs.rs](https://docs.rs/dcrypt-hybrid/badge.svg)](https://docs.rs/dcrypt-hybrid)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Repository](https://img.shields.io/badge/repository-GitHub-blue.svg)](https://github.com/DePINNetwork/dcrypt)

## Overview

`dcrypt-hybrid` is a Rust crate that provides hybrid cryptographic schemes by combining classical and post-quantum algorithms. This approach is vital for ensuring long-term security against future threats, particularly from quantum computers, by providing resistance to "Harvest Now, Decrypt Later" attacks.

The core principle is to combine two cryptographic primitives—one classical (like ECDH) and one post-quantum (like Kyber)—such that the resulting scheme is secure as long as *at least one* of the underlying primitives remains secure.

This crate is part of the broader `dcrypt` library ecosystem.

## Implemented Schemes

The crate provides hybrid implementations for two primary cryptographic functions: Key Encapsulation Mechanisms (KEMs) and Digital Signatures.

### Hybrid Key Encapsulation Mechanisms (KEMs)

A KEM is used to securely establish a shared secret between two parties. Our hybrid KEM ensures that the shared secret remains confidential even if one of the constituent algorithms is broken in the future. The design is modular, allowing for easy addition of new hybrid combinations.

#### **Available KEMs**
*   **`EcdhP256Kyber768`**: Combines classical ECDH on the P-256 curve with post-quantum Kyber-768 (NIST Level 3).
*   **`EcdhP384Kyber1024`**: A higher-security variant combining ECDH on P-384 with Kyber-1024 (NIST Level 5).

**How it works:**
1.  A key pair is generated by creating both a classical and a post-quantum key pair. The public keys are concatenated.
2.  To encapsulate, the sender performs two separate encapsulation operations, one for each algorithm.
3.  The resulting two shared secrets are combined into a single, final shared secret using **HKDF-SHA256**.
4.  The recipient performs two decapsulations and combines the results in the same way to derive the identical final secret.

**Example Usage (`EcdhP256Kyber768`):**
```rust
use dcrypt::api::Kem;
use dcrypt::hybrid::kem::EcdhP256Kyber768;
use rand::rngs::OsRng;

// 1. Generate a hybrid key pair for the recipient.
let (pk, sk) = EcdhP256Kyber768::keypair(&mut OsRng)?;

// 2. The sender encapsulates a secret for the recipient's public key.
let (ciphertext, shared_secret_sender) = EcdhP256Kyber768::encapsulate(&mut OsRng, &pk)?;

// 3. The recipient decapsulates the ciphertext with their secret key.
let shared_secret_recipient = EcdhP256Kyber768::decapsulate(&sk, &ciphertext)?;

// 4. Both parties now have the same shared secret.
assert_eq!(
    *shared_secret_sender.to_bytes_zeroizing(),
    *shared_secret_recipient.to_bytes_zeroizing()
);
println!("Successfully established a hybrid shared secret!");
# Ok::<(), Box<dyn std::error::Error>>(())
```

### Hybrid Digital Signatures

A hybrid signature requires that both the classical and post-quantum signatures are valid to be accepted.

#### **`EcdsaDilithiumHybrid`**

This scheme combines:
*   **Classical:** `ECDSA` with the P-384 curve.
*   **Post-Quantum:** `Dilithium3`, a signature algorithm selected by the NIST PQC standardization process.

#### **`RsaFalconHybrid`**

This scheme combines:
*   **Classical:** `RSA-PSS`.
*   **Post-Quantum:** `Falcon-512`, another signature algorithm from the NIST PQC process.

**How it works:**
1.  A hybrid key pair consists of both a classical and a post-quantum key pair.
2.  To sign a message, two separate signatures are generated and concatenated.
3.  To verify, a recipient must successfully verify *both* component signatures. If either fails, the entire signature is invalid.

**Example Usage (`EcdsaDilithiumHybrid`):**
```rust
use dcrypt::api::Signature;
use dcrypt::hybrid::sign::EcdsaDilithiumHybrid;
use rand::rngs::OsRng;

// 1. Generate a hybrid key pair.
let (pk, sk) = EcdhDilithiumHybrid::keypair(&mut OsRng)?;

let message = b"This message needs a hybrid signature.";

// 2. Sign the message with the hybrid secret key.
let signature = EcdhDilithiumHybrid::sign(message, &sk)?;

// 3. Verify the hybrid signature with the public key.
let verification_result = EcdhDilithiumHybrid::verify(message, &signature, &pk);

assert!(verification_result.is_ok());
println!("Successfully created and verified a hybrid signature!");
# Ok::<(), Box<dyn std::error::Error>>(())
```

## Installation

Add `dcrypt-hybrid` to your `Cargo.toml` dependencies:
```toml
[dependencies]
dcrypt-hybrid = "0.13.0-beta.2"
```
Or use the cargo command:
```sh
cargo add dcrypt-hybrid
```

## Features

This crate is designed to be flexible and supports `no_std` environments.

*   **`std`** (default): Enables functionality that requires the standard library.
*   **`alloc`**: Enables functionality requiring a global allocator, used by `std` and `no_std`.
*   **`no_std`**: For use in environments without the standard library. You must depend on the crate with `default-features = false`.
*   **`serde`**: Enables serialization and deserialization for some public types via the [Serde](https://serde.rs/) framework.

## License

This crate is licensed under the Apache-2.0 License.