|
|
|
|
@ -1,14 +1,85 @@
|
|
|
|
|
/**
|
|
|
|
|
* @file |
|
|
|
|
* @defgroup altcp Application layered TCP |
|
|
|
|
* @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 |
|
|
|
|
* Application layered TCP connection API (to be used from TCPIP thread)\n |
|
|
|
|
* This interface mimics the tcp callback API to the application while preventing |
|
|
|
|
* |
|
|
|
|
* 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 |
|
|
|
|
* * 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_". |
|
|
|
|
* |
|
|
|
|
* This file contains the common functions for altcp to work. |
|
|
|
|
* 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()'. |
|
|
|
|
*/ |
|
|
|
|
|
|
|
|
|
/*
|
|
|
|
|
|
Simon Goldschmidt
8 years ago