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.

What is a MITM attack

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.

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

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

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.

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.

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

The commands listed in this section have been tested on Ubuntu, but they should work on other Linux-based OS as well.

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

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:

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.