Documentation improvements for 2.1.0 (mainly altcp/altcp_tls)

CHANGELOG

@@ -6,7 +6,7 @@ HISTORY
 
   * [Enter new changes just after this line - do not remove this line]
 
-(STABLE-2.0.3)
+(STABLE-2.1.0):
 
   ++ New features:
 
@@ -118,7 +118,7 @@ HISTORY
   * Implement UDP and RAW multicast support for IPv6 (core API, not netconn/sockets)
 
   2017-02-04: David van Moolenbroek
-    - IPv6 scopes support
+  * IPv6 scopes support
 
   2017-01-20: Joel Cunningham
   * sockets: add interface name/index APIs (task #14314)

README

@@ -1,15 +1,15 @@
 INTRODUCTION
 
-lwIP is a small independent implementation of the TCP/IP protocol
-suite that has been developed by Adam Dunkels at the Computer and
-Networks Architectures (CNA) lab at the Swedish Institute of Computer
-Science (SICS).
+lwIP is a small independent implementation of the TCP/IP protocol suite.
 
 The focus of the lwIP TCP/IP implementation is to reduce the RAM usage
 while still having a full scale TCP. This making lwIP suitable for use
 in embedded systems with tens of kilobytes of free RAM and room for
 around 40 kilobytes of code ROM.
 
+lwIP was originally developed by Adam Dunkels at the Computer and Networks
+Architectures (CNA) lab at the Swedish Institute of Computer Science (SICS)
+and is now developed and maintained by a worldwide network of developers.
 
 FEATURES
 
@@ -28,8 +28,8 @@ FEATURES
     fast recovery/fast retransmit and sending SACKs
   * raw/native API for enhanced performance
   * Optional Berkeley-like socket API
-  * Optional layered TCP ("altcp") for nearly transparent TLS for any TCP-based
-    protocol, ported to mbedTLS)
+  * TLS: optional layered TCP ("altcp") for nearly transparent TLS for any
+    TCP-based protocol (ported to mbedTLS) (see changelog for more info)
   * PPPoS and PPPoE (Point-to-point protocol over Serial/Ethernet)
   * DNS (Domain name resolver incl. mDNS)
   * 6LoWPAN (via IEEE 802.15.4, BLE or ZEP)

UPGRADING

@@ -12,6 +12,7 @@ with newer versions.
 
   ++ Application changes:
 
+  * Use the new altcp API for seamless TLS integration into existing TCP applications (see changelog)
   * TCP only kills existing connections with a LOWER priority than the one currently being opened.
     Previous implementations also kill existing connections of the SAME priority.
   * ip4_route_src: parameter order is reversed: ip4_route_src(dest, src) -> ip4_route_src(src, dest)

doc/doxygen/main_page.h

@@ -101,6 +101,15 @@
 
 /**
  * @page changelog Changelog
+ *
+ * 2.1.0
+ * -----
+ * * This version supports TLS via @ref altcp_api connection API
+ * * This version switches to cmake as the main build system (Makefile file
+ *   lists are maintained for now)
+ * 
+ * Detailed Changelog
+ * ------------------
  * @verbinclude "CHANGELOG"
  */
 

src/core/altcp.c

@@ -1,14 +1,85 @@
 /**
  * @file
- * @defgroup altcp Application layered TCP
- * @ingroup callbackstyle_api
- * Application layered TCP connection API (to be used from TCPIP thread)\n
- * This interface mimics the tcp callback API to the application while preventing
- * direct linking (much like virtual functions).
- * This way, an application can make use of other application layer protocols
- * on top of TCP without knowing the details (e.g. TLS, proxy connection).
+ * @defgroup altcp Application layered TCP Functions
+ * @ingroup altcp_api
  *
  * This file contains the common functions for altcp to work.
+ * For more details see @ref altcp_api.
+ */
+
+/**
+ * @defgroup altcp_api Application layered TCP Introduction
+ * @ingroup callbackstyle_api
+ *
+ * Overview
+ * --------
+ * altcp (application layered TCP connection API; to be used from TCPIP thread)
+ * is an abstraction layer that prevents applications linking hard against the
+ * @ref tcp.h functions while providing the same functionality. It is used to
+ * e.g. add SSL/TLS (see LWIP_ALTCP_TLS) or proxy-connect support to an application
+ * written for the tcp callback API without that application knowing the
+ * protocol details.
+ *
+ * * This interface mimics the tcp callback API to the application while preventing
+ *   direct linking (much like virtual functions).
+ * * This way, an application can make use of other application layer protocols
+ *   on top of TCP without knowing the details (e.g. TLS, proxy connection).
+ * * This is achieved by simply including "lwip/altcp.h" instead of "lwip/tcp.h",
+ *   replacing "struct tcp_pcb" with "struct altcp_pcb" and prefixing all functions
+ *   with "altcp_" instead of "tcp_".
+ *
+ * With altcp support disabled (LWIP_ALTCP==0), applications written against the
+ * altcp API can still be compiled but are directly linked against the tcp.h
+ * callback API and then cannot use layered protocols. To minimize code changes
+ * in this case, the use of altcp_allocators is strongly suggested.
+ *
+ * Usage
+ * -----
+ * To make use of this API from an existing tcp raw API application:
+ * * Include "lwip/altcp.h" instead of "lwip/tcp.h"
+ * * Replace "struct tcp_pcb" with "struct altcp_pcb"
+ * * Prefix all called tcp API functions with "altcp_" instead of "tcp_" to link
+ *   against the altcp functions
+ * * @ref altcp_new (and @ref altcp_new_ip_type/@ref altcp_new_ip6) take
+ *   an @ref altcp_allocator_t as an argument, whereas the original tcp API
+ *   functions take no arguments.
+ * * An @ref altcp_allocator_t allocator is an object that holds a pointer to an
+ *   allocator object and a corresponding state (e.g. for TLS, the corresponding
+ *   state may hold certificates or keys). This way, the application does not
+ *   even need to know if it uses TLS or pure TCP, this is handled at runtime
+ *   by passing a specific allocator.
+ * * An application can alternatively bind hard to the altcp_tls API by calling
+ *   @ref altcp_tls_new or @ref altcp_tls_wrap.
+ * * The TLS layer is not directly implemented by lwIP, but a port to mbedTLS is
+ *   provided.
+ * * Another altcp layer is proxy-connect to use TLS behind a HTTP proxy (see
+ *   @ref altcp_proxyconnect.h)
+ *
+ * altcp_allocator_t
+ * -----------------
+ * An altcp allocator is created by the application by combining an allocator
+ * callback function and a corresponding state, e.g.:\code{.c}
+ * static const unsigned char cert[] = {0x2D, "(see mbedTLS doc for how to create this)"};
+ * struct altcp_tls_config * conf = altcp_tls_create_config_client(cert, sizeof(cert));
+ * altcp_allocator_t tls_allocator = {
+ *   altcp_tls_alloc, conf
+ * };
+ * \endcode
+ *
+ *
+ * struct altcp_tls_config
+ * -----------------------
+ * The struct altcp_tls_config holds state that is needed to create new TLS client
+ * or server connections (e.g. certificates and private keys).
+ *
+ * It is not defined by lwIP itself but by the TLS port (e.g. altcp_tls to mbedTLS
+ * adaption). However, the parameters used to create it are defined in @ref
+ * altcp_tls.h (see @ref altcp_tls_create_config_server_privkey_cert for servers
+ * and @ref altcp_tls_create_config_client/@ref altcp_tls_create_config_client_2wayauth
+ * for clients).
+ *
+ * For mbedTLS, ensure that certificates can be parsed by 'mbedtls_x509_crt_parse()' and
+ * private keys can be parsed by 'mbedtls_pk_parse_key()'.
  */
 
 /*

src/include/lwip/altcp.h

@@ -1,12 +1,9 @@
 /**
  * @file
  * Application layered TCP connection API (to be used from TCPIP thread)\n
- * This interface mimics the tcp callback API to the application while preventing
- * direct linking (much like virtual functions).
- * This way, an application can make use of other application layer protocols
- * on top of TCP without knowing the details (e.g. TLS, proxy connection).
  *
  * This file contains the generic API.
+ * For more details see @ref altcp_api.
  */
 
 /*

src/include/lwip/opt.h

@@ -1479,15 +1479,19 @@
 #define LWIP_TCP_PCB_NUM_EXT_ARGS       0
 #endif
 
-/** LWIP_ALTCP==1: enable the altcp API
+/** LWIP_ALTCP==1: enable the altcp API.
  * altcp is an abstraction layer that prevents applications linking against the
  * tcp.h functions but provides the same functionality. It is used to e.g. add
  * SSL/TLS or proxy-connect support to an application written for the tcp callback
  * API without that application knowing the protocol details.
- * Applications written against the altcp API are directly linked against the
- * tcp callback API for LWIP_ALTCP==0, but then cannot use layered protocols.
+ *
+ * With LWIP_ALTCP==0, applications written against the altcp API can still be
+ * compiled but are directly linked against the tcp.h callback API and then
+ * cannot use layered protocols.
+ *
+ * See @ref altcp_api
  */
-#ifndef LWIP_ALTCP
+#if !defined LWIP_ALTCP || defined __DOXYGEN__
 #define LWIP_ALTCP                      0
 #endif
 
@@ -1496,7 +1500,7 @@
  * A port to ARM mbedtls is provided with lwIP, see apps/altcp_tls/ directory
  * and LWIP_ALTCP_TLS_MBEDTLS option.
  */
-#ifndef LWIP_ALTCP_TLS
+#if !defined LWIP_ALTCP_TLS || defined __DOXYGEN__
 #define LWIP_ALTCP_TLS                  0
 #endif
 
@@ -1548,7 +1552,7 @@
  * LWIP_PBUF_REF_T: Refcount type in pbuf.
  * Default width of u8_t can be increased if 255 refs are not enough for you.
  */
-#ifndef LWIP_PBUF_REF_T
+#if !defined LWIP_PBUF_REF_T || defined __DOXYGEN__
 #define LWIP_PBUF_REF_T                 u8_t
 #endif
 /**