ssl/record/README

   1 Record Layer Design
   2 ===================
   3
   4 This file provides some guidance on the thinking behind the design of the
   5 record layer code to aid future maintenance.
   6
   7 The record layer is divided into a number of components. At the time of writing
   8 there are four: SSL3_RECORD, SSL3_BUFFER, DLTS1_BITMAP and RECORD_LAYER. Each
   9 of these components is defined by:
  10 1) A struct definition of the same name as the component
  11 2) A set of source files that define the functions for that component
  12 3) A set of accessor macros
  13
  14 All struct definitions are in record.h. The functions and macros are either
  15 defined in record.h or record_locl.h dependent on whether they are intended to
  16 be private to the record layer, or whether they form part of the API to the rest
  17 of libssl.
  18
  19 The source files map to components as follows:
  20
  21 dtls1_bitmap.c                                   -> DTLS1_BITMAP component
  22 ssl3_buffer.c                                    -> SSL3_BUFFER component
  23 ssl3_record.c                                    -> SSL3_RECORD component
  24 rec_layer_s23.c, rec_layer_s3.c, rec_layer_d1.c  -> RECORD_LAYER component
  25
  26 The RECORD_LAYER component is a facade pattern, i.e. it provides a simplified
  27 interface to the record layer for the rest of libssl. The other 3 components are
  28 entirely private to the record layer and therefore should never be accessed
  29 directly by libssl.
  30
  31 Any component can directly access its own members - they are private to that
  32 component, e.g. ssl3_buffer.c can access members of the SSL3_BUFFER struct
  33 without using a macro. No component can directly access the members of another
  34 component, e.g. ssl3_buffer cannot reach inside the RECORD_LAYER component to
  35 directly access its members. Instead components use accessor macros, so if code
  36 in ssl3_buffer.c wants to access the members of the RECORD_LAYER it uses the
  37 RECORD_LAYER_* macros.
  38
  39 Conceptually it looks like this:
  40
  41                         libssl
  42                            |
  43 ---------------------------|-----record.h--------------------------------------
  44                            |
  45                     _______V______________
  46                    |                      |
  47                    |    RECORD_LAYER      |
  48                    |                      |
  49                    |    rec_layer_s23.c   |
  50                    |          ^           |
  51                    |          |           |
  52                    |    rec_layer_s3.c    |
  53                    |          ^           |
  54                    | _________|__________ |
  55                    ||                    ||
  56                    || DTLS1_RECORD_LAYER ||
  57                    ||                    ||
  58                    || rec_layer_d1.c     ||
  59                    ||____________________||
  60                    |______________________|
  61         record_locl.h     ^   ^   ^
  62          _________________|   |   |_________________
  63         |                     |                     |
  64    _____V_________      ______V________      _______V________
  65   |               |    |               |    |                |
  66   | SSL3_BUFFER   |    | SSL3_RECORD   |    | DTLS1_BITMAP   |
  67   |               |--->|               |    |                |
  68   | ssl3_buffer.c |    | ssl3_record.c |    | dtls1_bitmap.c |
  69   |_______________|    |_______________|    |________________|
  70
  71
  72 The three RECORD_LAYER source files build progressively on each other, i.e.
  73 the simplest is rec_layer_s23.c. This provides the most basic functions used
  74 for version negotiation. Next rec_layer_s3.c adds the SSL/TLS layer. Finally
  75 rec_layer_d1.c builds off of the SSL/TLS code to provide DTLS specific
  76 capabilities. It uses some DTLS specific RECORD_LAYER component members which
  77 should only be accessed from rec_layer_d1.c. These are held in the
  78 DTLS1_RECORD_LAYER struct.