1*b077aed3SPierre ProncheryRecord Layer Design 2*b077aed3SPierre Pronchery=================== 3*b077aed3SPierre Pronchery 4*b077aed3SPierre ProncheryThis file provides some guidance on the thinking behind the design of the 5*b077aed3SPierre Proncheryrecord layer code to aid future maintenance. 6*b077aed3SPierre Pronchery 7*b077aed3SPierre ProncheryThe record layer is divided into a number of components. At the time of writing 8*b077aed3SPierre Proncherythere are four: SSL3_RECORD, SSL3_BUFFER, DLTS1_BITMAP and RECORD_LAYER. Each 9*b077aed3SPierre Proncheryof these components is defined by: 10*b077aed3SPierre Pronchery1) A struct definition of the same name as the component 11*b077aed3SPierre Pronchery2) A set of source files that define the functions for that component 12*b077aed3SPierre Pronchery3) A set of accessor macros 13*b077aed3SPierre Pronchery 14*b077aed3SPierre ProncheryAll struct definitions are in record.h. The functions and macros are either 15*b077aed3SPierre Proncherydefined in record.h or record_local.h dependent on whether they are intended to 16*b077aed3SPierre Proncherybe private to the record layer, or whether they form part of the API to the rest 17*b077aed3SPierre Proncheryof libssl. 18*b077aed3SPierre Pronchery 19*b077aed3SPierre ProncheryThe source files map to components as follows: 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery dtls1_bitmap.c -> DTLS1_BITMAP component 22*b077aed3SPierre Pronchery ssl3_buffer.c -> SSL3_BUFFER component 23*b077aed3SPierre Pronchery ssl3_record.c -> SSL3_RECORD component 24*b077aed3SPierre Pronchery rec_layer_s3.c, rec_layer_d1.c -> RECORD_LAYER component 25*b077aed3SPierre Pronchery 26*b077aed3SPierre ProncheryThe RECORD_LAYER component is a facade pattern, i.e. it provides a simplified 27*b077aed3SPierre Proncheryinterface to the record layer for the rest of libssl. The other 3 components are 28*b077aed3SPierre Proncheryentirely private to the record layer and therefore should never be accessed 29*b077aed3SPierre Proncherydirectly by libssl. 30*b077aed3SPierre Pronchery 31*b077aed3SPierre ProncheryAny component can directly access its own members - they are private to that 32*b077aed3SPierre Proncherycomponent, e.g. ssl3_buffer.c can access members of the SSL3_BUFFER struct 33*b077aed3SPierre Proncherywithout using a macro. No component can directly access the members of another 34*b077aed3SPierre Proncherycomponent, e.g. ssl3_buffer cannot reach inside the RECORD_LAYER component to 35*b077aed3SPierre Proncherydirectly access its members. Instead components use accessor macros, so if code 36*b077aed3SPierre Proncheryin ssl3_buffer.c wants to access the members of the RECORD_LAYER it uses the 37*b077aed3SPierre ProncheryRECORD_LAYER_* macros. 38*b077aed3SPierre Pronchery 39*b077aed3SPierre ProncheryConceptually it looks like this: 40*b077aed3SPierre Pronchery 41*b077aed3SPierre Pronchery libssl 42*b077aed3SPierre Pronchery | 43*b077aed3SPierre Pronchery -------------------------|-----record.h------------------------------------ 44*b077aed3SPierre Pronchery | 45*b077aed3SPierre Pronchery _______V______________ 46*b077aed3SPierre Pronchery | | 47*b077aed3SPierre Pronchery | RECORD_LAYER | 48*b077aed3SPierre Pronchery | | 49*b077aed3SPierre Pronchery | rec_layer_s3.c | 50*b077aed3SPierre Pronchery | ^ | 51*b077aed3SPierre Pronchery | _________|__________ | 52*b077aed3SPierre Pronchery || || 53*b077aed3SPierre Pronchery || DTLS1_RECORD_LAYER || 54*b077aed3SPierre Pronchery || || 55*b077aed3SPierre Pronchery || rec_layer_d1.c || 56*b077aed3SPierre Pronchery ||____________________|| 57*b077aed3SPierre Pronchery |______________________| 58*b077aed3SPierre Pronchery record_local.h ^ ^ ^ 59*b077aed3SPierre Pronchery _________________| | |_________________ 60*b077aed3SPierre Pronchery | | | 61*b077aed3SPierre Pronchery _____V_________ ______V________ _______V________ 62*b077aed3SPierre Pronchery | | | | | | 63*b077aed3SPierre Pronchery | SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP | 64*b077aed3SPierre Pronchery | |--->| | | | 65*b077aed3SPierre Pronchery | ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c | 66*b077aed3SPierre Pronchery |_______________| |_______________| |________________| 67*b077aed3SPierre Pronchery 68*b077aed3SPierre ProncheryThe two RECORD_LAYER source files build on each other, i.e. 69*b077aed3SPierre Proncherythe main one is rec_layer_s3.c which provides the core SSL/TLS layer. The second 70*b077aed3SPierre Proncheryone is rec_layer_d1.c which builds off of the SSL/TLS code to provide DTLS 71*b077aed3SPierre Proncheryspecific capabilities. It uses some DTLS specific RECORD_LAYER component members 72*b077aed3SPierre Proncherywhich should only be accessed from rec_layer_d1.c. These are held in the 73*b077aed3SPierre ProncheryDTLS1_RECORD_LAYER struct. 74