Secure Sync Gateway Access

    +

    Couchbase Sync Gateway TLS encryption and verification

    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

    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.