lwIP  2.1.0
Lightweight IP stack
Application layered TCP Introduction

Modules

 Application layered TCP Functions
 

Detailed Description

Overview

altcp (application layered TCP connection API; to be used from TCPIP thread) is an abstraction layer that prevents applications linking hard against the 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.

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:

altcp_allocator_t

An altcp allocator is created by the application by combining an allocator callback function and a corresponding state, e.g.:

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 = {
};

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 altcp_tls.h (see altcp_tls_create_config_server_privkey_cert for servers and altcp_tls_create_config_client/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()'.