From ee3ef9cbe9b355c460ebb06c3eee0e503fe1fb1a Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Thu, 26 Mar 2015 13:51:32 +0000 Subject: [PATCH] Add Record Layer documentation Add some design documentation on how the record layer works to aid future maintenance. Reviewed-by: Richard Levitte --- ssl/record/README | 78 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 ssl/record/README diff --git a/ssl/record/README b/ssl/record/README new file mode 100644 index 0000000000..6870b53138 --- /dev/null +++ b/ssl/record/README @@ -0,0 +1,78 @@ +Record Layer Design +=================== + +This file provides some guidance on the thinking behind the design of the +record layer code to aid future maintenance. + +The record layer is divided into a number of components. At the time of writing +there are four: SSL3_RECORD, SSL3_BUFFER, DLTS1_BITMAP and RECORD_LAYER. Each +of these components is defined by: +1) A struct definition of the same name as the component +2) A set of source files that define the functions for that component +3) A set of accessor macros + +All struct definitions are in record.h. The functions and macros are either +defined in record.h or record_locl.h dependent on whether they are intended to +be private to the record layer, or whether they form part of the API to the rest +of libssl. + +The source files map to components as follows: + +dtls1_bitmap.c -> DTLS1_BITMAP component +ssl3_buffer.c -> SSL3_BUFFER component +ssl3_record.c -> SSL3_RECORD component +rec_layer_s23.c, rec_layer_s3.c, rec_layer_d1.c -> RECORD_LAYER component + +The RECORD_LAYER component is a facade pattern, i.e. it provides a simplified +interface to the record layer for the rest of libssl. The other 3 components are +entirely private to the record layer and therefore should never be accessed +directly by libssl. + +Any component can directly access its own members - they are private to that +component, e.g. ssl3_buffer.c can access members of the SSL3_BUFFER struct +without using a macro. No component can directly access the members of another +component, e.g. ssl3_buffer cannot reach inside the RECORD_LAYER component to +directly access its members. Instead components use accessor macros, so if code +in ssl3_buffer.c wants to access the members of the RECORD_LAYER it uses the +RECORD_LAYER_* macros. + +Conceptually it looks like this: + + libssl + | +---------------------------|-----record.h-------------------------------------- + | + _______V______________ + | | + | RECORD_LAYER | + | | + | rec_layer_s23.c | + | ^ | + | | | + | rec_layer_s3.c | + | ^ | + | _________|__________ | + || || + || DTLS1_RECORD_LAYER || + || || + || rec_layer_d1.c || + ||____________________|| + |______________________| + record_locl.h ^ ^ ^ + _________________| | |_________________ + | | | + _____V_________ ______V________ _______V________ + | | | | | | + | SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP | + | |--->| | | | + | ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c | + |_______________| |_______________| |________________| + + +The three RECORD_LAYER source files build progressively on each other, i.e. +the simplest is rec_layer_s23.c. This provides the most basic functions used +for version negotiation. Next rec_layer_s3.c adds the SSL/TLS layer. Finally +rec_layer_d1.c builds off of the SSL/TLS code to provide DTLS specific +capabilities. It uses some DTLS specific RECORD_LAYER component members which +should only be accessed from rec_layer_d1.c. These are held in the +DTLS1_RECORD_LAYER struct. -- 2.25.1