From 8262c208580858e67bea58131afb8893ed549288 Mon Sep 17 00:00:00 2001 From: jacobkeeler Date: Wed, 28 Mar 2018 10:50:23 -0400 Subject: Fix broken links and paths in SDD Documents Also removes some Ford-specific terms, fixes typos in these documents, and changes their naming schemes --- Doxyfile | 2 +- docs/FORD.OpenSDL.SDD.TPL.dox | 355 --------------------- docs/SDL.SDD.Template.dox | 355 +++++++++++++++++++++ docs/mainpage.dox | 4 +- .../docs/FORD.OpenSDL.SDD.Security.dox | 241 -------------- .../security_manager/docs/SDL.SDD.Security.dox | 241 ++++++++++++++ .../docs/assets/sm_class_diagram.png | Bin 0 -> 368935 bytes .../docs/assets/sm_class_digram.png | Bin 368935 -> 0 bytes .../docs/assets/sm_sequence_diagram_decryption.png | Bin 0 -> 28014 bytes .../docs/assets/sm_sequence_diagram_encryption.png | Bin 0 -> 22326 bytes .../docs/assets/sm_sequence_diagram_init.png | Bin 0 -> 119018 bytes .../docs/assets/sm_sequence_diagram_verify.png | Bin 0 -> 39820 bytes .../docs/assets/sm_sequence_digram_decryption.png | Bin 28014 -> 0 bytes .../docs/assets/sm_sequence_digram_encryption.png | Bin 22326 -> 0 bytes .../docs/assets/sm_sequence_digram_init.png | Bin 119018 -> 0 bytes .../docs/assets/sm_sequence_digram_verify.png | Bin 39820 -> 0 bytes 16 files changed, 599 insertions(+), 599 deletions(-) delete mode 100644 docs/FORD.OpenSDL.SDD.TPL.dox create mode 100644 docs/SDL.SDD.Template.dox delete mode 100644 src/components/security_manager/docs/FORD.OpenSDL.SDD.Security.dox create mode 100644 src/components/security_manager/docs/SDL.SDD.Security.dox create mode 100644 src/components/security_manager/docs/assets/sm_class_diagram.png delete mode 100644 src/components/security_manager/docs/assets/sm_class_digram.png create mode 100644 src/components/security_manager/docs/assets/sm_sequence_diagram_decryption.png create mode 100644 src/components/security_manager/docs/assets/sm_sequence_diagram_encryption.png create mode 100644 src/components/security_manager/docs/assets/sm_sequence_diagram_init.png create mode 100644 src/components/security_manager/docs/assets/sm_sequence_diagram_verify.png delete mode 100644 src/components/security_manager/docs/assets/sm_sequence_digram_decryption.png delete mode 100644 src/components/security_manager/docs/assets/sm_sequence_digram_encryption.png delete mode 100644 src/components/security_manager/docs/assets/sm_sequence_digram_init.png delete mode 100644 src/components/security_manager/docs/assets/sm_sequence_digram_verify.png diff --git a/Doxyfile b/Doxyfile index 0b46c939b6..36155e37a7 100644 --- a/Doxyfile +++ b/Doxyfile @@ -838,7 +838,7 @@ RECURSIVE = YES # run. EXCLUDE = **/CMakeLists.txt \ - docs/FORD.OpenSDL.SDD.TPL.dox + docs/SDL.SDD.Template.dox src/components/test_main.cc src/thirdPartyLibs \ tools/FlexeLint \ diff --git a/docs/FORD.OpenSDL.SDD.TPL.dox b/docs/FORD.OpenSDL.SDD.TPL.dox deleted file mode 100644 index c0106df5d4..0000000000 --- a/docs/FORD.OpenSDL.SDD.TPL.dox +++ /dev/null @@ -1,355 +0,0 @@ -/** -\cond FALSE ------- Design document template explanation ------- -This is a SW Detailed Design template for each SDl component update. -The original QCA template with more detail description is available at Luxoft portal -https://adc.luxoft.com/confluence/display/PORTAL/Software+Detailed+Design+Template - ----------------------- HOWTO ----------------------- -For adding new component documentation please follow this steps: -1. Copy this document to the 'doc' subdirectory in the Component working directory with a new name - - Example: - + src/components/transport_manager/docs/FORD.OpenSDL.SDD.TM.dox - + src/components/utils/docs/FORD.OpenSDL.SDD.Utils.dox - - https://adc.luxoft.com/confluence/display/PORTAL/Documentation+Control+Guideline#DocumentationControlGuideline-DocumentNaming -2. Replace with a correct naming according to SAD naming - - Name examples: - Application Manager, Connection Handler - - Replace examples: - ~ sed -i 's//Utils/g' FORD.OpenSDL.SDD.Utils.dox -3. Replace with a shot unique name - - Something like app_manage, connection_handler, policy - - It shall be one word without spaces and special symbols except '_' - - Replace examples: - ~ sed -i 's//connection_handler/g' FORD.OpenSDL.SDD.Utils.dox - Note: After that step all Doxygen tags becomes working well and IDE could be used -4. Add reference in mainpage.dox Table of Content using used in p.3 -5. Replace blocks marked as following with a content according to instructions in these blocks - - Each block starts as - - Each block ends as - - If chapter content is not applicable for a Component update it with "Not applicable, since/because of ." -6. Update source code doxygen comments for mentioning entities in the following SDD chapter: - - Public and private interfaces from chapter 3 - - Data types from chapter 4.2 -7. Update project Doxygen file with path to new images - * IMAGE_PATH parameter -8. Remove this template explanation from cond to endcond tags - -General notes/reminders: -- Commit both: images and them source to the git repository -- SDD file extension shall be 'dox' -- the preferable path for SDD is src/components/COMPONENT/docs -- the preferable path for SDD images is src/components/COMPONENT/docs/assets - -For more information, please follow: -- Doxygen documentation - http://www.stack.nl/~dimitri/doxygen/manual/index.html -- Markdown support by doxygen - http://www.stack.nl/~dimitri/doxygen/manual/markdown.html -- Text-base UML tool - http://plantuml.com/ -- Article "Providing design documentation with code changes" - https://github.com/smartdevicelink/sdl_core/wiki/Providing-design-documentation-with-code-changes - ---------------------------------------------- -\endcond -\page Detailed Design -## Table of contents -- \subpage _intoduction - + \ref _rationale "1.1 Rationale" - + \ref _scope "1.2 Scope" - + \ref _abbreviations "1.3 Abbreviations" -- \subpage _detail_design - + \ref _design_solutions "2.1 Design solutions" - + \ref _class_structure "2.2 Class Structure" - + \ref _sequence_diagram "2.3 Sequence diagram" - + \ref _state_chart "2.4 State chart diagram" -- \subpage _interfaces - + \ref _public_interfaces "3.1 Public interfaces description" - + \ref _internal_interfaces "3.2 Internal interfaces description" - + \ref _derived_interfaces "3.3 Derived interfaces and dependencies" -- \subpage _data_structure_resources - + \ref _data_structure "4.1 Element Data Structure" - + \ref _resources "4.2 Resource usage" -- \subpage _references_and_history - + \ref _references "5.1 References" - + \ref _history "5.2 Document history change and approve" -*/ -//----------------------------------------------------------- -/** -\page _intoduction 1. Introduction -The document is intended to support software developers, -maintenance and integration engineers with sufficient, -detailed information concerning the design, development and -deployment concepts, to accomplish their respective tasks without reliance on the authors. - -\anchor _rationale -## 1.1 Rationale - implements SDL Architectural Solution according to: - - -Here need to be a link SAD Components View and Requirements if applicable) -Example: - https://smartdevicelink.com/en/guides/core/software-architecture-document/components-view/#hmi-message-handler - - -\anchor _scope -## 1.2 Scope - extracted as a separate component for - - -Here need to be added a reason and short description of the components functionality -Example: - Security Manager component extracted as a separate module for - Ford channel data protection. - This components is used to : - - Provide security communications - - Protect income and outcome business layer data from interception - - Verify the relation between a mobile application certificate and its owner - - -\anchor _abbreviations -## 1.3 Abbreviations -Abbreviations used in this document please find in the table below. -| Abbreviation | Expansion | -|------------------|----------------------------------| -| | | - -Here need to be added all component-specific terms, as -| TA | Transport Adapter | - - -Definitions used in this document are in the table below. - -| Definition | Description | -|------------------|-----------------------------------| -| | | - -Here need to be added all component-specific terms, as -| WebSocket | a protocol providing full-duplex communication channels over a single TCP connection | - -*/ -//----------------------------------------------------------- -/** -\page _detail_design 2. Component detail design -\anchor _design_solutions -### 2.1 Design solutions -The following design approaches and pattern was used for : - - -Here need to be added GoF (or other) SW design patterns, -technologies and approaches with short description -Example: - - Command design pattern is used to treat requests as an object that provides - possibility to add new request without existing code modification - - Factory method pattern design used for SSLContext objects creation - + It also guaranty correctness of SSLContext destruction by the - same Compiled SecurityManger object - - All database reading are cached by CacheManager class, which - guaranty meeting timing contrariness - - SQLite database was chosen as a lightweight, embedded, transactional SQL database engine - - -\anchor _class_structure -### 2.2 Class Structure -The following UML class digram shows the component classes structure. - - -Here need to be added class diagram -Example: - ![Security Manager class diagram](sm_class_digram.png) -For adding images in MD format follow https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images -As a tool for image preparing could be used Gliffy digram -https://adc.luxoft.com/confluence/pages/createpage.action?showGliffyMacro=true&fromCreateDialog=true&spaceKey=APPLINK -OR plantuml diagram -http://plantuml.com/classes.html -Note: Source files of diagram and output images need to be also committed to git. - - -For more information about class digram follow: -- http://www.uml-diagrams.org/class-diagrams-overview.html -- https://sourcemaking.com/uml/modeling-it-systems/structural-view/class-diagram - -\anchor _sequence_diagram -### 2.3 Sequence diagram -The following UML sequence digram shows how objects operate with one another and in what order. - - -Here need to be added sequence diagram -Example: - Short description - ![Connection](connection.png) - ![job](job.png) - ![disconnection](disconnection.png) -For adding images in MD format follow https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images -As a tool for image preparing could be used Gliffy digram -https://adc.luxoft.com/confluence/pages/createpage.action?showGliffyMacro=true&fromCreateDialog=true&spaceKey=APPLINK -OR plantuml diagram -http://plantuml.com/sequence.html -Note: Source files of diagram and output images need to be also committed to git. - - -For more information about sequence digram follow: -- http://www.uml-diagrams.org/sequence-diagrams.html -- https://sourcemaking.com/uml/modeling-it-systems/external-view/use-case-sequence-diagram - -\anchor _state_chart -### 2.4 State chart diagram -The following UML state digram shows the component life cycle states. - - -Here need to be added state diagram -Example: - ![StateControllerImpl state](state_contoroller_states.png) -For adding images in MD format follow https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images -As a tool for image preparing could be used Gliffy digram -https://adc.luxoft.com/confluence/pages/createpage.action?showGliffyMacro=true&fromCreateDialog=true&spaceKey=APPLINK -OR plantuml diagram -http://plantuml.com/state.html -Note: Source files of diagram and output images need to be also committed to git. - - -For more information about class digram follow: -- http://www.uml-diagrams.org/state-machine-diagrams.html -*/ -//----------------------------------------------------------- -/** -\page _interfaces 3. Component Interfaces -\anchor _public_interfaces -### 3.1 Public interfaces description - provides functionality with following interfaces: - - -Here need to be added a list of external interfaces -Example: - - security_manager::SecurityManager - - security_manager::SecurityManagerListener - - security_manager::SSLContext -(!) All link will be auto-added by doxygen -For more auto-linking follow - https://www.stack.nl/~dimitri/doxygen/manual/autolink.html#linkclass - - -\anchor _internal_interfaces -### 3.2 Internal interfaces description -The following interfaces are provided by component for internal usage only: - - -Here need to be added a list of internal interfaces -Example: - - security_manager::CryptoManager - - security_manager::CryptoManagerSettings - - security_manager::SecurityQuery - - -\anchor _derived_interfaces -### 3.3 Derived interfaces and dependencies - required following 3d-party libraries: - - -Here need to be added a list of libraries -Example: - - OpenSSL library v 1.0.1g and higher to meet TLS cipher restricts - - -The following interfaces are required by component: -- \ref src/components/include/utils Utils - - -Here need to be added a list of external interfaces -Example: - - protocol_handler::ProtocolObserver for getting Protocol notifications - - implements protocol_handler::SessionObserver for providing SSLContext object managing - - [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) : - + SSL_library_init() - registers the available SSL/TLS ciphers and digests. -All link will be auto-added by doxygen - -*/ -//----------------------------------------------------------- -/** -\page _data_structure_resources 4. Component data and resources -\anchor _data_structure -### 4.1 Element Data Structure -The following data types are used by the Component: - - -Here need to be added a list of component data types -Example: - - security_manager::SecurityQuery - - protocol_handler::ProtocolPacket -All link will be auto-added by doxygen - - -The format of processing/saving/loading data is: - - -Here need to be added a list of formats -Example: - - Json data according to APPLINK-19421 - - Binary data array according to Ford Protocol Specification - + https://github.com/smartdevicelink/protocol_spec - - PEM certificates according to APPLINK-21512 -All link will be auto-added by doxygen - - -\anchor _resources -### 4.2 Resource usage -The following system resources are used by the Component: - - -Here need to be added all resource-related information -All file, database or network reading -An amount of processing by component data -Example: - Resumption uses QBD/JSON database with configurable limitation 10 Mb - Request Controller Handle a configured amount of RPCs: - - A XXX count of messages from application in NONE level - + - - A YYY count of messages per second for each application - + - (!) In case of no such restrict it need to be clarified (!) - -*/ -//----------------------------------------------------------- -/** -\page _references_and_history 5. References and history -\anchor _references -### 5.1 References -- [Software Architecture Document](https://smartdevicelink.com/en/guides/core/software-architecture-document/table-of-contents/) - - -Here need to be added a list of all related to component functionality -references, including 3d-party libraries, documentation, requirements -Example: - - [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) - - [SQLite Documents](https://www.sqlite.org/docs.html) - - -\anchor _history -### 5.2 Document history -Document change history - -| Version | Data | Author/Editor | Change description | -|-------------|------------|-----------------------------|---------------------| - -Example: -| 0.1 | MM/DD/YYYY | [Name](Github account link) | Initially created | -For more details follow -https://adc.luxoft.com/confluence/display/PORTAL/Documentation+Control+Guideline#DocumentationControlGuideline-DocumentVersion - - -Document approve history - -| Version | Data | Author/Editor | Change description | -|-------------|------------|-----------------------------|---------------------| - -Example: -| 0.1 | MM/DD/YYYY | [Name](Github account link) | Initially created | - - -For more precise document change history follow github history - - -Example for this template: -- https://github.com/smartdevicelink/sdl_core/commits/master/docs/software_detailed_design_template.dox -- https://github.com/smartdevicelink/sdl_core/commits/develop/docs/software_detailed_design_template.dox - -*/ \ No newline at end of file diff --git a/docs/SDL.SDD.Template.dox b/docs/SDL.SDD.Template.dox new file mode 100644 index 0000000000..435da665db --- /dev/null +++ b/docs/SDL.SDD.Template.dox @@ -0,0 +1,355 @@ +/** +\cond FALSE +------ Design document template explanation ------- +This is a SW Detailed Design template for each SDl component update. +The original QCA template with more detail description is available at Luxoft portal +https://adc.luxoft.com/confluence/display/PORTAL/Software+Detailed+Design+Template + +---------------------- HOWTO ----------------------- +For adding new component documentation please follow this steps: +1. Copy this document to the 'doc' subdirectory in the Component working directory with a new name + - Example: + + src/components/transport_manager/docs/SDL.SDD.TM.dox + + src/components/utils/docs/SDL.SDD.Utils.dox + - https://adc.luxoft.com/confluence/display/PORTAL/Documentation+Control+Guideline#DocumentationControlGuideline-DocumentNaming +2. Replace with a correct naming according to SAD naming + - Name examples: + Application Manager, Connection Handler + - Replace examples: + ~ sed -i 's//Utils/g' SDL.SDD.Utils.dox +3. Replace with a shot unique name + - Something like app_manage, connection_handler, policy + - It shall be one word without spaces and special symbols except '_' + - Replace examples: + ~ sed -i 's//connection_handler/g' SDL.SDD.Utils.dox + Note: After that step all Doxygen tags becomes working well and IDE could be used +4. Add reference in mainpage.dox Table of Content using used in p.3 +5. Replace blocks marked as following with a content according to instructions in these blocks + - Each block starts as + - Each block ends as + - If chapter content is not applicable for a Component update it with "Not applicable, since/because of ." +6. Update source code doxygen comments for mentioning entities in the following SDD chapter: + - Public and private interfaces from chapter 3 + - Data types from chapter 4.2 +7. Update project Doxygen file with path to new images + * IMAGE_PATH parameter +8. Remove this template explanation from cond to endcond tags + +General notes/reminders: +- Commit both: images and them source to the git repository +- SDD file extension shall be 'dox' +- the preferable path for SDD is src/components/COMPONENT/docs +- the preferable path for SDD images is src/components/COMPONENT/docs/assets + +For more information, please follow: +- Doxygen documentation + http://www.stack.nl/~dimitri/doxygen/manual/index.html +- Markdown support by doxygen + http://www.stack.nl/~dimitri/doxygen/manual/markdown.html +- Text-base UML tool + http://plantuml.com/ +- Article "Providing design documentation with code changes" + https://github.com/smartdevicelink/sdl_core/wiki/Providing-design-documentation-with-code-changes + +--------------------------------------------- +\endcond +\page Detailed Design +## Table of contents +- \subpage _intoduction + + \ref _rationale "1.1 Rationale" + + \ref _scope "1.2 Scope" + + \ref _abbreviations "1.3 Abbreviations" +- \subpage _detail_design + + \ref _design_solutions "2.1 Design solutions" + + \ref _class_structure "2.2 Class Structure" + + \ref _sequence_diagram "2.3 Sequence diagram" + + \ref _state_chart "2.4 State chart diagram" +- \subpage _interfaces + + \ref _public_interfaces "3.1 Public interfaces description" + + \ref _internal_interfaces "3.2 Internal interfaces description" + + \ref _derived_interfaces "3.3 Derived interfaces and dependencies" +- \subpage _data_structure_resources + + \ref _data_structure "4.1 Element Data Structure" + + \ref _resources "4.2 Resource usage" +- \subpage _references_and_history + + \ref _references "5.1 References" + + \ref _history "5.2 Document history change and approve" +*/ +//----------------------------------------------------------- +/** +\page _intoduction 1. Introduction +The document is intended to support software developers, +maintenance and integration engineers with sufficient, +detailed information concerning the design, development and +deployment concepts, to accomplish their respective tasks without reliance on the authors. + +\anchor _rationale +## 1.1 Rationale + implements SDL Architectural Solution according to: + + +Here need to be a link SAD Components View and Requirements if applicable) +Example: + https://smartdevicelink.com/en/guides/core/software-architecture-document/components-view/#hmi-message-handler + + +\anchor _scope +## 1.2 Scope + extracted as a separate component for + + +Here need to be added a reason and short description of the components functionality +Example: + Security Manager component extracted as a separate module for + SDL channel data protection. + This components is used to : + - Provide security communications + - Protect income and outcome business layer data from interception + - Verify the relation between a mobile application certificate and its owner + + +\anchor _abbreviations +## 1.3 Abbreviations +Abbreviations used in this document please find in the table below. +| Abbreviation | Expansion | +|------------------|----------------------------------| +| | | + +Here need to be added all component-specific terms, as +| TA | Transport Adapter | + + +Definitions used in this document are in the table below. + +| Definition | Description | +|------------------|-----------------------------------| +| | | + +Here need to be added all component-specific terms, as +| WebSocket | a protocol providing full-duplex communication channels over a single TCP connection | + +*/ +//----------------------------------------------------------- +/** +\page _detail_design 2. Component detail design +\anchor _design_solutions +### 2.1 Design solutions +The following design approaches and pattern was used for : + + +Here need to be added GoF (or other) SW design patterns, +technologies and approaches with short description +Example: + - Command design pattern is used to treat requests as an object that provides + possibility to add new request without existing code modification + - Factory method pattern design used for SSLContext objects creation + + It also guaranty correctness of SSLContext destruction by the + same Compiled SecurityManger object + - All database reading are cached by CacheManager class, which + guaranty meeting timing contrariness + - SQLite database was chosen as a lightweight, embedded, transactional SQL database engine + + +\anchor _class_structure +### 2.2 Class Structure +The following UML class diagram shows the component classes structure. + + +Here need to be added class diagram +Example: + ![Security Manager class diagram](sm_class_diagram.png) +For adding images in MD format follow https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images +As a tool for image preparing could be used Gliffy diagram +https://adc.luxoft.com/confluence/pages/createpage.action?showGliffyMacro=true&fromCreateDialog=true&spaceKey=APPLINK +OR plantuml diagram +http://plantuml.com/classes.html +Note: Source files of diagram and output images need to be also committed to git. + + +For more information about class diagram follow: +- http://www.uml-diagrams.org/class-diagrams-overview.html +- https://sourcemaking.com/uml/modeling-it-systems/structural-view/class-diagram + +\anchor _sequence_diagram +### 2.3 Sequence diagram +The following UML sequence diagram shows how objects operate with one another and in what order. + + +Here need to be added sequence diagram +Example: + Short description + ![Connection](connection.png) + ![job](job.png) + ![disconnection](disconnection.png) +For adding images in MD format follow https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images +As a tool for image preparing could be used Gliffy diagram +https://adc.luxoft.com/confluence/pages/createpage.action?showGliffyMacro=true&fromCreateDialog=true&spaceKey=APPLINK +OR plantuml diagram +http://plantuml.com/sequence.html +Note: Source files of diagram and output images need to be also committed to git. + + +For more information about sequence diagram follow: +- http://www.uml-diagrams.org/sequence-diagrams.html +- https://sourcemaking.com/uml/modeling-it-systems/external-view/use-case-sequence-diagram + +\anchor _state_chart +### 2.4 State chart diagram +The following UML state diagram shows the component life cycle states. + + +Here need to be added state diagram +Example: + ![StateControllerImpl state](state_contoroller_states.png) +For adding images in MD format follow https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images +As a tool for image preparing could be used Gliffy diagram +https://adc.luxoft.com/confluence/pages/createpage.action?showGliffyMacro=true&fromCreateDialog=true&spaceKey=APPLINK +OR plantuml diagram +http://plantuml.com/state.html +Note: Source files of diagram and output images need to be also committed to git. + + +For more information about class diagram follow: +- http://www.uml-diagrams.org/state-machine-diagrams.html +*/ +//----------------------------------------------------------- +/** +\page _interfaces 3. Component Interfaces +\anchor _public_interfaces +### 3.1 Public interfaces description + provides functionality with following interfaces: + + +Here need to be added a list of external interfaces +Example: + - security_manager::SecurityManager + - security_manager::SecurityManagerListener + - security_manager::SSLContext +(!) All link will be auto-added by doxygen +For more auto-linking follow - https://www.stack.nl/~dimitri/doxygen/manual/autolink.html#linkclass + + +\anchor _internal_interfaces +### 3.2 Internal interfaces description +The following interfaces are provided by component for internal usage only: + + +Here need to be added a list of internal interfaces +Example: + - security_manager::CryptoManager + - security_manager::CryptoManagerSettings + - security_manager::SecurityQuery + + +\anchor _derived_interfaces +### 3.3 Derived interfaces and dependencies + required following 3d-party libraries: + + +Here need to be added a list of libraries +Example: + - OpenSSL library v 1.0.1g and higher to meet TLS cipher restricts + + +The following interfaces are required by component: +- \ref src/components/include/utils Utils + + +Here need to be added a list of external interfaces +Example: + - protocol_handler::ProtocolObserver for getting Protocol notifications + - implements protocol_handler::SessionObserver for providing SSLContext object managing + - [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) : + + SSL_library_init() - registers the available SSL/TLS ciphers and digests. +All link will be auto-added by doxygen + +*/ +//----------------------------------------------------------- +/** +\page _data_structure_resources 4. Component data and resources +\anchor _data_structure +### 4.1 Element Data Structure +The following data types are used by the Component: + + +Here need to be added a list of component data types +Example: + - security_manager::SecurityQuery + - protocol_handler::ProtocolPacket +All link will be auto-added by doxygen + + +The format of processing/saving/loading data is: + + +Here need to be added a list of formats +Example: + - Json data according to APPLINK-19421 + - Binary data array according to SDL Protocol Specification + + https://github.com/smartdevicelink/protocol_spec + - PEM certificates according to APPLINK-21512 +All link will be auto-added by doxygen + + +\anchor _resources +### 4.2 Resource usage +The following system resources are used by the Component: + + +Here need to be added all resource-related information +All file, database or network reading +An amount of processing by component data +Example: + Resumption uses QBD/JSON database with configurable limitation 10 Mb + Request Controller Handle a configured amount of RPCs: + - A XXX count of messages from application in NONE level + + + - A YYY count of messages per second for each application + + + (!) In case of no such restrict it need to be clarified (!) + +*/ +//----------------------------------------------------------- +/** +\page _references_and_history 5. References and history +\anchor _references +### 5.1 References +- [Software Architecture Document](https://smartdevicelink.com/en/docs/sdl-core/master/software-architecture-document/table-of-contents/) + + +Here need to be added a list of all related to component functionality +references, including 3d-party libraries, documentation, requirements +Example: + - [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) + - [SQLite Documents](https://www.sqlite.org/docs.html) + + +\anchor _history +### 5.2 Document history +Document change history + +| Version | Data | Author/Editor | Change description | +|-------------|------------|-----------------------------|---------------------| + +Example: +| 0.1 | MM/DD/YYYY | [Name](Github account link) | Initially created | +For more details follow +https://adc.luxoft.com/confluence/display/PORTAL/Documentation+Control+Guideline#DocumentationControlGuideline-DocumentVersion + + +Document approve history + +| Version | Data | Author/Editor | Change description | +|-------------|------------|-----------------------------|---------------------| + +Example: +| 0.1 | MM/DD/YYYY | [Name](Github account link) | Initially created | + + +For more precise document change history follow github history - + +Example for this template: +- https://github.com/smartdevicelink/sdl_core/commits/master/docs/SDL.SDD.Template.dox +- https://github.com/smartdevicelink/sdl_core/commits/develop/docs/SDL.SDD.Template.dox + +*/ \ No newline at end of file diff --git a/docs/mainpage.dox b/docs/mainpage.dox index 91ee95fc26..08ef020594 100644 --- a/docs/mainpage.dox +++ b/docs/mainpage.dox @@ -1,9 +1,9 @@ /** * \mainpage Software Detail Design Documentation * - * This documents contain SW detailed design information fro each [SmartDeviceLink component](https://smartdevicelink.com/en/guides/core/software-architecture-document/components-view/). + * This documents contain SW detailed design information fro each [SmartDeviceLink component](https://smartdevicelink.com/en/docs/sdl-core/master/software-architecture-document/components-view/). * - * For getting SmartDeviceLink overview, please, refer to [Software Architecture Document](https://smartdevicelink.com/en/docs/core/master/software-architecture-document/table-of-contents/) + * For getting SmartDeviceLink overview, please, refer to [Software Architecture Document](https://smartdevicelink.com/en/docs/sdl-core/master/software-architecture-document/table-of-contents/) * * ##Table of contents * - \ref security_manager diff --git a/src/components/security_manager/docs/FORD.OpenSDL.SDD.Security.dox b/src/components/security_manager/docs/FORD.OpenSDL.SDD.Security.dox deleted file mode 100644 index 42da2364d3..0000000000 --- a/src/components/security_manager/docs/FORD.OpenSDL.SDD.Security.dox +++ /dev/null @@ -1,241 +0,0 @@ -/** -\page security_manager Security Manager Detailed Design -## Table of contents -- \subpage security_manager_intoduction - + \ref security_manager_rationale "1.1 Rationale" - + \ref security_manager_scope "1.2 Scope" - + \ref security_manager_abbreviations "1.3 Abbreviations" -- \subpage security_manager_detail_design - + \ref security_manager_design_solutions "2.1 Design solutions" - + \ref security_manager_class_structure "2.2 Class Structure" - + \ref security_manager_sequence_diagram "2.3 Sequence diagram" - + \ref security_manager_state_chart "2.4 State chart diagram" -- \subpage security_manager_interfaces - + \ref security_manager_public_interfaces "3.1 Public interfaces description" - + \ref security_manager_internal_interfaces "3.2 Internal interfaces description" - + \ref security_manager_derived_interfaces "3.3 Derived interfaces and dependencies" -- \subpage security_manager_data_structure_resources - + \ref security_manager_data_structure "4.1 Element Data Structure" - + \ref security_manager_resources "4.2 Resource usage" -- \subpage security_manager_references_and_history - + \ref security_manager_references "5.1 References" - + \ref security_manager_history "5.2 Document history change and approve" -*/ -//----------------------------------------------------------- -/** -\page security_manager_intoduction 1 Introduction -The document is intended to support software developers, -maintenance and integration engineers with sufficient, -detailed information concerning the design, development and -deployment concepts, to accomplish their respective tasks without reliance on the authors. - -\anchor security_manager_rationale -## 1.1 Rationale -Security Manager implements SDL Architectural Solution according to: -- https://smartdevicelink.com/en/guides/core/software-architecture-document/components-view/#security-manager - -\anchor security_manager_scope -## 1.2 Scope -Security Manager component extracted as a separate module for -Ford channel data protection. -This components is used to: -- Provide security communications -- Protect income and outcome business layer data from interception -- Verify the relation between a mobile application certificate and its owner - -\anchor security_manager_abbreviations -## 1.3 Abbreviations -Abbreviations used in this document please find in the table below. -| Abbreviation | Expansion | -|------------------|----------------------------------| -| SSL | Secure Sockets Layer cryptographic protocol | -| TLS | Transport Layer Security cryptographic protocol | -| DTLS | Datagram TLS cryptographic protocol | - -Definitions used in this document are in the table below. - -| Definition | Description | -|---------------------------|-----------------------------------| -| SSL/TLS/DTL | Cryptographic protocols that provide communications security over a computer network | -*/ -//----------------------------------------------------------- -/** -\page security_manager_detail_design 2 Component detail design -\anchor security_manager_design_solutions -### 2.1 Design solutions -The following design approaches and pattern was used for Security Manager: -- Protection, creation and business logic is spitted to separates interfaces - + SecurityManager for handling Security queries from mobile side - + SSLContext provides for SSL connection establishing, encryption and decryption - + CryptoManager provides a factory for SSLContext -- [Abstract Factory pattern design](https://sourcemaking.com/design_patterns/abstract_factory) - used for SSLContext objects creation - + It also guaranty correctness of SSLContext destruction by the - same Compiled SecurityManager object - -#### Design description -security_manager::SSLContext is an interface for TLS connection establishing, data encryption and -decryption within this connection. -security_manager::SSLContextImpl implements SSLContext and wraps OpenSSL library handshake procedure, -encryption and decryption, contains handshake procedure error handling. -_Note:_ security_manager::SSLContext objects are stored in connection_handler::ConnectionHandlerImpl, -which implements protocol_handler::SessionObserver interface. - -security_manager::CryptoManager is an interface for SSLContext creation and destruction, -CA certificate update and last SSL error providing. -security_manager::CryptoManagerImpl implements security_manager::CryptoManager and hides -all OpenSSL initialization logics and SSL internal structures creation. - -security_manager::SecurityManager is a Facade of security_manager component and provides -external interface for security_manager::SSLContext creation and sending security error -via control service. -security_manager::SecurityManagerImpl implements security_manager::SecurityManager and -encapsulates control service data (security internal errors, handshake data) handling. - -security_manager::SecurityManagerListener is an interface for protection result notification -to other components. -security_manager::SecurityManagerListener is implemented in a protocol_handler::ProtocolHandlerImpl for sending -protocol layer response on handshake procedure finish. - - -\anchor security_manager_class_structure -### 2.2 Class Structure -The following UML class digram shows the component structure. -![Security Manager class diagram](sm_class_digram.png) -For more information about class digram follow: -- http://www.uml-diagrams.org/class-diagrams-overview.htqml -- https://sourcemaking.com/uml/modeling-it-systems/structural-view/class-diagram - -\anchor security_manager_sequence_diagram -### 2.3 Sequence diagram -The following UML sequence digram shows the component dynamic behavior. -For more information about sequence digram follow: -- http://www.uml-diagrams.org/sequence-diagrams.html -- https://sourcemaking.com/uml/modeling-it-systems/external-view/use-case-sequence-diagram - -Security first initialization on session: -![Start encryption](sm_sequence_digram_init.png) - -Security initialization for service on session with already initialized security: -![Initialization](sm_sequence_digram_verify.png) - -Decryption procedure: -![Decryption](sm_sequence_digram_decryption.png) - -Encryption procedure: -![Encryption](sm_sequence_digram_encryption.png) - -\anchor security_manager_state_chart -### 2.4 State chart diagram -Not applicable for Security Manager. -*/ -//----------------------------------------------------------- -/** -\page security_manager_interfaces 3 Component Interfaces -\anchor security_manager_public_interfaces -### 3.1 Public interfaces description -Security Manager provides functionality with following interfaces: -- security_manager::SecurityManager -- security_manager::SecurityManagerListener -- security_manager::SSLContext - -\anchor security_manager_internal_interfaces -### 3.2 Internal interfaces description -The following interfaces are provided by component for internal usage only: - - security_manager::CryptoManager - - security_manager::CryptoManagerSettings - -\anchor security_manager_derived_interfaces -### 3.3 Derived interfaces and dependencies -Security Manager required following 3d-party libraries: - - OpenSSL library v 1.0.1g and higher to meet TLS cipher restricts - -The following interfaces are required by component: -- \ref src/components/include/utils Utils -- protocol_handler::ProtocolObserver for getting Protocol notifications -- implements protocol_handler::SessionObserver for providing SSLContext object managing -- [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) - + [SSL_library_init()](https://www.openssl.org/docs/manmaster/ssl/SSL_library_init.html) - - registers the available SSL/TLS ciphers and digests. - + [SSL_METHOD](https://www.openssl.org/docs/manmaster/ssl/ssl.html) - - That's a dispatch structure describing the internal ssl library methods/functions which implement the various protocol versions (SSLv3 TLSv1, ...). It's needed to create an SSL_CTX. - + [(D)TLSv1(_1/2)_(server/client)_method, ] - (https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_new.html) - - TLS/SSL connections established with these methods will understand the TLSv1 protocol. - - A client will send out TLSv1 client hello messages and will indicate that it only understands TLSv1. A server will only understand TLSv1 client hello messages. - + [SSL_CTX_new](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_new.html) - - creates a new SSL_CTX object as framework to establish TLS/SSL enabled connections. - + [SSL_CTX_free](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_free.html) - - decrements the reference count of ctx, and removes the SSL_CTX object pointed to by ctx and frees up the allocated memory if the the reference count has reached 0. - + [SSL_CTX_use_certificate_file, SSL_CTX_use_PrivateKey_file, SSL_CTX_check_private_key] - (https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_use_certificate.html) - - load certificate and key data - + [SSL_CTX_set_cipher_list](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_cipher_list.html) - - choose list of available [cipher suites](https://en.wikipedia.org/wiki/Cipher_suite) - + [SSL_new](https://www.openssl.org/docs/manmaster/ssl/SSL_new.html) - - creates a new SSL structure which is needed to hold the data for a TLS/SSL connection. The new structure inherits the settings of the underlying context ctx: connection method, options, verification settings, timeout settings. - + [SSL_CTX_set_verify](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_verify.html) - - sets the verification flags for ctx to be mode and specifies the verify_callback function to be used. - + [SSL_CTX_load_verify_locations](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_load_verify_locations.html) - - specifies the locations for ctx, at which CA certificates for verification purposes are located. - + [X509_STORE_CTX_get_error, X509_STORE_CTX_set_error](https://www.openssl.org/docs/manmaster/crypto/X509_STORE_CTX_set_error.html) - - get or set certificate verification status information - + [SSL_do_handshake](https://www.openssl.org/docs/manmaster/ssl/SSL_do_handshake.html) - - waits for a SSL/TLS handshake to take place. If the connection is in client mode, the handshake will be started. - - The handshake routines may have to be explicitly set in advance using either SSL_set_connect_state or SSL_set_accept_state. - + [SSL_shutdown](https://www.openssl.org/docs/manmaster/ssl/SSL_shutdown.html) - - shuts down an active TLS/SSL connection. It sends the "close notify" shutdown alert to the peer. - + [SSL_free](https://www.openssl.org/docs/manmaster/ssl/SSL_free.html) - - decrements the reference count of ssl, and removes the SSL structure pointed to by ssl - - frees up the allocated memory if the reference count has reached 0. - +[BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all](https://www.openssl.org/docs/manmaster/crypto/bio.html) - - BIO allocation and freeing functions - + [BIO_read, BIO_write, BIO_gets, BIO_puts](https://www.openssl.org/docs/manmaster/crypto/BIO_read.html) - - BIO I/O functions -*/ -//----------------------------------------------------------- -/** -\page security_manager_data_structure_resources 4 Component data and resources -\anchor security_manager_data_structure -### 4.1 Element Data Structure -The following data types are used by the Component: - - security_manager::SecurityQuery - - protocol_handler::ProtocolPacket - -The format of certificate data exchange is: - - PEM certificates according to [APPLINK-21512](https://adc.luxoft.com/jira/browse/APPLINK-21512) - -\anchor security_manager_resources -### 4.2 Resource usage -Security Manager get an assess to certificate and private key -data using OpenSSl API. -*/ -//----------------------------------------------------------- -/** -\page security_manager_references_and_history 5 References and history -\anchor security_manager_references -### 5.1 References -- [Software Architecture Document](https://smartdevicelink.com/en/guides/core/software-architecture-document/table-of-contents/) -- [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) -- [TLS 1.1 RFC](https://tools.ietf.org/html/rfc4346) -- [TLS 1.2 RFC](https://tools.ietf.org/html/rfc5246) -- [DTLS RFC](https://tools.ietf.org/html/rfc4347) - -\anchor security_manager_history -### 5.2 Document history -Document change history - -| Version | Data | Author/Editor | Change description | -|-------------|------------|----------------------------------------|---------------------| -| 0.1 | 08/11/2016 | [EZamakhov](https://github.com/pestOO) | Initial version from the previous [SDL SDD](https://adc.luxoft.com/confluence/pages/viewpage.action?pageId=279677125) | - -Document approve history - -| Version | Data | Author/Editor | Change description | -|-------------|------------|-----------------------------|---------------------| -| | | | | - -For more precise document change history follow github history - -- https://github.com/smartdevicelink/sdl_core/commits/master/src/components/security_manager/docs/security_manager_software_detailed_design.dox -- https://github.com/smartdevicelink/sdl_core/commits/develop/src/components/security_manager/docs/security_manager_software_detailed_design.dox -*/ \ No newline at end of file diff --git a/src/components/security_manager/docs/SDL.SDD.Security.dox b/src/components/security_manager/docs/SDL.SDD.Security.dox new file mode 100644 index 0000000000..ba35bc116e --- /dev/null +++ b/src/components/security_manager/docs/SDL.SDD.Security.dox @@ -0,0 +1,241 @@ +/** +\page security_manager Security Manager Detailed Design +## Table of contents +- \subpage security_manager_intoduction + + \ref security_manager_rationale "1.1 Rationale" + + \ref security_manager_scope "1.2 Scope" + + \ref security_manager_abbreviations "1.3 Abbreviations" +- \subpage security_manager_detail_design + + \ref security_manager_design_solutions "2.1 Design solutions" + + \ref security_manager_class_structure "2.2 Class Structure" + + \ref security_manager_sequence_diagram "2.3 Sequence diagram" + + \ref security_manager_state_chart "2.4 State chart diagram" +- \subpage security_manager_interfaces + + \ref security_manager_public_interfaces "3.1 Public interfaces description" + + \ref security_manager_internal_interfaces "3.2 Internal interfaces description" + + \ref security_manager_derived_interfaces "3.3 Derived interfaces and dependencies" +- \subpage security_manager_data_structure_resources + + \ref security_manager_data_structure "4.1 Element Data Structure" + + \ref security_manager_resources "4.2 Resource usage" +- \subpage security_manager_references_and_history + + \ref security_manager_references "5.1 References" + + \ref security_manager_history "5.2 Document history change and approve" +*/ +//----------------------------------------------------------- +/** +\page security_manager_intoduction 1 Introduction +The document is intended to support software developers, +maintenance and integration engineers with sufficient, +detailed information concerning the design, development and +deployment concepts, to accomplish their respective tasks without reliance on the authors. + +\anchor security_manager_rationale +## 1.1 Rationale +Security Manager implements SDL Architectural Solution according to: +- https://smartdevicelink.com/en/docs/sdl-core/master/software-architecture-document/components-view/#security-manager + +\anchor security_manager_scope +## 1.2 Scope +Security Manager component extracted as a separate module for +SDL channel data protection. +This components is used to: +- Provide security communications +- Protect income and outcome business layer data from interception +- Verify the relation between a mobile application certificate and its owner + +\anchor security_manager_abbreviations +## 1.3 Abbreviations +Abbreviations used in this document please find in the table below. +| Abbreviation | Expansion | +|------------------|----------------------------------| +| SSL | Secure Sockets Layer cryptographic protocol | +| TLS | Transport Layer Security cryptographic protocol | +| DTLS | Datagram TLS cryptographic protocol | + +Definitions used in this document are in the table below. + +| Definition | Description | +|---------------------------|-----------------------------------| +| SSL/TLS/DTL | Cryptographic protocols that provide communications security over a computer network | +*/ +//----------------------------------------------------------- +/** +\page security_manager_detail_design 2 Component detail design +\anchor security_manager_design_solutions +### 2.1 Design solutions +The following design approaches and pattern was used for Security Manager: +- Protection, creation and business logic is spitted to separates interfaces + + SecurityManager for handling Security queries from mobile side + + SSLContext provides for SSL connection establishing, encryption and decryption + + CryptoManager provides a factory for SSLContext +- [Abstract Factory pattern design](https://sourcemaking.com/design_patterns/abstract_factory) + used for SSLContext objects creation + + It also guaranty correctness of SSLContext destruction by the + same Compiled SecurityManager object + +#### Design description +security_manager::SSLContext is an interface for TLS connection establishing, data encryption and +decryption within this connection. +security_manager::SSLContextImpl implements SSLContext and wraps OpenSSL library handshake procedure, +encryption and decryption, contains handshake procedure error handling. +_Note:_ security_manager::SSLContext objects are stored in connection_handler::ConnectionHandlerImpl, +which implements protocol_handler::SessionObserver interface. + +security_manager::CryptoManager is an interface for SSLContext creation and destruction, +CA certificate update and last SSL error providing. +security_manager::CryptoManagerImpl implements security_manager::CryptoManager and hides +all OpenSSL initialization logics and SSL internal structures creation. + +security_manager::SecurityManager is a Facade of security_manager component and provides +external interface for security_manager::SSLContext creation and sending security error +via control service. +security_manager::SecurityManagerImpl implements security_manager::SecurityManager and +encapsulates control service data (security internal errors, handshake data) handling. + +security_manager::SecurityManagerListener is an interface for protection result notification +to other components. +security_manager::SecurityManagerListener is implemented in a protocol_handler::ProtocolHandlerImpl for sending +protocol layer response on handshake procedure finish. + + +\anchor security_manager_class_structure +### 2.2 Class Structure +The following UML class diagram shows the component structure. +![Security Manager class diagram](sm_class_diagram.png) +For more information about class diagram follow: +- http://www.uml-diagrams.org/class-diagrams-overview.htqml +- https://sourcemaking.com/uml/modeling-it-systems/structural-view/class-diagram + +\anchor security_manager_sequence_diagram +### 2.3 Sequence diagram +The following UML sequence diagram shows the component dynamic behavior. +For more information about sequence diagram follow: +- http://www.uml-diagrams.org/sequence-diagrams.html +- https://sourcemaking.com/uml/modeling-it-systems/external-view/use-case-sequence-diagram + +Security first initialization on session: +![Start encryption](sm_sequence_diagram_init.png) + +Security initialization for service on session with already initialized security: +![Initialization](sm_sequence_diagram_verify.png) + +Decryption procedure: +![Decryption](sm_sequence_diagram_decryption.png) + +Encryption procedure: +![Encryption](sm_sequence_diagram_encryption.png) + +\anchor security_manager_state_chart +### 2.4 State chart diagram +Not applicable for Security Manager. +*/ +//----------------------------------------------------------- +/** +\page security_manager_interfaces 3 Component Interfaces +\anchor security_manager_public_interfaces +### 3.1 Public interfaces description +Security Manager provides functionality with following interfaces: +- security_manager::SecurityManager +- security_manager::SecurityManagerListener +- security_manager::SSLContext + +\anchor security_manager_internal_interfaces +### 3.2 Internal interfaces description +The following interfaces are provided by component for internal usage only: + - security_manager::CryptoManager + - security_manager::CryptoManagerSettings + +\anchor security_manager_derived_interfaces +### 3.3 Derived interfaces and dependencies +Security Manager required following 3d-party libraries: + - OpenSSL library v 1.0.1g and higher to meet TLS cipher restricts + +The following interfaces are required by component: +- \ref src/components/include/utils Utils +- protocol_handler::ProtocolObserver for getting Protocol notifications +- implements protocol_handler::SessionObserver for providing SSLContext object managing +- [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) + + [SSL_library_init()](https://www.openssl.org/docs/manmaster/ssl/SSL_library_init.html) + - registers the available SSL/TLS ciphers and digests. + + [SSL_METHOD](https://www.openssl.org/docs/manmaster/ssl/ssl.html) + - That's a dispatch structure describing the internal ssl library methods/functions which implement the various protocol versions (SSLv3 TLSv1, ...). It's needed to create an SSL_CTX. + + [(D)TLSv1(_1/2)_(server/client)_method, ] + (https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_new.html) + - TLS/SSL connections established with these methods will understand the TLSv1 protocol. + - A client will send out TLSv1 client hello messages and will indicate that it only understands TLSv1. A server will only understand TLSv1 client hello messages. + + [SSL_CTX_new](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_new.html) + - creates a new SSL_CTX object as framework to establish TLS/SSL enabled connections. + + [SSL_CTX_free](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_free.html) + - decrements the reference count of ctx, and removes the SSL_CTX object pointed to by ctx and frees up the allocated memory if the the reference count has reached 0. + + [SSL_CTX_use_certificate_file, SSL_CTX_use_PrivateKey_file, SSL_CTX_check_private_key] + (https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_use_certificate.html) + - load certificate and key data + + [SSL_CTX_set_cipher_list](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_cipher_list.html) + - choose list of available [cipher suites](https://en.wikipedia.org/wiki/Cipher_suite) + + [SSL_new](https://www.openssl.org/docs/manmaster/ssl/SSL_new.html) + - creates a new SSL structure which is needed to hold the data for a TLS/SSL connection. The new structure inherits the settings of the underlying context ctx: connection method, options, verification settings, timeout settings. + + [SSL_CTX_set_verify](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_verify.html) + - sets the verification flags for ctx to be mode and specifies the verify_callback function to be used. + + [SSL_CTX_load_verify_locations](https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_load_verify_locations.html) + - specifies the locations for ctx, at which CA certificates for verification purposes are located. + + [X509_STORE_CTX_get_error, X509_STORE_CTX_set_error](https://www.openssl.org/docs/manmaster/crypto/X509_STORE_CTX_set_error.html) + - get or set certificate verification status information + + [SSL_do_handshake](https://www.openssl.org/docs/manmaster/ssl/SSL_do_handshake.html) + - waits for a SSL/TLS handshake to take place. If the connection is in client mode, the handshake will be started. + - The handshake routines may have to be explicitly set in advance using either SSL_set_connect_state or SSL_set_accept_state. + + [SSL_shutdown](https://www.openssl.org/docs/manmaster/ssl/SSL_shutdown.html) + - shuts down an active TLS/SSL connection. It sends the "close notify" shutdown alert to the peer. + + [SSL_free](https://www.openssl.org/docs/manmaster/ssl/SSL_free.html) + - decrements the reference count of ssl, and removes the SSL structure pointed to by ssl + - frees up the allocated memory if the reference count has reached 0. + +[BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all](https://www.openssl.org/docs/manmaster/crypto/bio.html) + - BIO allocation and freeing functions + + [BIO_read, BIO_write, BIO_gets, BIO_puts](https://www.openssl.org/docs/manmaster/crypto/BIO_read.html) + - BIO I/O functions +*/ +//----------------------------------------------------------- +/** +\page security_manager_data_structure_resources 4 Component data and resources +\anchor security_manager_data_structure +### 4.1 Element Data Structure +The following data types are used by the Component: + - security_manager::SecurityQuery + - protocol_handler::ProtocolPacket + +The format of certificate data exchange is: + - PEM certificates according to [APPLINK-21512](https://adc.luxoft.com/jira/browse/APPLINK-21512) + +\anchor security_manager_resources +### 4.2 Resource usage +Security Manager get an assess to certificate and private key +data using OpenSSl API. +*/ +//----------------------------------------------------------- +/** +\page security_manager_references_and_history 5 References and history +\anchor security_manager_references +### 5.1 References +- [Software Architecture Document](https://smartdevicelink.com/en/docs/sdl-core/master/software-architecture-document/table-of-contents/) +- [OpenSSL API](https://www.openssl.org/docs/manmaster/ssl/) +- [TLS 1.1 RFC](https://tools.ietf.org/html/rfc4346) +- [TLS 1.2 RFC](https://tools.ietf.org/html/rfc5246) +- [DTLS RFC](https://tools.ietf.org/html/rfc4347) + +\anchor security_manager_history +### 5.2 Document history +Document change history + +| Version | Data | Author/Editor | Change description | +|-------------|------------|----------------------------------------|---------------------| +| 0.1 | 08/11/2016 | [EZamakhov](https://github.com/pestOO) | Initial version from the previous [SDL SDD](https://adc.luxoft.com/confluence/pages/viewpage.action?pageId=279677125) | + +Document approve history + +| Version | Data | Author/Editor | Change description | +|-------------|------------|-----------------------------|---------------------| +| | | | | + +For more precise document change history follow github history - +- https://github.com/smartdevicelink/sdl_core/commits/master/src/components/security_manager/docs/SDL.SDD.Security.dox +- https://github.com/smartdevicelink/sdl_core/commits/develop/src/components/security_manager/docs/SDL.SDD.Security.dox +*/ \ No newline at end of file diff --git a/src/components/security_manager/docs/assets/sm_class_diagram.png b/src/components/security_manager/docs/assets/sm_class_diagram.png new file mode 100644 index 0000000000..61e300f4e7 Binary files /dev/null and b/src/components/security_manager/docs/assets/sm_class_diagram.png differ diff --git a/src/components/security_manager/docs/assets/sm_class_digram.png b/src/components/security_manager/docs/assets/sm_class_digram.png deleted file mode 100644 index 61e300f4e7..0000000000 Binary files a/src/components/security_manager/docs/assets/sm_class_digram.png and /dev/null differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_diagram_decryption.png b/src/components/security_manager/docs/assets/sm_sequence_diagram_decryption.png new file mode 100644 index 0000000000..849fe45b88 Binary files /dev/null and b/src/components/security_manager/docs/assets/sm_sequence_diagram_decryption.png differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_diagram_encryption.png b/src/components/security_manager/docs/assets/sm_sequence_diagram_encryption.png new file mode 100644 index 0000000000..66dffd265e Binary files /dev/null and b/src/components/security_manager/docs/assets/sm_sequence_diagram_encryption.png differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_diagram_init.png b/src/components/security_manager/docs/assets/sm_sequence_diagram_init.png new file mode 100644 index 0000000000..334b42b258 Binary files /dev/null and b/src/components/security_manager/docs/assets/sm_sequence_diagram_init.png differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_diagram_verify.png b/src/components/security_manager/docs/assets/sm_sequence_diagram_verify.png new file mode 100644 index 0000000000..cb040c918b Binary files /dev/null and b/src/components/security_manager/docs/assets/sm_sequence_diagram_verify.png differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_digram_decryption.png b/src/components/security_manager/docs/assets/sm_sequence_digram_decryption.png deleted file mode 100644 index 849fe45b88..0000000000 Binary files a/src/components/security_manager/docs/assets/sm_sequence_digram_decryption.png and /dev/null differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_digram_encryption.png b/src/components/security_manager/docs/assets/sm_sequence_digram_encryption.png deleted file mode 100644 index 66dffd265e..0000000000 Binary files a/src/components/security_manager/docs/assets/sm_sequence_digram_encryption.png and /dev/null differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_digram_init.png b/src/components/security_manager/docs/assets/sm_sequence_digram_init.png deleted file mode 100644 index 334b42b258..0000000000 Binary files a/src/components/security_manager/docs/assets/sm_sequence_digram_init.png and /dev/null differ diff --git a/src/components/security_manager/docs/assets/sm_sequence_digram_verify.png b/src/components/security_manager/docs/assets/sm_sequence_digram_verify.png deleted file mode 100644 index cb040c918b..0000000000 Binary files a/src/components/security_manager/docs/assets/sm_sequence_digram_verify.png and /dev/null differ -- cgit v1.2.1