From: Thomas Pornin <pornin@bolet.org>
Date: Tue, 14 Aug 2018 20:41:04 +0000 (+0200)
Subject: Some documentation fixes.
X-Git-Tag: v0.6^0
X-Git-Url: https://bearssl.org/gitweb//home/git/?a=commitdiff_plain;h=8ef7680081c61b486622f2d983c0d3d21e83caad;p=BearSSL

Some documentation fixes.
---

diff --git a/Doxyfile b/Doxyfile
index df5bc95..088682d 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -771,7 +771,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = inc/bearssl.h inc/bearssl_aead.h inc/bearssl_block.h inc/bearssl_ec.h inc/bearssl_hash.h inc/bearssl_hmac.h inc/bearssl_pem.h inc/bearssl_prf.h inc/bearssl_rand.h inc/bearssl_rsa.h inc/bearssl_ssl.h inc/bearssl_x509.h
+INPUT                  = inc/bearssl.h inc/bearssl_aead.h inc/bearssl_block.h inc/bearssl_ec.h inc/bearssl_hash.h inc/bearssl_hmac.h inc/bearssl_kdf.h inc/bearssl_pem.h inc/bearssl_prf.h inc/bearssl_rand.h inc/bearssl_rsa.h inc/bearssl_ssl.h inc/bearssl_x509.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/README.txt b/README.txt
index 0e318aa..0cb5288 100644
--- a/README.txt
+++ b/README.txt
@@ -5,15 +5,16 @@ The most up-to-date documentation is supposed to be available on the
 
 # Disclaimer
 
-BearSSL is for now considered alpha-level software. This means that it
-probably still has some bugs, possibly very serious ones (e.g. buffer
-overflows -- one of the perks of using C as programming language). It
-still lacks some functionalities. The API will probably change and may
-break both source and binary compatibility.
-
-In other words, you would be quite mad to use it for any production
-purpose. Right now, this is for learning, testing and possibly
-contributing.
+BearSSL is considered beta-level software. Most planned functionalities
+are implemented; new evolution may still break both source and binary
+compatibility.
+
+Using BearSSL for production purposes would be a relatively bold but not
+utterly crazy move. BearSSL is free, open-source software, provided
+without any guarantee of fitness or reliability. That being said, it
+appears to behave properly, and only minor issues have been found (and
+fixed) so far. You are encourage to inspect its API and code for
+learning, testing and possibly contributing.
 
 The usage license is explicited in the `LICENSE.txt` file. This is the
 "MIT license". It can be summarised in the following way:
diff --git a/inc/bearssl_rand.h b/inc/bearssl_rand.h
index e22d5d4..0a9f544 100644
--- a/inc/bearssl_rand.h
+++ b/inc/bearssl_rand.h
@@ -29,6 +29,7 @@
 #include <stdint.h>
 
 #include "bearssl_block.h"
+#include "bearssl_hash.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -353,10 +354,10 @@ extern const br_prng_class br_aesctr_drbg_vtable;
  *
  * The `aesctr` parameter defines the underlying AES/CTR implementation.
  *
- * \param ctx            HMAC_DRBG context to initialise.
- * \param digest_class   vtable for the underlying hash function.
- * \param seed           initial seed (can be `NULL` if `seed_len` is zero).
- * \param seed_len       initial seed length (in bytes).
+ * \param ctx        AESCTR_DRBG context to initialise.
+ * \param aesctr     vtable for the AES/CTR implementation.
+ * \param seed       initial seed (can be `NULL` if `seed_len` is zero).
+ * \param seed_len   initial seed length (in bytes).
  */
 void br_aesctr_drbg_init(br_aesctr_drbg_context *ctx,
 	const br_block_ctr_class *aesctr, const void *seed, size_t seed_len);
diff --git a/inc/bearssl_rsa.h b/inc/bearssl_rsa.h
index f3825d1..0eaf2a2 100644
--- a/inc/bearssl_rsa.h
+++ b/inc/bearssl_rsa.h
@@ -1315,8 +1315,9 @@ br_rsa_compute_pubexp br_rsa_compute_pubexp_get_default(void);
  * Not all error conditions are detected when `d` is `NULL`; therefore, the
  * returned value shall be checked also when actually producing the value.
  *
- * \param d    destination buffer (or `NULL`).
- * \param sk   RSA private key.
+ * \param d        destination buffer (or `NULL`).
+ * \param sk       RSA private key.
+ * \param pubexp   the public exponent.
  * \return  the private exponent length (in bytes), or 0.
  */
 typedef size_t (*br_rsa_compute_privexp)(void *d,
@@ -1327,8 +1328,9 @@ typedef size_t (*br_rsa_compute_privexp)(void *d,
  *
  * \see br_rsa_compute_privexp
  *
- * \param d    destination buffer (or `NULL`).
- * \param sk   RSA private key.
+ * \param d        destination buffer (or `NULL`).
+ * \param sk       RSA private key.
+ * \param pubexp   the public exponent.
  * \return  the private exponent length (in bytes), or 0.
  */
 size_t br_rsa_i15_compute_privexp(void *d,
@@ -1339,8 +1341,9 @@ size_t br_rsa_i15_compute_privexp(void *d,
  *
  * \see br_rsa_compute_privexp
  *
- * \param d    destination buffer (or `NULL`).
- * \param sk   RSA private key.
+ * \param d        destination buffer (or `NULL`).
+ * \param sk       RSA private key.
+ * \param pubexp   the public exponent.
  * \return  the private exponent length (in bytes), or 0.
  */
 size_t br_rsa_i31_compute_privexp(void *d,