poprf_ristretto/lib.rs
1//! # poprf-ristretto
2//!
3//! RFC 9497 **Partially-Oblivious Pseudorandom Function** (POPRF) over the
4//! `ristretto255-SHA512` ciphersuite.
5//!
6//! Implements the POPRF protocol variant from
7//! [RFC 9497](https://www.rfc-editor.org/rfc/rfc9497) §3.3.3 with the
8//! ristretto255-SHA512 ciphersuite defined in §4.1. All RFC 9497 Appendix A
9//! test vectors for POPRF/ristretto255-SHA512 pass.
10//!
11//! ## Quick start
12//!
13//! ```rust
14//! # #[cfg(feature = "std")] {
15//! use poprf_ristretto::{PoprfClient, PoprfServer};
16//! use rand_core::OsRng;
17//!
18//! let server = PoprfServer::generate(&mut OsRng);
19//! let client = PoprfClient::new(server.public_key());
20//!
21//! let input = b"my secret input";
22//! let info = b"public context";
23//!
24//! let (state, blinded) = client.blind(input, info, &mut OsRng).unwrap();
25//! let (evaluated, proof) = server.blind_evaluate(&mut OsRng, &blinded, info).unwrap();
26//! let output = client
27//! .finalize(input, &state, &evaluated, &blinded, &proof, info)
28//! .expect("proof verified");
29//!
30//! // Server-side offline evaluation must agree.
31//! assert_eq!(output, server.evaluate(input, info).unwrap());
32//! # }
33//! ```
34//!
35//! ## Wire format
36//!
37//! Every wire-bound type exposes a fixed-size byte serialization
38//! (`from_bytes` / `to_bytes` / `LEN` constant). All `from_bytes`
39//! implementations enforce canonical encoding (RFC 9496 §A.2) and reject
40//! the identity element on `Element` types (RFC 9497 §4.1).
41//!
42//! | Type | `LEN` | Source |
43//! |----------------------|-------------|------------------|
44//! | [`SecretKey`] | 32 (`Ns`) | server |
45//! | [`PublicKey`] | 32 (`Ne`) | server → client |
46//! | [`BlindedElement`] | 32 (`Ne`) | client → server |
47//! | [`EvaluatedElement`] | 32 (`Ne`) | server → client |
48//! | [`Proof`] | 64 (`2·Ns`) | server → client |
49//! | [`PoprfBlindState`] | 64 (`Ns + Ne`) | client-internal |
50//! | [`PoprfOutput`] | 64 (`Nh`) | client / server |
51//!
52//! ## Security
53//!
54//! * **Constant-time discipline.** [`PoprfClient::finalize`],
55//! [`PoprfClient::finalize_batch`], [`PoprfServer::blind_evaluate`],
56//! [`PoprfServer::blind_evaluate_batch`], [`PoprfServer::evaluate`], and
57//! [`PoprfServer::evaluate_tables`] are constant-time in every secret
58//! scalar: `skS`, the client `blind`, the DLEQ proof nonce `r`, and the
59//! per-`info` evaluation scalar `t = skS + m`. The test-vector siblings
60//! ([`PoprfClient::blind_with_scalar`],
61//! [`PoprfServer::blind_evaluate_with_proof_scalar`],
62//! [`PoprfServer::blind_evaluate_batch_with_proof_scalar`]) share the
63//! same path; the caller supplies the random scalar instead of sampling
64//! it from a CSPRNG. DLEQ challenge equality uses
65//! `subtle::ConstantTimeEq`. [`PoprfOutput`] equality is constant-time.
66//! * **`fast-dleq` vartime MSM** is used for DLEQ composite computation.
67//! This is safe because the per-element scalars `dᵢ` are derived from a
68//! public Fiat-Shamir transcript (RFC 9497 §2.2.1) and contain no
69//! secret input.
70//! * **Secret material.** [`SecretKey`] is server-secret. [`PoprfBlindState`]
71//! contains the client-secret blinding scalar; never transmit it to the
72//! server. All secret-bearing types ([`SecretKey`], [`PoprfServer`],
73//! [`PoprfBlindState`], [`PoprfOutput`]) implement `ZeroizeOnDrop` and
74//! are wiped automatically when they go out of scope. [`Proof`] is wire
75//! data with no secret content (see its type-level docs) and is not
76//! zeroized; nor is [`PoprfInputTable`] (see its docs).
77//! * **`info` parameter.** Both client and server must agree on `info`
78//! out-of-band. A mismatch yields [`Error::Verify`] on the client (the
79//! reconstructed `tweakedKey` will not match the server's), not silent
80//! garbage.
81//! * **Domain separation.** Every hash invocation is namespaced with a DST
82//! of the form `<label> || "OPRFV1-" || I2OSP(mode, 1) || "-" || suite_id`
83//! per RFC 9497 §3.1 / §4.
84//!
85//! ## Cargo features
86//!
87//! | Feature | Default | Description |
88//! |----------------------|---------|-------------|
89//! | `std` | yes | Enables `std::error::Error` impl on [`Error`]. |
90//! | `alloc` | yes | Required by all protocol APIs (implied by `std`). |
91//! | `fast-dleq` | yes | Vartime Pippenger MSM in DLEQ composite computation. |
92//! | `precomputed-tables` | yes | Windowed fixed-base tables: ~30 KB per live [`PoprfInputTable`]. |
93//! | `serde` | no | `serde::{Serialize, Deserialize}` for wire types. |
94//!
95//! At least one of `std` or `alloc` is required to build — the batched
96//! protocol APIs return `Vec`. The crate is `#![no_std]`-capable with
97//! `alloc`. `ZeroizeOnDrop` on secret-bearing types is unconditional;
98//! there is no cargo feature to disable it.
99
100#![cfg_attr(not(feature = "std"), no_std)]
101#![cfg_attr(docsrs, feature(doc_cfg))]
102#![forbid(unsafe_code)]
103#![warn(missing_docs)]
104#![allow(clippy::type_complexity)]
105
106#[cfg(not(feature = "alloc"))]
107compile_error!(
108 "poprf-ristretto requires the `alloc` feature (enabled by default via `std`). \
109 The batched protocol APIs return `Vec`. Enable `alloc` or `std`."
110);
111
112extern crate alloc;
113
114mod dleq;
115mod error;
116mod group;
117mod key;
118mod poprf;
119#[cfg(feature = "serde")]
120mod serde_util;
121mod util;
122
123pub use dleq::Proof;
124pub use error::Error;
125pub use key::{PublicKey, SecretKey, derive_key_pair, generate_key_pair};
126pub use poprf::{
127 BlindedElement, EvaluatedElement, PoprfBlindState, PoprfClient, PoprfInputTable, PoprfOutput,
128 PoprfServer,
129};
130
131/// Mode identifier for POPRF (RFC 9497 §3.1).
132pub const MODE_POPRF: u8 = 0x02;
133
134/// RFC 9497 ciphersuite identifier for this crate.
135pub const SUITE_ID: &str = "ristretto255-SHA512";