# Security Recommendations

In 8.8.0, we’ve implemented SSL pinning to protect our clients from MITM attacks. We strongly recommend adding a built-in certificate whitelist to your application to prevent fraud with third-party certificates set as trusted.

<details>

<summary>What is a MITM attack</summary>

MITM (man in the middle) attack is a type of attacks when a cyber fraudster breaks into the communication between application and backend, setting up a proxy to intercept and alter the traffic (e.g., substitute the video being sent). Typically, these attacks involve the fraudster setting their certificate as trusted on the user's device beforehand.

</details>

You can add a list of certificates your application should trust at the moment of connection to Oz API via the optional sslPins field of OzConnection class. As an input, this field takes a list of public certificate key hashes with their expiration dates as shown below:

#### Android

```kotlin
Connection.fromServiceToken(
   "your API server host",
   "your token",
   listOf(
     SslPin(
       "your hash", // SHA256 key hash in base64
       <date> // key expiration date as a UNIX timestamp, UTC time
     )
   ),
 )
```

#### iOS

```swift
let pins = [SSLPin.pin(
      publicKeyHash: "your hash", // SHA256 key hash in base64
      expirationDate: date)] // key expiration date as a UNIX timestamp, UTC time
OZSDK.setApiConnection(.fromServiceToken(
        host: "your API server host",
        token: "your token",
        sslPins: pins)) { (token, error) in
          //
        }
```

### **Getting keys and dates: the simplest way**

1. Go to the <https://globalsign.ssllabs.com/> website.
2. Enter your domain address. Once the address is processed, you’ll see a list of your servers.
3. Click the server address needed to load a list of certificates. Certificate key is in the **Pin SHA256** line of the **Subject** field. Expiration date is shown in the **Valid until** field.

<figure><img src="/files/ofpEQUxNcgvmtnp4rZlC" alt=""><figcaption></figcaption></figure>

Certificate number one is your host certificate. Your root certificate is in the very bottom of the list. Others are intermediate. For SSL pinning, any of them fits.

#### **Choosing a certificate**

The higher the certificate is on the list, the better the level of protection against theft. Thus, if you use the host certificate to pin in your application, you get the highest security level. However, the lifetime of these certificates is significantly shorter than that of intermediate or root certificates. To keep your application secure, you will need to change your pins as soon as they expire; otherwise, functionality might become unavailable.

As a reasonable balance between safety and the resources needed to maintain it, we recommend using intermediate or even root certificate keys for pinning. While the security level is slightly lower, you won’t need to change these pins as often because these certificates have a much longer lifetime.

<figure><img src="/files/ktmlo9qCYPom6cv5Fvb5" alt=""><figcaption></figcaption></figure>

| **Certificate owner**              | **Trust level**                                                                                                                                                  | **Resources requirements (depend on the certificate’s lifetime)**                                               |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Host                               | Highest                                                                                                                                                          | High, but requires the most resources to maintain: keys’ list should be updated at the same time as certificate |
| Intermediate certificate authority | Above average; the application considers all certificates that have been issued by this authority as trusted                                                     | Average                                                                                                         |
| Root certificate authority         | Average; the application considers all certificates that have been issued by this authority as trusted, including the intermediate authority-issued certificates | Low                                                                                                             |

#### Obtaining Hash and Date

{% hint style="info" %}
The commands listed in this section have been tested on Ubuntu, but they should work on other Linux-based OS as well.
{% endhint %}

To obtain the hash, run the following command with your server domain and port:

```bash
echo | openssl s_client -connect {SERVER_DOMAIN_NAME}:{PORT} 2> /dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary| openssl enc -base64
```

In the response, you’ll receive hash for your SslPin.

To get the certificate’s expiration date, run the next command – again with your server domain and port:

```bash
openssl s_client -servername {SERVER_DOMAIN_NAME} -connect {SERVER_DOMAIN_NAME}:{PORT} | openssl x509 -noout -dates
echo -n Q | openssl s_client -servername {SERVER_DOMAIN_NAME} -connect {SERVER_DOMAIN_NAME}:{PORT} | openssl x509 -noout -dates
```

The date you require will be in the `notAfter` parameter.

We’ll provide you with the hash and date of our API server certificate.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/oz-mobile-sdk/security-recommendations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.