PolarSSL TCP/IP module MLD

Introduction

This document describes the internal functionality of the PolarSSL TCP/IP module.

Component overview

The TCP/IP module provides a generic communication channel. It provides the following basic functions:

• Setup a connection
• Send/receive data
• Close a connection

This module can be used between hosts to provide a basic means of communication over the internet. There is no interaction with other components.

Component design

To setup an TCP/IP communication channel one host must listen and must connect. The host that listens must accept the connection. Data can then be sent and received. The connection can be closed. The host that listens is called the server and the one that connects is the client. To achieve the above the following functions provided:

Server-side functions

• Listen to a socket. A socket is a mapping of a port number with an IP address.
• Accept a connection on a socket.

Client-side functions

• Connect to a socket

Common functions

• Set a socket to blocking/non-blocking.
• Read/write data from a socket.
• Close a socket.

All functions are prefixed net_ for coherence.

Server-side functions

A server typically listens on an interface to a port for clients that want to connect. When such a connection request is received, the server may accept by binding the local server socket (IP address + port number) to the remote client socket. The TCP/IP channel is ready for data communication.

Client-side functions

A client typically connects to a known host and port. If a server is listening and accepts the connection a TCP/IP communication channel is ready for use.

Common functions

When a TCP/IP communication channel has been set up (see the sections above) either side can send and receive data. It is advisable to somehow coordinate the sending and receiving of data to avoid collisions. After either side is done sending data it can close the connection.

When a socket is set to blocking it waits when requesting data, with non-blocking it returns with an error code if the requested data is not available.

Used structures

Only built-in socket and host structures are used.

Internal state

There is no internal state structure. State is communicated through return codes and by keeping a socket identifier. The following diagrams are typical for TCP/IP client-server communication:

Scenarios

The following scenarios are described:

• Setting up a connection
• Failing to setup a connection
• Complex usage: TCP/IP setup, communication and breakdown

Setting up a connection

This scenario describes how a connection is set up between a client and a server host.

Failing to setup a connection

This scenario describes how a connection set up between a client and a server host fails.

Complex usage: TCP/IP setup, communication and breakdown

This scenario describes how a TCP/IP communication usually takes place. It covers setup, communication and breakdown.

Use cases

All uses are:

• Listen to a socket
• Connect to a socket
• Accept a connection on a socket
• Set socket to blocking/non-blocking
• Send data
• Receive data
• Close a connection