dcrypt-hybrid 4.0.0

Hybrid cryptography schemes for the dcrypt library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# 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` composes classical and post-quantum algorithms. Hybrid designs
can reduce dependence on a single primitive during a migration, but their
security also depends on the combiner, framing, domain separation, protocol
context, key validation, and both component implementations.

Do not interpret this composition as an unconditional guarantee that the result
is secure whenever either component survives. Applications still need an
independent review of the complete protocol and its assumptions.

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 establishes a shared secret between two parties. These hybrid KEMs combine
two component secrets through a KDF. The resulting security claim is conditional
on the combiner and surrounding protocol as well as the component assumptions;
it is not established by concatenating algorithms alone.

#### **Available KEMs**
*   **`EcdhK256MlKem512`**: Combines ECDH on secp256k1 with ML-KEM-512.
*   **`EcdhP256MlKem512`**: Combines ECDH on P-256 with ML-KEM-512.
*   **`EcdhP256MlKem768`**: Combines classical ECDH on P-256 with final FIPS 203 ML-KEM-768.
*   **`EcdhP384MlKem1024`**: Combines classical ECDH on P-384 with final FIPS 203 ML-KEM-1024.
*   **`EcdhP521MlKem1024`**: Combines ECDH on P-521 with ML-KEM-1024.

**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 (`EcdhP256MlKem768`):**
```rust
use dcrypt::api::Kem;
use dcrypt::hybrid::kem::EcdhP256MlKem768;
use dcrypt::internal::{CryptoRng, RngCore};

fn establish<R: CryptoRng + RngCore>(rng: &mut R) -> dcrypt::api::Result<()> {
    // The application supplies a fallible cryptographic RNG.
    let (pk, sk) = EcdhP256MlKem768::keypair(rng)?;

    let (ciphertext, shared_secret_sender) = EcdhP256MlKem768::encapsulate(rng, &pk)?;

    let shared_secret_recipient = EcdhP256MlKem768::decapsulate(&sk, &ciphertext)?;

    assert_eq!(
        &shared_secret_sender.to_bytes_zeroizing()[..],
        &shared_secret_recipient.to_bytes_zeroizing()[..],
    );
    Ok(())
}
```

### Hybrid Digital Signatures

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

#### **`EcdsaMlDsa65Hybrid`**

This scheme combines:
*   **Classical:** `ECDSA` with the P-384 curve.
*   **Post-Quantum:** final FIPS 204 `ML-DSA-65`.

Public keys, secret keys, and signatures use domain-separated version-2 framing.
The decoder rejects version-1 legacy objects because their post-quantum
component used a nonstandard, incompatible encoding. Version-1
objects are not migrated or relabeled as ML-DSA.

**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 (`EcdsaMlDsa65Hybrid`):**
```rust
use dcrypt::api::Signature;
use dcrypt::hybrid::sign::EcdsaMlDsa65Hybrid;
use dcrypt::internal::{CryptoRng, RngCore};

fn sign_message<R: CryptoRng + RngCore>(rng: &mut R) -> dcrypt::api::Result<()> {
    let (pk, sk) = EcdsaMlDsa65Hybrid::keypair(rng)?;

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

    let signature = EcdsaMlDsa65Hybrid::sign(message, &sk)?;

    EcdsaMlDsa65Hybrid::verify(message, &signature, &pk)
}
```

## Release status

Version 3.0.0 is the supported corrective release. Version 2.0.0 was
withdrawn and every pre-v3 release is unsupported. Review the repository
`SECURITY.md` and the v3 migration notes before deployment.

## Features

*   **`std`** (default): Standard-library support; also enables `alloc`.
*   **`alloc`**: Allocation-backed hybrid APIs in a `no_std` environment.
*   **`no_std`**: Compatibility spelling that enables the supported `alloc`
    profile without selecting the standard library.

## License

This crate is licensed under the Apache-2.0 License.