libcouchbase 0.3.3 → 1.0.0

data/ext/libcouchbase/contrib/cJSON/cJSON.c

@@ -350,7 +350,7 @@ static const char *parse_object(cJSON *item,const char *value);
 static char *print_object(cJSON *item,int depth,int fmt);
 
 /* Utility to jump whitespace and cr/lf */
-static const char *skip(const char *in) {while (in && (unsigned char)*in<=32) in++; return in;}
+static const char *skip(const char *in) {while (in && *in && (unsigned char)*in<=32) in++; return in;}
 
 /* Parse an object - create a new root, and populate. */
 cJSON *cJSON_Parse(const char *value)

data/ext/libcouchbase/contrib/cbsasl/src/client.c

@@ -163,6 +163,8 @@ cbsasl_error_t cbsasl_client_step(cbsasl_conn_t *conn,
     cbsasl_secret_t *pass;
     cbsasl_error_t ret;
 
+    (void)not_used;
+
     if (conn->client == 0) {
         return SASL_BADPARAM;
     }

data/ext/libcouchbase/example/users/README

@@ -0,0 +1,48 @@
+This sample demonstrates how to manage user accounts.
+
+$ cc -lcouchbase users.c
+
+$ ./a.out couchbase://192.168.1.194 Administrator password
+1. Create account 'cbtestuser' with predefined set of roles
+HTTP status: 200
+Server: Couchbase Server
+Pragma: no-cache
+Date: Fri, 23 Jun 2017 12:39:52 GMT
+Content-Type: application/json
+Content-Length: 2
+Cache-Control: no-cache
+""
+2. Retrieve list of all accounts in the cluster
+HTTP status: 200
+Transfer-Encoding: chunked
+Server: Couchbase Server
+Pragma: no-cache
+Date: Fri, 23 Jun 2017 12:39:52 GMT
+Content-Type: application/json
+Cache-Control: no-cache
+[
+  {
+    "name": "TestUser",
+    "id": "cbtestuser",
+    "domain": "local",
+    "roles": [
+      {
+        "role": "bucket_admin",
+        "bucket_name": "default"
+      },
+      {
+        "role": "cluster_admin"
+      }
+    ]
+  }
+]
+
+3. Remove account 'cbtestuser'
+HTTP status: 200
+Server: Couchbase Server
+Pragma: no-cache
+Date: Fri, 23 Jun 2017 12:39:52 GMT
+Content-Type: application/json
+Content-Length: 2
+Cache-Control: no-cache
+""

data/ext/libcouchbase/example/users/users.c

@@ -0,0 +1,147 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2017 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+/**
+ * @file
+ *
+ * This is an example file showing how to create and list user accounts
+ * on Couchbase Cluster 5.
+ *
+ * https://developer.couchbase.com/documentation/server/current/rest-api/rbac.html
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <libcouchbase/couchbase.h>
+
+static void die(lcb_t instance, const char *msg, lcb_error_t err)
+{
+    fprintf(stderr, "%s. Received code 0x%X (%s)\n", msg, err, lcb_strerror(instance, err));
+    exit(EXIT_FAILURE);
+}
+
+void http_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *r)
+{
+    const lcb_RESPHTTP *resp = (const lcb_RESPHTTP *)r;
+
+    printf("HTTP status: %d\n", resp->htstatus);
+    if (resp->headers) {
+        for (const char *const *cur = resp->headers; *cur; cur += 2) {
+            printf("%s: %s\n", cur[0], cur[1]);
+        }
+    }
+    if (resp->nbody) {
+        printf("%*s\n", (int)resp->nbody, (char *)resp->body);
+    }
+    if (resp->rc != LCB_SUCCESS) {
+        die(instance, "Failed to execute HTTP request", resp->rc);
+    }
+}
+
+int main(int argc, char *argv[])
+{
+    lcb_error_t err;
+    lcb_t instance;
+    struct lcb_create_st create_options = {0};
+
+    create_options.version = 3;
+
+    if (argc < 3) {
+        fprintf(stderr, "Usage: %s couchbase://host/bucket ADMIN_NAME ADMIN_PASSWORD\n", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    create_options.v.v3.connstr = argv[1];
+    create_options.v.v3.username = argv[2];
+    create_options.v.v3.passwd = argv[3];
+
+    err = lcb_create(&instance, &create_options);
+    if (err != LCB_SUCCESS) {
+        die(NULL, "Failed create couchbase handle", err);
+    }
+
+    err = lcb_connect(instance);
+    if (err != LCB_SUCCESS) {
+        die(instance, "Failed schedule connection", err);
+    }
+
+    lcb_wait(instance);
+
+    err = lcb_get_bootstrap_status(instance);
+    if (err != LCB_SUCCESS) {
+        die(instance, "Failed bootstrap from cluster", err);
+    }
+
+    lcb_install_callback3(instance, LCB_CALLBACK_HTTP, http_callback);
+
+    printf("1. Create account 'cbtestuser' with predefined set of roles\n");
+    {
+        lcb_CMDHTTP cmd = {0};
+        char *path = "/settings/rbac/users/local/cbtestuser";
+        char *body = "name=TestUser&password=cbtestuserpwd&roles=cluster_admin,bucket_admin[default]";
+
+        cmd.type = LCB_HTTP_TYPE_MANAGEMENT;
+        cmd.method = LCB_HTTP_METHOD_PUT;
+        cmd.content_type = "application/x-www-form-urlencoded";
+        LCB_CMD_SET_KEY(&cmd, path, strlen(path));
+        cmd.body = body;
+        cmd.nbody = strlen(body);
+
+        err = lcb_http3(instance, NULL, &cmd);
+        if (err != LCB_SUCCESS) {
+            die(instance, "Failed schedule command to upsert user", err);
+        }
+        lcb_wait(instance);
+    }
+
+    printf("2. Retrieve list of all accounts in the cluster\n");
+    {
+        lcb_CMDHTTP cmd = {0};
+        char *path = "/settings/rbac/users/local";
+
+        cmd.type = LCB_HTTP_TYPE_MANAGEMENT;
+        cmd.method = LCB_HTTP_METHOD_GET;
+        LCB_CMD_SET_KEY(&cmd, path, strlen(path));
+
+        err = lcb_http3(instance, NULL, &cmd);
+        if (err != LCB_SUCCESS) {
+            die(instance, "Failed schedule command to upsert user", err);
+        }
+        lcb_wait(instance);
+    }
+
+    printf("3. Remove account 'cbtestuser'\n");
+    {
+        lcb_CMDHTTP cmd = {0};
+        char *path = "/settings/rbac/users/local/cbtestuser";
+
+        cmd.type = LCB_HTTP_TYPE_MANAGEMENT;
+        cmd.method = LCB_HTTP_METHOD_DELETE;
+        LCB_CMD_SET_KEY(&cmd, path, strlen(path));
+
+        err = lcb_http3(instance, NULL, &cmd);
+        if (err != LCB_SUCCESS) {
+            die(instance, "Failed schedule command to upsert user", err);
+        }
+        lcb_wait(instance);
+    }
+    /* Now that we're all done, close down the connection handle */
+    lcb_destroy(instance);
+    return 0;
+}

data/ext/libcouchbase/include/libcouchbase/auth.h

@@ -1,6 +1,11 @@
 #ifndef LCB_AUTH_H
 #define LCB_AUTH_H
 
+/**
+ * @file
+ * Credentials store for Couchbase
+ */
+
 #ifdef __cplusplus
 namespace lcb { class Authenticator; }
 typedef lcb::Authenticator lcb_AUTHENTICATOR;
@@ -10,20 +15,109 @@ typedef struct lcb_AUTHENTICATOR_Cdummy lcb_AUTHENTICATOR;
 #endif
 
 /**
- * @class lcb_AUTHENTICATOR
+ * @ingroup lcb-public-api
+ * @defgroup lcb-auth Authentication
+ *
+ * @details
+ *
+ * The @ref lcb_AUTHENTICATOR object is how the library stores credentials
+ * internally, and may be used in cases where you'd like to manage credentials
+ * in an object separate from the library. This interface also provides better
+ * clarification between 'old style' (Classic) and new style (RBAC) auth.
+ *
+ * If you don't have a specific need to have credentials managed in their own.
+ * @ref lcb_create_st3::username and @ref lcb_create_st3::passwd fields (note
+ * that `username` is only valid on clusters 5.0 and higher):
+ *
+ * @code{.c}
+ * crst.v.v3.username = "user"; // Only for newer clusters
+ * crst.v.v3.passwd = "s3cr3t";
+ * lcb_create(&instance, &crst);
+ * @endcode
  *
- * The lcb_AUTHENTICATOR object allows greater flexibility with regard to
- * adding more than a single bucket/password credential pair. It also restores
- * the ability to use "true" usernames (though these are not used at present
- * yet).
+ * If you are connecting to a cluster older than 5.0 and would like to issue
+ * N1QL queries against multiple password-protected buckets, you can use
+ * the @ref LCB_CNTL_BUCKET_CRED setting to "add" more bucket:password pairs
+ * to the library. The library will then send these credentials whenever you
+ * issue a query with the @ref LCB_CMD_F_MULTIAUTH flag set.
+ *
+ * @code{.c}
+ * lcb_BUCKETCRED creds;
+ * creds[0] = "secondBucket";
+ * creds[1] = "secondPass";
+ * lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_BUCKET_CRED, creds);
+ * @endcode
+ *
+ * Or if you have a JSON encoder handy (or are interfacing from a higher level
+ * language) you can use the lcb_cntl_string() variant:
+ *
+ * @code{.c}
+ * JsonArray *arr = new_json_array();
+ * json_array_push_string("secondBucket");
+ * json_array_push_string("secondPass");
+ * char *s = json_encode(arr);
+ * lcb_cntl_string(instance, "bucket_cred", s);
+ * @endcode
+ *
+ * The json functions in the above example are mockups of however you would
+ * actually create a JSON array.
+ *
+ * @addtogroup lcb-auth
+ * @{
  */
 
 /**
- * @volatile
+ * @class lcb_AUTHENTICATOR
+ * Opaque pointer containing credentials for the library.
+ */
+
+/**
+ * @uncommitted
+ *
  * Creates a new authenticator object. You may destroy it using lcbauth_unref().
  * The returned object initially has a refcount of 1.
  *
  * @return A new authenticator object.
+ *
+ * You must set the mode on this object before adding credentials to it. See
+ * @ref lcbauth_set_mode().
+ *
+ * Once you have added all the credentials to the object, you may assign it
+ * (or a copy, see lcbauth_clone()) to a library handle via lcb_set_auth().
+ *
+ * Setting RBAC Auth:
+ *
+ * @code{.c}
+ * lcb_AUTHENTICATOR *auth = lcbauth_new();
+ * lcbauth_set_mode(auth, LCBAUTH_MODE_RBAC);
+ * lcbauth_add_pass(auth, "mark", "secret", LCBAUTH_F_CLUSTER);
+ *
+ * lcb_t instance;
+ * lcb_create_st crst = { 0 };
+ * crst.version = 3;
+ * crst.v.v3.connstr = "couchbase://cbhost.com/myBucket";
+ * lcb_create(&instance, &crst);
+ * lcb_set_auth(instance, auth);
+ * lcbauth_unref(auth);
+ * @endcode
+ *
+ * Setting multi-bucket classic auth, also with cluster administrative
+ * credentials:
+ *
+ * @code{.c}
+ * lcb_AUTHENTICATOR *auth = lcbauth_new();
+ * lcbauth_set_mode(auth, LCBAUTH_MODE_CLASSIC);
+ * lcbauth_add_pass(auth, "myBucket", "secret", LCBAUTH_F_BUCKET);
+ * lcbauth_add_pass(auth, "otherBucket", "otherSecret", LCBAUTH_F_BUCKET);
+ * lcbauth_add_pass(auth, "Administrator", "password", LCBAUTH_F_CLUSTER);
+ * lcb_t instance;
+ * lcb_create_st crst = { 0 };
+ * crst.version = 3;
+ * crst.v.v3.connstr = "couchbase://cbhost.com/myBucket";
+ * lcb_create(&instance, &crst);
+ * lcb_set_auth(instance, auth);
+ * lcbauth_unref(auth);
+ * @endcode
  */
 LIBCOUCHBASE_API
 lcb_AUTHENTICATOR *
@@ -36,18 +130,34 @@ typedef enum {
     /** User/Password is administrative; for cluster */
     LCBAUTH_F_CLUSTER = 1<<1,
 
-    /** User is bucket name. Password is bucket password */
+    /**
+     * User is bucket name. Password is bucket password. This flag is only
+     * used for legacy authentication. Using it with RBAC authentication will
+     * return an error
+     */
     LCBAUTH_F_BUCKET = 1<<2
 } lcbauth_ADDPASSFLAGS;
 
 /**
- * @volatile
+ * @uncommitted
  *
  * Add a set of credentials
  * @param auth
  * @param user the username (or bucketname, if LCBAUTH_F_BUCKET is passed)
  * @param pass the password. If the password is NULL, the credential is removed
- * @param flags one of @ref LCBAUTH_F_CLUSTER or @ref LCBAUTH_F_BUCKET.
+ * @param flags one of @ref LCBAUTH_F_CLUSTER or @ref LCBAUTH_F_BUCKET. If both
+ * flags are combined then the credential will be used for both bucket-level
+ * and cluster-level administrative operations
+ * (using @ref LCB_HTTP_TYPE_MANAGEMENT).
+ * @return LCB_OPTIONS_CONFLICT if @ref LCBAUTH_F_BUCKET is used in conjunction
+ * with @ref LCBAUTH_MODE_RBAC.
+ *
+ * @note
+ * You must set the mode of the authenticator using @ref lcbauth_set_mode()
+ * before calling this function
+ *
+ * @note when using @ref LCBAUTH_MODE_RBAC, only @ref LCBAUTH_F_CLUSTER is
+ * supported.
  */
 LIBCOUCHBASE_API
 lcb_error_t
@@ -56,44 +166,78 @@ lcbauth_add_pass(lcb_AUTHENTICATOR *auth, const char *user, const char *pass, in
 /**
  * @volatile
  *
- * Gets the global username and password. This is either the lone bucket
- * password, or an explicit cluster password.
+ * Increments the refcount on the authenticator object
  * @param auth
- * @param[out] u Global username
- * @param[out] p Global password
+ *
+ * The only time you would want to call this function is when sharing a single
+ * @ref lcb_AUTHENTICATOR with multiple @ref lcb_t instances. While doing
+ * so is theoretically possible, it is not supported or tested.
  */
+LIBCOUCHBASE_API
 void
-lcbauth_get_upass(const lcb_AUTHENTICATOR *auth, const char **u, const char **p);
-
+lcbauth_ref(lcb_AUTHENTICATOR *auth);
 
 /**
- * @private
+ * @uncomitted
  *
- * Get a user/bucket password
- * @param auth the authenticator
- * @param name the name of the bucket
- * @return the password for the bucket, or NULL if the bucket has no password
- * (or is unknown to the authenticator)
+ * Decrements the refcount on the authenticator object, freeing it if there
+ * are no more owners.
+ *
+ * @param auth
  */
-const char *
-lcbauth_get_bpass(const lcb_AUTHENTICATOR *auth, const char *name);
+LIBCOUCHBASE_API
+void
+lcbauth_unref(lcb_AUTHENTICATOR *auth);
 
 /**
  * @uncomitted
- * Increments the refcount on the authenticator object
- * @param auth
+ *
+ * Makes a copy of an existing lcb_AUTHENTICATOR object. The returned
+ * authenticator object has a reference count of 1.
+ * @param src the authenticator object to clone
+ * @return the cloned authenticator.
+ *
+ * This function is useful when you wish to copy an existing set of credentials
+ * for use with a new client.
  */
 LIBCOUCHBASE_API
-void
-lcbauth_ref(lcb_AUTHENTICATOR *auth);
+lcb_AUTHENTICATOR *
+lcbauth_clone(const lcb_AUTHENTICATOR *src);
+
+typedef enum {
+    /**
+     * Use "bucket-specific" credentials when authenticating. This is the
+     * only way of authenticating up to server version 5.0
+     */
+    LCBAUTH_MODE_CLASSIC = 0,
+
+    /**
+     * Use role-based access control. This allows the same user to have
+     * access to multiple buckets with a single set of credentials.
+     *
+     * Note that if this option is selected, it becomes impossible to use
+     * @ref LCBAUTH_F_BUCKET with lcbauth_add_pass()
+     */
+    LCBAUTH_MODE_RBAC = 1
+} lcbauth_MODE;
 
 /**
- * Decrements the refcount on the authenticator object
- * @param auth
+ * @uncomitted
+ *
+ * Set the mode of this authenticator.
+ * @param src the authenticator
+ * @param mode the mode to use.
+ * @return error if the authenticator already contains credentials.
+ *
+ * @note
+ * This function should be called as early as possible. It is not possible to
+ * change the mode after credentials have been added
  */
 LIBCOUCHBASE_API
-void
-lcbauth_unref(lcb_AUTHENTICATOR *auth);
+lcb_error_t
+lcbauth_set_mode(lcb_AUTHENTICATOR *src, lcbauth_MODE mode);
+
+/** @} */
 
 #ifdef __cplusplus
 }