libcouchbase 1.3.0 → 1.3.2

data/ext/libcouchbase/include/libcouchbase/couchbase.h

@@ -57,6 +57,7 @@ typedef struct lcb_http_request_st *lcb_http_request_t;
 #include <libcouchbase/auth.h>
 #include <libcouchbase/tracing.h>
 #include <libcouchbase/_cxxwrap.h>
+#include <libcouchbase/cntl.h>
 
 #ifdef __cplusplus
 extern "C"{
@@ -275,7 +276,7 @@ struct lcb_create_st2 { LCB_CREATE_V2_FIELDS };
 #endif
 
 /**
- * @brief Innser structure for lcb_create().
+ * @brief Inner structure V3 for lcb_create().
  */
 struct lcb_create_st3 {
     const char *connstr; /**< Connection string */
@@ -296,6 +297,30 @@ struct lcb_create_st3 {
     lcb_type_t type;
 };
 
+/**
+ * @brief Inner structure V4 for lcb_create().
+ *
+ * Same as V3, but allows to supply logger (@see LCB_CNTL_LOGGER).
+ */
+struct lcb_create_st4 {
+    const char *connstr; /**< Connection string */
+
+    /**
+     * Username to use for authentication. This should only be set when
+     * connecting to a server 5.0 or greater.
+     */
+    const char *username;
+
+    /**
+     * Password for bucket. Can also be password for username on servers >= 5.0
+     */
+    const char *passwd;
+
+    lcb_logprocs *logger; /**< Logger */
+    struct lcb_io_opt_st *io; /**< IO Options */
+    lcb_type_t type;
+};
+
 /**
  * @brief Wrapper structure for lcb_create()
  * @see lcb_create_st3
@@ -311,6 +336,7 @@ struct lcb_create_st {
         struct lcb_create_st1 v1;
         struct lcb_create_st2 v2;
         struct lcb_create_st3 v3; /**< Use this field */
+        struct lcb_create_st4 v4;
     } v;
     LCB_DEPR_CTORS_CRST
 };
@@ -2396,7 +2422,7 @@ typedef lcb_CMDBASE lcb_CMDNOOP;
 typedef lcb_RESPSERVERBASE lcb_RESPNOOP;
 
 /**
- * @uncommitted
+ * @committed
  *
  * Send NOOP to the node
  *
@@ -2439,6 +2465,11 @@ lcb_noop3(lcb_t instance, const void *cookie, const lcb_CMDNOOP *cmd);
  */
 #define LCB_PINGSVC_F_FTS 0x08
 
+/**
+ * Ping Analytics for N1QL service. Used in lcb_CMDPING#services
+ */
+#define LCB_PINGSVC_F_ANALYTICS 0x10
+
 /**
  * Do not record any metrics or status codes from ping responses.
  * This might be useful to reduce overhead, when user-space
@@ -2467,7 +2498,7 @@ lcb_noop3(lcb_t instance, const void *cookie, const lcb_CMDNOOP *cmd);
 /**
  * Structure for PING requests.
  *
- * @uncommitted
+ * @committed
  */
 typedef struct {
     LCB_CMD_BASE;
@@ -2479,7 +2510,7 @@ typedef struct {
 /**
  * Type of the service. This enumeration is used in PING responses.
  *
- * @uncommitted
+ * @committed
  */
 typedef enum {
     LCB_PINGSVC_KV = 0,
@@ -2492,7 +2523,7 @@ typedef enum {
 /**
  * Status of the service
  *
- * @uncommitted
+ * @committed
  */
 typedef enum {
     LCB_PINGSTATUS_OK = 0,
@@ -2505,7 +2536,7 @@ typedef enum {
  * Entry describing the status of the service in the cluster.
  * It is part of lcb_RESPING structure.
  *
- * @uncommitted
+ * @committed
  */
 typedef struct {
     lcb_PINGSVCTYPE type; /**< type of the service */
@@ -2522,7 +2553,7 @@ typedef struct {
 /**
  * Structure for PING responses.
  *
- * @uncommitted
+ * @committed
  */
 typedef struct {
     LCB_RESP_BASE
@@ -2536,7 +2567,7 @@ typedef struct {
 /**
  * @brief Check connections by sending NOOP-like messages to all services.
  *
- * @uncommitted
+ * @committed
  *
  * When no metrics, required, it is possible to reduce memory overhead
  * by turning off response contents using #LCB_PINGOPT_F_NOMETRICS.
@@ -2590,7 +2621,7 @@ typedef struct {
 /**
  * @brief Returns diagnostics report about network connections.
  *
- * @uncommitted
+ * @committed
  *
  * @par Request
  * @code{.c}
@@ -2669,6 +2700,13 @@ typedef enum {
     /** Execute an Analytics Query */
     LCB_HTTP_TYPE_CBAS = 5,
 
+    /**
+     * Special pseudo-type, for ping endpoints in various services.
+     * Behaves like RAW (the lcb_ping3() function will setup custom path),
+     * but supports Keep-Alive
+     */
+    LCB_HTTP_TYPE_PING = 6,
+
     LCB_HTTP_TYPE_MAX
 } lcb_http_type_t;
 
@@ -4046,7 +4084,6 @@ int lcb_is_redacting_logs(lcb_t instance);
 }
 #endif /* __cplusplus */
 #include <libcouchbase/subdoc.h>
-#include <libcouchbase/cntl.h>
 #include <libcouchbase/deprecated.h>
 #include <libcouchbase/api-legacy.h>
 #endif /* LIBCOUCHBASE_COUCHBASE_H */

data/ext/libcouchbase/include/libcouchbase/crypto.h

@@ -29,110 +29,276 @@
 extern "C" {
 #endif
 
-typedef enum {
-    /* encryption (e.g. private key for assymetric ciphers) */
-    LCBCRYPTO_KEY_ENCRYPT = 0,
-    /* decryption (e.g. private key for assymetric ciphers) */
-    LCBCRYPTO_KEY_DECRYPT = 1,
-    LCBCRYPTO_KEY__MAX
-} lcbcrypto_KEYTYPE;
+/**
+ * @ingroup lcb-public-api
+ * @defgroup lcb-crypto-api Encryption
+ * @brief Register crypto-providers and working with encrypted fields of the documents.
+ * @details
+ * These routines contain functionality to define and hook crypto providers, as well as
+ * functions which should be used for portable (cross SDK) encoding of encrypted fields.
+ */
 
+/**
+ * @addtogroup lcb-crypto-api
+ * @{
+ */
+
+/**
+ * IOV-style structure for signing functions of crypto-provider.
+ *
+ * @committed
+ */
 typedef struct lcbcrypto_SIGV {
-    const uint8_t *data;
-    size_t len;
+    const uint8_t *data; /**< pointer to data */
+    size_t len;          /**< length of the data in bytes */
 } lcbcrypto_SIGV;
 
 struct lcbcrypto_PROVIDER;
+/**
+ * Crypto-provider interface.
+ *
+ * See full example in @ref example/crypto/openssl_symmetric_provider.c
+ *
+ * @see lcbcrypto_register
+ * @see lcbcrypto_unregister
+ *
+ * @committed
+ */
 typedef struct lcbcrypto_PROVIDER {
-    uint16_t version;
-    int16_t _refcnt;
-    uint64_t flags;
-    void *cookie;
-    void (*destructor)(struct lcbcrypto_PROVIDER *provider);
+    uint16_t version;                                        /**< version of the structure, current value is 1 */
+    int16_t _refcnt;                                         /**< reference counter */
+    uint64_t flags;                                          /**< provider-specific flags */
+    void *cookie;                                            /**< opaque pointer (e.g. pointer to wrapper instance) */
+    void (*destructor)(struct lcbcrypto_PROVIDER *provider); /**< destructor function, or NULL */
     union {
+        LCB_DEPRECATED2(
+            struct {
+                void (*release_bytes)(struct lcbcrypto_PROVIDER * provider, void *bytes);
+                lcb_error_t (*load_key)(struct lcbcrypto_PROVIDER * provider, lcbcrypto_KEYTYPE type, const char *keyid,
+                                        uint8_t **key, size_t *key_len);
+                lcb_error_t (*generate_iv)(struct lcbcrypto_PROVIDER * provider, uint8_t * *iv, size_t * iv_len);
+                lcb_error_t (*sign)(struct lcbcrypto_PROVIDER * provider, const lcbcrypto_SIGV *inputs,
+                                    size_t input_num, uint8_t **sig, size_t *sig_len);
+                lcb_error_t (*verify_signature)(struct lcbcrypto_PROVIDER * provider, const lcbcrypto_SIGV *inputs,
+                                                size_t input_num, uint8_t *sig, size_t sig_len);
+                lcb_error_t (*encrypt)(struct lcbcrypto_PROVIDER * provider, const uint8_t *input, size_t input_len,
+                                       const uint8_t *key, size_t key_len, const uint8_t *iv, size_t iv_len,
+                                       uint8_t **output, size_t *output_len);
+                lcb_error_t (*decrypt)(struct lcbcrypto_PROVIDER * provider, const uint8_t *input, size_t input_len,
+                                       const uint8_t *key, size_t key_len, const uint8_t *iv, size_t iv_len,
+                                       uint8_t **output, size_t *output_len);
+            } v0,
+            "v0 crypto API has been deprecated, use v1");
         struct {
+            /** function to use when the library wants to deallocate memory, returned by provider */
             void (*release_bytes)(struct lcbcrypto_PROVIDER *provider, void *bytes);
-            lcb_error_t (*load_key)(struct lcbcrypto_PROVIDER *provider, lcbcrypto_KEYTYPE type, const char *keyid,
-                                    uint8_t **key, size_t *key_len);
+            /** initialization vector (IV) generator */
             lcb_error_t (*generate_iv)(struct lcbcrypto_PROVIDER *provider, uint8_t **iv, size_t *iv_len);
+            /** generate cryptographic signature for the data */
             lcb_error_t (*sign)(struct lcbcrypto_PROVIDER *provider, const lcbcrypto_SIGV *inputs, size_t input_num,
                                 uint8_t **sig, size_t *sig_len);
+            /** verify signature of the data */
             lcb_error_t (*verify_signature)(struct lcbcrypto_PROVIDER *provider, const lcbcrypto_SIGV *inputs,
                                             size_t input_num, uint8_t *sig, size_t sig_len);
+            /** encrypt data */
             lcb_error_t (*encrypt)(struct lcbcrypto_PROVIDER *provider, const uint8_t *input, size_t input_len,
-                                   const uint8_t *key, size_t key_len, const uint8_t *iv, size_t iv_len,
-                                   uint8_t **output, size_t *output_len);
+                                   const uint8_t *iv, size_t iv_len, uint8_t **output, size_t *output_len);
+            /** decrypt data */
             lcb_error_t (*decrypt)(struct lcbcrypto_PROVIDER *provider, const uint8_t *input, size_t input_len,
-                                   const uint8_t *key, size_t key_len, const uint8_t *iv, size_t iv_len,
-                                   uint8_t **output, size_t *output_len);
-        } v0;
+                                   const uint8_t *iv, size_t iv_len, uint8_t **output, size_t *output_len);
+            /** returns key identifier, associated with the crypto-provider */
+            const char *(*get_key_id)(struct lcbcrypto_PROVIDER *provider);
+        } v1;
     } v;
 } lcbcrypto_PROVIDER;
 
+/**
+ * Structure for JSON field specification for encrypt/decrypt API.
+ *
+ * @see lcbcrypto_encrypt_fields
+ * @see lcbcrypto_decrypt_fields
+ *
+ * @committed
+ */
 typedef struct lcbcrypto_FIELDSPEC {
-    const char *name;
-    const char *alg;
-    const char *kid;
+    const char *name; /**< field name (NUL-terminated) */
+    const char *alg;  /**< crypto provider alias (NUL-terminated) */
+    LCB_DEPRECATED2(const char *kid,
+                    "Do not use kid field. Encryption keys have to be part of the provider implementation");
 } lcbcrypto_FIELDSPEC;
 
+/**
+ * Command to encrypt JSON fields.
+ *
+ * @see lcbcrypto_encrypt_fields
+ * @committed
+ */
 typedef struct lcbcrypto_CMDENCRYPT {
-    uint16_t version;
-    const char *prefix;
-    const char *doc;
-    size_t ndoc;
-    char *out;
-    size_t nout;
-    lcbcrypto_FIELDSPEC *fields;
-    size_t nfields;
+    uint16_t version;   /**< version of the structure, currently valid value is 0 */
+    const char *prefix; /**< prefix to encrypted field. When NULL, it will use @ref LCBCRYPTO_DEFAULT_FIELD_PREFIX */
+    const char *doc;    /**< pointer to the input JSON document */
+    size_t ndoc;        /**< size of the input JSON document */
+    char *out;   /**< pointer to output JSON document. When no changes were applied, this field will be set to NULL */
+    size_t nout; /**< size of the output JSON document */
+    lcbcrypto_FIELDSPEC *fields; /**< list of field specs */
+    size_t nfields;              /**< number of field specs */
 } lcbcrypto_CMDENCRYPT;
 
+/**
+ * Command to decrypt JSON fields.
+ *
+ * @see lcbcrypto_decrypt_fields
+ * @committed
+ */
 typedef struct lcbcrypto_CMDDECRYPT {
-    uint16_t version;
-    const char *prefix;
-    const char *doc;
-    size_t ndoc;
-    char *out;
-    size_t nout;
+    uint16_t version;   /**< version of the structure, currently valid value is 0 */
+    const char *prefix; /**< prefix to encrypted field. When NULL, it will use @ref LCBCRYPTO_DEFAULT_FIELD_PREFIX */
+    const char *doc;    /**< pointer to the input JSON document */
+    size_t ndoc;        /**< size of the input JSON document */
+    char *out;   /**< pointer to output JSON document. When no changes were applied, this field will be set to NULL */
+    size_t nout; /**< size of the output JSON document */
+    lcbcrypto_FIELDSPEC *fields; /**< list of field specs */
+    size_t nfields;              /**< number of field specs */
 } lcbcrypto_CMDDECRYPT;
 
 /**
- * @uncommitted
+ * Register crypto-provider for specified alias.
+ *
+ * See full example in @ref example/crypto/openssl_symmetric_provider.c
+ *
+ * @param instance the handle
+ * @param name provider alias, this will be recorded in JSON.
+ * @param provider implementation of the crypto-provider
+ *
+ * @par Register provider as "AES-256-HMAC-SHA256".
+ * @code{.c}
+ * lcbcrypto_PROVIDER *provider = calloc(1, sizeof(lcbcrypto_PROVIDER));
+ * provider->version = 1;
+ * provider->destructor = osp_free;
+ * provider->v.v1.release_bytes = osp_release_bytes;
+ * provider->v.v1.generate_iv = osp_generate_iv;
+ * provider->v.v1.sign = osp_sign;
+ * provider->v.v1.verify_signature = osp_verify_signature;
+ * provider->v.v1.encrypt = osp_encrypt;
+ * provider->v.v1.decrypt = osp_decrypt;
+ * provider->v.v1.get_key_id = osp_get_key_id;
+ * lcbcrypto_register(instance, "AES-256-HMAC-SHA256", provider);
+ * @endcode
  */
 LIBCOUCHBASE_API void lcbcrypto_register(lcb_t instance, const char *name, lcbcrypto_PROVIDER *provider);
 
 /**
- * @uncommitted
+ * Unregister crypto-provider for specified alias.
+ *
+ * See full example in @ref example/crypto/openssl_symmetric_provider.c
+ *
+ * @param instance the handle
+ * @param name provider alias.
  */
 LIBCOUCHBASE_API void lcbcrypto_unregister(lcb_t instance, const char *name);
 
 /**
- * @uncommitted
+ * Increment reference counter for crypto-provider.
+ *
+ * @param provider provider instance
  */
 LIBCOUCHBASE_API void lcbcrypto_ref(lcbcrypto_PROVIDER *provider);
 
 /**
- * @uncommitted
+ * Decrement reference counter for crypto-provider.
+ *
+ * It calls destructor once counter reaches zero. The provider instance should not be used after calling this function.
+ *
+ * @param provider provider instance
  */
 LIBCOUCHBASE_API void lcbcrypto_unref(lcbcrypto_PROVIDER *provider);
 
 /**
- * @uncommitted
+ * Default prefix for encrypted JSON fields.
+ */
+#define LCBCRYPTO_DEFAULT_FIELD_PREFIX "__crypt_"
+
+/**
+ * Encrypt all specified fields in the JSON encoded object.
  *
- * encrypt and replace fields specified by JSON paths (zero-terminated) with encrypted contents
+ * The function will remove original content of the field, and rename it using @ref LCBCRYPTO_DEFAULT_FIELD_PREFIX, or
+ * custom prefix, specified in the command.
+ *
+ * See full example in @ref example/crypto/openssl_symmetric_encrypt.c
+ *
+ * @param instance the handle
+ * @param cmd the command structure
+ * @return LCB_SUCCESS if successful, an error code otherwise
+ *
+ * @par Encrypt field "message" in the document using provider registered as "AES-256-HMAC-SHA256"
+ * @code{.c}
+ * lcbcrypto_CMDENCRYPT cmd = {};
+ * lcbcrypto_FIELDSPEC field = {};
+ * lcb_error_t err;
+ *
+ * cmd.version = 0;
+ * cmd.prefix = NULL;
+ * cmd.doc = "{\"message\":\"hello world\"}";
+ * cmd.ndoc = strlen(cmd.doc);
+ * cmd.nfields = 1;
+ * cmd.fields = &field;
+ * field.name = "message";
+ * field.alg = "AES-256-HMAC-SHA256";
+ *
+ * err = lcbcrypto_encrypt_fields(instance, &cmd);
+ * @endcode
+ *
+ * @committed
  */
 LIBCOUCHBASE_API lcb_error_t lcbcrypto_encrypt_fields(lcb_t instance, lcbcrypto_CMDENCRYPT *cmd);
 
 /**
- * @uncommitted
+ * Decrypt all specified fields in the JSON encoded object.
+ *
+ * The function will remove original content of the field, and rename it using @ref LCBCRYPTO_DEFAULT_FIELD_PREFIX, or
+ * custom prefix, specified in the command.
+ *
+ * See full example in @ref example/crypto/openssl_symmetric_decrypt.c
+ *
+ * @param instance the handle
+ * @param cmd the command structure
+ * @return LCB_SUCCESS if successful, an error code otherwise
+ *
+ * @par Decrypt field "message" in the document using provider registered as "AES-256-HMAC-SHA256"
+ * @code{.c}
+ * lcbcrypto_CMDDECRYPT cmd = {};
+ * lcbcrypto_FIELDSPEC field = {};
+ * lcb_error_t err;
+ *
+ * cmd.version = 0;
+ * cmd.prefix = NULL;
+ * cmd.doc = "{\"__crypt_message\":{" \
+ *               "\"alg\":\"AES-256-HMAC-SHA256\"," \
+ *               "\"ciphertext\":\"gYuyEhf6S0AiMGZJZZV35Q==\"," \
+ *               "\"iv\":\"ZedmvjWy0lIrLn6OmQmNqQ==\"," \
+ *               "\"kid\":\"mykeyid\"," \
+ *               "\"sig\":\"FgleInW3Iia04XqLbm5Hd3qVoa77Ocs7g2x4pOutEtY=\"}" \
+ *           "}";
+ * cmd.ndoc = strlen(cmd.doc);
+ * cmd.nfields = 1;
+ * cmd.fields = &field;
+ * field.name = "message";
+ * field.alg = "AES-256-HMAC-SHA256";
+ *
+ * err = lcbcrypto_decrypt_fields(instance, &cmd);
+ * @endcode
  *
- * find and decrypt all fields in the JSON encoded object
+ * @committed
  */
 LIBCOUCHBASE_API lcb_error_t lcbcrypto_decrypt_fields(lcb_t instance, lcbcrypto_CMDDECRYPT *cmd);
+/**@}*/
 
 /** @deprecated Use @ref lcbcrypto_encrypt_fields() */
-LCB_DEPR_API2(lcb_error_t lcbcrypto_encrypt_document(lcb_t instance, lcbcrypto_CMDENCRYPT *cmd), "Use lcbcrypto_encrypt_fields");
+LCB_DEPR_API2(lcb_error_t lcbcrypto_encrypt_document(lcb_t instance, lcbcrypto_CMDENCRYPT *cmd),
+              "Use lcbcrypto_encrypt_fields");
 /** @deprecated Use @ref lcbcrypto_decrypt_fields() */
-LCB_DEPR_API2(lcb_error_t lcbcrypto_decrypt_document(lcb_t instance, lcbcrypto_CMDDECRYPT *cmd), "Use lcbcrypto_decrypt_fields");
+LCB_DEPR_API2(lcb_error_t lcbcrypto_decrypt_document(lcb_t instance, lcbcrypto_CMDDECRYPT *cmd),
+              "Use lcbcrypto_decrypt_fields");
 
 #ifdef __cplusplus
 }