TinyPoker

libtinypoker application programming interface

libtinypoker provides application programming interfaces (APIs) to applications implementing the Internet Poker Protocol (IPP) Version 2.0. The library provides a robust communications framework that allows clients and servers to communicate over secure Transport Layer Security (TLS) using Internet Protocol version 4 (IPv4) and/or Internet Protocol version 6 (IPv6). The underlying code is designed to gracefully handle network problems such as unexpected disconnections and bad input. IPP message validation, normalization and parsing functions are available to developers as are several predefined types for representing poker games, players and cards.

This document will descibe how to use libtinypoker in your applications. The document also covers installing the library itself. Please read and make sure you understand the license before proceeding.

Install the Dependencies

libtinypoker has just two dependencies, GNU Transport Layer Security and GNU Scientific Library.

Obtain the Source Code

The next step is to get a copy of the libtinypoker source code. This can be done by checking out a fresh copy from the subversion repository or by downloading the latest release.

Build and Install libtinypoker

Example: Configure, make and install
 $ cmake -D CMAKE_INSTALL_PREFIX=/usr .
 $ make
 # make install

Generate X.509 Certificates

libtinypoker uses TLS to secure client/server communications. This is not a standard part of the Internet Poker Protocol, but it adds a layer of security that preventing players from snooping on each other with packet sniffers. See server setup for instructions on setting up a proxy server with stunnel that will allow unmodified legacy clients to connect.

For libtinypoker to work, it needs a server side certificate. You can obtain a certificate from a trusted certificate authority or you can create your own certificate authority and sign your own certificates. The example below demonstrates how to create your own certificate authority and sign your own certificates using the certtool program that comes with GNU TLS.

Example: ca.tmpl
cn = Dummy Certificate Authority
ca
cert_signing_key
Example: localhost.tmpl
organization = Dummy Organization
cn = localhost
tls_www_server
encryption_key
signing_key
dns_name = localhost
 $ certtool --generate-privkey > ca-key.pem
 $ certtool --generate-privkey > key.pem
 $ certtool --generate-self-signed --load-privkey ca-key.pem \
       --template ca.tmpl --outfile ca.pem
 $ certtool --generate-certificate --load-privkey key.pem \
       --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem \
       --template localhost.tmpl --outfile cert.pem

Library Initialization and Destruction

Several GNU TLS resources need to be allocated before network communications begin and deallocated after network connications end. Two functions are provided to accomplish this, ipp_init() and ipp_exit(). Additionally, the random number generator is allocated and freed in those functions. The one and only header file needed to use the API is tinypoker.h.

What follows is an example that simply initializes and cleans up after libtinypoker.

Example: test.c
#include <tinypoker.h>

int main(int argc, char *argv[]) {
        ipp_init();

        ipp_exit();
        return 0;
}

Compilation

Compiling a libtinypoker application is relatively simple. One simply needs to instruct the compiler to link against the library and GNU TLS.

 $ gcc -lpthread -ltinypoker -lgnutls -lgsl -lgslcblas -o test test.c

Shaking hands with the Server

The protocol calls for a handshake to happen between the client and the server. During the handshake the client connects, the server notifies the client of the supported protocol version, the client response with a buy in request and the server responds with a welcome message.

This can be done manually with a connect, a read, a send and another read. Since the code is 25+ lines and since every client application will need to do this, libtinypoker provides a helper function (demonstrated below).

Example: test.c
#include <tinypoker.h>

int main(int argc, char *argv[]) {
        ipp_socket *sock;

        ipp_init();

        sock = ipp_client_handshake("localhost", "ca.pem", "JSMITH", "ABC123", "500", NULL);
        if (!sock) {
                ipp_exit();
                return 1;
        }

        ipp_disconnect(sock);
        ipp_free_socket(sock);
        sock = NULL;

        ipp_exit();
        return 0;
}

Protocol Logging

Having access to the payload (text string) of every message that gets sent or recieved is useful for debugging. Each message could also be saved to a file for analysis and statistics gathering. Therefore, the send and read functions have a protocol logger callback. You can create your own logging function like the one below.

Example: test.c
#include <tinypoker.h>

void protocol_logger(char *msg) {
        if (msg && msg[0]) {
                printf("%s\n", msg);
        }
}

int main(int argc, char *argv[]) {
        ipp_socket *sock;

        ipp_init();

        sock = ipp_client_handshake("localhost", "ca.pem", "JSMITH", "ABC123", "500", protocol_logger);
        if (!sock) {
                ipp_exit();
                return 1;
        }

        ipp_disconnect(sock);
        ipp_free_socket(sock);
        sock = NULL;

        ipp_exit();
        return 0;
}

tinypokerd includes its own protocol logger which writes the messages to an XML file using libxml2.

To be continued

This document is being written as tinypokerclient and tinypokerbot are being developed, so it is still very much a work in progress. If you want to go further, take a look at tinypoker.h; it is well commented and should give you and idea about the functions and structures available.