| lh | 9ed821d | 2023-04-07 01:36:19 -0700 | [diff] [blame] | 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 | - 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 | |
| 27 | The message flow state machine is divided into a reading sub-state machine and a |
| 28 | writing sub-state machine. See the source comments in statem.c for a more |
| 29 | detailed description of the various states and transitions possible. |
| 30 | |
| 31 | Conceptually 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_lib.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 | |