Note: Example and DP2 binaries updated on 6/13/2014


Last month we released Developer Preview 1 of the Couchbase .NET SDK 2.0, which showcased support for general key/value operations, a new View Query API, and probably most interesting, an early peak at our new query language, N1QL (pronounced “nickel”). You can read more about that release, here. This month, we are releasing Developer Preview 2 (henceforth DP2) of the Couchbase .NET SDK 2.0, cram full of new features in support of our upcoming Couchbase Server 3.0 release later this year!

SSL Support

Currently, communication between Couchbase Server and the client SDK is done via non-secured channels. With Couchbase Server 3.0, Secure Socket Layers (SSL) will allow optionally allow this communication through a secure, encrypted channel.

Enabling SSL requires a couple of things:

  • Couchbase Server 3.0 (Beta to be available later this summer)
  • An SSL certificate (acquired from Couchbase Server 3.0)
  • Configuration changes on the client: setting useSsl = true on a bucket or cluster configuration
  • Storing the certificate in the Trusted Root Certification Authorities store (in Windows)

At this point, all you need to do is enable SSL support on the client. To do this, you can either enable it at the cluster level or on a per-Bucket basis. Setting SSL support at the cluster level means that all buckets within the cluster will use SSL. If you wish to only use SSL on specific Buckets, you simply configure your individual Bucket to use SSL.

var configuration = new ClientConfiguration
UseSsl = true
var cluster = CouchbaseCluster.Get();

Note that if you set UseSSL to true at the cluster level, it will override any configuration set at the Bucket level.

Expect a future post to over setting up SSL in detail in the future.

CRAM-MD5 Authentication

Couchbase Server uses Simple Authenticating and Security Layer (SASL) for authenticating user interaction at the Server and at the Bucket levels. SASL provides several mechanisms for handling authentication. In its simplest form, it uses a Plain Text mechanism which sends the username and password between the clients in its plain text form.

Sending username and password across the network in plain-text is inherently not secure and potentially open’s you up to all kinds of filtering and sniffing attacks using publically available tools like Wire Shark. However, with the release of Couchbase 2.2 last year, CRAM-MD5 SASL authentication at the server is supported, and now with DP2 it’s available from the .NET SDK as well.

What CRAM-MD5 SASL does is use a challenge-response authentication mechanism to ensure that the password is hashed between the client and the server. How this works is the client initiates the communication and the server replies with a challenge. The client then uses the challenge to create HMAC-MD5 of the password and some additional information and sends this back to the server. The server uses the same challenge to compare the expected response. If they match, the authentication continues and if successful the client is granted access to the resource.

Note that to enable CRAM-MD5 on the client you don’t have to do anything! When the client initiates the communication it requests a list of supported SASL mechanisms, if the server it is attempting to connect to supports CRAM-MD5, then the client will use that mechanism.

Web.Config and App.Config Configuration Support

In DP1, we showed how to programmatically configure your cluster and Buckets. In DP2, we added support for Web.config and App.config configuration. Here is an example App.config:

<?xml version=”1.0″ encoding=”utf-8″ ?>
<sectionGroup name=”couchbaseClients”>
<section name=”couchbase” type=”Couchbase.Configuration.Client.Providers.CouchbaseClientSection, Couchbase”/>
<add uri=”http://localhost:8091″></add>
<add name=”default” password=”” useSsl=”false”>
<connectionPool name=”custom” maxSize=”10″ minSize=”5″ waitTimeout=”5000″ shutdownTimeout=”3000″></connectionPool>
<supportedRuntime version=”v4.0″ sku=”.NETFramework,Version=v4.5″ />


You start by creating a sectionGroup under the configSections for the CouchbaseClientSection that you will define later in the config file. Within the sectionGroup you create a new section and name it, in this case we are using an aptly named section called “couchbase”. Within the “couchbase” section you can specify a set of servers to use for bootstrapping and the Buckets you wish to work with. A Bucket specifies the connectionPool element which provides a means of configuring the internal TCP connection pool for a Bucket instance.

Additional Operator Support

Insert and Get operations were released in DP1, in DP2 the supported operations were expanded to include the following:

  • Upsert: update a key if it exists, otherwise add it.
  • Replace: update a key if it exists, failing if it doesn’t
  • Remove: removes a key from the database

Additionally, a number of internal operations for supporting SASL CRAM-MD5 are included in this release. Expect a full-set of operations including Check and Swap (CAS) and support for durability constraints in Beta 1 to be released sometime next month.

Getting the Bits

You can download DP2 from here and we have a very simple example here. Like any pre-release software, there are likely bugs and you can expect things to change in subsequent releases, so don’t use DP2 in production! If you do encounter a bug, wish to provide feedback (we hope you do), or want to suggest a feature, feel free to provide a comment or create an NCBC here.


Posted by Jeff Morris, Senior Software Engineer, Couchbase

Jeff Morris is a Senior Software Engineer at Couchbase. Prior to joining Couchbase, Jeff spent six years at Source Interlink as an Enterprise Web Architect. Jeff is responsible for the development of Couchbase SDKs and how to integrate with N1QL (query language).

Leave a reply