From bac71a24e05f064fc3de93b6c724afad276d19cc Mon Sep 17 00:00:00 2001 From: David Cook Date: Tue, 28 Nov 2023 15:06:32 -0600 Subject: [PATCH] Flesh out documentation (#42) --- README.md | 6 +- .../main/java/org/divviup/android/Client.java | 82 +++++++++++++++++++ .../main/java/org/divviup/android/TaskId.java | 13 ++- .../org/divviup/android/package-info.java | 9 ++ 4 files changed, 104 insertions(+), 6 deletions(-) create mode 100644 divviup/src/main/java/org/divviup/android/package-info.java diff --git a/README.md b/README.md index d3f392d..9476bde 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ An Android client library for the [Distributed Aggregation Protocol][DAP]. The following versions of the DAP protocol are supported by different branches and releases. -| Package version | Git branch | Protocol version | Conformant? | Status | -|-----------------|------------|------------------|-------------|--------| -| 0.1.0 (forthcoming) | `main` | [`draft-ietf-ppm-dap-07`][draft-07] | Yes | Supported | +| Package version | Git branch | Protocol version | Conformant? | Status | +|---------------------|------------|-------------------------------------|-------------|-----------| +| 0.1.0 (forthcoming) | `main` | [`draft-ietf-ppm-dap-07`][draft-07] | Yes | Supported | [draft-07]: https://datatracker.ietf.org/doc/draft-ietf-ppm-dap/07/ diff --git a/divviup/src/main/java/org/divviup/android/Client.java b/divviup/src/main/java/org/divviup/android/Client.java index 8183dce..f2e5d78 100644 --- a/divviup/src/main/java/org/divviup/android/Client.java +++ b/divviup/src/main/java/org/divviup/android/Client.java @@ -10,6 +10,12 @@ import java.net.URL; import java.util.Arrays; +/** + * A client that can submit reports to a particular DAP task. Objects of this class are immutable, + * and thus thread-safe. + * + * @param the type of measurements (determined by the VDAF) + */ public class Client { private static final String HPKE_CONFIG_LIST_CONTENT_TYPE = "application/dap-hpke-config-list"; private static final String REPORT_CONTENT_TYPE = "application/dap-report"; @@ -50,6 +56,19 @@ private Client( this.reportPreparer = reportPreparer; } + /** + * Constructs a client for a DAP task using the Prio3Count VDAF. Measurements are + * Booleans. The aggregate result is the number of true measurements. + * + * @param leaderEndpoint the URI of the leader aggregator's HTTPS endpoint + * @param helperEndpoint the URI of the helper aggregator's HTTPS endpoint + * @param taskId the {@link TaskId} of the DAP task + * @param timePrecisionSeconds the time precision of the DAP task, in seconds + * @return a client for the configured DAP task + * @throws IllegalArgumentException if the scheme of leaderEndpoint or helperEndpoint is not + * http or https, or if timePrecisionSeconds is not a positive + * number + */ public static Client createPrio3Count( URI leaderEndpoint, URI helperEndpoint, @@ -65,6 +84,22 @@ public static Client createPrio3Count( ); } + /** + * Constructs a client for a DAP task using the Prio3Sum VDAF. Measurements are Long + * integers. Valid measurements must be greater than or equal to zero, and less than + * 2 ^ bits. The aggregate result is the sum of all measurements. + * + * @param leaderEndpoint the URI of the leader aggregator's HTTPS endpoint + * @param helperEndpoint the URI of the helper aggregator's HTTPS endpoint + * @param taskId the {@link TaskId} of the DAP task + * @param timePrecisionSeconds the time precision of the DAP task, in seconds + * @param bits the bit width of measurements. This is a parameter of the + * Prio3Sum VDAF. + * @return a client for the configured DAP task + * @throws IllegalArgumentException if the scheme of leaderEndpoint or helperEndpoint is not + * http or https, or if timePrecisionSeconds is not a positive + * number + */ public static Client createPrio3Sum( URI leaderEndpoint, URI helperEndpoint, @@ -81,6 +116,26 @@ public static Client createPrio3Sum( ); } + /** + * Constructs a client for a DAP task using the Prio3SumVec VDAF. Measurements are vectors of + * integers, as a long[] array of the given length. Valid measurements must have + * every integer be greater than or equal to zero, and less than 2 ^ bits. The + * aggregate result is the element-wise sum of all measurements. + * + * @param leaderEndpoint the URI of the leader aggregator's HTTPS endpoint + * @param helperEndpoint the URI of the helper aggregator's HTTPS endpoint + * @param taskId the {@link TaskId} of the DAP task + * @param timePrecisionSeconds the time precision of the DAP task, in seconds + * @param length the length of measurement vectors. This is a parameter of + * the Prio3SumVec VDAF. + * @param bits the bit width of each element of the measurement vector. + * This is a parameter of the Prio3SumVec VDAF. + * @param chunkLength the chunk length internally used by the Prio3SumVec VDAF + * @return a client for the configured DAP task + * @throws IllegalArgumentException if the scheme of leaderEndpoint or helperEndpoint is not + * http or https, or if timePrecisionSeconds is not a positive + * number + */ public static Client createPrio3SumVec( URI leaderEndpoint, URI helperEndpoint, @@ -99,6 +154,24 @@ public static Client createPrio3SumVec( ); } + /** + * Constructs a client for a DAP task using the Prio3Histogram VDAF. Measurements are bucket + * indexes, as Long integers. Valid measurements must be greater than or equal to + * zero, and less than the length parameter. The aggregate result counts how many + * times each bucket index appeared in a measurement. + * + * @param leaderEndpoint the URI of the leader aggregator's HTTPS endpoint + * @param helperEndpoint the URI of the helper aggregator's HTTPS endpoint + * @param taskId the {@link TaskId} of the DAP task + * @param timePrecisionSeconds the time precision of the DAP task, in seconds + * @param length the total number of histogram buckets. This is a parameter + * of the Prio3Histogram VDAF. + * @param chunkLength the chunk length internally used by the Prio3Histogram VDAF + * @return a client for the configured DAP task + * @throws IllegalArgumentException if the scheme of leaderEndpoint or helperEndpoint is not + * http or https, or if timePrecisionSeconds is not a positive + * number + */ public static Client createPrio3Histogram( URI leaderEndpoint, URI helperEndpoint, @@ -116,6 +189,15 @@ public static Client createPrio3Histogram( ); } + /** + * Encodes a measurement into a DAP report, and submits it. This must not be called from the UI + * thread. + * + * @param measurement the measurement to be aggregated + * @throws IOException if requests to either aggregator fail + * @throws IllegalArgumentException if the measurement is of the wrong type + * @throws RuntimeException if there is an internal error while preparing the report + */ public void sendMeasurement(M measurement) throws IOException { HpkeConfigList leaderConfigList = this.fetchHPKEConfigList(this.leaderEndpoint, this.taskId); HpkeConfigList helperConfigList = this.fetchHPKEConfigList(this.helperEndpoint, this.taskId); diff --git a/divviup/src/main/java/org/divviup/android/TaskId.java b/divviup/src/main/java/org/divviup/android/TaskId.java index 07330ab..715cd14 100644 --- a/divviup/src/main/java/org/divviup/android/TaskId.java +++ b/divviup/src/main/java/org/divviup/android/TaskId.java @@ -2,6 +2,11 @@ import android.util.Base64; +/** + * A DAP task identifier. This is the unique identifier that clients, aggregators, and collectors + * use to distinguish between different kinds of measurements, and associate reports with a task. + * Objects of this class are immutable. + */ public class TaskId { private final byte[] bytes; @@ -13,7 +18,7 @@ private TaskId(byte[] bytes) { } /** - * Encodes a task ID into its textual representation. + * Encodes this task ID into its textual representation. * * @return the task ID in un-padded base64url form */ @@ -27,8 +32,10 @@ public String encodeToString() { /** * Parses a task ID from its textual representation, as seen in DAP URLs. * - * @param input the task ID in un-padded base64url form - * @return the task ID + * @param input the task ID in un-padded base64url form + * @return the task ID + * @throws IllegalArgumentException if the input is not a valid un-padded base64url value, or if + * it does not decode to 32 bytes */ public static TaskId parse(String input) { byte[] bytes = Base64.decode( diff --git a/divviup/src/main/java/org/divviup/android/package-info.java b/divviup/src/main/java/org/divviup/android/package-info.java new file mode 100644 index 0000000..2cc22c3 --- /dev/null +++ b/divviup/src/main/java/org/divviup/android/package-info.java @@ -0,0 +1,9 @@ +/** + * An Android client library for the Distributed + * Aggregation Protocol. + *

+ * This library is developed and maintained by Divvi Up, a + * project of the Internet Security Research Group. + */ +package org.divviup.android;