1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
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.
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:
Security initialization for service on session with already initialized security:
Decryption procedure:
Encryption procedure:
\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
*/
|
