- Proposal: SDL-0317
- Author: Kujtim Shala, Andrii Kalinich
- Status: Accepted with Revisions
- Impacted Platforms: [Protocol]
This proposal adds the documentation and specification around protected communication, encryption and handshake to the SDL protocol specification. It is a collaborated effort with Ford and Luxoft to protect the implemented SDL security from unexpected changes and to allow SDL Evolution proposals to improve it.
SDL has used protected services since the start of mobile navigation apps. Unfortunately the protocol specification doesn't contain a section around establishing a protected service with handshake and encryption. This leads to contradictory implementations in SDL Core and the app libraries. Recently we have identified a number of bugs in SDL Core and the app libraries which break with protected communication. These issues are difficult to address with the SDLC as there is no specification around protected communication that Core and the app libraries should follow. In order to resolve the issues there must be a proper specification within SDLC around protected communication.
The solution is to provide a new section into the protocol spec around security and protection. The baseline for this section is reverse engineered from SDL Core and the currently implemented behavior of the security manager but also existing documentation from SDL Core and the app libraries.
Because SDL Core already has a defined behavior, Protocol Spec must be changed accordingly to reflect this behavior:
| Field | Size | Description |
|---|---|---|
| E | 1 bit |
Encryption Flag 0x0 This packet is not encrypted 0x1 This packet is encrypted Note: Only available in Protocol Version 2 and higher. Must be always set to zero for a First Frame |
| Data Size | 32 bit |
... Frame Type = 0x02 (First Frame) 0x08 The data size for a first frame is always 8 bytes. In the payload, the first four bytes denote the Total Size of the data contained in all consecutive frames. This is always the size of whole non-encrypted payload (even if consecutive frames are encrypted). The second four bytes denote the number of consecutive frames following this one Frame Type = 0x01 or 0x03 (Single or Consecutive Frame) The total bytes in this frame's payload. If frame is encrypted this is the size of encrypted payload, otherwise size of non-encrypted payload. ... |
The following section should be added to the protocol spec:
The RPC service always needs to be started as unencrypted first, then it can be moved to an encrypted state by sending another StartService request containing an encryption flag set to 1 at a later point. Services of another type can be started as encrypted initially, i.e. it is not necessary to start them as unencrypted and then move to encrypted state using second StartService request (however such sequence of actions is also valid). See "7. Secured Communication" section for more details.
The TLS Payload is sent in a binary query header. The size is 12 bytes which matches the size of the RPC Payload Binary Header.
The security query is able to contain JSON data as well as binary data. During the handshake the TLS handshake data is sent as binary data. In case of an error, a notification is sent with an error code and error message as JSON data. See "Error handling" section for details.
| Binary Query Header |
| JSON Data |
| Binary Data |
| Byte 1 | Byte 2 | Byte 3 | Byte 4 |
|---|---|---|---|
| Query Type | Query ID | ||
| Sequential Number | |||
| JSON Size | |||
| Field | Size | Description |
|---|---|---|
| Query Type | 8 bit |
0x00 Request 0x01 - 0x0F Reserved 0x10 Response 0x11 - 0x1F Reserved 0x20 Notification 0x21 - 0xFE Reserved 0xFF Invalid Query Type |
| Query ID | 24 bit |
0x000001 Send Handshake Data 0x000002 Send Internal Error 0x000003 - 0xFFFFFE Reserved 0xFFFFFF Invalid Query ID |
| Sequential Number | 32 bit | Message ID can be set by the Mobile libraries to track security messages. The system uses the same Message ID when replying to the query allowing the mobile to correlate messages. |
| JSON Size | 32 bit | The size of the JSON data following the binary query header. |
If an error occurs during the TLS handshake, a notification is sent with both JSON data and binary data describing the error. The JSON data contains the error code and an error text. The binary data is one single byte and only contains the error code.
The error code in JSON data and the binary data are the same value from the same code list.
The following query header is used by the system and the application to send error messages.
| Binary Query Header | |||
|---|---|---|---|
| Query Type | TLS Message Type | Sequential Number | JSON Size |
| Notification | Send Internal Error | Any number to be used to correlate query messages | Size of the JSON data |
| 0x20 | 0x000002 | 0xNNNNNNNN | 0xNNNNNNNN |
| JSON Data | |||
| Binary Data: Single Byte Error Code | |||
| Key | Description |
|---|---|
| id | A decimal value representing an Error code. |
| text | A string describing the error. |
| Error code | Byte | Value | Description |
|---|---|---|---|
| ERROR_SUCCESS | 0x00 | 0 | Internal Security Manager value |
| ERROR_INVALID_QUERY_SIZE | 0x01 | 1 | Wrong size of query data |
| ERROR_INVALID_QUERY_ID | 0x02 | 2 | Unknown Query ID |
| ERROR_NOT_SUPPORTED | 0x03 | 3 | SDL does not support encryption |
| ERROR_SERVICE_ALREADY_PROTECTED | 0x04 | 4 | Received request to protect a service that was protected before |
| ERROR_SERVICE_NOT_PROTECTED | 0x05 | 5 | Received handshake or encrypted data for not protected service |
| ERROR_DECRYPTION_FAILED | 0x06 | 6 | Decryption failed |
| ERROR_ENCRYPTION_FAILED | 0x07 | 7 | Encryption failed |
| ERROR_SSL_INVALID_DATA | 0x08 | 8 | SSL invalid data |
| ERROR_HANDSHAKE_FAILED | 0x09 | 9 | In case of all other handshake errors |
| INVALID_CERT | 0x0A | 10 | Handshake failed because certificate is invalid |
| EXPIRED_CERT | 0x0B | 11 | Handshake failed because certificate is expired |
| ERROR_INTERNAL | 0xFF | 255 | Internal error |
| ERROR_UNKNOWN_INTERNAL_ERROR | 0xFE | 254 | Error value for testing |
It is possible to establish a secured and encrypted communication with the system by setting the frame header encryption flag to 1 when starting a new service or by sending another StartService with the encryption flag set to 1 when the service is already established (this the required flow for the RPC service). If the authentication is successful, the system will reply with a StartService ACK frame with the encryption flag also set to 1 indicating that encrypted data is now accepted. If the authentication fails for some reason, the system will reset the TLS connection and return a StartService NAK frame.
Before the encryption of RPC service is enabled (encryption is not available), SDL Core rejects any RPC request with result code ENCRYPTION_NEEDED if the RPC needs protection (please see policy updates for which RPCs need protection). SDL Core continues processing an RPC request if the RPC does not need protection. SDL Core sends a notification only if the notification RPC does not need protection.
After the encryption of RPC service is enabled (encryption is available), SDL Core rejects any unencrypted RPC requests with result code ENCRYPTION_NEEDED with the unencrypted response if the RPC needs protection. SDL Core continues processing an unencrypted RPC request if the RPC does not need protection and responds with an unencrypted response. SDL Core continues processing an encrypted RPC request if the RPC needs protection and responds with an encrypted response. SDL Core sends an unencrypted notification if the RPC does not need protection. SDL Core sends an encrypted notification if the RPC needs protection. In addition, SDL Core shall continue processing an encrypted RPC request if the RPC does not need protection and responds with an encrypted response.
The below diagram shows the sequence of how the TLS handshake exchanges certificates to compute the master secret.
The authentication is done using TLS handshake. The TLS handshake process is defined by TLS and is not part of the SDL protocol. The handshake is designed as a client server communication which is configurable in the system settings. An application must take the role of a server where the system is the client. The client entity will initiate a TLS handshake with the corresponding security manager of the server. The client will do this only if the server was not authenticated before in the current transport connection. According to the TLS handshake process the peer certificate can be omitted for the server but it's required for the client. Certificate peer verification can be enabled/disabled on the Core side by changing VerifyPeer parameter in the configuration file. On the other hand, the SDL app library does not require the certificate from Core for the TLS handshake. However, Core performs its internal certificate validation before starting the actual TLS handshake. During internal validation, Core checks if the certificate is missing (or outdated/invalid) and if so, it initiates a PTU to obtain a new certificate from the Policy Server. If a valid certificate can't be obtained, Core does not start the TLS handshake and it notifies the app library that the protected service start has failed.
The system can be configured to support one encryption method. The following methods are supported:
- SSLv3
- TLSv1
- TLSv1.1
- TLSv1.2
- DTLSv1
The system has to initiate with the corresponding client method. For instance, if the system is configured to use DTLSv1, it has to use the method DTLSv1_client. The application role has to be server and must use DTLSv1_server.
The system also supports configurable SSL Security level introduced in OpenSSL 1.1.0. This parameter can be changed by SecurityLevel parameter in the Core configuration file. By default, system uses security level 1 for TLS handshakes. At this time setting the security level higher than 1 for general internet use is likely to cause considerable interoperability issues and is not recommended. This is because the SHA1 algorithm is very widely used in certificates and will be rejected at levels higher than 1 because it only offers 80 bits of security.
The system will initiate a TLS handshake to authenticate the application where the system's role will be the client while the application's role will be the server. The system will do this only once if the application was not authenticated before in the current transport connection. The TLS handshake data is always sent in single frames. The service type for TLS handshake is the control service.
The following SDL frame header is used for every frame related to TLS handshake.
| SDL Protocol Frame Header | |||||||
|---|---|---|---|---|---|---|---|
| Version | E | Frame Type | Service Type | Frame Info | Session ID | Data Size | Message ID |
| Max major version supported by module and application |
no | Single Frame | Control Service | Single Frame Info | Assigned Session ID |
Query Binary Header + JSON Data size + Binary Handshake Data size |
Enumerated number |
| 0xN | 0b0 | 0b001 | 0x00 | 0x00 | 0xNN | 0xC + 0xNNNNNNNN + 0xNNNNNNNN | 0xNNNNNNNN |
The following query header is used by the system and the application to send TLS handshake data.
| Binary Query Header | |||
|---|---|---|---|
| Query Type | TLS Message Type | Sequential Number | JSON Size |
| Request | Send Handshake Data | Any number to be used to correlate query messages | Zero |
| 0x00 | 0x000001 | 0xNNNNNNNN | 0x00000000 |
| Binary TLS Handshake Data | |||
In case of an error, the system and the application should reset the active SSL connection of the current transport connection. This impacts already established secured service sessions as all of them will be closed. The application will need to restart all services which require protection.
Identifying potential downsides is difficult as this proposal adds specifications and documentation to the existing implementation. The downside of accepting this proposal is the effort that's required to review and audit the implementations of every SDL platform.
The proposed updates would only require changes in SDL protocol specification. Code of SDL Core, Mobile libraries or any other project wouldn't be impacted.
The author couldn't think of other alternatives to add a security specification to SDL. There are security enabled vehicles on the road which limit the abilities to design a new specification. However with the protocol specification version and this security section it is possible to improve the security with a future version.