REST API traffic encryption

This section explains how Infobip handles public traffic encryption and how security changes are handled to avoid interruptions in using our REST API.

TLS encryption of HTTP traffic

Infobip uses Transport Layer Security (TLS), known as its predecessor Secure Socket Layer (SSL), to securely transfer data over the network.

We have ensured the use of the most secure versions and cryptographic algorithms within the TLS protocol, which has multiple iterations.

The following list contains the supported REST API TLS versions and cipher suites:

• TLSv1.3 with suites in server-preferred order:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256
  • TLS_AES_128_CCM_SHA256

• TLSv1.2 with suites in server-preferred order:

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_CCM
  • TLS_DHE_RSA_WITH_AES_256_CCM
  • TLS_DHE_RSA_WITH_AES_128_CCM_8
  • TLS_DHE_RSA_WITH_AES_256_CCM_8
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

TLS/SSL changes

In order to provide the best transparent experience to our customers, we adhere to the following TLS change policy:

• For TLS version or cipher suite changes, the customers will be notified at least 6 months in advance.
• For TLS cipher suite changes, the customers will be notified at least 60 days in advance.
• For SSL certificate changes, a notification will be sent at least 60 days before the SSL certificate change that will include information about any changes in the trust chain. Before any notification is issued, the certificate will be installed on our TLS testing endpoint.

All changes will be posted on our Status (opens in a new tab) page with three states:

1. Scheduled - Certificate change is announced and a new certificate is available on test endpoint.
2. In progress - Renew is in progress.
3. Completed - Certificate replacement is completed.

Bear in mind that in the event of a security emergency, such as the discovery of a TLS protocol vulnerability, essential adjustments to TLS will be implemented immediately to uphold product safety. Subsequently, customers will promptly be notified regarding these changes.

For any additional questions, contact Support (opens in a new tab).

TLS/SSL certificate changes

For TLS encryption, we use SSL certificates signed by DigiCert as one of the most used Certificate Authorities (CA).

Public REST API endpoints have a certificate that is valid for 1 year and are renewed accordingly. Customers who do not pin the certificate and have automated trust store updates enabled will remain unaffected by these changes.

Cases impacted by the changes

Leaf certificate pinning

This practice has high agility costs and limitations so we do not recommend it (opens in a new tab). However, if you choose to use this practice, make sure to:

• Proactively monitor and update pinned certificates in a timely manner.
• Have in mind the Infobip certificate replacement policy.

As a more secure alternative, we suggest using mTLS (client certificate authentication). For more information, contact Support (opens in a new tab).

Manually operated trust store

Most trust stores are updated automatically, but some customers can choose to operate their trust stores manually. We rely on DigiCert's PKI - all CAs can be downloaded from their Root CA website (opens in a new tab).

If you are not bound to trust only one CA, we recommend to install CAs that Mozilla trusts (opens in a new tab) in the PEM format.

TLS test endpoints

When a certificate change is scheduled, we will make a new certificate available on test endpoints. TLS test endpoints should be used from production environments from where Infobip services are accessed and use the same trust store as the service integrating them.

    tls-test.api-<location>.infobip.com

How to test

Certificates that are not wildcard will be installed on the same endpoint and they can be tested with the curl command. For example, with api.infobip.com (opens in a new tab), 172.201.176.225 is the IP of our TLS test endpoint:

    curl -vi --resolve api.infobip.com:443:172.201.176.225 https://api.infobip.com

In the below example, a US location is used for testing wildcard certificates:

    curl https://tls-test.api-us.infobip.com

Here is an example of a successful TLS test endpoint JSON response:

 
    {
      "certificate": {
        "fingerprintSHA256hex": "D0B356D14E8C9BCD48AF9BE3AA38014DE95012FB2A19363E63474D0476BF3E98",
        "tlsVersion": "TLSv1.3",
        "usedCipher": "TLS_AES_256_GCM_SHA384",
        "commonName": "*.api.infobip.com",
        "sni": "tls-test.api.infobip.com",
        "issuedBy": "RapidSSL TLS RSA CA G1",
        "expire": "240711235959Z"
      }
    }
 

For a better response understanding, check the items below:

• fingerprintSHA256hex - SHA256 fingerprint in hex format of the server SSL certificate.
• tlsVersion - TLS version used for the https encryption.
• usedCipher - Cipher algoritham used for the SSL handshake.
• commonName - CN that is in the server certificate.
• sni - SNI (Server Name Indication) used to choose the correct SSL certificate.
• issuedBy - CN of the CA that signed the leaf certificate.
• expire - Expire date of the SSL certificate as a formatted string YYMMDDhhmmss[Z].

For customers that are manually operating the trust store and/or pining our leaf or intermediate certificates, we strongly recommend to:

1. Watch out for changes: Subscribe to the Status (opens in a new tab) page.
2. Test: When a change is announced, use the provided test endpoints to test the TLS connections with any http client.
3. Update configuration: If the TLS connection fails, update the local SSL configuration.
4. Verify: After each local configuration change, verify if the Connect to test TLS endpoint works.

Note: If preparations are not completed on time, the changes will not be postponed or reverted. However, we are more than willing to provide technical support to adopt the new changes as quickly as possible. For more information, contact Support (opens in a new tab).

Possible TLS/SSL errors and how to resolve them

There are many common TLS/SSL errors for which we try to provide the best support to resolve them as soon as possible. You can detect possible issues by checking our test endpoints before the scheduled replacement.

To be more efficient, check the following common issues and provide us with actionable information.

TLS chain errors

The TLS chain error indicates that the local system or client does not have Infobip's CA configured as expected:

Curl unknown CA error example:

    curl: (60) SSL certificate problem: self signed certificate in certificate chain
    More details here: https://curl.haxx.se/docs/sslcerts.html
     
    curl failed to verify the legitimacy of the server and therefore could not
    establish a secure connection to it. To learn more about this situation and
    how to fix it, please visit the web page mentioned above.

Possible solutions:

1. Check which CA certificates are present on the client's system, download and install CAs that Mozilla trusts (opens in a new tab) in the PEM format.
2. Verify that the client loads the CA certificate from the correct directory.

SSL handshake errors

SSL handshake errors also commonly manifest as protocol error or cipher errors. They happen when client does not support TLS versions or Ciphers.

Curl protocol error example:

    curl: (35) error:1425F102:SSL routines:ssl_choose_client_version:unsupported protocol

Curl handshake error due to unsupported client ciphers example:

    curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure

Possible solutions:

1. If the client is behind a firewall, SSL inspection or VPN, check if they support the TLS and ciphers that Infobip supports.
2. Check if the client supports available TLS versions and ciphers.
3. Explicitly configure the client to use the latest TLS version if possible.