From eb2d57a35a0df1c4b81c96a71bef60c9e2f63e64 Mon Sep 17 00:00:00 2001
From: pmendes <pmendes@cloudflare.com>
Date: Tue, 1 Oct 2024 16:45:02 +0100
Subject: [PATCH] Improve dapf documentation

---
 crates/dapf/README.md   | 59 +++++++++++++++++++++++++++++++++++++++++
 crates/dapf/src/main.rs | 28 ++++++++++++++++---
 2 files changed, 83 insertions(+), 4 deletions(-)
 create mode 100644 crates/dapf/README.md

diff --git a/crates/dapf/README.md b/crates/dapf/README.md
new file mode 100644
index 00000000..eb6feab6
--- /dev/null
+++ b/crates/dapf/README.md
@@ -0,0 +1,59 @@
+# dapf (DAP functions)
+
+This binary provides various functions that can be called to interact with DAP
+deployments.
+
+It several subcommands and their function can be consulted with the built in
+help pages the CLI provides.
+
+
+## Examples
+
+Here are some examples of common functionality of dapf. To avoid installing the
+tool replace all instances of `dapf` with `cargo run --bin dapf`.
+
+### Generate an hpke config
+
+With the default algorithm
+```
+dapf hpke generate
+```
+
+With a specific algorithm
+```
+dapf hpke generate x25519_hkdf_sha256
+```
+
+This will output the config twice
+```
+{
+  "config": {
+    "id": 131,
+    "kem_id": "x25519_hkdf_sha256",
+    "kdf_id": "hkdf_sha256",
+    "aead_id": "aes128_gcm",
+    "public_key": "3ccc3ada22dc0b3367d031ea4b02876a77a59ef32b5a1c06109552a51a739a13"
+  },
+  "private_key": "PRIVATE_KEY"
+}
+hpke config prio encoded and base64 encoded: gwAgAAEAAQAgPMw62iLcCzNn0DHqSwKHanelnvMrWhwGEJVSpRpzmhM
+```
+
+First as JSON and second as a prio encoded + base64 encoded string which can be
+used when issuing requests to `internal/test/add_task`
+
+
+### Decoding responses from aggregators
+
+
+#### Decoding aggregate shares
+Once you've collected from the leader you may want to see what the result of the
+aggregation was, for that you can use the `decode` subcommand
+
+```sh
+dapf decode ./aggregate_share collection \
+    --vdaf-config '{"prio3": { "sum": { "bits": 8 } } }' \
+    --task-id "THE_TASK_ID" \
+    --hpke-config-path ./hpke-config.json \
+    --report-count 2
+```
diff --git a/crates/dapf/src/main.rs b/crates/dapf/src/main.rs
index ecda4596..1579c785 100644
--- a/crates/dapf/src/main.rs
+++ b/crates/dapf/src/main.rs
@@ -3,6 +3,7 @@
 
 use anyhow::{anyhow, Context, Result};
 use clap::{builder::PossibleValue, Args, Parser, Subcommand, ValueEnum};
+use core::fmt;
 use dapf::{
     acceptance::{load_testing, LoadControlParams, LoadControlStride, TestOptions},
     deduce_dap_version_from_url, response_to_anyhow, HttpClient,
@@ -251,7 +252,13 @@ enum HpkeAction {
         dap_version: DapVersion,
     },
     /// Generate an hpke receiver config.
-    GenerateReceiverConfig { kem_alg: KemAlg },
+    ///
+    /// This command outputs to stdout the hpke config in json and to stderr the config encoded
+    /// first by prio and then in base64. This version can later be used when TODO
+    Generate {
+        #[arg(default_value_t)]
+        kem_alg: KemAlg,
+    },
     /// Rotate the HPKE config advertised by the Aggregator.
     RotateReceiverConfig {
         #[arg(short = 'c', long)]
@@ -260,6 +267,7 @@ enum HpkeAction {
         wrangler_env: Option<String>,
         #[arg(default_value_t, long)]
         dap_version: DapVersion,
+        #[arg(default_value_t)]
         kem_alg: KemAlg,
     },
 }
@@ -269,7 +277,7 @@ enum TestAction {
     /// Add an hpke config to a test-utils enabled `daphne-server`.
     AddHpkeConfig {
         aggregator_url: Url,
-        #[arg(short, long, default_value = "x25519_hkdf_sha256")]
+        #[arg(short, long, default_value_t)]
         kem_alg: KemAlg,
     },
     /// Clear all storage of an aggregator.
@@ -385,6 +393,18 @@ impl LoadControlParamsCli {
 #[derive(Clone, Debug)]
 struct KemAlg(HpkeKemId);
 
+impl Default for KemAlg {
+    fn default() -> Self {
+        Self(HpkeKemId::X25519HkdfSha256)
+    }
+}
+
+impl fmt::Display for KemAlg {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.to_possible_value().unwrap().get_name())
+    }
+}
+
 impl ValueEnum for KemAlg {
     fn value_variants<'a>() -> &'a [Self] {
         &[
@@ -783,12 +803,12 @@ async fn handle_hpke_actions(hpke: HpkeAction, http_client: HttpClient) -> anyho
             println!("{}", serde_json::to_string_pretty(&config)?);
             Ok(())
         }
-        HpkeAction::GenerateReceiverConfig { kem_alg } => {
+        HpkeAction::Generate { kem_alg } => {
             let receiver_config = HpkeReceiverConfig::gen(rng.gen(), kem_alg.0)
                 .with_context(|| "failed to generate HPKE receiver config")?;
             println!(
                 "{}",
-                serde_json::to_string(&receiver_config)
+                serde_json::to_string_pretty(&receiver_config)
                     .with_context(|| "failed to JSON-encode the HPKE receiver config")?
             );
             eprintln!(