From 630128ce1634a49c3aeb963778230dd15d6bfb34 Mon Sep 17 00:00:00 2001 From: Kevin Lewi Date: Thu, 21 Mar 2024 00:41:13 -0700 Subject: [PATCH] Add documentation around HistoryParams insecure options --- akd/benches/directory.rs | 2 +- akd/src/directory.rs | 16 ++++++++++------ akd/src/lib.rs | 22 +++++++++++++++++++--- akd/src/tests.rs | 15 ++++++++++++--- 4 files changed, 42 insertions(+), 13 deletions(-) diff --git a/akd/benches/directory.rs b/akd/benches/directory.rs index 03f2a686..87e9f505 100644 --- a/akd/benches/directory.rs +++ b/akd/benches/directory.rs @@ -79,7 +79,7 @@ fn history_generation(c: &mut Criterion) { // generate for the most recent 10 updates let label = AkdLabel::from("User 1"); - let params = akd::HistoryParams::MostRecent(5); + let params = akd::HistoryParams::MostRecentInsecure(5); runtime .block_on(directory.key_history(&label, params)) .unwrap(); diff --git a/akd/src/directory.rs b/akd/src/directory.rs index ce54fc13..7f536878 100644 --- a/akd/src/directory.rs +++ b/akd/src/directory.rs @@ -461,8 +461,10 @@ where // apply filters specified by HistoryParams struct user_data = match params { HistoryParams::Complete => user_data, - HistoryParams::MostRecent(n) => user_data.into_iter().take(n).collect::>(), - HistoryParams::SinceEpoch(epoch) => { + HistoryParams::MostRecentInsecure(n) => { + user_data.into_iter().take(n).collect::>() + } + HistoryParams::SinceEpochInsecure(epoch) => { user_data = user_data .into_iter() .filter(|val| val.epoch >= epoch) @@ -861,10 +863,12 @@ where pub enum HistoryParams { /// Returns a complete history for a label Complete, - /// Returns up to the most recent N updates for a label - MostRecent(usize), - /// Returns all updates since a specified epoch (inclusive) - SinceEpoch(u64), + /// Returns up to the most recent N updates for a label. This is not secure, and + /// should not be used in a production environment. + MostRecentInsecure(usize), + /// Returns all updates since a specified epoch (inclusive). This is not secure, and + /// should not be used in a production environment. + SinceEpochInsecure(u64), } impl Default for HistoryParams { diff --git a/akd/src/lib.rs b/akd/src/lib.rs index c6eec37a..baf86b96 100644 --- a/akd/src/lib.rs +++ b/akd/src/lib.rs @@ -198,11 +198,14 @@ //! ``` //! //! ## History Proofs -//! As mentioned above, the security is defined by consistent views of the value for a key at any epoch. +//! As mentioned above, security is defined by consistent views of the value for a key at any epoch. //! To this end, a server running an AKD needs to provide a way to check the history of a key. Note that in this case, //! the server is trusted for validating that a particular client is authorized to run a history check on a particular key. -//! We can use [`Directory::key_history`] to prove the history of a key's values at a given epoch. The [HistoryParams] field -//! can be used to limit the history that we issue proofs for, but in this example we default to a complete history. +//! We can use [`Directory::key_history`] to prove the history of a key's values at a given epoch. +//! +//! The [HistoryParams] field can be used to limit the history that we issue proofs for, but in this +//! example we default to a complete history. For more information on the parameters, see the +//! [History Parameters](#history-parameters) section. //! ``` //! # use akd::storage::StorageManager; //! # use akd::storage::memory::AsyncInMemoryDatabase; @@ -422,6 +425,19 @@ //! ``` //! An application can set their own specific domain label to a custom string achieve domain separation from other applications. //! +//! ## History Parameters +//! +//! The [HistoryParams] enum can be used to limit the number of updates for a given entry that the server provides +//! to the client. The enum has the following options: +//! - [HistoryParams::Complete]: Includes a complete history of all updates to an entry. This is the default option. +//! - [HistoryParams::MostRecentInsecure]: Includes (at most) the most recent input number of updates for an entry. +//! - [HistoryParams::SinceEpochInsecure]: Includes all updates to an entry since a given epoch. +//! +//! Note that the "insecure" options are not recommended for use in production, as they do not provide a +//! complete history of updates, and lack inclusion proofs for earlier entries. These options should only be +//! used for testing purposes. +//! +//! //! ## Compilation Features //! //! This crate supports multiple compilation features: diff --git a/akd/src/tests.rs b/akd/src/tests.rs index 008bd9c4..b871ec50 100644 --- a/akd/src/tests.rs +++ b/akd/src/tests.rs @@ -567,7 +567,10 @@ async fn test_limited_key_history() -> Result<(), AkdError> { // "hello" was updated in epochs 1,2,3,5. Pull the latest item from the history (i.e. a lookup proof) let (history_proof, root_hash) = akd - .key_history(&AkdLabel::from("hello"), HistoryParams::MostRecent(1)) + .key_history( + &AkdLabel::from("hello"), + HistoryParams::MostRecentInsecure(1), + ) .await?; assert_eq!(1, history_proof.update_proofs.len()); assert_eq!(5, history_proof.update_proofs[0].epoch); @@ -584,7 +587,10 @@ async fn test_limited_key_history() -> Result<(), AkdError> { // Take the top 3 results, and check that we're getting the right epoch updates let (history_proof, root_hash) = akd - .key_history(&AkdLabel::from("hello"), HistoryParams::MostRecent(3)) + .key_history( + &AkdLabel::from("hello"), + HistoryParams::MostRecentInsecure(3), + ) .await?; assert_eq!(3, history_proof.update_proofs.len()); assert_eq!(5, history_proof.update_proofs[0].epoch); @@ -603,7 +609,10 @@ async fn test_limited_key_history() -> Result<(), AkdError> { // "hello" was updated in epochs 1,2,3,5. Pull the updates since epoch 3 (inclusive) let (history_proof, root_hash) = akd - .key_history(&AkdLabel::from("hello"), HistoryParams::SinceEpoch(3)) + .key_history( + &AkdLabel::from("hello"), + HistoryParams::SinceEpochInsecure(3), + ) .await?; assert_eq!(2, history_proof.update_proofs.len()); assert_eq!(5, history_proof.update_proofs[0].epoch);