README 3.5 KB

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