Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

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.

    1. Create your own self-signed certificate with the openssl command. After completing this step, you should have 3 files: cert.pem, cert.cer and privkey.pem.

    2. Configure Sync Gateway with the cert.pem and privkey.pem files. After completing this step, Sync Gateway is reachable over https/wss.

    3. On the Couchbase Lite side, the replication must point to a URL with the wss scheme and configured with the cert.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.

    4. 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"

    Related Content

    How to . . .
    Learn more . . .
    Dive Deeper . . .