In today’s connected world, securing app communication is a top priority for Android developers. Whenever your app exchanges data with a server, there’s a risk that attackers could intercept and alter this information. A reliable way to guard against this is by using certificate pinning. This security measure helps protect your app from Man-in-the-Middle (MITM) attacks, which aim to intercept the communication between your app and its server.

In this guide, we’ll explore what certificate pinning involves, why it’s an essential security practice for Android apps, and how to set it up in Kotlin. By the end, you’ll be equipped with the knowledge to implement certificate pinning in your projects and bolster your app’s security. Let’s get started!

What is Certificate Pinning?

Certificate pinning is a security measure that ensures our app only trusts specific SSL/TLS certificates for a given domain, instead of relying solely on certificates issued by Certificate Authorities (CAs). This guarantees that our app communicates securely with the intended server and not with a fake or malicious one.

Wait, wait—what exactly are SSL/TLS certificates, and who are Certificate Authorities (CAs)? These terms might sound familiar, but let’s break them down in simple terms. To make things clearer, let’s first look at the basic concept of a secure connection, using an everyday example.

Imagine you’re visiting a coffee shop. You trust the barista because you’ve been coming there for years. But how do you know you’re talking to the right person when they serve you your coffee? You check their name tag — it’s a simple form of identification. In the digital world, this “name tag” is an SSL/TLS certificate, which proves the identity of the server you’re connecting to.

Now, who gives the barista their name tag? In the digital world, that’s the role of Certificate Authorities (CAs). These trusted entities issue and verify certificates, ensuring that the server you’re connecting to is actually the one it claims to be.

Once you understand this basic “handshake” concept, you’ll see how certificate pinning adds an additional layer of security — ensuring your app always talks to the right server, using only a specific certificate, and not a potential imposter.

What Makes Certificate Pinning Essential?

Certificate Pinning is a security technique that binds or “pins” your app to a specific server certificate. Instead of trusting any certificate signed by a recognized Certificate Authority (CA), the app is set up to accept only a specific certificate or public key. This means that if a CA is compromised or a fraudulent certificate is used, your app will detect the mismatch and reject the connection.

When your app communicates with a server, it typically relies on HTTPS to encrypt and secure the data exchange. While HTTPS provides strong protection, it still has vulnerabilities—like the risk of malicious CAs issuing fake certificates that attackers could use to intercept sensitive data. Certificate Pinning protects against this by validating only the exact certificate your app should trust, making it much harder for attackers to impersonate your server.

By default, Android apps trust a broad set of CAs, which means that if any of these is compromised, a malicious actor could intercept the app-server communication. By using Certificate Pinning, your app trusts only specific certificates, reducing the risk of Man-in-the-Middle (MITM) attacks and keeping your data exchanges more secure.

Implementing Certificate Pinning in Android

Let’s dive into how to implement certificate pinning in an Android app using Kotlin. We’ll go through a step-by-step approach to setting up and verifying certificates with the OkHttp library, a popular HTTP client library for Android.

Identify the Server Certificate

Before implementing Certificate Pinning, you need the certificate’s public key or SHA-256 hash. You can use tools like browsers or OpenSSL to extract this information.

openssl s_client -connect google.com:443 -showcerts

Or use a browser,

Add OkHttp Dependency

Nest, add OkHttp and OkHttp-TLS dependency in your build.gradle file to manage network operations with certificate pinning support.

implementation("com.squareup.okhttp3:okhttp:4.9.3")
implementation("com.squareup.okhttp3:okhttp:4.9.3-tls")

Set Up Certificate Pinning in OkHttp

Now, let’s configure certificate pinning using the SHA-256 fingerprint obtained earlier.

import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.CertificatePinner

fun createPinnedOkHttpClient(): OkHttpClient {
    // Define the certificate pin for your server
    val certificatePinner = CertificatePinner.Builder()
        .add("yourserver.com", "sha256/YourCertificateSHA256FingerprintHere")
        .build()

    // Configure OkHttpClient with certificate pinning
    return OkHttpClient.Builder()
        .certificatePinner(certificatePinner)
        .build()
}

fun makeSecureRequest() {
    val client = createPinnedOkHttpClient()
    val request = Request.Builder()
        .url("https://yourserver.com/api/endpoint")
        .build()

    // Make the secure request
    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            println("Response: ${response.body?.string()}")
        } else {
            println("Failed to fetch data: ${response.code}")
        }
    }
}

Here,

CertificatePinner Configuration:

• First, we create an instance of CertificatePinner.
• We use the add() method to define a specific certificate pin for our server. Replace "yourserver.com" with your actual server’s domain and "sha256/YourCertificateSHA256FingerprintHere" with your SHA-256 certificate fingerprint. This fingerprint serves as the unique identifier that OkHttp will use to verify the server’s authenticity.

OkHttpClient Configuration:

• Next, we configure an OkHttpClient instance and set the certificatePinner to it. This ensures that any requests made through this client will only trust the pinned certificate. If the server presents a certificate that doesn’t match the pinned one, OkHttp will throw an exception and reject the connection.

Making a Secure Request:

• Finally, we create a request with the secure OkHttpClient instance configured with our certificate pinner. This request attempts to connect to https://yourserver.com/api/endpoint.
• Upon receiving the response, we check if it’s successful. If the certificate matches, data is retrieved; if it doesn’t match, an exception is raised, preventing insecure data exchanges.

Handling Multiple Pinning with Backup Certificates

What happens if your server’s certificate is updated or rotated? This is where backup pinning comes into play. By pinning multiple certificates or public keys, you allow your app to connect even if one certificate changes.

fun pinMultipleCertificates() {
    val certificatePinner = CertificatePinner.Builder()
        .add("your-website.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")  // Old pin
        .add("your-website.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")  // New pin
        .build()

    val client = OkHttpClient.Builder()
        .certificatePinner(certificatePinner)
        .build()

    val request = Request.Builder()
        .url("https://your-website.com/api/endpoint")
        .build()

    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) throw IOException("Unexpected code $response")
        println(response.body!!.string())
    }
}

This ensures that if your certificate rotates, the app will still trust the new certificate as long as its public key hash is pinned.

Dynamically Pinning Certificates

In some scenarios, it might be necessary to pin certificates dynamically, particularly when working with multiple environments or during development. You can achieve this by fetching the certificate hash at runtime.

fun getPinnedCertificate(environment: String): String {
    return when (environment) {
        "production" -> "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
        "staging" -> "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
        else -> throw IllegalArgumentException("Unknown environment")
    }
}

fun pinCertificateDynamically(environment: String) {
    val pin = getPinnedCertificate(environment)
    val certificatePinner = CertificatePinner.Builder()
        .add("your-website.com", pin)
        .build()

    val client = OkHttpClient.Builder()
        .certificatePinner(certificatePinner)
        .build()

    val request = Request.Builder()
        .url("https://your-website.com/api/endpoint")
        .build()

    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) throw IOException("Unexpected code $response")
        println(response.body!!.string())
    }
}

Here, the correct pin is selected based on the environment, giving you flexibility across various stages of development and deployment.

Challenges and Considerations

While certificate pinning is a powerful tool for securing your app, there are a few challenges and considerations to keep in mind:

• Updating pins: If the server’s certificate needs to be changed (for example, when the certificate expires), we’ll need to update the pinned certificate in the app and release a new version. This means we must ensure the certificate is updated regularly and we have a good process in place for deploying new app versions.
• Risk of breakage: If the pinning is too strict, we might face situations where legitimate changes to the server’s certificate (e.g., switching to a different CA) could break the connection. This is why it’s important to monitor certificate changes and have an update strategy.
• Backup mechanism: We can implement a backup mechanism to allow updates to the certificate pin during runtime, giving us flexibility without forcing users to update the app every time a pin change occurs.

Best Practices

Here are a few best practices to ensure we’re using certificate pinning effectively:

1. Pin multiple certificates: It’s a good idea to pin more than one certificate or public key. This gives us flexibility in case of certificate rotation or renewal without breaking the app’s functionality.

2. Handle certificate expiry gracefully: Plan for certificate expiration by regularly rotating certificates and testing your app with updated pins before they expire.

3. Hardcoding Pins: Avoid hardcoding pins in your app for security reasons. If the app is decompiled, attackers can retrieve the pinned certificate hash. Consider dynamically fetching pins or using obfuscation techniques to secure your app.

4. Managing Multiple Environments: As demonstrated earlier, dynamically switching pins based on environments (development, staging, production) is crucial. Be careful not to expose development pins in production environments.

5. Monitor and audit pins: Regularly audit your pinned certificates to ensure they’re up-to-date and match the server’s current certificates. You can also use logging to track failed pin validation attempts.

6. Fallback to normal SSL checks: In cases where pinning fails, allow the app to fall back to the standard SSL/TLS verification to avoid completely blocking the user.

Conclusion

Certificate pinning is a vital security practice for any Android app that exchanges sensitive information over the network. By enforcing a strict check on the server’s certificate, you can significantly reduce the risk of MITM attacks. 

In this guide, we explored how to set up certificate pinning using Kotlin and OkHttp. Implementing certificate pinning might seem a bit complex at first, but it’s a worthy investment in the long run. It gives your users confidence that their data is secure, especially in an age where data breaches are increasingly common. Give certificate pinning a try in your Android project to keep your app secure and trustworthy!