add missing docs in crypto_digest*

4 files changed, 43 insertions, 5 deletions

diff --git a/src/lib/crypt_ops/crypto_digest.c b/src/lib/crypt_ops/crypto_digest.c
index ba226f8756..d14a40f321 100644
--- a/src/lib/crypt_ops/crypto_digest.c
+++ b/src/lib/crypt_ops/crypto_digest.c
@@ -150,6 +150,9 @@ struct crypto_xof_t {
    */
   EVP_MD_CTX *ctx;
 #else /* !defined(OPENSSL_HAS_SHAKE3_EVP) */
+  /**
+   * State of the Keccak sponge for the SHAKE-256 computation.
+   **/
   keccak_state s;
 #endif /* defined(OPENSSL_HAS_SHAKE3_EVP) */
 };
diff --git a/src/lib/crypt_ops/crypto_digest.h b/src/lib/crypt_ops/crypto_digest.h
index 5869db7800..fb819b12e7 100644
--- a/src/lib/crypt_ops/crypto_digest.h
+++ b/src/lib/crypt_ops/crypto_digest.h
@@ -38,6 +38,9 @@
 /** Length of hex encoding of SHA512 digest, not including final NUL. */
 #define HEX_DIGEST512_LEN 128
 
+/**
+ * An identifier for a cryptographic digest algorithm.
+ **/
 typedef enum {
   DIGEST_SHA1 = 0,
   DIGEST_SHA256 = 1,
@@ -45,16 +48,31 @@ typedef enum {
   DIGEST_SHA3_256 = 3,
   DIGEST_SHA3_512 = 4,
 } digest_algorithm_t;
+/** Number of digest algorithms that we know */
 #define  N_DIGEST_ALGORITHMS (DIGEST_SHA3_512+1)
+/** Number of digest algorithms to compute when computing "all the
+ * commonly used digests."
+ *
+ * (This is used in common_digests_t and related functions.)
+ */
 #define  N_COMMON_DIGEST_ALGORITHMS (DIGEST_SHA256+1)
 
+/**
+ * Bytes of storage needed to record the state of an in-progress SHA-1 digest.
+ *
+ * This is a deliberate overestimate.
+ **/
 #define DIGEST_CHECKPOINT_BYTES (SIZEOF_VOID_P + 512)
+
 /** Structure used to temporarily save the a digest object. Only implemented
  * for SHA1 digest for now. */
 typedef struct crypto_digest_checkpoint_t {
 #ifdef ENABLE_NSS
+  /** The number of bytes used in <b>mem</b>. */
   unsigned int bytes_used;
 #endif
+  /** A buffer to store the SHA1 state. Its contents are unspecified, and
+   * are managed by the underlying crypto library.*/
   uint8_t mem[DIGEST_CHECKPOINT_BYTES];
 } crypto_digest_checkpoint_t;
 
@@ -67,10 +85,19 @@ typedef struct crypto_digest_checkpoint_t {
  * once.
  **/
 typedef struct {
+  /** An array of digest outputs, one for each "common" digest algorithm. */
   char d[N_COMMON_DIGEST_ALGORITHMS][DIGEST256_LEN];
 } common_digests_t;
 
+/**
+ * State for computing a digest over a stream of data.
+ **/
 typedef struct crypto_digest_t crypto_digest_t;
+
+/**
+ * State for computing an "extendable-output function" (like SHAKE) over a
+ * stream of data, and/or streaming the output.
+ **/
 typedef struct crypto_xof_t crypto_xof_t;
 
 struct smartlist_t;
@@ -97,6 +124,9 @@ crypto_digest_t *crypto_digest_new(void);
 crypto_digest_t *crypto_digest256_new(digest_algorithm_t algorithm);
 crypto_digest_t *crypto_digest512_new(digest_algorithm_t algorithm);
 void crypto_digest_free_(crypto_digest_t *digest);
+/**
+ * Release all storage held in <b>d</b>, and set it to NULL.
+ **/
 #define crypto_digest_free(d) \
   FREE_AND_NULL(crypto_digest_t, crypto_digest_free_, (d))
 void crypto_digest_add_bytes(crypto_digest_t *digest, const char *data,
@@ -122,6 +152,9 @@ crypto_xof_t *crypto_xof_new(void);
 void crypto_xof_add_bytes(crypto_xof_t *xof, const uint8_t *data, size_t len);
 void crypto_xof_squeeze_bytes(crypto_xof_t *xof, uint8_t *out, size_t len);
 void crypto_xof_free_(crypto_xof_t *xof);
+/**
+ * Release all storage held in <b>xof</b>, and set it to NULL.
+ **/
 #define crypto_xof_free(xof) \
   FREE_AND_NULL(crypto_xof_t, crypto_xof_free_, (xof))
 void crypto_xof(uint8_t *output, size_t output_len,
diff --git a/src/lib/crypt_ops/crypto_digest_nss.c b/src/lib/crypt_ops/crypto_digest_nss.c
index b73f0736fd..54fb714436 100644
--- a/src/lib/crypt_ops/crypto_digest_nss.c
+++ b/src/lib/crypt_ops/crypto_digest_nss.c
@@ -44,7 +44,11 @@ digest_alg_to_nss_oid(digest_algorithm_t alg)
   }
 }
 
-/* Helper: get an unkeyed digest via pk11wrap */
+/** Helper: Compute an unkeyed digest of the <b>msg_len</b> bytes at
+ * <b>msg</b>, using the digest algorithm specified by <b>alg</b>.
+ * Store the result in the <b>len_out</b>-byte buffer at <b>digest</b>.
+ * Return the number of bytes written on success, and -1 on failure.
+ **/
 static int
 digest_nss_internal(SECOidTag alg,
                     char *digest, unsigned len_out,
@@ -557,4 +561,3 @@ crypto_hmac_sha256(char *hmac_out,
 
   tor_assert(ok);
 }
-
diff --git a/src/lib/crypt_ops/crypto_digest_openssl.c b/src/lib/crypt_ops/crypto_digest_openssl.c
index b0d8b6aee9..319714f868 100644
--- a/src/lib/crypt_ops/crypto_digest_openssl.c
+++ b/src/lib/crypt_ops/crypto_digest_openssl.c
@@ -147,9 +147,9 @@ crypto_digest_get_algorithm(crypto_digest_t *digest)
 static size_t
 crypto_digest_alloc_bytes(digest_algorithm_t alg)
 {
-  /* Helper: returns the number of bytes in the 'f' field of 'st' */
+  /** Helper: returns the number of bytes in the 'f' field of 'st' */
 #define STRUCT_FIELD_SIZE(st, f) (sizeof( ((st*)0)->f ))
-  /* Gives the length of crypto_digest_t through the end of the field 'd' */
+  /** Gives the length of crypto_digest_t through the end of the field 'd' */
 #define END_OF_FIELD(f) (offsetof(crypto_digest_t, f) + \
                          STRUCT_FIELD_SIZE(crypto_digest_t, f))
   switch (alg) {
@@ -519,4 +519,3 @@ crypto_hmac_sha256(char *hmac_out,
             (unsigned char*)hmac_out, NULL);
   tor_assert(rv);
 }
-