Updated doxygen documentation in header files and HTML pages

doxygen/input/doc_encdec.h

@@ -5,33 +5,47 @@
 
 /**
  * @addtogroup encdec_module Encryption/decryption module
- * 
- * The Encryption/decryption module provides encryption/decryption functions. 
- * One can differtiate between symmetric and asymetric algorithms; the 
- * symmetric ones are mostly used for message confidentiality and the asymmetric 
- * ones for key exchange and message integrity.
- * Some symmetric algorithms provide different block cipher modes, mainly 
- * Electronic Code Book (ECB) which is used for short (64-bit) messages and 
- * Cipher Block Chaining (CBC) which provides the structure needed for longer 
- * messages. In addition the Cipher Feedback Mode (CFB-128) stream cipher mode
- * is implemented for specific algorithms.
  *
- * Sometimes the same functions are used for encryption and decryption.
+ * The Encryption/decryption module provides encryption/decryption functions.
+ * One can differentiate between symmetric and asymmetric algorithms; the
+ * symmetric ones are mostly used for message confidentiality and the asymmetric
+ * ones for key exchange and message integrity.
+ * Some symmetric algorithms provide different block cipher modes, mainly
+ * Electronic Code Book (ECB) which is used for short (64-bit) messages and
+ * Cipher Block Chaining (CBC) which provides the structure needed for longer
+ * messages. In addition the Cipher Feedback Mode (CFB-128) stream cipher mode,
+ * Counter mode (CTR) and Galois Counter Mode (GCM) are implemented for
+ * specific algorithms.
+ *
+ * All symmetric encryption algorithms are accessible via the generic cipher layer
+ * (see \c cipher_init_ctx()).
+ *
+ * The asymmetric encryptrion algorithms are accessible via the generic public
+ * key layer (see \c pk_init()).
+ *
  * The following algorithms are provided:
  * - Symmetric:
- *   - AES (see \c aes_crypt_ecb(), \c aes_crypt_cbc() and \c aes_crypt_cfb128()).
+ *   - AES (see \c aes_crypt_ecb(), \c aes_crypt_cbc(), \c aes_crypt_cfb128() and
+ *     \c aes_crypt_ctr()).
  *   - ARCFOUR (see \c arc4_crypt()).
- *   - Camellia (see \c camellia_crypt_ecb(), \c camellia_crypt_cbc() and \c camellia_crypt_cfb128()).
- *   - DES/3DES (see \c des_crypt_ecb(), \c des_crypt_cbc(), \c des3_crypt_ecb() 
+ *   - Blowfish / BF (see \c blowfish_crypt_ecb(), \c blowfish_crypt_cbc(),
+ *     \c blowfish_crypt_cfb64() and \c blowfish_crypt_ctr())
+ *   - Camellia (see \c camellia_crypt_ecb(), \c camellia_crypt_cbc(),
+ *     \c camellia_crypt_cfb128() and \c camellia_crypt_ctr()).
+ *   - DES/3DES (see \c des_crypt_ecb(), \c des_crypt_cbc(), \c des3_crypt_ecb()
  *     and \c des3_crypt_cbc()).
  *   - XTEA (see \c xtea_crypt_ecb()).
  * - Asymmetric:
- *   - Diffie-Hellman-Merkle (see \c dhm_read_public(), \c dhm_make_public() 
+ *   - Diffie-Hellman-Merkle (see \c dhm_read_public(), \c dhm_make_public()
  *     and \c dhm_calc_secret()).
  *   - RSA (see \c rsa_public() and \c rsa_private()).
+ *   - Elliptic Curves over GF(p) (see \c ecp_point_init()).
+ *   - Elliptic Curve Digital Signature Algorithm (ECDSA) (see \c ecdsa_init()).
+ *   - Elliptic Curve Diffie Hellman (ECDH) (see \c ecdh_init()).
  *
- * This module provides encryption/decryption which can be used to provide 
+ * This module provides encryption/decryption which can be used to provide
  * secrecy.
- * It also provides asymmetric key functions which can be used for 
- * confidentiality, integrity, authentication and non-repudiation. 
+ *
+ * It also provides asymmetric key functions which can be used for
+ * confidentiality, integrity, authentication and non-repudiation.
  */

doxygen/input/doc_hashing.h

@@ -5,16 +5,20 @@
 
 /**
  * @addtogroup hashing_module Hashing module
- * 
+ *
  * The Hashing module provides one-way hashing functions. Such functions can be
- * used for creating a hash message authentication code (HMAC) when sending a 
+ * used for creating a hash message authentication code (HMAC) when sending a
  * message. Such a HMAC can be used in combination with a private key
- * for authentication, which is a message integrity control. 
+ * for authentication, which is a message integrity control.
+ *
+ * All hash algorithms can be accessed via the generic MD layer (see
+ * \c md_init_ctx())
+ *
  * The following hashing-algorithms are provided:
- * - MD2, MD4, MD5 128-bit one-way hash functions by Ron Rivest (see 
+ * - MD2, MD4, MD5 128-bit one-way hash functions by Ron Rivest (see
  *   \c md2_hmac(), \c md4_hmac() and \c md5_hmac()).
- * - SHA-1, SHA-256, SHA-384/512 160-bit or more one-way hash functions by 
- *   NIST and NSA (see\c sha1_hmac(), \c sha2_hmac() and \c sha4_hmac()).
+ * - SHA-1, SHA-256, SHA-384/512 160-bit or more one-way hash functions by
+ *   NIST and NSA (see\c sha1_hmac(), \c sha256_hmac() and \c sha512_hmac()).
  *
  * This module provides one-way hashing which can be used for authentication.
  */

doxygen/input/doc_mainpage.h

@@ -5,23 +5,22 @@
 
 /**
  * @mainpage PolarSSL v1.2.6 source code documentation
- * 
+ *
  * This documentation describes the internal structure of PolarSSL.  It was
  * automatically generated from specially formatted comment blocks in
  * PolarSSL's source code using Doxygen.  (See
  * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen)
- * 
- * PolarSSL has a simple setup: it provides the ingredients for an SSL/TLS 
- * implementation. These ingredients are listed as modules in the 
- * \ref mainpage_modules "Modules section". This "Modules section" introduces 
- * the high-level module concepts used throughout this documentation.\n 
+ *
+ * PolarSSL has a simple setup: it provides the ingredients for an SSL/TLS
+ * implementation. These ingredients are listed as modules in the
+ * \ref mainpage_modules "Modules section". This "Modules section" introduces
+ * the high-level module concepts used throughout this documentation.\n
  * Some examples of PolarSSL usage can be found in the \ref mainpage_examples
  * "Examples section".
- * 
- * 
+ *
  * @section mainpage_modules Modules
- * 
- * PolarSSL supports SSLv3 up to TLSv1.2 communication by providing the 
+ *
+ * PolarSSL supports SSLv3 up to TLSv1.2 communication by providing the
  * following:
  * - TCP/IP communication functions: listen, connect, accept, read/write.
  * - SSL/TLS communication functions: init, handshake, read/write.
@@ -30,19 +29,19 @@
  * - Hashing
  * - Encryption/decryption
  *
- * Above functions are split up neatly into logical interfaces. These can be 
- * used separately to provide any of the above functions or to mix-and-match 
- * into an SSL server/client solution that utilises a X.509 PKI. Examples of 
- * such implementations are amply provided with the source code. Note that 
- * there is also an OpenSSL wrapper provided.\n
+ * Above functions are split up neatly into logical interfaces. These can be
+ * used separately to provide any of the above functions or to mix-and-match
+ * into an SSL server/client solution that utilises a X.509 PKI. Examples of
+ * such implementations are amply provided with the source code.
+ *
  * Note that PolarSSL does not provide a control channel or (multiple) session
- * handling. 
+ * handling without additional work from the developer.
  *
  * @section mainpage_examples Examples
- * 
+ *
  * Example server setup:
  *
- * \b Prerequisites: 
+ * \b Prerequisites:
  * - X.509 certificate and private key
  * - session handling functions
  *
@@ -57,7 +56,6 @@
  * - Read/write data (SSL/TLS interface)
  * - Close and cleanup (all interfaces)
  *
- *
  * Example client setup:
  *
  * \b Prerequisites:
@@ -75,6 +73,4 @@
  * - Verify the server certificate (SSL/TLS interface)
  * - Write/read data (SSL/TLS interface)
  * - Close and cleanup (all interfaces)
- *
- * 
  */

doxygen/input/doc_rng.h

@@ -5,18 +5,19 @@
 
 /**
  * @addtogroup rng_module Random number generator (RNG) module
- * 
- * The Random number generator (RNG) module provides random number
- * generation, see \c ctr_dbrg_random() or \c havege_random().
  *
- * The former uses the block-cipher counter-mode based deterministic random
+ * The Random number generator (RNG) module provides random number
+ * generation, see \c ctr_dbrg_random().
+ *
+ * The block-cipher counter-mode based deterministic random
  * bit generator (CTR_DBRG) as specified in NIST SP800-90. It needs an external
  * source of entropy. For these purposes \c entropy_func() can be used. This is
  * an implementation based on a simple entropy accumulator design.
  *
- * The latter random number generator uses the HAVEGE (HArdware Volatile
- * Entropy Gathering and Expansion) software heuristic which is claimed 
- * to be an unpredictable or empirically strong* random number generation.
+ * The other number generator that is included is less strong and uses the HAVEGE
+ * (HArdware Volatile Entropy Gathering and Expansion) software heuristic
+ * which considered unsafe for primary usage, but provides additional random
+ * to the entropy pool if enables.
  *
  * \* Meaning that there seems to be no practical algorithm that can guess
  * the next bit with a probability larger than 1/2 in an output sequence.

doxygen/input/doc_ssltls.h

@@ -5,16 +5,16 @@
 
 /**
  * @addtogroup ssltls_communication_module SSL/TLS communication module
- * 
+ *
  * The SSL/TLS communication module provides the means to create an SSL/TLS
- * communication channel. 
+ * communication channel.
+ *
  * The basic provisions are:
  * - initialise an SSL/TLS context (see \c ssl_init()).
  * - perform an SSL/TLS handshake (see \c ssl_handshake()).
  * - read/write (see \c ssl_read() and \c ssl_write()).
  * - notify a peer that conection is being closed (see \c ssl_close_notify()).
  *
- *
  * Many aspects of such a channel are set through parameters and callback
  * functions:
  * - the endpoint role: client or server.
@@ -24,7 +24,6 @@
  * - the ciphers to use for encryption/decryption.
  * - session control functions.
  * - X.509 parameters for certificate-handling and key exchange.
- * 
  *
  * This module can be used to create an SSL/TLS server and client and to provide a basic
  * framework to setup and communicate through an SSL/TLS communication channel.\n

doxygen/input/doc_tcpip.h

@@ -5,12 +5,12 @@
 
 /**
  * @addtogroup tcpip_communication_module TCP/IP communication module
- * 
+ *
  * The TCP/IP communication module provides for a channel of
- * communication for the \link ssltls_communication_module SSL/TLS communication 
- * module\endlink to use. 
- * In the TCP/IP-model it provides for communication up to the Transport 
- * (or Host-to-host) layer. 
+ * communication for the \link ssltls_communication_module SSL/TLS communication
+ * module\endlink to use.
+ * In the TCP/IP-model it provides for communication up to the Transport
+ * (or Host-to-host) layer.
  * SSL/TLS resides on top of that, in the Application layer, and makes use of
  * its basic provisions:
  * - listening on a port (see \c net_bind()).
@@ -18,9 +18,9 @@
  * - read/write (through \c net_recv()/\c net_send()).
  * - close a connection (through \c net_close()).
  *
- * This way you have the means to, for example, implement and use an UDP or 
+ * This way you have the means to, for example, implement and use an UDP or
  * IPSec communication solution as a basis.
- * 
+ *
  * This module can be used at server- and clientside to provide a basic
  * means of communication over the internet.
  */

doxygen/input/doc_x509.h

@@ -5,17 +5,19 @@
 
 /**
  * @addtogroup x509_module X.509 module
- * 
+ *
  * The X.509 module provides X.509 support which includes:
  * - X.509 certificate (CRT) reading (see \c x509parse_crt() and
  *   \c x509parse_crtfile()).
  * - X.509 certificate revocation list (CRL) reading (see \c x509parse_crl()
  *   and\c x509parse_crlfile()).
- * - X.509 (RSA) private key reading (see \c x509parse_key_rsa() and
- *   \c x509parse_keyfile_rsa()).
+ * - X.509 (RSA and ECC) private key reading (see \c x509parse_key() and
+ *   \c x509parse_keyfile()).
  * - X.509 certificate signature verification (see \c x509parse_verify())
+ * - X.509 certificate writing and certificate request writing (see
+ *   \c x509write_crt_der() and \c x509write_csr_der()).
  *
  * This module can be used to build a certificate authority (CA) chain and
- * verify its signature. It is also used to get a (RSA) private key for signing
- * and decryption.
+ * verify its signature. It is also used to generate Certificate Signing
+ * Requests and X509 certificates just as a CA would do.
  */