freeDiameter.h @ 640:237cf6339546

Last change on this file since 640:237cf6339546 was 640:237cf6339546, checked in by Sebastien Decugis <sdecugis@nict.go.jp>, 2 years ago
dbg_interactive almost complete
File size: 34.3 KB

Line
1	/*********************************************************************************************************
2	* Software License Agreement (BSD License) *
3	* Author: Sebastien Decugis <sdecugis@nict.go.jp> *
4	* *
5	* Copyright (c) 2010, WIDE Project and NICT *
6	* All rights reserved. *
7	* *
8	* Redistribution and use of this software in source and binary forms, with or without modification, are *
9	* permitted provided that the following conditions are met: *
10	* *
11	* * Redistributions of source code must retain the above *
12	* copyright notice, this list of conditions and the *
13	* following disclaimer. *
14	* *
15	* * Redistributions in binary form must reproduce the above *
16	* copyright notice, this list of conditions and the *
17	* following disclaimer in the documentation and/or other *
18	* materials provided with the distribution. *
19	* *
20	* * Neither the name of the WIDE Project or NICT nor the *
21	* names of its contributors may be used to endorse or *
22	* promote products derived from this software without *
23	* specific prior written permission of WIDE Project and *
24	* NICT. *
25	* *
26	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
27	* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
28	* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
29	* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT *
30	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS *
31	* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
32	* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF *
33	* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
34	*********************************************************************************************************/
35
36	#ifndef _FREEDIAMETER_H
37	#define _FREEDIAMETER_H
38
39
40	#include <freeDiameter/libfreeDiameter.h>
41	#include <gnutls/gnutls.h>
42	#include <gnutls/x509.h>
43
44	/* GNUTLS version */
45	#ifndef GNUTLS_VERSION
46	#define GNUTLS_VERSION LIBGNUTLS_VERSION
47	#endif /* GNUTLS_VERSION */
48
49	/* GNUTLS calls debug level */
50	#ifndef GNUTLS_DBG_LEVEL
51	#define GNUTLS_DBG_LEVEL ANNOYING
52	#endif /* GNUTLS_DBG_LEVEL */
53
54	/* Check the return value of a GNUTLS function, log and propagate */
55	#define CHECK_GNUTLS_DO( __call__, __fallback__ ) { \
56	int __ret__; \
57	TRACE_DEBUG(GNUTLS_DBG_LEVEL, "GNUTLS call: " #__call__ ); \
58	__ret__ = (__call__); \
59	if (__ret__ < 0) { \
60	TRACE_DEBUG(INFO, "Error in '" #__call__ "':\t%s", gnutls_strerror(__ret__)); \
61	__fallback__; \
62	} \
63	}
64
65	/* For GNUTLS routines that do not return a value */
66	#define GNUTLS_TRACE( __call__) { \
67	TRACE_DEBUG(GNUTLS_DBG_LEVEL, "GNUTLS call: " #__call__ ); \
68	(__call__); \
69	}
70
71	/* Structure to hold the configuration of the freeDiameter daemon */
72	#define EYEC_CONFIG 0xC011F16
73	struct fd_config {
74	int cnf_eyec; /* Eye catcher: EYEC_CONFIG */
75
76	char cnf_file; / Configuration file to parse, default is DEFAULT_CONF_FILE */
77
78	char cnf_diamid; / Diameter Identity of the local peer (FQDN -- UTF-8) */
79	size_t cnf_diamid_len; /* length of the previous string */
80	char cnf_diamrlm; / Diameter realm of the local peer, default to realm part of diam_id */
81	size_t cnf_diamrlm_len;/* length of the previous string */
82
83	unsigned int cnf_timer_tc; /* The value in seconds of the default Tc timer */
84	unsigned int cnf_timer_tw; /* The value in seconds of the default Tw timer */
85
86	uint16_t cnf_port; /* the local port for legacy Diameter (default: 3868) in host byte order */
87	uint16_t cnf_port_tls; /* the local port for Diameter/TLS (default: 3869) in host byte order */
88	uint16_t cnf_sctp_str; /* default max number of streams for SCTP associations (def: 30) */
89	struct fd_list cnf_endpoints; /* the local endpoints to bind the server to. list of struct fd_endpoint. default is empty (bind all) */
90	struct fd_list cnf_apps; /* Applications locally supported (except relay, see flags). Use fd_disp_app_support to add one. list of struct fd_app. */
91	uint16_t cnf_dispthr; /* Number of dispatch threads to create */
92	struct {
93	unsigned no_fwd : 1; /* the peer does not relay messages (0xffffff app id) */
94	unsigned no_ip4 : 1; /* disable IP */
95	unsigned no_ip6 : 1; /* disable IPv6 */
96	unsigned no_tcp : 1; /* disable use of TCP */
97	unsigned no_sctp: 1; /* disable the use of SCTP */
98	unsigned pr_tcp : 1; /* prefer TCP over SCTP */
99	unsigned tls_alg: 1; /* TLS algorithm for initiated cnx. 0: separate port. 1: inband-security (old) */
100	} cnf_flags;
101
102	struct {
103	/* Credentials parameters (backup) */
104	char * cert_file;
105	char * key_file;
106
107	char * ca_file;
108	int ca_file_nr;
109	char * crl_file;
110
111	char * prio_string;
112	unsigned int dh_bits;
113	char * dh_file;
114
115	/* GNUTLS parameters */
116	gnutls_priority_t prio_cache;
117	gnutls_dh_params_t dh_cache;
118
119	/* GNUTLS server credential(s) */
120	gnutls_certificate_credentials_t credentials;
121
122	} cnf_sec_data;
123
124	uint32_t cnf_orstateid; /* The value to use in Origin-State-Id, default to random value */
125	struct dictionary cnf_dict; / pointer to the global dictionary */
126	struct fifo cnf_main_ev; / events for the daemon's main (struct fd_event items) */
127	};
128	extern struct fd_config fd_g_config; / The pointer to access the global configuration, initalized in main */
129
130
131	/***************************************/
132	/* Peers information */
133	/***************************************/
134
135	/* States of a peer */
136	enum peer_state {
137	/* Stable states */
138	STATE_NEW = 0, /* The peer has been just been created, PSM thread not started yet */
139	STATE_OPEN, /* Connexion established */
140
141	/* Peer state machine */
142	STATE_CLOSED, /* No connection established, will re-attempt after TcTimer. */
143	STATE_CLOSING, /* the connection is being shutdown (DPR/DPA in progress) */
144	STATE_WAITCNXACK, /* Attempting to establish transport-level connection */
145	STATE_WAITCNXACK_ELEC, /* Received a CER from this same peer on an incoming connection (other peer object), while we were waiting for cnx ack */
146	STATE_WAITCEA, /* Connection established, CER sent, waiting for CEA */
147	/* STATE_WAITRETURNS_ELEC, / / This state is not stable and therefore deprecated:
148	We have sent a CER on our initiated connection, and received a CER from the remote peer on another connection. Election.
149	If we win the election, we must disconnect the initiated connection and send a CEA on the other => we go to OPEN state.
150	If we lose, we disconnect the other connection (receiver) and fallback to WAITCEA state. */
151	STATE_OPEN_HANDSHAKE, /* TLS Handshake and validation are in progress in open state -- we use it only for debug purpose, it is never displayed */
152
153	/* Failover state machine */
154	STATE_SUSPECT, /* A DWR was sent and not answered within TwTime. Failover in progress. */
155	STATE_REOPEN, /* Connection has been re-established, waiting for 3 DWR/DWA exchanges before putting back to service */
156
157	/* Error state */
158	STATE_ZOMBIE /* The PSM thread is not running anymore; it must be re-started or peer should be deleted. */
159	#define STATE_MAX STATE_ZOMBIE
160	};
161	/* The following macro is called in freeDiameter/p_psm.c */
162	#define DECLARE_STATE_STR() \
163	const char *peer_state_str[] = { \
164	"STATE_NEW" \
165	, "STATE_OPEN" \
166	, "STATE_CLOSED" \
167	, "STATE_CLOSING" \
168	, "STATE_WAITCNXACK" \
169	, "STATE_WAITCNXACK_ELEC" \
170	, "STATE_WAITCEA" \
171	, "STATE_OPEN_HANDSHAKE" \
172	, "STATE_SUSPECT" \
173	, "STATE_REOPEN" \
174	, "STATE_ZOMBIE" \
175	};
176	extern const char *peer_state_str[];
177	#define STATE_STR(state) \
178	(((unsigned)(state)) <= STATE_MAX ? peer_state_str[((unsigned)(state)) ] : "<Invalid>")
179
180	/* Constants for the peer_info structure bellow */
181	#define PI_P3_DEFAULT 0 /* Use any available protocol */
182	#define PI_P3_IP 1 /* Use only IP to connect to this peer */
183	#define PI_P3_IPv6 2 /* resp, IPv6 */
184
185	#define PI_P4_DEFAULT 0 /* Attempt any available protocol */
186	#define PI_P4_TCP 1 /* Only use TCP */
187	#define PI_P4_SCTP 2 /* Only use SCTP */
188
189	#define PI_ALGPREF_SCTP 0 /* SCTP is attempted first (default) */
190	#define PI_ALGPREF_TCP 1 /* TCP is attempted first */
191
192	#define PI_SEC_DEFAULT 0 /* New TLS security (handshake after connection, protecting also CER/CEA) */
193	#define PI_SEC_NONE 1 /* Transparent security with this peer (IPsec) */
194	#define PI_SEC_TLS_OLD 2 /* Old TLS security (use Inband-Security-Id AVP during CER/CEA) */
195	/* Set sec = 3 to authorize use of (Inband-Security-Id == NONE) with this peer, sec = 2 only authorizing TLS */
196
197	#define PI_EXP_NONE 0 /* the peer entry does not expire */
198	#define PI_EXP_INACTIVE 1 /* the peer entry expires (i.e. is deleted) after pi_lft seconds without activity */
199
200	#define PI_PRST_NONE 0 /* the peer entry is deleted after disconnection / error */
201	#define PI_PRST_ALWAYS 1 /* the peer entry is persistant (will be kept as ZOMBIE in case of error) */
202
203	/* Information about a remote peer */
204	struct peer_info {
205
206	char * pi_diamid; /* UTF-8, \0 terminated. The Diameter Identity of the remote peer. */
207
208	struct {
209	struct {
210	unsigned pro3 :2; /* PI_P3_* */
211	unsigned pro4 :2; /* PI_P4_* */
212	unsigned alg :1; /* PI_ALGPREF_* */
213	unsigned sec :2; /* PI_SEC_* */
214	unsigned exp :1; /* PI_EXP_* */
215	unsigned persist :1; /* PI_PRST_* */
216
217	} pic_flags; /* Flags influencing the connection to the remote peer */
218
219	char * pic_realm; /* If configured, the daemon will match the received realm in CER/CEA matches this. */
220	uint16_t pic_port; /* port to connect to. 0: default. */
221
222	uint32_t pic_lft; /* lifetime of this peer when inactive (see pic_flags.exp definition) */
223	int pic_tctimer; /* use this value for TcTimer instead of global, if != 0 */
224	int pic_twtimer; /* use this value for TwTimer instead of global, if != 0 */
225
226	char * pic_priority; /* Priority string for GnuTLS if we don't use the default */
227
228	} config; /* Configured data (static for this peer entry) */
229
230	struct {
231
232	enum peer_state pir_state; /* Current state of the peer in the state machine. fd_cpu_flush_cache() might be useful before reading. */
233
234	char * pir_realm; /* The received realm in CER/CEA. */
235
236	uint32_t pir_vendorid; /* Content of the Vendor-Id AVP, or 0 by default */
237	uint32_t pir_orstate; /* Origin-State-Id value */
238	char * pir_prodname; /* copy of UTF-8 Product-Name AVP (\0 terminated) */
239	uint32_t pir_firmrev; /* Content of the Firmware-Revision AVP */
240	int pir_relay; /* The remote peer advertized the relay application */
241	struct fd_list pir_apps; /* applications advertised by the remote peer, except relay (pi_flags.relay) */
242	int pir_isi; /* Inband-Security-Id advertised (PI_SEC_* bits) */
243
244	uint32_t pir_lastDC; /* The last Disconnect-Cause value received */
245
246	int pir_proto; /* The L4 protocol currently used with the peer (IPPROTO_TCP or IPPROTO_SCTP) */
247	const gnutls_datum_t pir_cert_list; / The (valid) credentials that the peer has presented, or NULL if TLS is not used */
248	/* This is inspired from http://www.gnu.org/software/gnutls/manual/gnutls.html#ex_003ax509_002dinfo
249	see there for example of using this data */
250	unsigned int pir_cert_list_size; /* Number of certificates in the list */
251
252	} runtime; /* Data populated after connection, may change between 2 connections -- not used by fd_peer_add */
253
254	struct fd_list pi_endpoints; /* Endpoint(s) of the remote peer (configured, discovered, or advertized). list of struct fd_endpoint. DNS resolved if empty. */
255	};
256
257
258	struct peer_hdr {
259	struct fd_list chain; /* List of all the peers, ordered by their Diameter Id */
260	struct peer_info info; /* The public data */
261
262	/* This header is followed by more data in the private peer structure definition */
263	};
264
265	/* the global list of peers.
266	Since we are not expecting so many connections, we don't use a hash, but it might be changed.
267	The list items are peer_hdr structures (actually, fd_peer, but the cast is OK) */
268	extern struct fd_list fd_g_peers;
269	extern pthread_rwlock_t fd_g_peers_rw; /* protect the list */
270
271	/*
272	* FUNCTION: fd_peer_add
273	*
274	* PARAMETERS:
275	* info : Information to create the peer.
276	* orig_dbg : A string indicating the origin of the peer information, for debug (ex: conf, redirect, ...)
277	* cb : optional, a callback to call (once) when the peer connection is established or failed
278	* cb_data : opaque data to pass to the callback.
279	*
280	* DESCRIPTION:
281	* Add a peer to the list of peers to which the daemon must maintain a connexion.
282	*
283	* The content of info parameter is copied, except for the list of endpoints if
284	* not empty, which is simply moved into the created object. It means that the list
285	* items must have been malloc'd, so that they can be freed.
286	*
287	* If cb is not null, the callback is called when the connection is in OPEN state or
288	* when an error has occurred. The callback should use the pi_state information to
289	* determine which one it is. If the first parameter of the called callback is NULL, it
290	* means that the peer is being destroyed before attempt success / failure.
291	* cb is called to allow freeing cb_data in * this case.
292	*
293	* The orig_dbg string is only useful for easing debug, and can be left to NULL.
294	*
295	* RETURN VALUE:
296	* 0 : The peer is added.
297	* EINVAL : A parameter is invalid.
298	* EEXIST : A peer with the same Diameter-Id is already in the list.
299	* (other standard errors may be returned, too, with their standard meaning. Example:
300	* ENOMEM : Memory allocation for the new object element failed.)
301	*/
302	int fd_peer_add ( struct peer_info * info, char * orig_dbg, void (cb)(struct peer_info , void ), void cb_data );
303
304	/*
305	* FUNCTION: fd_peer_getbyid
306	*
307	* PARAMETERS:
308	* diamid : A \0 terminated string.
309	* peer : The peer is stored here if it exists.
310	*
311	* DESCRIPTION:
312	* Search a peer by its Diameter-Id.
313	*
314	* RETURN VALUE:
315	* 0 : *peer has been updated (to NULL if the peer is not found).
316	* !0 : An error occurred.
317	*/
318	int fd_peer_getbyid( char * diamid, struct peer_hdr ** peer );
319
320	/*
321	* FUNCTION: fd_peer_validate_register
322	*
323	* PARAMETERS:
324	* peer_validate : Callback as defined bellow.
325	*
326	* DESCRIPTION:
327	* Add a callback to authorize / reject incoming peer connections.
328	* All registered callbacks are called until a callback sets auth = -1 or auth = 1.
329	* If no callback returns a clear decision, the default behavior is applied (reject unknown connections)
330	* The callbacks are called in FILO order of their registration.
331	*
332	* RETURN VALUE:
333	* 0 : The callback is added.
334	* !0 : An error occurred.
335	*/
336	int fd_peer_validate_register ( int (peer_validate)(struct peer_info /* info /, int /* auth /, int (cb2)(struct peer_info )) );
337	/*
338	* CALLBACK: peer_validate
339	*
340	* PARAMETERS:
341	* info : Structure containing information about the peer attempting the connection.
342	* auth : Store there the result if the peer is accepted (1), rejected (-1), or unknown (0).
343	* cb2 : If != NULL and in case of PI_SEC_TLS_OLD, another callback to call after handshake (if auth = 1).
344	*
345	* DESCRIPTION:
346	* This callback is called when a new connection is being established from an unknown peer,
347	* after the CER is received. An extension must register such callback with peer_validate_register.
348	*
349	* The callback can learn if the peer has sent Inband-Security-Id AVPs in runtime.pir_isi fields.
350	* It can also learn if a handshake has already been performed in runtime.pir_cert_list field.
351	* The callback must set the value of config.pic_flags.sec appropriately to allow a connection without TLS.
352	*
353	* If the old TLS mechanism is used,
354	* the extension may also need to check the credentials provided during the TLS
355	* exchange (remote certificate). For this purpose, it may set the address of a new callback
356	* to be called once the handshake is completed. This new callback receives the information
357	* structure as parameter (with pir_cert_list set) and returns 0 if the credentials are correct,
358	* or an error code otherwise. If the error code is received, the connection is closed and the
359	* peer is destroyed.
360	* Note that freeDiameter already achieves some usual checks. The callback may be used to enforce
361	* additional restrictions.
362	*
363	* RETURN VALUE:
364	* 0 : The authorization decision has been written in the location pointed by auth.
365	* !0 : An error occurred.
366	*/
367
368	/***************************************/
369	/* Sending a message on the network */
370	/***************************************/
371
372	/*
373	* FUNCTION: fd_msg_send
374	*
375	* PARAMETERS:
376	* pmsg : Location of the message to be sent on the network (set to NULL on function return to avoid double deletion).
377	* anscb : A callback to be called when answer is received, if msg is a request (optional)
378	* anscb_data : opaque data to be passed back to the anscb when it is called.
379	*
380	* DESCRIPTION:
381	* Sends a message on the network. (actually simply queues it in a global queue, to be picked by a daemon's thread)
382	* For requests, the end-to-end id must be set (see fd_msg_get_eteid / MSGFL_ALLOC_ETEID).
383	* For answers, the message must be created with function fd_msg_new_answ.
384	*
385	* The routing module will handle sending to the correct peer, usually based on the Destination-Realm / Destination-Host AVP.
386	*
387	* If the msg is a request, there are two ways of receiving the answer:
388	* - either having registered a callback in the dispatch module (see fd_disp_register)
389	* - or provide a callback as parameter here. If such callback is provided, it is called before the dispatch callbacks.
390	* The prototype for this callback function is:
391	* void anscb(void * data, struct msg ** answer)
392	* where:
393	* data : opaque data that was registered along with the callback.
394	* answer : location of the pointer to the answer.
395	* note1: on function return, if *answer is not NULL, the message is passed to the dispatch module for regular callbacks.
396	* otherwise, the callback must take care of freeing the message (fd_msg_free).
397	* note2: the opaque data is not freed by the daemon in any case, extensions should ensure clean handling in fd_ext_fini.
398	*
399	* If no callback is registered to handle an answer, the message is discarded and an error is logged.
400	*
401	* RETURN VALUE:
402	* 0 : The message has been queued for sending (sending may fail asynchronously).
403	* EINVAL : A parameter is invalid (ex: anscb provided but message is not a request).
404	* ...
405	*/
406	int fd_msg_send ( struct msg ** pmsg, void (anscb)(void , struct msg *), void data );
407
408	/*
409	* FUNCTION: fd_msg_rescode_set
410	*
411	* PARAMETERS:
412	* msg : A msg object -- it must be an answer.
413	* rescode : The name of the returned error code (ex: "DIAMETER_INVALID_AVP")
414	* errormsg : (optional) human-readable error message to put in Error-Message AVP
415	* optavp : (optional) If provided, the content will be put inside a Failed-AVP
416	* type_id : 0 => nothing; 1 => adds Origin-Host and Origin-Realm with local info. 2=> adds Error-Reporting-Host.
417	*
418	* DESCRIPTION:
419	* This function adds a Result-Code AVP to a message, and optionally
420	* - sets the 'E' error flag in the header,
421	* - adds Error-Message, Error-Reporting-Host and Failed-AVP AVPs.
422	*
423	* RETURN VALUE:
424	* 0 : Operation complete.
425	* !0 : an error occurred.
426	*/
427	int fd_msg_rescode_set( struct msg * msg, char * rescode, char * errormsg, struct avp * optavp, int type_id );
428
429	/* Add Origin-Host, Origin-Realm, (if osi) Origin-State-Id AVPS at the end of the message */
430	int fd_msg_add_origin ( struct msg * msg, int osi );
431
432	/* Parse a message against our dictionary, and in case of error log and eventually build the error reply (on return and EBADMSG, msg == NULL or msg is the error message ready to send) */
433	int fd_msg_parse_or_error( struct msg ** msg );
434
435
436	/***************************************/
437	/* Dispatch module, daemon's part */
438	/***************************************/
439
440	/*
441	* FUNCTION: fd_disp_app_support
442	*
443	* PARAMETERS:
444	* app : The dictionary object corresponding to the Application.
445	* vendor : (Optional) the dictionary object of a Vendor to claim support in Vendor-Specific-Application-Id
446	* auth : Support auth app part.
447	* acct : Support acct app part.
448	*
449	* DESCRIPTION:
450	* Registers an application to be advertized in CER/CEA exchanges.
451	* Messages with an application-id matching a registered value are passed to the dispatch module,
452	* while other messages are simply relayed or an error is returned (if local node does not relay)
453	*
454	* RETURN VALUE:
455	* 0 : The application support is registered.
456	* EINVAL : A parameter is invalid.
457	*/
458	int fd_disp_app_support ( struct dict_object * app, struct dict_object * vendor, int auth, int acct );
459
460	/* Note: if we want to support capabilities updates, we'll have to add possibility to remove an app as well... */
461
462
463	/***************************************/
464	/* Routing module */
465	/***************************************/
466
467	/* This file contains the definitions of types and functions involved in the routing decisions in freeDiameter,
468	* and that can be called by extensions.
469	*
470	* Three different type of messages must be distinguished:
471	* - Messages received, and the peer is final recipient (IN messages)
472	* - Messages received, and the peer is not final recipient (FWD messages)
473	* - Message is locally generated (OUT messages)
474	*
475	* There are three global message queues (in queues.c) and also peers-specific queues (in struct fd_peer).
476	*
477	* (*) IN messages processing details:
478	* - the message is received from the remote peer, a FDEVP_CNX_MSG_RECV event is generated for the peer.
479	* - the PSM thread parses the buffer, does some verifications, handles non routable messages (fd_msg_is_routable)
480	* - routable messages are queued in the fd_g_incoming global queue.
481	* - a thread (routing-in) picks the message and takes the decision if it is handled locally or forwarded,
482	* based on local capabilities (registered by extensions with fd_disp_app_support).
483	* - If the message is handled locally, it is queued in fd_g_local.
484	* - Another thread (dispatch.c) will handle this message and pass it to registered callbacks (see fd_disp_register in libfreeDiameter.h).
485	*
486	* (*) FWD messages details:
487	* - The process is the same as for IN messages, until the routing-in threads makes its decision that the message is not handled locally.
488	* - If the local peer does not relay message, an error DIAMETER_APPLICATION_UNSUPPORTED is returned.
489	* - All callbacks registered with fd_rt_fwd_register are called for the message (see bellow).
490	* - these callbacks will typically do proxying work. Note that adding the route-record is handled by the daemon.
491	* - Once all callbacks have been called, the message is queued in the global fd_g_outgoing queue.
492	* - The remaining processing is the same as for OUT messages, as described bellow.
493	*
494	* (*) OUT messages details:
495	* - The message are picked from fd_g_outgoing (they are queued there as result of forwarding process or call to fd_msg_send.)
496	* - The (routing-out) thread builds a list of possible destinations for the message, as follow:
497	* - create a list of all known peers in the "OPEN" state.
498	* - remove from that list all peers that are in a Route-Record AVP of the message, to avoid routing loops.
499	* - remove also all peers that have previously replied an error message for this message.
500	* - If the list is empty, create an error UNABLE_TO_DELIVER (note: should we trig dynamic discovery here???) and reply.
501	* - Otherwise, call all callbacks registered by function fd_rt_out_register, with the list of peers and the message.
502	* - Order the resulting list of peers by score (see bellow), and sent the message to the peer with highest (positive) score.
503	* - in case the peer is no longer in the "OPEN" state, send the message to the second peer in the list.
504	* - if no peer is in OPEN state anymore, restart the process of creating the list.
505	* - Once a peer has been selected, the message is queued into that peer's outgoing queue.
506	*
507	* The following functions allow an extension to register or remove a callback as described above.
508	*/
509
510	/******** Forwarding callbacks: for Proxy operations *********/
511
512	/* Handle to registered callback */
513	struct fd_rt_fwd_hdl;
514
515	/* Message direction for the callback */
516	enum fd_rt_fwd_dir {
517	RT_FWD_REQ = 1, /* The callback will be called on forwarded requests only */
518	RT_FWD_ALL = 2, /* The callback will be called on all forwarded messages (requests and answers )*/
519	RT_FWD_ANS = 3 /* The callback will be called on answers and errors only */
520	};
521
522	/*
523	* FUNCTION: fd_rt_fwd_register
524	*
525	* PARAMETERS:
526	* rt_fwd_cb : The callback function to register (see prototype bellow).
527	* cbdata : Pointer to pass to the callback when it is called. The data is opaque to the daemon.
528	* dir : One of the RT_FWD_* directions defined above.
529	* handler : On success, a handler to the registered callback is stored here.
530	* This handler will be used to unregister the cb.
531	*
532	* DESCRIPTION:
533	* Register a new callback for forwarded messages. See explanations above.
534	* Note that there is no guaranteed order for the callbacks calls.
535	*
536	* RETURN VALUE:
537	* 0 : The callback is registered.
538	* EINVAL : A parameter is invalid.
539	* ENOMEM : Not enough memory to complete the operation
540	*/
541	int fd_rt_fwd_register ( int (rt_fwd_cb)(void cbdata, struct msg ** msg), void * cbdata, enum fd_rt_fwd_dir dir, struct fd_rt_fwd_hdl ** handler );
542	/*
543	* CALLBACK: rt_fwd_cb
544	*
545	* PARAMETERS:
546	* data : pointer to some data that was passed when the callback was registered (optional).
547	* msg : The message that is being forwarded.
548	*
549	* DESCRIPTION:
550	* This callback is called when a message is forwarded to another peer. It may for example add a Proxy-Info AVP.
551	* The callback may also choose to handle the message in a more complex form. In that case, it must set *msg = NULL
552	* and handle it differently. In such case, the forwarding thread will stop processing this message.
553	*
554	* RETURN VALUE:
555	* 0 : Operation complete.
556	* !0 : An error occurred -- will result in daemon's termination.
557	*/
558
559	/*
560	* FUNCTION: fd_rt_fwd_unregister
561	*
562	* PARAMETERS:
563	* handler : The handler of the callback that must be unregistered.
564	* cbdata : Will receive the data registered with the callback, that can be freed if needed.
565	*
566	* DESCRIPTION:
567	* Removes a callback from the list of registered callbacks.
568	*
569	* RETURN VALUE:
570	* 0 : The callback is unregistered.
571	* EINVAL : A parameter is invalid.
572	*/
573	int fd_rt_fwd_unregister ( struct fd_rt_fwd_hdl * handler, void ** cbdata );
574
575
576	/******** Out callbacks: for next hop routing decision operations *********/
577
578	/* Handle to registered callback */
579	struct fd_rt_out_hdl;
580
581	enum fd_rt_out_score {
582	FD_SCORE_NO_DELIVERY = -70, /* We should not send this message to this candidate */
583	FD_SCORE_INI = -2, /* All candidates are initialized with this value */
584	FD_SCORE_LOAD_BALANCE = 1, /* Use this to differentiate between several peers with the same score */
585	FD_SCORE_DEFAULT = 5, /* The peer is a default route for all messages */
586	FD_SCORE_DEFAULT_REALM = 10, /* The peer is a default route for this realm */
587	FD_SCORE_REALM = 15, /* The peer belongs to Destination-Realm of the message */
588	FD_SCORE_REDIR_HOST = 25, /* If there is a redirect rule with ALL_HOST for these message and peer */
589	FD_SCORE_REDIR_APP = 30, /* If there is a redirect rule with ALL_APPLICATION for these message and peer */
590	FD_SCORE_REDIR_REALM = 35, /* If there is a redirect rule with ALL_REALM for these message and peer */
591	FD_SCORE_REDIR_REALM_APP = 40, /* If there is a redirect rule with REALM_AND_APPLICATION for these message and peer */
592	FD_SCORE_REDIR_USER = 45, /* If there is a redirect rule with ALL_USER for these message and peer */
593	FD_SCORE_REDIR_SESSION = 50, /* If there is a redirect rule with ALL_SESSION for these message and peer */
594	FD_SCORE_FINALDEST = 100 /* If the peer is the final recipient of the message (i.e. matching Destination-Host), it receives a big score. */
595	};
596
597	/*
598	* FUNCTION: fd_rt_out_register
599	*
600	* PARAMETERS:
601	* rt_out_cb : The callback function to register (see prototype bellow).
602	* cbdata : Pointer to pass to the callback when it is called. The data is opaque to the daemon.
603	* priority : Order for calling this callback. The callbacks are called in reverse priority order (higher priority = called sooner).
604	* handler : On success, a handler to the registered callback is stored here.
605	* This handler will be used to unregister the cb.
606	*
607	* DESCRIPTION:
608	* Register a new callback to handle OUT routing decisions. See explanations above.
609	*
610	* RETURN VALUE:
611	* 0 : The callback is registered.
612	* EINVAL : A parameter is invalid.
613	* ENOMEM : Not enough memory to complete the operation
614	*/
615	int fd_rt_out_register ( int (rt_out_cb)(void cbdata, struct msg * msg, struct fd_list * candidates), void * cbdata, int priority, struct fd_rt_out_hdl ** handler );
616	/*
617	* CALLBACK: rt_out_cb
618	*
619	* PARAMETERS:
620	* cbdata : pointer to some data that was registered with the callback.
621	* msg : The message that must be sent.
622	* list : The list of peers to which the message may be sent to, as returned by fd_rtd_candidate_extract
623	*
624	* DESCRIPTION:
625	* This callback must attribute a score (preferably from FD_SCORE_*) to each candidate peer in the list.
626	* Once all registered callbacks have been called, the message is sent to the candidate with the highest score.
627	* Note that each callback must add its locally-attributed score to the candidate current "score" parameter, not replace it!
628	* Note also that this callback must be re-entrant since it may be called by several threads at the same time
629	* (for different messages)
630	*
631	* RETURN VALUE:
632	* 0 : Operation complete.
633	* !0 : An error occurred.
634	*/
635
636	/*
637	* FUNCTION: fd_rt_out_unregister
638	*
639	* PARAMETERS:
640	* handler : The handler of the callback that must be unregistered.
641	* cbdata : Will receive the data registered with the callback, that can be freed if needed.
642	*
643	* DESCRIPTION:
644	* Removes a callback from the list of registered callbacks.
645	*
646	* RETURN VALUE:
647	* 0 : The callback is unregistered.
648	* EINVAL : A parameter is invalid.
649	*/
650	int fd_rt_out_unregister ( struct fd_rt_out_hdl * handler, void ** cbdata );
651
652
653	/***************************************/
654	/* Events helpers */
655	/***************************************/
656
657	struct fd_event {
658	int code; /* codespace depends on the queue */
659	size_t size;
660	void *data;
661	};
662
663	/* Daemon's codespace: 1000->1999 (1500->1999 defined in fD.h) */
664	enum {
665	FDEV_TERMINATE = 1000 /* request to terminate */
666	,FDEV_DUMP_DICT /* Dump the content of the dictionary */
667	,FDEV_DUMP_EXT /* Dump state of extensions */
668	,FDEV_DUMP_SERV /* Dump the server socket status */
669	,FDEV_DUMP_QUEUES /* Dump the message queues */
670	,FDEV_DUMP_CONFIG /* Dump the configuration */
671	,FDEV_DUMP_PEERS /* Dump the list of peers */
672	};
673
674	int fd_event_send(struct fifo queue, int code, size_t datasz, void data);
675	int fd_event_get(struct fifo queue, int code, size_t * datasz, void ** data);
676	int fd_event_timedget(struct fifo queue, struct timespec timeout, int timeoutcode, int * code, size_t * datasz, void ** data);
677	void fd_event_destroy(struct fifo *queue, void (free_cb)(void * data));
678	const char * fd_ev_str(int event);
679
680
681	/* The following function does not really use events, but it may be used
682	by extensions that need to start an action when the framework is fully initialized.
683	This function will block until all initializations are performed in the daemon.
684	It is meant to be used as follow by extensions:
685	- in initialization callback, create a new thread.
686	- this new thread calls this function.
687	- when the function returns, the thread can start working and using all framework features.
688	*/
689	int fd_wait_initialization_complete(void);
690
691
692	/***************************************/
693	/* Endpoints lists helpers */
694	/***************************************/
695
696	struct fd_endpoint {
697	struct fd_list chain; /* link in cnf_endpoints list */
698
699	union {
700	sSS ss; /* the socket information. List is always ordered by ss value (memcmp) -- see fd_ep_add_merge */
701	sSA4 sin;
702	sSA6 sin6;
703	sSA sa;
704	}
705	#ifdef SWIG /* nested anonymous unions are not supported yet */
706	s
707	#endif /* SWIG */
708	;
709
710	#define EP_FL_CONF (1 << 0) /* This endpoint is statically configured in a configuration file */
711	#define EP_FL_DISC (1 << 1) /* This endpoint was resolved from the Diameter Identity or other DNS query */
712	#define EP_FL_ADV (1 << 2) /* This endpoint was advertized in Diameter CER/CEA exchange */
713	#define EP_FL_LL (1 << 3) /* Lower layer mechanism provided this endpoint */
714	#define EP_FL_PRIMARY (1 << 4) /* This endpoint is primary in a multihomed SCTP association */
715	#define EP_ACCEPTALL (1 << 15) /* This flag allows bypassing the address filter in fd_ep_add_merge. */
716	uint32_t flags; /* Additional information about the endpoint */
717
718	/* To add: a validity timestamp for DNS records ? How do we retrieve this lifetime from DNS ? */
719	};
720
721	int fd_ep_add_merge( struct fd_list * list, sSA * sa, socklen_t sl, uint32_t flags );
722	int fd_ep_filter( struct fd_list * list, uint32_t flags );
723	int fd_ep_filter_family( struct fd_list * list, int af );
724	int fd_ep_filter_list( struct fd_list * list, struct fd_list * exclude_list );
725	int fd_ep_clearflags( struct fd_list * list, uint32_t flags );
726	void fd_ep_dump_one( char * prefix, struct fd_endpoint * ep, char * suffix );
727	void fd_ep_dump( int indent, struct fd_list * eps );
728
729	/***************************************/
730	/* Applications lists helpers */
731	/***************************************/
732
733	struct fd_app {
734	struct fd_list chain; /* link in cnf_apps list. List ordered by appid. */
735	struct {
736	unsigned auth : 1;
737	unsigned acct : 1;
738	} flags;
739	vendor_id_t vndid; /* if not 0, Vendor-Specific-App-Id AVP will be used */
740	application_id_t appid; /* The identifier of the application */
741	};
742
743	int fd_app_merge(struct fd_list * list, application_id_t aid, vendor_id_t vid, int auth, int acct);
744	int fd_app_check(struct fd_list * list, application_id_t aid, struct fd_app **detail);
745	int fd_app_check_common(struct fd_list * list1, struct fd_list * list2, int * common_found);
746	int fd_app_empty(struct fd_list * list);
747
748	#endif /* _FREEDIAMETER_H */

Note: See TracBrowser for help on using the repository browser.

Navigation

source: freeDiameter/include/freeDiameter/freeDiameter.h @ 640:237cf6339546

Download in other formats: