Security-relevant configuration

Internal whitelist URLs

By default, only the configured Unblu base URL and its subroutes may be accessed by the SDK’s internal WebView. However, you may want to specify that a URL is also accessible if, say, the initial URL is redirected to another domain. To this end, you can provide a list of regular expressions in UnbluClientConfiguration.internalUrlPatternWhitelist.

If you want to use Google fonts in your mobile app, take into account that https://fonts.googleapis.com redirects to https://fonts.gstatics.com. You have to include a pattern for the latter domain in the internal pattern whitelist.

If you don’t have any of the requirements outlined above, you needn’t configure the internal link pattern whitelist.

Whitelisting external links

The patterns in the internal pattern whitelist are used by the Unblu-enabled application itself. If you want to specify which URL patterns may be accessed by having your app launch another application, adapt the external link pattern whitelist. This is necessary even if the patterns describe URLs within your organization’s domain. iframe elements are also checked against the external link pattern whitelist.

Whitelisting external links is handled by the externalLinkHandler property of the UnbluClientConfiguration and the UnbluExternalLinkHandler protocol.

When you initialize UnbluClientConfiguration, you must provide an object that conforms to the UnbluExternalLinkHandler protocol. UnbluClientConfiguration exposes the link handler via the new externalLinkHandler property.

When a participant taps a link in a conversation, Unblu calls the function decidePolicy(for: URL) → UnbluExternalLinkHandlingPolicy on the UnbluExternalLinkHandler. How Unblu then proceeds depends on whether the function returns .open, .block, or .ignore. This check occurs before the request is sent to the Collaboration Server.

Unblu provides a default implementation of this protocol called UnbluDefaultExternalLinkHandler.

For more information, refer to the Unblu iOS mobile SDK reference entries of the following types:

Certificate pinning

The SDK uses a WKWebView for most of its communication, and URLSession for file downloads. For certificate pinning, the WKNavigationDelegate method is called to handle URLAuthenticationChallenges and file download challenges triggered via URLSessionDelegate method.

To define a handler for these challenges, provide an object that conforms to the AuthenticationChallengeDelegate protocol and pass it to UnbluClientConfiguration.authenticationChallengeDelegate.

`UnbluAuthenticationChallengeHandler`

If you don’t want to write the code to handle certificate pinning yourself, Unblu provides a class called UnbluAuthenticationChallengeHandler that does the heavy lifting for you. All you have to do is pass the certificate data, or public keys.

For more information, refer to the class’s reference documentation.

Adding a Client Certificate for Mutual TLS (mTLS)

Mutual TLS (mTLS) enhances security by requiring both the client and the server in a communication to authenticate each other using certificates. The application can provide a certificate that the server can verify.

Complete the following steps to enable this option:

Create a password-protected PKCS#12 file with the ".p12" extension for the certificates. For example, use the following command:
```
openssl pkcs12 -export -out client_certificate.p12 -inkey client_private_key.pem  -in client_certificate.pem -certfile root_certificate.pem
```
you must use OpenSSL 1.1 as it is the only version supported by iOS.

Place the file (client_certificate.p12) in the iOS project, next to the Info.plist file, and add it to the project.

In your application, add the following code. Implement the protocol AuthenticationChallengeDelegate, set the file name without the path and extension, and set the password. During the TLS handshake, the app automatically presents this certificate:

var unbluConfiguration: UnbluClientConfiguration

....

unbluConfiguration.authenticationChallengeDelegate = ClientAuthenticationChallengeDelegate()

....

class ClientAuthenticationChallengeDelegate: AuthenticationChallengeDelegate {
    let challengeHandler = UnbluAuthenticationChallengeHandler(pkcs12FileName: "client_certificate",
                                                               pkcs12Password: "password")
    func didReceive(authenticationChallenge challenge: URLAuthenticationChallenge,
                        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
            challengeHandler.didReceive(authenticationChallenge: challenge, completionHandler: completionHandler)
    }
}

File downloads

The SDK needs to know how to download files.

In most cases, the default handling provided by UnbluDefaultFileDownloadHandler is sufficient, so passing an instance of this class to the initializer of UnbluClientConfiguration is all you’ll need to do. However, if you want to implement your own solution, you must pass your own object conforming to the UnbluFileDownloadHandler protocol to the initializer of UnbluClientConfiguration.

Log stripping

In iOS, there’s no need to explicitly strip out log statements as there’s no simple way to access them from the app’s binary anymore, although they’re visible within the binary files delivered by Unblu.

Encrypting stored preferences

The SDK needs to store some internal values inside the app to properly identify the user device against the Collaboration Server even after restarting the app. By default, UserDefaults.standard is used to store these values. this is achieved by passing an instance of UserDefaultsPreferencesStorage to UnbluClientConfiguration when it’s initialized.

In many cases this is enough because normally, only the app itself has access to this data. You may, however, wish to encrypt the values before storing them. To do so, you have two options:

Provide the SDK with a custom implementation of UnbluPreferencesStorage when you initialize UnbluClientConfiguration. The SDK will then use this storage whenever it needs to write or read the value of a preference to persistent storage.
Use UnbluKeychainPreferencesStorage to store preferences in the iOS keychain. Refer to the documentation for this class for more information on how to use it.