diff --git a/detailed_docs/INI_file_settings/SecurityManager_section.md b/detailed_docs/INI_file_settings/SecurityManager_section.md new file mode 100644 index 0000000..e411882 --- /dev/null +++ b/detailed_docs/INI_file_settings/SecurityManager_section.md @@ -0,0 +1,45 @@ +## [SecurityManager] + + +|Parameter|Type|Example|Description| +|:---|:----|:----|:----------| +|Protocol|String|Protocol = TLSv1.2, DTLSv1.0.|Supported protocol version TLSv1.2, DTLSv1.0.| +|ForceProtectedService|String|ForceProtectedService = Non|Force protected services (could be id's from 0x01 to 0xFF or “Non” value)| +|ForceUnprotectedService|String|ForceUnprotectedService = Non|Force unprotected services (could be id's from 0x01 to 0xFF or “Non” value) +|UpdateBeforeHours|Integer|UpdateBeforeHours = 24|The "UpdateBeforeHours" parameter defines the amount of time in hours for certificate expiration AND after expiration PTU sequence will be triggered| + +### Functional requirements + +1. +The "Protocol" parameter at [.ini file](https://github.com/smartdevicelink/sdl_core/blob/develop/src/appMain/smartDeviceLink.ini) of [Security Manager](https://github.com/smartdevicelink/sdl_core/blob/develop/src/appMain/smartDeviceLink.ini#L155) section defines the version of encryption protocol and must be used for: +a) protected service handshake +b) encryption +c) decryption by SDL + +SDL must + +support the following version of "Protocol": +-> TLSv1.2 +-> DTLSv1.0 + +2. +In case +the value of "Protocol" param is DTLSv1.0 at [Security Manager] section of .ini file +and mobile application successfully opens encrypted service (TLS handshake was succesfull) +and at least one of encrypted packet is **malformed** due to any reason + +SDL must +- ignore this malformed packet +- search for the next valid header +- continue processing of the next valid encrypted packet + +3. +The "ForceProtectedService" parameter defines services which cannot be started as unprotected + +_Info: Service type 0x07 (RPC service) cannot be the value of "ForceprotectedService"_ + +4. +The "ForceUnprotectedService" parameter defines services which cannot be started as protected OR delayed protected + +5. +The "UpdateBeforeHours" parameter defines the amount of time in hours for certificate expiration AND after expiration PTU sequence will be triggered. diff --git a/detailed_docs/INI_file_settings/ini_general_requirements.md b/detailed_docs/INI_file_settings/ini_general_requirements.md new file mode 100644 index 0000000..b037ff0 --- /dev/null +++ b/detailed_docs/INI_file_settings/ini_general_requirements.md @@ -0,0 +1,12 @@ +## Functional requirements + +1. +The SDL's configuration file must be located at SDL's root directory with 'smartdevicelink'.ini name + +2. +In case +.ini file is omited or is NOT presented at defined directory + +SDL must +start working sucessfully +retrieve and use default settings for correct work \ No newline at end of file diff --git a/detailed_docs/Protocol/assets/StartService_with_the_same_service_type.png b/detailed_docs/Protocol/assets/StartService_with_the_same_service_type.png new file mode 100644 index 0000000..b7bba8e Binary files /dev/null and b/detailed_docs/Protocol/assets/StartService_with_the_same_service_type.png differ diff --git a/detailed_docs/Protocol/assets/Start_session_and_open_services.png b/detailed_docs/Protocol/assets/Start_session_and_open_services.png new file mode 100644 index 0000000..8aa0ce4 Binary files /dev/null and b/detailed_docs/Protocol/assets/Start_session_and_open_services.png differ diff --git a/detailed_docs/Protocol/establishing_encrypted_service.md b/detailed_docs/Protocol/establishing_encrypted_service.md new file mode 100644 index 0000000..5bbee00 --- /dev/null +++ b/detailed_docs/Protocol/establishing_encrypted_service.md @@ -0,0 +1,55 @@ +## Functional requirements + +### Establishing encrypted service +1. +In case +mobile application successfully registers on SDL +and sends StartService (``, encrypted:true) +and TLS/DTLS handshake is successfull + +SDL must + +respond ACK via StartService over control service to mobile application +start secure `` service + +_Information:_ +1. Control Service provides the following features: +1.1. TLS/DTLS handshake (uses routine implemented by OpenSSDL library) +1.2. error handling + +2. +In case +mobile application successfully registers on SDL +and sends StartService (``, encrypted:true) +and TLS/DTLS handshake is failed + +SDL must behave +depending on ``requested for encryption: + +a. in case `` is a value of "ForceProtectedService" param of .ini file, +this ``must receive NACK from SDL (`` must not be started as non-encrypted). + +b. in case `` is not a value either of "ForceProtectedService" or "ForceUnprotectedService" params of .ini file, +this `` must receive ACK with encryption flag OFF (`` must be started as non-encrypted). + + +### Ending of encrypted service + +3. +In case +mobile application sends EndService (``) with valid `` over control service + +SDL must +- respond EndService_ACK to mobile app +- close all opened services on established session with this mobile application +- close the established session with this mobile application + +Information: +a. `` mobile application receives in case of opening session from SDL + +## Diagram + +StartService with the same service type + +![StartService with the same service type](https://github.com/smartdevicelink/sdl_requirements/blob/master/detailed_docs/Protocol/assets/StartService_with_the_same_service_type.png) + diff --git a/detailed_docs/Protocol/establishing_session.md b/detailed_docs/Protocol/establishing_session.md new file mode 100644 index 0000000..d1f6679 --- /dev/null +++ b/detailed_docs/Protocol/establishing_session.md @@ -0,0 +1,63 @@ +## Functional requirement + +### Establishing Session + +1. +In case +mobile application sends ControlFrame (V=``) +and SDL responds with ControlFrame (V=``) +and then SDL receives ControlFrame (V=``) from mobile application + +SDL must + +- respond ACK to the mobile app +- and start session over the highest supported version of protocol for both sides (mobile app and SDL) + +2. +In case +mobile application sends valid ControlFrame (``, SessionID=0, StartService, ServiceType=7) + +SDL must +respond ControlFrame(``, ``, StartService_ACK, ``) to mobile application + +_Information: +a. each new session should start 7 = RPC service firstly +b. hashID=4 bytes (located in payload) must be provided from SDL over ControlFrame_ + +3. +In case +mobile application requests to open a session (sends valid ControlFrame (``, SessionID=0, StartService, ServiceType=7) + +SDL must +generate a "hashID" of 4 bytes long and send in payload via StartService_ACK message to mobile application + + +SDL must + +- respond ACK to the mobile app +- and start session over the highest supported version of protocol for both sides (mobile application and SDL) + +### Ending Session + +4. +In case +mobile application sends EndService (ServiceType=7) with valid `` over control service + +SDL must + +- respond EndService_ACK to mobile app +- close all opened services on established session with this mobile app +- close the established session with this mobile app + +5. +In case +mobile application requests to close a session ( sends valid ControlFrame (``, SessionID, EndService, ServiceType=7) + +either without or with invalid hashID + +SDL must +respond with EndService_NACK and keep the session with this application open + +## Diagram + +![Start session and open services](https://github.com/smartdevicelink/sdl_requirements/blob/master/detailed_docs/Protocol/assets/Start_session_and_open_services.png)