Enable SSL Pinning certificates - Mattermost

What is SSL Pinning?

SSL (Secure Sockets Layer) pinning is a technique used in mobile app development to ensure that the app communicates only with a server that has a specific certificate. This is done by embedding the server’s certificate in the app itself and then validating the server’s certificate against this embedded certificate during communication. If the server's certificate does not match the pinned certificate, the connection is rejected.

Advantages of SSL Pinning

Increased Security: Protects against man-in-the-middle (MITM) attacks by ensuring that the app only communicates with trusted servers.
Trustworthiness: Guarantees that the data sent and received is from the expected server.
Prevention of Certificate Spoofing: Ensures that the server’s certificate is exactly what is expected, preventing spoofing attempts.

Disadvantages of SSL Pinning

Certificate Management: Requires regular updates to the app when the server’s certificate is renewed or changed.
Deployment Complexity: Coordination between development and deployment teams is necessary to avoid disruptions during certificate rotations.
Maintenance Overhead: Adds additional steps and complexity to the app’s maintenance process.

<Note title="Important Note"> SSL pinning requires that both development and deployment teams understand and follow best practices for cryptographic key management, certificate rotation, and incident response. - Coordinating the timing of certificate updates and app updates is crucial to minimize impact on end-users. When the server's SSL certificate is renewed or rotated, the hardcoded public key in the app no longer matches the server's new certificate, leading to connection failures until the app is updated with the new key. - Both development and deployment teams need to align on a deployment window that considers factors like user downtime, mobile app store review timelines, and peak usage times, as well as a coordinated rollback plan. </Note>

Steps to Enable SSL Pinning in Your Mobile App

1. Obtain the Certificate from the Server

Use openssl to retrieve the certificate from your server and save it to a file. This can be done with the following command:

openssl s_client -connect yourserver.com:443 -showcerts < /dev/null | openssl x509 -outform DER -out yourserver.cer

Alternatively, to save it in PEM format:

openssl s_client -connect yourserver.com:443 -showcerts < /dev/null | openssl x509 -outform PEM -out yourserver.crt

2. Naming the Certificate Files

Name the certificate files using the domain name as the filename with either .cer or .crt as the extension. For example, if your server’s domain is example.com, your files should be named example.com.cer and/or example.com.crt.

Optionally you can have both file types (.cer and .crt) to match the server trust and to ensure continued app functionality during certificate rotations. Coordinate certificate rotations with the deployment teams to avoid disruptions between the app and the server.

3. Copy the Certificate Files to the Assets Folder

Place the certificate files in the assets/certs folder of your project. This is necessary for the app to access and use the certificates during runtime.

4. Build Your App

Follow the instructions in the Build the iOS app or Build the Android app sections to build your app with SSL pinning enabled.