lib/HACKING

   1 HACKING file for libradsec (in Emacs -*- org -*- mode).
   2
   3 Status as of libradsec-0.2.0.dev (2013-05-02).
   4
   5 * Build instructions
   6 sh autogen.sh
   7 ./configure #--enable-tls
   8 make
   9
  10 examples/client -r examples/client.conf blocking-tls; echo $?
  11
  12 * Dependencies
  13 Details (within parentheses) apply to Debian Wheezy.
  14
  15 - libconfuse (2.7-4)
  16   sudo apt-get install libconfuse-dev libconfuse0
  17 - libevent2 (2.0.19-stable-3)
  18   sudo apt-get install libevent-dev libevent-2.0-5
  19 - OpenSSL (1.0.1c-4) -- optional, for TLS and DTLS support
  20   sudo apt-get install libssl-dev libssl1.0.0
  21
  22 * Functionality and quality in 0.0.x
  23 ** Not well tested
  24 - reading config file
  25 - [TCP] short read
  26 - [TCP] short write
  27 - [TLS] basic tls support
  28 - [TLS] preshared key support
  29 - [TLS] verification of CN
  30
  31 ** Known issues
  32 - error handling when server can't bind to given listen_addr+port
  33 - configuration of listen_addr/service is per realm
  34 - error stack is only one entry deep
  35 - custom allocation scheme is not used in all places
  36
  37 ** Not implemented
  38 - dispatch mode (planned for 0.1)
  39 - [client] server failover / RFC3539 watchdog (planned for 0.1)
  40 - [server] support (planned for 0.2)
  41 - [client] TCP keepalive
  42 - on-your-own mode
  43 - [DTLS] support
  44
  45 * Found a bug?
  46 Please report it. That is how we improve the quality of the code.
  47
  48 If possible, please build the library with DEBUG defined (CFLAGS="-g
  49 -DDEBUG") and reproduce the problem. With DEBUG defined, lots of
  50 asserts are enabled which might give a hint about what's gone wrong.
  51
  52 Running the library under gdb is another good idea. If you experience
  53 a crash, catching the crash in gdb and providing a backtrace is highly
  54 valuable for debugging.
  55
  56 Contact: mailto:linus+libradsec@nordu.net
  57
  58
  59 * Design of the API
  60 - There are three usage modes:
  61
  62   - Application uses blocking send and receive calls (blocking
  63     mode). This is typically fine for a simple client.
  64
  65   - Application registers callbacks with libradsec and runs the
  66     libevent dispatch loop (a.k.a. user dispatch mode). This would
  67     probably be how one would implement a server or a proxy.
  68
  69   - Application runs its own event loop, using fd's for select and
  70     performs I/O using libradsec send/receive functions
  71     (a.k.a. on-your-own mode). Might be useful for an application
  72     which already has an event loop that wants to add RadSec
  73     functionality.
  74
  75 - Apart from configuration and error handling, an application
  76   shouldn't need to handle TCP and UDP connections
  77   differently. Similarly, the use of TLS/DTLS or not shouldn't
  78   influence the libradsec calls made by the application.
  79
  80 - Configuration is done either by using the API or by pointing at a
  81   configuration file which is parsed by libradsec.
  82
  83 - Fully reentrant.
  84
  85 - Application chooses allocation regime.
  86
  87 Note that as of 0.0.2.dev libradsec suffers from way too much focus on
  88 the behaviour of a blocking client and is totally useless as a server.
  89 Not only does it lack most of the functions needed for writing a
  90 server but it also contains at least one architectural mishap which
  91 kills the server idea -- a connection timeout (TCP) or a retransmit
  92 timeout (UDP) will result in the event loop being broken. The same
  93 thing will happen if there's an error on a TCP connection, f.ex. a
  94 failing certificate validation (TLS).
  95
  96 * Notes on internals
  97 ** How to connect an outgoing connection?
  98 Connecting is not done explicitly by the application but implicitly by
  99 rs_message_send(). The application can treat connections in the same
 100 way regardless of whether they're connection-oriented (i.e. TCP) or
 101 not (UDP).
 102
 103 rs_message_send(msg)
 104   if msg->conn is open: mesasge_do_send(msg)
 105   else:
 106     -> _conn_open(conn, msg)
 107       pick configured peer
 108       event_init_socket(peer)
 109       if TCP or TLS:
 110         init tcp timers
 111         event_init_bufferevent(conn, peer)
 112       else:
 113         init udp timers
 114       if not connected and not connecting:
 115         event_do_connect(conn)
 116
 117   if TCP:
 118     bufferevent_setcb()
 119     bufferevent_enable()
 120   else:
 121     event_assign(write_ev)         ; libevent func?
 122     event_add(write_ev)
 123
 124   if not in user-dispatch-mode:
 125     event_base_dispatch()
 126 ** How to bind a listener and start listening for incoming connections?
 127