Certificate Pinning in Android with Couchbase Mobile

Couchbase Mobile 2.0 supports certificate pinning on all Couchbase mobile platforms. Certificate pinning is a technique used by applications to “pin” a host to it’s certificate/public key. Communication between Couchbase Lite and Sync Gateway is encryped and secured using SSL/TLS. The SSL/TLS protocol relies on a Public Key Infrastructure (PKI) mechanism using a X.509 certificate to establish the Sync Gateway server’s identity. The certificate is typically issued/signed by a trusted Certificate Authority and is installed on the Sync Gateway.

In a development environment, this certificate may be self-signed.

If the trustworthiness of the certificate is somehow compromised or if you are using a self signed certificate, then the identity of the server cannot be reliably established and there can be no confidentiality guarantees on the communication between the client and server. To alleviate these issues, Couchbase Lite supports certificate pinning. To accomplish certificate pinning, the public-key certificate is typically delivered to the client appv via an out-of-band channel and bundled with the client app. By pinning the certficate, the verifying client app no longer needs to rely on a third party CA for verifying the signature. This technique is also required to communicate with Sync Gateway confgured with self signed certificates.

This post will discuss how to pin certificates within your Coucbase Lite Version 2.0 enabled Android app. Version 1.4 of Couchbase Lite only supported certificate pinning in iOS and that was discussed in this blog post.

You can download the latest pre-release builds of Couchbase Mobile 2.0 from here.

Background

If you are familiar with SSL/TLS or have read this blog post, you can skip ahead to the “Supporting Certificate Pinning with Couchbase Mobile” section of this blog post.

Communication between Couchbase Lite and Sync Gateway is encryped using SSL/TLS.At a very high level, the TLS protocol works as follows. A X.509 certificate containing the public key and server identity is installed on the Sync Gateway. This public key certificate may be signed by a trusted third party Certificate Authority or may be self-signed, the latter typically the case in development environments. During connection establishment, the client app running Couchbase Lite verifies the identity of the Sync Gateway using the server certificate. Couchbase Lite uses the trusted CA’s root certificate to validate the certificate. Once verified, the client proceeds with the secret key exchange. The shared secret is then used to encyrpt communication between the client and Sync Gateway. Please refer to the RFC for specifics on the SSL/TLS protocol.

There are some issues with this approach :- – While under most circumstances, it is reasonable to rely on the trustworthiness of the CA, it is possible for a CA itself to be compromised. If that happens, then there is no reliable way to authenticate the Sync Gateway because the CA that is used for the verification itself is not trustworthy! – The client-server communication may be subject to a Man-in-the-Middle (MiTM) attack whereby a rogue server impersonating as a Sync Gateway can issue a fake certificate representing the Sync Gateway, signed by a bogus CA. If the client is somehow misled to include the fake CA’s certificate in it’s trusted root Certificate Authority store, then the client will trust the fake certificate signed by the bogus CA. This will result in the client now communicating with a bogus Sync Gateway. – If you are using self-signed certificates in your development environment, there is no way for the client to reliably validate the identity of the server.

Certificate Pinning

One common way to handle the issues listed above is to “pin” the Sync Gateway server to it’s certificate/public key. In this technique, the Couchbase Lite is pre-configured with the trusted Sync Gateway certificate. So during connection establishment, Couchbase Lite uses this pre-configured certificate to verify the identity of the server. This removes the reliance on an external third party CA for verification of certificate. The OWASP website is a good reference on Certificate Pinning.

Caveat

It is important to note that since the applications are bundled with the certificate, every time the certificate expires, the application needs to be updated with the new certificate. This may be a bit more challenging in mobile environments where the onus is on the users to upgrade their apps. So be aware of when the certificates expire and make appropriate plans to publish the applications with the new certificates in advance of the certificate expiration.

Supporting Certificate Pinning with Couchbase Mobile

This post assumes that you are familiar with developing Android apps and configuring your app to use Couchbase Lite 2.0. If not, please review this Getting Started guide. We will use Sync Gateway 1.5 in the cloud backed by a Couchbase server persisting the data in the cloud. The Couchbase Server is not relevant for the discussions in this post.

If you are generating a self-signed certificate, probably the most important field is the CommonName. It should be your Sync Gateway’s FQDN. If you Sync Gateway does not have one, then you must specify use 10.0.2.2 for localhost or the static IPAddress of your Sync Gateway.

Sync Gateway Config File

Confirm that the Sync Gateway config file includes the following properties

1

2

"SSLCert":"ssl/cert.pem",

"SSLKey":"ssl/privkey.pem",

Verifying SSL Setup in your Sync Gateway

To verify that you can connect to your Sync Gateway over SSL, run the following curl command in a terminal command. Replace localhost in command below with IP Address of your Sync Gateway.

You can refer to this SSL cheat sheet for details on the various openSSL commands.

Copy the cert.pem file into your Assets folder. Your Android Studio project folder should be similar to this

Pinning the Sync Gateway Server Certificate

In order to pin the certificate, we must first load the certificate that is bundled with the Assets folder.

Java

1

2

3

4

5

6

7

8

9

10

11

12

13

privatebyte[]getPinnedCertFile(Context context){

AssetManager assetManager=context.getAssets();

InputStream is=null;

byte[]bytes=newbyte[0];

try{

is=assetManager.open("cert.cer");

return(IOUtils.toByteArray(is));

}catch(IOExceptione){

e.printStackTrace();

}

returnnull;

}

In this example, we are using IOUtils utility classes from [Apache Commons IO](https://commons.apache.org/proper/commons-io/description.html) to convert the certificate read from File Input Stream to byte array. You can choose any other tool/method for the conversion.

– Configure the Replicator with the pinned certificate. In a real app, you will to do a null check in the certificate before you set it. Omitting the checks here for brevity.

That’s it! With just couple of steps, you can enable certificate pinning in your Android App with Couchbase Mobile 2.0.

What Next

This blog post discussed the benefits of certificate pinning within your mobile apps and how you can enable certificate pinning with Couchbase Lite 2.0. The example discussed an Android app but the approach would be similar on other platforms as well.

Posted by Priya Rajagopal , Principal Product Manager

Priya Rajagopal is a Principal Product Manager for Couchbase focusing on the Couchbase Mobile and IoT platform. She has been professionally developing software for over 19 years in several technical leadership positions, with the last 8 years focussed on mobile technologies. She is a co-inventor on 22 US patents and holds a masters degree in Computer Science.