docs: prototype design and implementation risks

src/api.rs

@@ -34,13 +34,14 @@ pub type Mask = [u8; 32];
 
 /// Entitlement to enroll.
 ///
-/// Contains provider commitments `([a10]G, [a11]G)` and a proof of knowledge
-/// of `a10`.
+/// Contains provider commitments ([<i>a</i><sub>10</sub>]<i>G</i>,
+/// [<i>a</i><sub>11</sub>]<i>G</i>) and a Schnorr zero-knowledge proof of
+/// knowledge of <i>a</i><sub>10</sub>.
 pub type Voucher = [u8; 131];
 
 /// Attempt to redeem a [Voucher] to enroll.
 ///
-/// Contains subscriber commitments `([a20]G, [a21]G)`, a proof of knowledge
+/// Contains subscriber commitments () `([a20]G, [a21]G)`, a proof of knowledge
 /// of `a20`, and a secret share `a20 + a21 * 1` for the provider.
 pub type Redemption = [u8; 163];
 
@@ -147,6 +148,12 @@ pub unsafe extern "C" fn pay(
 }
 
 /// Releases a [Payload] from memory.
+///
+/// # Risk
+///
+/// - It is easy for users to forget releasing allocated memory. Possibly this
+///   does not require a separate function anyway, since the functions consuming
+///   a payload would release it anyway.
 #[no_mangle]
 #[export_name = "scal3_release"]
 pub unsafe extern "C" fn release(

src/api/provider.rs

@@ -100,6 +100,11 @@ pub extern "C" fn vouch(
 /// let process = provider::process(&randomness, &redemption, &mut info);
 /// assert!(!process.is_null())
 /// ```
+///
+/// # Risks
+///
+/// - The output `info` leaks implementation details. It could be better to
+///   output a fixed-size digest for use with a pre-hashed signing function.
 #[no_mangle]
 #[export_name = "scal3_provider_process"]
 pub extern "C" fn process(
@@ -259,6 +264,14 @@ pub extern "C" fn challenge(
 /// # Ok(())
 /// # }
 /// ```
+///
+/// # Risks
+///
+/// - A person in the middle could change the subscriber’s signature share
+///   before forwarding to the provider, potentially exhausting an attempt
+///   rate limiting counter, and thereby causing a denial of service. This
+///   could be mitigated by additionally verifying a checksum of input data
+///   under the device signature.
 #[export_name = "scal3_provider_prove"]
 pub extern "C" fn prove(
     randomness: &Randomness,

src/api/subscriber.rs

@@ -153,6 +153,11 @@ pub type Data = [u8; DATA_TO_SIGN_DOMAIN.len() + 32];
 /// # Ok(())
 /// # }
 /// ```
+///
+/// # Risks
+///
+/// - The output `data` leaks implementation details. It could be better to
+///   output a fixed-size digest for use with a pre-hashed signing function.
 #[no_mangle]
 #[export_name = "scal3_subscriber_authenticate"]
 pub extern "C" fn authenticate(

src/lib.rs

@@ -30,6 +30,21 @@
 //! ## Auditing
 //!
 //! The [subscriber] or any other party with access can [verify] the [Evidence].
+//!
+//! # Risks
+//!
+//! - Not all hash functions are checked for proper domain separation. This risk
+//!   could be limited by centralizing all hash function definitions for easier
+//!   review.
+//! - This library does not apply its dependencies everywhere in an idiomatic
+//!   way. For example, where dependency constructors are not exposed, the
+//!   implementation now relies on serialization/deserialization. Also,
+//!   sometimes too low-level types are used, such as `Scalar` instead of
+//!   `SecretKey` and `ProjectivePoint` instead of `PublicKey`, which
+//!   potentially means missing out on some security features.
+//! - The implementation may still be vulnerability to side channel attacks,
+//!   such as timing attacks and reading memory that was not zeroized in time.
+//!   The security dependencies offer functions to implement this properly.
 
 mod api;
 mod group;