Certificate Pinning
Description — Couchbase Lite Database Sync — Pinning SSL certificates in you application
Related Content — Remote Sync using Sync Gateway | Handling Data Conflicts
Introduction
Couchbase Lite supports certificate pinning. Certificate pinning is a technique that can be used by applications to "pin" a host to its certificate. The certificate is typically delivered to the client by an out-of-band channel and bundled with the client. In this case, Couchbase Lite uses this embedded certificate to verify the trustworthiness of the server and no longer needs to rely on a trusted third party for that (commonly referred to as the Certificate Authority).
The following steps describe how to configure certificate pinning between Couchbase Lite and Sync Gateway.
-
Create your own self-signed certificate with the
openssl
command. After completing this step, you should have 3 files:cert.pem
,cert.cer
andprivkey.pem
. -
Configure Sync Gateway with the
cert.pem
andprivkey.pem
files. After completing this step, Sync Gateway is reachable overhttps
/wss
. -
On the Couchbase Lite side, the replication must point to a URL with the
wss
scheme and configured with thecert.cer
file created in step 1.InputStream is = getAsset("cert.cer"); byte[] cert = IOUtils.toByteArray(is); if (is != null) { try { is.close(); } catch (IOException ignore) {} } config.setPinnedServerCertificate(cert);
This example loads the certificate from the application sandbox, then converts it to the appropriate type to configure the replication object.
-
Build and run your app. The replication should now run successfully over https with certificate pinning.
Troubleshooting
If Sync Gateway is configured with a self signed certificate but your app points to a ws
scheme instead of wss
you will encounter an error with status code 11006
.
CouchbaseLite Replicator ERROR: {Repl#2} Got LiteCore error: WebSocket error 1006 "connection closed abnormally"
If Sync Gateway is configured with a self signed certificate, and your app points to a wss
scheme but the replicator configuration isn’t using the certificate you will encounter an error with status code 5011
.
CouchbaseLite Replicator ERROR: {Repl#2} Got LiteCore error: Network error 11 "server TLS certificate is self-signed or has unknown root cert"