Skip to main content

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";