Update various documentation comments

This was originally done by René in a series of doc updates related to
using Breathe for our API reference. I (Jack) am still unconvinced of
adopting this for various reasons (build times, limited distro
support, apparently abandoned upstream, etc) but the documentation
comments themselves are certainly an improvement.

src/build-data/buildh.in

@@ -24,9 +24,18 @@
  * @{
  */
 
+/// The major version of the release
 #define BOTAN_VERSION_MAJOR %{version_major}
+/// The minor version of the release
 #define BOTAN_VERSION_MINOR %{version_minor}
+/// The patch version of the release
 #define BOTAN_VERSION_PATCH %{version_patch}
+
+/**
+ * Expands to an integer of the form YYYYMMDD if this is an official
+ * release, or 0 otherwise. For instance, 2.19.0, which was released
+ * on January 19, 2022, has a `BOTAN_VERSION_DATESTAMP` of 20220119.
+ */
 #define BOTAN_VERSION_DATESTAMP %{version_datestamp}
 
 %{if version_suffix}
@@ -36,8 +45,20 @@
 
 #define BOTAN_VERSION_RELEASE_TYPE "%{release_type}"
 
+/**
+ * A macro expanding to a string that is set to a revision identifier
+ * corresponding to the source, or "unknown" if this could not be
+ * determined. It is set for all official releases, and for builds that
+ * originated from within a git checkout.
+ */
 #define BOTAN_VERSION_VC_REVISION "%{version_vc_rev}"
 
+/**
+ * A macro expanding to a string that is set at build time using the
+ * `--distribution-info` option. It allows a packager of the library
+ * to specify any distribution-specific patches. If no value is given
+ * at build time, the value is the string "unspecified".
+ */
 #define BOTAN_DISTRIBUTION_INFO "%{distribution_info}"
 
 /**

src/lib/compression/compression.h

@@ -34,16 +34,26 @@ class BOTAN_PUBLIC_API(2, 0) Compression_Algorithm {
 
       /**
       * Begin compressing. Most compression algorithms offer a tunable
-      * time/compression tradeoff parameter generally represented by
-      * an integer in the range of 1 to 9.
+      * time/compression tradeoff parameter generally represented by an integer
+      * in the range of 1 to 9. Higher values typically imply better compression
+      * and more memory and/or CPU time consumed by the compression process.
       *
       * If 0 or a value out of range is provided, a compression algorithm
       * specific default is used.
+      *
+      * @param comp_level the desired level of compression (typically from 1 to 9)
       */
       virtual void start(size_t comp_level = 0) = 0;
 
       /**
       * Process some data.
+      *
+      * The leading @p offset bytes of @p buf are ignored and remain untouched;
+      * this can be useful for ignoring packet headers.  If @p flush is true,
+      * the compression state is flushed, allowing the decompressor to recover
+      * the entire message up to this point without having to see the rest of
+      * the compressed stream.
+      *
       * @param buf in/out parameter which will possibly be resized or swapped
       * @param offset an offset into blocks to begin processing
       * @param flush if true the compressor will be told to flush state
@@ -53,6 +63,10 @@ class BOTAN_PUBLIC_API(2, 0) Compression_Algorithm {
       /**
       * Finish compressing
       *
+      * The @p buf and @p offset parameters are treated as in update(). It is
+      * acceptable to call start() followed by finish() with the entire message,
+      * without any intervening call to update().
+      *
       * @param final_block in/out parameter
       * @param offset an offset into final_block to begin processing
       */
@@ -92,7 +106,10 @@ class BOTAN_PUBLIC_API(2, 0) Decompression_Algorithm {
 
       /**
       * Begin decompressing.
-      * Decompression does not support levels, as compression does.
+      *
+      * This initializes the decompression engine and must be done before
+      * calling update() or finish(). No level is provided here; the
+      * decompressor can accept input generated by any compression parameters.
       */
       virtual void start() = 0;
 
@@ -106,6 +123,12 @@ class BOTAN_PUBLIC_API(2, 0) Decompression_Algorithm {
       /**
       * Finish decompressing
       *
+      * Decompress the material in the in/out parameter @p buf. The leading
+      * @p offset bytes of @p buf are ignored and remain untouched; this can
+      * be useful for ignoring packet headers.
+      *
+      * This function may throw if the data seems to be invalid.
+      *
       * @param final_block in/out parameter
       * @param offset an offset into final_block to begin processing
       */

src/lib/mac/mac.h

@@ -53,7 +53,7 @@ class BOTAN_PUBLIC_API(2, 0) MessageAuthenticationCode : public Buffered_Computa
       * Prepare for processing a message under the specified nonce
       *
       * Most MACs neither require nor support a nonce; for these algorithms
-      * calling `start_msg` is optional and calling it with anything other than
+      * calling start() is optional and calling it with anything other than
       * an empty string is an error. One MAC which *requires* a per-message
       * nonce be specified is GMAC.
       *

src/lib/math/numbertheory/numthry.h

@@ -102,6 +102,11 @@ size_t BOTAN_PUBLIC_API(2, 0) low_zero_bits(const BigInt& x);
 
 /**
 * Check for primality
+*
+* This uses probabilistic algorithms - there is some non-zero (but very low)
+* probability that this function will return true even if *n* is actually
+* composite.
+*
 * @param n a positive integer to test for primality
 * @param rng a random number generator
 * @param prob chance of false positive is bounded by 1/2**prob

src/lib/modes/aead/aead.h

@@ -46,13 +46,13 @@ class BOTAN_PUBLIC_API(2, 0) AEAD_Mode : public Cipher_Mode {
                                                         std::string_view provider = "");
 
       /**
-      * Set associated data that is not included in the ciphertext but
-      * that should be authenticated. Must be called after set_key and
-      * before start.
+      * Set associated data that is not included in the ciphertext but that
+      * should be authenticated. Must be called after set_key() and before
+      * start().
       *
-      * Unless reset by another call, the associated data is kept
-      * between messages. Thus, if the AD does not change, calling
-      * once (after set_key) is the optimum.
+      * Unless reset by another call, the associated data is kept between
+      * messages. Thus, if the AD does not change, calling once (after
+      * set_key()) is the optimum.
       *
       * @param ad the associated data
       */
@@ -62,12 +62,12 @@ class BOTAN_PUBLIC_API(2, 0) AEAD_Mode : public Cipher_Mode {
 
       /**
       * Set associated data that is not included in the ciphertext but
-      * that should be authenticated. Must be called after set_key and
-      * before start.
+      * that should be authenticated. Must be called after set_key() and
+      * before start().
       *
       * Unless reset by another call, the associated data is kept
       * between messages. Thus, if the AD does not change, calling
-      * once (after set_key) is the optimum.
+      * once (after set_key()) is the optimum.
       *
       * Some AEADs (namely SIV) support multiple AD inputs. For
       * all other modes only nominal AD input 0 is supported; all
@@ -99,8 +99,8 @@ class BOTAN_PUBLIC_API(2, 0) AEAD_Mode : public Cipher_Mode {
 
       /**
       * Set associated data that is not included in the ciphertext but
-      * that should be authenticated. Must be called after set_key and
-      * before start.
+      * that should be authenticated. Must be called after set_key() and
+      * before start().
       *
       * See @ref set_associated_data().
       *
@@ -114,8 +114,8 @@ class BOTAN_PUBLIC_API(2, 0) AEAD_Mode : public Cipher_Mode {
 
       /**
       * Set associated data that is not included in the ciphertext but
-      * that should be authenticated. Must be called after set_key and
-      * before start.
+      * that should be authenticated. Must be called after set_key() and
+      * before start().
       *
       * See @ref set_associated_data().
       *

src/lib/modes/cipher_mode.h

@@ -84,6 +84,15 @@ class BOTAN_PUBLIC_API(2, 0) Cipher_Mode : public SymmetricAlgorithm {
    public:
       /**
       * Begin processing a message with a fresh nonce.
+      *
+      * @warning Typically one must not reuse the same nonce for more than one
+      *          message under the same key. For most cipher modes this would
+      *          mean total loss of security and/or authenticity guarantees.
+      *
+      * @note If reliably generating unique nonces is difficult in your
+      *       environment, use SIV which retains security even if nonces
+      *       are repeated.
+      *
       * @param nonce the per message nonce
       */
       void start(std::span<const uint8_t> nonce) { start_msg(nonce.data(), nonce.size()); }
@@ -125,7 +134,14 @@ class BOTAN_PUBLIC_API(2, 0) Cipher_Mode : public SymmetricAlgorithm {
       size_t process(uint8_t msg[], size_t msg_len) { return this->process_msg(msg, msg_len); }
 
       /**
-      * Process some data. Input must be in size update_granularity() uint8_t blocks.
+      * Process some data. Input must be in size update_granularity() uint8_t
+      * blocks. The @p buffer is an in/out parameter and may be resized. In
+      * particular, some modes require that all input be consumed before any
+      * output is produced; with these modes, @p buffer will be returned empty.
+      *
+      * The first @p offset bytes of @p buffer will be ignored (this allows in
+      * place processing of a buffer that contains an initial plaintext header).
+      *
       * @param buffer in/out parameter which will possibly be resized
       * @param offset an offset into blocks to begin processing
       */
@@ -137,7 +153,25 @@ class BOTAN_PUBLIC_API(2, 0) Cipher_Mode : public SymmetricAlgorithm {
       }
 
       /**
-      * Complete processing of a message.
+      * Complete procession of a message with a final input of @p buffer, which
+      * is treated the same as with update(). If you have the entire message in
+      * hand, calling finish() without ever calling update() is both efficient
+      * and convenient.
+      *
+      * When using an AEAD_Mode, if the supplied authentication tag does not
+      * validate, this will throw an instance of Invalid_Authentication_Tag.
+      *
+      * If this occurs, all plaintext previously output via calls to update must
+      * be destroyed and not used in any way that an attacker could observe the
+      * effects of. This could be anything from echoing the plaintext back
+      * (perhaps in an error message), or by making an external RPC whose
+      * destination or contents depend on the plaintext. The only thing you can
+      * do is buffer it, and in the event of an invalid tag, erase the
+      * previously decrypted content from memory.
+      *
+      * One simple way to assure this could never happen is to never call
+      * update, and instead always marshal the entire message into a single
+      * buffer and call finish on it when decrypting.
       *
       * @param final_block in/out parameter which must be at least
       *        minimum_final_size() bytes, and will be set to any final output
@@ -172,6 +206,10 @@ class BOTAN_PUBLIC_API(2, 0) Cipher_Mode : public SymmetricAlgorithm {
       virtual size_t output_length(size_t input_length) const = 0;
 
       /**
+      * The :cpp:class:`Cipher_Mode` interface requires message processing in
+      * multiples of the block size. This returns size of required blocks to
+      * update. If the mode implementation does not require buffering it will
+      * return 1.
       * @return size of required blocks to update
       */
       virtual size_t update_granularity() const = 0;
@@ -180,7 +218,7 @@ class BOTAN_PUBLIC_API(2, 0) Cipher_Mode : public SymmetricAlgorithm {
       * Return an ideal granularity. This will be a multiple of the result of
       * update_granularity but may be larger. If so it indicates that better
       * performance may be achieved by providing buffers that are at least that
-      * size.
+      * size (due to SIMD execution, etc).
       */
       virtual size_t ideal_granularity() const = 0;
 
@@ -217,8 +255,11 @@ class BOTAN_PUBLIC_API(2, 0) Cipher_Mode : public SymmetricAlgorithm {
       virtual void reset() = 0;
 
       /**
+      * Return the length in bytes of the authentication tag this algorithm
+      * generates. If the mode is not authenticated, this will return 0.
+      *
       * @return true iff this mode provides authentication as well as
-      * confidentiality.
+      *         confidentiality.
       */
       bool authenticated() const { return this->tag_size() > 0; }
 

src/lib/passhash/argon2fmt/argon2fmt.h

@@ -14,6 +14,10 @@ namespace Botan {
 
 class RandomNumberGenerator;
 
+/**
+* Generate an Argon2 hash of the specified @p password. The @p y parameter
+* specifies the variant: 0 for Argon2d, 1 for Argon2i, and 2 for Argon2id.
+*/
 std::string BOTAN_PUBLIC_API(2, 11) argon2_generate_pwhash(const char* password,
                                                            size_t password_len,
                                                            RandomNumberGenerator& rng,
@@ -26,6 +30,11 @@ std::string BOTAN_PUBLIC_API(2, 11) argon2_generate_pwhash(const char* password,
 
 /**
 * Check a previously created password hash
+*
+* Verify an Argon2 password @p hash against the provided @p password. Returns
+* false if the input hash seems malformed or if the computed hash does not
+* match.
+*
 * @param password the password to check against
 * @param password_len the length of password
 * @param hash the stored hash to check against

src/lib/passhash/bcrypt/bcrypt.h

@@ -18,6 +18,37 @@ class RandomNumberGenerator;
 /**
 * Create a password hash using Bcrypt
 *
+* Takes the @p password to hash, a @p rng, and a @p work_factor. The resulting
+* password hash is returned as a string.
+*
+* Higher work factors increase the amount of time the algorithm runs, increasing
+* the cost of cracking attempts. The increase is exponential, so a work factor
+* of 12 takes roughly twice as long as work factor 11. The default work factor
+* was set to 10 up until the 2.8.0 release.
+*
+* It is recommended to set the work factor as high as your system can tolerate
+* (from a performance and latency perspective) since higher work factors greatly
+* improve the security against GPU-based attacks.  For example, for protecting
+* high value administrator passwords, consider using work factor 15 or 16; at
+* these work factors each bcrypt computation takes several seconds. Since admin
+* logins will be relatively uncommon, it might be acceptable for each login
+* attempt to take some time. As of 2018, a good password cracking rig (with 8
+* NVIDIA 1080 cards) can attempt about 1 billion bcrypt computations per month
+* for work factor 13. For work factor 12, it can do twice as many.  For work
+* factor 15, it can do only one quarter as many attempts.
+*
+* Due to bugs affecting various implementations of bcrypt, several different
+* variants of the algorithm are defined. As of 2.7.0 Botan supports generating
+* (or checking) the 2a, 2b, and 2y variants.  Since Botan has never been
+* affected by any of the bugs which necessitated these version upgrades, all
+* three versions are identical beyond the version identifier. Which variant to
+* use is controlled by the @p version argument.
+*
+* The bcrypt @p work_factor must be at least 4 (though at this work factor
+* bcrypt is not very secure). The bcrypt format allows up to 31, but Botan
+* currently rejects all work factors greater than 18 since even that work factor
+* requires roughly 15 seconds of computation on a fast machine.
+*
 * @warning The password is truncated at at most 72 characters; characters after
 *          that do not have any effect on the resulting hash. To support longer
 *          passwords, consider pre-hashing the password, for example by using
@@ -38,6 +69,10 @@ std::string BOTAN_PUBLIC_API(2, 0) generate_bcrypt(std::string_view password,
 
 /**
 * Check a previously created password hash
+*
+* Takes a @p password and a bcrypt @p hash and returns true if the password is
+* the same as the one that was used to generate the bcrypt hash.
+*
 * @param password the password to check against
 * @param hash the stored hash to check against
 */

src/lib/passhash/passhash9/passhash9.h

@@ -17,15 +17,25 @@ class RandomNumberGenerator;
 
 /**
 * Create a password hash using PBKDF2
+*
+* Functions much like generate_bcrypt(). The last parameter,
+* @p alg_id, specifies which PRF to use. Currently defined values are:
+*
+* - 0: HMAC(SHA-1)
+* - 1: HMAC(SHA-256)
+* - 2: CMAC(Blowfish)
+* - 3: HMAC(SHA-384)
+* - 4: HMAC(SHA-512)
+*
+* The @p work_factor must be greater than zero and less than 512. This performs
+* 10000 * @p work_factor PBKDF2 iterations, using 96 bits of salt taken from
+* @p rng. Using work factor of 10 or more is recommended.
+*
 * @param password the password
 * @param rng a random number generator
 * @param work_factor how much work to do to slow down guessing attacks
-* @param alg_id specifies which PRF to use with PBKDF2
-*        0 is HMAC(SHA-1)
-*        1 is HMAC(SHA-256)
-*        2 is CMAC(Blowfish)
-*        3 is HMAC(SHA-384)
-*        4 is HMAC(SHA-512)
+* @param alg_id specifies which PRF to use with PBKDF2 0 is HMAC(SHA-1) 1 is
+*        HMAC(SHA-256) 2 is CMAC(Blowfish) 3 is HMAC(SHA-384) 4 is HMAC(SHA-512)
 *        all other values are currently undefined
 */
 std::string BOTAN_PUBLIC_API(2, 0) generate_passhash9(std::string_view password,