SDL Security iOS

SDL Security is a security library for encrypting data transmitted between an SDL iOS application and SDL Core. On setup, a certificate associated with the SDL app's unique app id is downloaded from a URL. Then the OpenSSL cryptographic library is used to encrypt and decrypt data using the DTLS protocol.

How It Works

SDL Security is an example security library that automotive OEMs can use to build their own proprietary security libraries. The security library must be modified by the OEM to work with their proprietary version of SDL Core. Once the security library has been modified, it is used to generate a static library that developers add to their SDL iOS apps.

OEMs implementing this library should take care to add additional protections as this library is not cryptographically secure out-of-the box.

What Can Be Encrypted?

This library can be used to encrypt SDL services such as the video, audio or RPC services.

Configuring the Library

The following customizations must be made by the OEM in order for the library to work with their proprietary version of SDL Core:

Certificate URL

The CertificateURL in the SDLPrivateSecurityConstants.m file should be updated to point to an API URL that will return certificate data for a specific SDL appID. The certificate data will be stored on disk as a .pfx file so it can persist between app sessions. If the certificate has expired, the library will automatically try to download a new certificate.

Depending on the response you return for the certificate request, you may need to update how the certificate is extracted from the JSON object in SDLCertificateManager.m. Currently the certificate manager is set up to handle parsing this JSON format:

{
  "meta": {
    "request_id": "<The id of your request>",
    "code": 200,
    "message": null
  },
  "data": {
    "certificate": "<The base64 encoded PFX file data>"
  }
}

Vehicle Makes

The availableMakes property should be updated in the SDLPrivateSecurityConstants.m file to list all supported vehicle types. The vehicleType returned by SDL Core's RegisterAppInterface response is used to select the security manager associated with that vehicle type. It is important that the vehicle types listed in availableMakes match exactly the vehicleTypes returned by the RegisterAppInterface response, otherwise the security manager will not be selected and configured.

Checking Certificate Parameters

In order to check the mobile certificate parameters, the security library needs the TLS issuer and certificate password used to generate the certificate. Currently the the SDLTLSIssuer and SDLTLSCertPassword properties used to check the certificate are hardcoded in the SDLPrivateSecurityConstants.m file.

Certificate Storage

Once the certificate is downloaded it is stored on disk so the certificate can persist between app sessions. The VendorName property in the SDLPrivateSecurityConstants.m file is used to create a directory where your certificate is stored. We recommend updating this property to your company name.

Renaming the Library

In order to use this security library with SDL, an OEM must rename this library and classes. This is because a developer who wants to support multiple OEMS will have to add a security manager from each OEM. If OEMS use the same class names then it will be impossible for the developer to include more than one security library in their application.

Static Security Library

Once the security library has been configured by the OEM, it is used to generate a static library that developers add to their SDL iOS apps. The static library, libSDLSecurityStatic.a, can easily be built in Xcode using the SDLSecurityStatic target.

Generating the Static Security Library

1. In the scheme menu of Xcode, set the active scheme to SDLSecurityStatic.
2. Build and run the SDLSecurityStatic scheme (Product > Build For > Running).
3. Locate the SDLSecurityStatic.xcframework file in the root directory of the project with Finder. The .xcframework folder contains the static library builds and header files in a structure that Xcode 12+ can understand.

Adding the Static Security Library to a SDL App

1. Drag the SDLSecurityStatic.xcframework (or its equivalent after OEM naming modifications are made) file to the app project in Xcode. The .xcframework file contains the static library and header files. For Swift apps, the headers will need to be imported in the bridging header for the app.

2. Import SDLSecurityManager.h into the file where the the SDLConfiguration's SDLEncryptionConfiguration or SDLStreamingMediaConfiguration is being set. If you have a Swift project, this will require adding a bridging header to the project.

   Swift

   let encryptionConfig = SDLEncryptionConfiguration(securityManagers: [SDLSecurityManager.self]], delegate: self)

   Objective-C

   SDLEncryptionConfiguration *encryptionConfig = [[SDLEncryptionConfiguration alloc] initWithSecurityManagers:@[SDLSecurityManager.self] delegate:self];

Dynamic Security Library Framework

For convenience when debugging (it's less secure than a static framework, which can more easily be obfuscated), a dynamic framework can be easily built and dropped into a SDL iOS app.

Generating the Dynamic Security Library Framework

1. In the scheme menu of Xcode, set the active scheme to SDLSecurity.
2. Build and run the SDLSecurity scheme (Product > Build For > Running). If you want to use the build in the simulator, you must select a simulated device as the run destination before building and running; likewise, to use on an iPhone, you must select a real device as the run destination.
3. In the project navigator you will find the SDLSecurity.framework build under SDLSecurity > Products.
4. Right click on the SDLSecurity.framework build and select Show in Finder. This will take you to the derived data of the project which has the framework.

Adding the Dynamic Security Library Framework to a SDL App

1. In Xcode, drag and drop the framework into your project.

2. Import the SDLSecurity module into the file where the the SDLConfiguration's SDLEncryptionConfiguration or SDLStreamingMediaConfiguration is being set.

   Swift

   import SDLSecurity
   
   let encryptionConfig = SDLEncryptionConfiguration(securityManagers: [SDLSecurityManager.self]], delegate: self)

   Objective-C

   @import SDLSecurity;
   
   SDLEncryptionConfiguration *encryptionConfig = [[SDLEncryptionConfiguration alloc] initWithSecurityManagers:@[SDLSecurityManager.self] delegate:self];

Updating the OpenSSL Dependency

We have included a build of the OpenSSL library so that the security library can work out of the box with a few minor customizations. However, this example does not often update the OpenSSL build and it is provided for example purposes. Production versions of this library should replace the OpenSSL dependency with an updated and trusted build. The following configurations may have to be updated:

1. Make sure that the OpenSSL library builds libcrypto.a and libssl.a have been added to the SDLSecurityStatic and the SDLSecurity targets.
2. Configure the build settings for the SDLSecurityStatic and SDLSecurity targets.
   • In Build Settings > Library Search Paths include the path to the libcrypto.a and libssl.a static libraries.
   • In Build Settings > Header Search Paths include the path to the OpenSSL public headers.