| 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_local.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_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_s3.c |
|
|---|
| 50 | | ^ |
|
|---|
| 51 | | _________|__________ |
|
|---|
| 52 | || ||
|
|---|
| 53 | || DTLS1_RECORD_LAYER ||
|
|---|
| 54 | || ||
|
|---|
| 55 | || rec_layer_d1.c ||
|
|---|
| 56 | ||____________________||
|
|---|
| 57 | |______________________|
|
|---|
| 58 | record_local.h ^ ^ ^
|
|---|
| 59 | _________________| | |_________________
|
|---|
| 60 | | | |
|
|---|
| 61 | _____V_________ ______V________ _______V________
|
|---|
| 62 | | | | | | |
|
|---|
| 63 | | SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP |
|
|---|
| 64 | | |--->| | | |
|
|---|
| 65 | | ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c |
|
|---|
| 66 | |_______________| |_______________| |________________|
|
|---|
| 67 |
|
|---|
| 68 |
|
|---|
| 69 | The two RECORD_LAYER source files build on each other, i.e.
|
|---|
| 70 | the main one is rec_layer_s3.c which provides the core SSL/TLS layer. The second
|
|---|
| 71 | one is rec_layer_d1.c which builds off of the SSL/TLS code to provide DTLS
|
|---|
| 72 | specific capabilities. It uses some DTLS specific RECORD_LAYER component members
|
|---|
| 73 | which should only be accessed from rec_layer_d1.c. These are held in the
|
|---|
| 74 | DTLS1_RECORD_LAYER struct.
|
|---|
