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.// Note: `GetCertificate` is a fake method. This would be the platform-specific method // to find and load the certificate as an instance of `X509Certificate2`. // For .NET Core / .NET Framework this can be loaded from the filesystem path. // For UWP, from the assets directory. // For iOS, from the main bundle. // For Android, from the assets directory. var certificate = GetCertificate("cert.cer"); var config = new ReplicatorConfiguration(db, target) { PinnedServerCertificate = certificate };
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"