Introduction to libkarmaclient

2.0.7

About libkarmaclient

libkarmaclient is a client library for the Karmasphere reputation system. It implements a protocol encoding for requests, and includes a threadsafe blocking socket API on POSIX systems. The library also gives access to the raw packet data to permit the use of an external I/O library, for example, a non-blocking I/O library.

This introductory document includes installation instructions, example usage of the library, and pointers for what to read next.

Download

The latest version of the source code is available for download from http://my.karmasphere.com/downloads/libkarmaclient/

Installation on Unix and MacOS/X

tar -zxvf libkarmaclient-<version>.tar.gz
cd libkarmaclient-<version>
./configure
make
make install

Installation on Windows

A build file is included for Microsoft Visual C.

Getting started

A full example of how to use the library is included below. There is also a commandline client in karmaquery.c. Beyond that, the best place to get started is by learning the query and response API in ks_bquery.c and ks_response.c If you want to use the builtin socket functions, you will also want to read ks_socket_posix.c.

The basic types provided by this library are:

• ks_number.c - integer number type
• ks_string.c - string type
• ks_array.c - array type
• ks_assoc.c - associative array type (also known as hash, map or dictionary)
• ks_bquery.c - Karmasphere BQuery object
• ks_response.c - Karmasphere response object
• ks_fact.c - Karmasphere fact object
• ks_combination.c - Karmasphere combination object
• ks_socket_posix.c - socket object, posix implementation (optional)

Coding and API Conventions

The library is written in pure ANSI C, and is object oriented. The first argument to any function is the target object. Constructors end in _new, destructors end in _free. The person creating any object is responsible for freeing it, unless it is placed into a container. All container types will deallocate their contents. Pointers may not be shared between containers; this will result in a double-deallocation, which is an error.

Apart from the primary interface, there are a number of ways to better interface your product with libkarmaclient.

• Custom allocation routines may be registered using ks_malloc_set()
• Custom error handlers may be registered with ks_error_handler_set()

Creating a query.

// Create a new query.
ks_bquery_t     *q = ks_bquery_new();

// Set a distinctive id on the query.
ks_bquery_id_set(q, "myid", 4);

// Scan through your data and add identities to the query.
// Add any relevant identities. The server will decompose and
// analyse them. Distinguish "special" identities with tags.
ks_bquery_identity_add_tagged(q, "fred@foo.com",
                                KS_IDT_DOMAIN_NAME, KS_TAG_SMTP_ENV_MAIL_FROM);
ks_bquery_identity_add_tagged(q, "123.45.6.7",
                                KS_IDT_IP4_ADDRESS, KS_TAG_SMTP_CLIENT_IP);
ks_bquery_identity_add(q, "http://www.phisher.com/?abc",
                                KS_IDT_URL);

// Specify the feedset you want to query.
ks_bquery_composite_add(q, "karmasphere.email-sender");

// Set any query flags. This example returns all facts individually.
ks_bquery_flags_set(q, KS_FL_FACTS);

Sending the query using builtin socket functions:

// If you want to use the builtin POSIX socket functions with retries:
ks_socket_t             *k = ks_socket_new(NULL, 0, IPPROTO_UDP);
ks_response_t   *r = ks_socket_ask(k, q, 0);
// Now check that r != NULL.

Sending the query using custom socket functions

If you want to write your own socket implementation, please read the documentation in ks_socket.h.

// If you use nio, get the raw packet data and send it:
ks_string_t     *s = ks_bquery_packet(q);
my_nio_send(socket, ks_string_get(s), ks_string_len(s));

// Then receive raw packet data and parse it:
char[] buf;
int     len = my_nio_recv(buf);
ks_response_t   *r = ks_response_bparse(buf, len);

Handling the response.

// Check whether the query generated an error.
ks_string_t             *e = ks_response_error(r);
if (e != NULL) {
        ...
}

// Retrieve combinations from the query.
ks_combination_t        *c = ks_response_combination(r, "mycombiner");
printf("%d : %s", ks_combination_score(c), ks_combination_data(c));

// Inspect the original facts, if KS_FL_FACTS was set.
for (int i = 0; i < ks_response_facts_length(r); i++) {
        ks_fact_t                       *fact = ks_response_fact(r, i);
        printf("%s : %d : %s", ks_fact_identity(fact),
                        ks_fact_score(fact), ks_fact_data(fact));
}

Freeing the query and response.

ks_bquery_free(q);
ks_response_free(r);

License

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. A full copy of the license is included in the file called LICENSE.

---