ssl/statem/README

   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_locl.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