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.


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.
Basic TLS Exchange
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.


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.

Installing Certificate on the Sync Gateway

Follow the instructions in the Couchbase Developer Portal to generate / install relevant server certificate on your Sync Gateway

Couple of points to note during certificate generation:-

  • The certificate and corresponding private key must be in .pem format
  • Install the certificates in a location accesible to the Sync Gateway. Failing to do so will result in an error when you launch the Sync Gateway with the config file.

  • 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 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

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.

If configuration is correct, you should see something like this in the output

  • Convert the PEM certificate in der format using command below

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.

In this example, we are using IOUtils utility classes from [Apache Commons IO]( 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.

If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me  The Couchbase Forums are another good place to reach out with questions.



Posted by Priya Rajagopal, Director, Product Management

Priya Rajagopal is a Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

Leave a reply