Home | History | Annotate | Line # | Download | only in statem 
      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_lib.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     |_____________________________| |_______________________________|
     64