README
1State Machine Design
2====================
3
4This file provides some guidance on the thinking behind the design of the
5state machine code to aid future maintenance.
6
7The state machine code replaces an older state machine present in OpenSSL
8versions 1.0.2 and below. The new state machine has the following objectives:
9 - Remove duplication of state code between client and server
10 - Remove duplication of state code between TLS and DTLS
11 - Simplify transitions and bring the logic together in a single location
12 so that it is easier to validate
13 - Remove duplication of code between each of the message handling functions
14 - Receive a message first and then work out whether that is a valid
15 transition - not the other way around (the other way causes lots of issues
16 where we are expecting one type of message next but actually get something
17 else)
18 - Separate message flow state from handshake state (in order to better
19 understand each)
20 - message flow state = when to flush buffers; handling restarts in the
21 event of NBIO events; handling the common flow of steps for reading a
22 message and the common flow of steps for writing a message etc
23 - handshake state = what handshake message are we working on now
24 - Control complexity: only the state machine can change state: keep all
25 the state changes local to the state machine component
26
27The message flow state machine is divided into a reading sub-state machine and a
28writing sub-state machine. See the source comments in statem.c for a more
29detailed description of the various states and transitions possible.
30
31Conceptually the state machine component is designed as follows:
32
33 libssl
34 |
35---------------------------|-----statem.h--------------------------------------
36 |
37 _______V____________________
38 | |
39 | statem.c |
40 | |
41 | Core state machine code |
42 |____________________________|
43 statem_local.h ^ ^
44 _________| |_______
45 | |
46 _____________|____________ _____________|____________
47 | | | |
48 | statem_clnt.c | | statem_srvr.c |
49 | | | |
50 | TLS/DTLS client specific | | TLS/DTLS server specific |
51 | state machine code | | state machine code |
52 |__________________________| |__________________________|
53 | |_______________|__ |
54 | ________________| | |
55 | | | |
56 ____________V_______V________ ________V______V_______________
57 | | | |
58 | statem_both.c | | statem_dtls.c |
59 | | | |
60 | Non core functions common | | Non core functions common to |
61 | to both servers and clients | | both DTLS servers and clients |
62 |_____________________________| |_______________________________|
63
64