diff options
Diffstat (limited to 'lib/HACKING')
| -rw-r--r-- | lib/HACKING | 112 |
1 files changed, 74 insertions, 38 deletions
diff --git a/lib/HACKING b/lib/HACKING index d312ce3..62da414 100644 --- a/lib/HACKING +++ b/lib/HACKING @@ -1,6 +1,6 @@ HACKING file for libradsec (in Emacs -*- org -*- mode). -Status as of libradsec-0.0.2.dev (2013-01-25). +Status as of libradsec-0.2.0.dev (2013-05-02). * Build instructions sh autogen.sh @@ -9,43 +9,6 @@ make examples/client -r examples/client.conf blocking-tls; echo $? -* Design of the API -- There are three usage modes: - - - Application uses blocking send and receive calls (blocking - mode). This is typically fine for a simple client. - - - Application registers callbacks with libradsec and runs the - libevent dispatch loop (a.k.a. user dispatch mode). This would - probably be how one would implement a server or a proxy. - - - Application runs its own event loop, using fd's for select and - performs I/O using libradsec send/receive functions - (a.k.a. on-your-own mode). Might be useful for an application - which already has an event loop that wants to add RadSec - functionality. - -- Apart from configuration and error handling, an application - shouldn't need to handle TCP and UDP connections - differently. Similarly, the use of TLS/DTLS or not shouldn't - influence the libradsec calls made by the application. - -- Configuration is done either by using the API or by pointing at a - configuration file which is parsed by libradsec. - -- Fully reentrant. - -- Application chooses allocation regime. - -Note that as of 0.0.2.dev libradsec suffers from way too much focus on -the behaviour of a blocking client and is totally useless as a server. -Not only does it lack most of the functions needed for writing a -server but it also contains at least one architectural mishap which -kills the server idea -- a connection timeout (TCP) or a retransmit -timeout (UDP) will result in the event loop being broken. The same -thing will happen if there's an error on a TCP connection, f.ex. a -failing certificate validation (TLS). - * Dependencies Details (within parentheses) apply to Debian Wheezy. @@ -66,6 +29,8 @@ Details (within parentheses) apply to Debian Wheezy. - [TLS] verification of CN ** Known issues +- error handling when server can't bind to given listen_addr+port +- configuration of listen_addr/service is per realm - error stack is only one entry deep - custom allocation scheme is not used in all places @@ -89,3 +54,74 @@ a crash, catching the crash in gdb and providing a backtrace is highly valuable for debugging. Contact: mailto:linus+libradsec@nordu.net + + +* Design of the API +- There are three usage modes: + + - Application uses blocking send and receive calls (blocking + mode). This is typically fine for a simple client. + + - Application registers callbacks with libradsec and runs the + libevent dispatch loop (a.k.a. user dispatch mode). This would + probably be how one would implement a server or a proxy. + + - Application runs its own event loop, using fd's for select and + performs I/O using libradsec send/receive functions + (a.k.a. on-your-own mode). Might be useful for an application + which already has an event loop that wants to add RadSec + functionality. + +- Apart from configuration and error handling, an application + shouldn't need to handle TCP and UDP connections + differently. Similarly, the use of TLS/DTLS or not shouldn't + influence the libradsec calls made by the application. + +- Configuration is done either by using the API or by pointing at a + configuration file which is parsed by libradsec. + +- Fully reentrant. + +- Application chooses allocation regime. + +Note that as of 0.0.2.dev libradsec suffers from way too much focus on +the behaviour of a blocking client and is totally useless as a server. +Not only does it lack most of the functions needed for writing a +server but it also contains at least one architectural mishap which +kills the server idea -- a connection timeout (TCP) or a retransmit +timeout (UDP) will result in the event loop being broken. The same +thing will happen if there's an error on a TCP connection, f.ex. a +failing certificate validation (TLS). + +* Notes on internals +** How to connect an outgoing connection? +Connecting is not done explicitly by the application but implicitly by +rs_message_send(). The application can treat connections in the same +way regardless of whether they're connection-oriented (i.e. TCP) or +not (UDP). + +rs_message_send(msg) + if msg->conn is open: mesasge_do_send(msg) + else: + -> _conn_open(conn, msg) + pick configured peer + event_init_socket(peer) + if TCP or TLS: + init tcp timers + event_init_bufferevent(conn, peer) + else: + init udp timers + if not connected and not connecting: + event_do_connect(conn) + + if TCP: + bufferevent_setcb() + bufferevent_enable() + else: + event_assign(write_ev) ; libevent func? + event_add(write_ev) + + if not in user-dispatch-mode: + event_base_dispatch() +** How to bind a listener and start listening for incoming connections? + |