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