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.

Secure Sync Gateway Access

      +

      Couchbase Sync Gateway TLS encryption and verification

      Related Security topics: User Authentication | TLS Certificate Authentication

      Overview

      TLS is required by default for all communications with Couchbase Server [1]. TLS v1.3 is supported as the default protocol.

      We strongly recommend always having TLS enabled, although this can be over-ridden for development and testing only.

      Additionally, the Admin and Metrics REST API security is also enhanced by the use of Couchbase Server RBAC user credentials to authenticate and authorize access — see: REST API Access

      Couchbase Server Connection

      By default Sync Gateway requires TLS encryption and the server scheme is specified as couchbases://.

      You can set the bootstrap.server_tls_skip_verify flag true to connect to 'default CBS'. But, this must only be done for testing or development purposes.

      The content in Table 1 shows the TLS configuration options for sync gateway-Couchbase Server communication. The options include flags that will allow you to override the requirement to use TLS — for use in testing and-or development environments only.

      Table 1. Configuration options sync gateway ←→Couchbase Server
      Bootstrap Configuration /
      Command-line flag      		 Default Behavior Opt-out

      bootstrap.use_tls_server
      CLI: -bootstrap.use_tls_server

      TLS enabled

      Set this false in CLI or bootstrap file to turn-off off TLS completely — development and testing only

      bootstrap.server_tls_skip_verify
      CLI: -bootstrap.server_tls_skip_verify

      TLS enabled unless use_tls_server opt-out used

      • Set this true in CLI or bootstrap file to skip server verification of certificates (self- or CA-signed) but leave encryption enabled.

      • Do not provide ca_cert_path

      • Use for development and testing only

      bootstrap.ca_cert_path
      CLI: -bootstrap.ca_cert_path

      Provides the path to the root CA certificate to verify the certificate chain and hostname of the Couchbase Server cluster

      Omit if not required

      bootstrap.x509_cert_path
      CLI: -bootstrap.x509_cert_path

      Provides the path to the client’s certificate to authenticate against Couchbase Server [2]

      2. 5.5 or above

      Omit if not required

      bootstrap.x509_key_path
      CLI: -bootstrap.x509_key_path

      Provides the path to the the client’s private key to authenticate against Couchbase Server [3]

      3. 5.5 or above

      Omit if not required

      Behavior

      Table 2. Sync Gateway ←→ Couchbase Server behavior
      Required Configuration Default Behavior Opt-Out Trigger

      Use couchbases:// server scheme
      Set the certificate and key path:

      • Sync Gateway will error non-secure server schemes (couchbase: or ws:) unless the opt-out is triggered

      • If a ca_cert_path is specified then only certificates from that CA will be accepted.

      • If ca_cert_path is omitted

        • If server_skip_tls_verify=true
          Then sync gateway will skip validation of any server cert, but still require encryption. This includes skipping validation of certs that are from a trusted/well known CA

        • If server_skip_tls_verify=false
          Then only certificates from a trusted/well known CA will be accepted

      use_tls_server=false
      server_skip_tls_verify=true (or included)

      For more on creating and installing certificates, see: TLS Certificate Authentication.

      Client Connection

      Couchbase Lite client applications must be updated to use TLS when connecting to sync gateway nodes running in default mode.

      Table 1 shows the TLS configuration options, whilst Table 4 shows the default and opt-out behavior.

      Table 3. TLS configuration options
      Bootstrap Configuration Command-line flag Default Purpose

      api.https.tls_key_path

      -api.https.tls_key_path

      nil

      Provide the path [4] to the TLS private key file.

      4. This can be absolute, or relative to the sync gateway executable's directory

      api.https.tls_cert_path

      -api.https.tls_cert_path

      -

      Provide the path to the TLS certificate file.

      Omit both options to use plaintext — for development and-or testing only — see the Bootstrap Configuration.

      Table 4. TLS behavior

      Configuration Properties

      Default Behavior

      Opt-Out Trigger

      api.api.https.tls_cert_path
      api.api.https.tls_key_path

      TLS verification and encryption is enabled by default, unless the opt-out is triggered

      Omit from configuration

      Running Sync Gateway

      As a Service

      The serviceconfig.json file uses the couchbases: scheme, with server_skip_tls_verify=true by default, to facilitate testing and development; no TLS validation is done.

      Use the following settings to configure TLS:

      For more on configuration options, see: Bootstrap Configuration.

      Command Line

      Use the following command line flags to configure TLS:

      • -bootstrap.ca_cert_path

      • -bootstrap.x509_cert_path

      • -bootstrap.x509_key_path

      • -bootstrap.server_skip_tls_verify

      Sync Gateway will error non-secure server schemes (couchbase: or ws:) unless the opt-out option is true.

      Note that you can no longer start sync gateway without providing at least one parameter, as with no configuration file specified, you need to either provide a TLS Cert/Key, or disable TLS.

      For more on command line options, see: Command Line Options.

      Related Content

      API Topics
      Reference
      Community

      Mobile Forum | Blog | Blog (Mobile) | Tutorials

      1. From release 3.0