]>
Commit | Line | Data |
---|---|---|
ee3ef9cb MC |
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 | |
706457b7 | 15 | defined in record.h or record_local.h dependent on whether they are intended to |
ee3ef9cb MC |
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 | |
a3680c8f | 24 | rec_layer_s3.c, rec_layer_d1.c -> RECORD_LAYER component |
ee3ef9cb MC |
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 | | | | |
ee3ef9cb MC |
49 | | rec_layer_s3.c | |
50 | | ^ | | |
51 | | _________|__________ | | |
52 | || || | |
53 | || DTLS1_RECORD_LAYER || | |
54 | || || | |
55 | || rec_layer_d1.c || | |
56 | ||____________________|| | |
57 | |______________________| | |
706457b7 | 58 | record_local.h ^ ^ ^ |
ee3ef9cb MC |
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 | ||
a3680c8f MC |
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 | |
ee3ef9cb | 74 | DTLS1_RECORD_LAYER struct. |