embedaddon/bird/doc/prog-7.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / prog-7.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Aug 22 12:33:54 2017 UTC (7 years, 2 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_8p3, v1_6_3p0, v1_6_3, HEAD

bird 1.6.3

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9"> <TITLE>BIRD Programmer's Documentation: Library functions</TITLE> <LINK HREF="prog-8.html" REL=next> <LINK HREF="prog-6.html" REL=previous> <LINK HREF="prog.html#toc7" REL=contents> </HEAD> <BODY> <A HREF="prog-8.html">Next</A> <A HREF="prog-6.html">Previous</A> <A HREF="prog.html#toc7">Contents</A> <HR> <H2><A NAME="s7">7.</A> <A HREF="prog.html#toc7">Library functions</A></H2> <H2><A NAME="ss7.1">7.1</A> <A HREF="prog.html#toc7.1">IP addresses</A> </H2>  BIRD uses its own abstraction of IP address in order to share the same code for both IPv4 and IPv6. IP addresses are represented as entities of type ip_addr which are never to be treated as numbers and instead they must be manipulated using the following functions and macros.  <HR><H3>Function</H3> char * ip_scope_text (uint scope) -- get textual representation of address scope  <H3>Arguments</H3>  <DL> <DT>uint scope<DD>scope (SCOPE_xxx) </DL> <H3>Description</H3> Returns a pointer to a textual name of the scope given. <HR><H3>Function</H3> int ipa_equal (ip_addr x, ip_addr y) -- compare two IP addresses for equality  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address <DT>ip_addr y<DD>IP address </DL> <H3>Description</H3> ipa_equal() returns 1 if x and y represent the same IP address, else 0. <HR><H3>Function</H3> int ipa_nonzero (ip_addr x) -- test if an IP address is defined  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> ipa_nonzero returns 1 if x is a defined IP address (not all bits are zero), else 0. The undefined all-zero address is reachable as a <CODE>IPA_NONE</CODE> macro. <HR><H3>Function</H3> ip_addr ipa_and (ip_addr x, ip_addr y) -- compute bitwise and of two IP addresses  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address <DT>ip_addr y<DD>IP address </DL> <H3>Description</H3> This function returns a bitwise and of x and y. It's primarily used for network masking. <HR><H3>Function</H3> ip_addr ipa_or (ip_addr x, ip_addr y) -- compute bitwise or of two IP addresses  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address <DT>ip_addr y<DD>IP address </DL> <H3>Description</H3> This function returns a bitwise or of x and y. <HR><H3>Function</H3> ip_addr ipa_xor (ip_addr x, ip_addr y) -- compute bitwise xor of two IP addresses  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address <DT>ip_addr y<DD>IP address </DL> <H3>Description</H3> This function returns a bitwise xor of x and y. <HR><H3>Function</H3> ip_addr ipa_not (ip_addr x) -- compute bitwise negation of two IP addresses  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> This function returns a bitwise negation of x. <HR><H3>Function</H3> ip_addr ipa_mkmask (int x) -- create a netmask  <H3>Arguments</H3>  <DL> <DT>int x<DD>prefix length </DL> <H3>Description</H3> This function returns an ip_addr corresponding of a netmask of an address prefix of size x. <HR><H3>Function</H3> int ipa_masklen (ip_addr x) -- calculate netmask length  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> This function checks whether x represents a valid netmask and returns the size of the associate network prefix or -1 for invalid mask. <HR><H3>Function</H3> int ipa_hash (ip_addr x) -- hash IP addresses  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> ipa_hash() returns a 16-bit hash value of the IP address x. <HR><H3>Function</H3> void ipa_hton (ip_addr x) -- convert IP address to network order  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> Converts the IP address x to the network byte order. Beware, this is a macro and it alters the argument! <HR><H3>Function</H3> void ipa_ntoh (ip_addr x) -- convert IP address to host order  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> Converts the IP address x from the network byte order. Beware, this is a macro and it alters the argument! <HR><H3>Function</H3> int ipa_classify (ip_addr x) -- classify an IP address  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> ipa_classify() returns an address class of x, that is a bitwise or of address type (IADDR_INVALID, IADDR_HOST, IADDR_BROADCAST, IADDR_MULTICAST) with address scope (SCOPE_HOST to SCOPE_UNIVERSE) or -1 (IADDR_INVALID) for an invalid address. <HR><H3>Function</H3> ip4_addr ip4_class_mask (ip4_addr x) -- guess netmask according to address class  <H3>Arguments</H3>  <DL> <DT>ip4_addr x<DD>IPv4 address </DL> <H3>Description</H3> This function (available in IPv4 version only) returns a network mask according to the address class of x. Although classful addressing is nowadays obsolete, there still live routing protocols transferring no prefix lengths nor netmasks and this function could be useful to them. <HR><H3>Function</H3> u32 ipa_from_u32 (ip_addr x) -- convert IPv4 address to an integer  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address </DL> <H3>Description</H3> This function takes an IPv4 address and returns its numeric representation. <HR><H3>Function</H3> ip_addr ipa_to_u32 (u32 x) -- convert integer to IPv4 address  <H3>Arguments</H3>  <DL> <DT>u32 x<DD>a 32-bit integer </DL> <H3>Description</H3> ipa_to_u32() takes a numeric representation of an IPv4 address and converts it to the corresponding ip_addr. <HR><H3>Function</H3> int ipa_compare (ip_addr x, ip_addr y) -- compare two IP addresses for order  <H3>Arguments</H3>  <DL> <DT>ip_addr x<DD>IP address <DT>ip_addr y<DD>IP address </DL> <H3>Description</H3> The ipa_compare() function takes two IP addresses and returns -1 if x is less than y in canonical ordering (lexicographical order of the bit strings), 1 if x is greater than y and 0 if they are the same. <HR><H3>Function</H3> ip_addr ipa_build6 (u32 a1, u32 a2, u32 a3, u32 a4) -- build an IPv6 address from parts  <H3>Arguments</H3>  <DL> <DT>u32 a1<DD>part #1 <DT>u32 a2<DD>part #2 <DT>u32 a3<DD>part #3 <DT>u32 a4<DD>part #4 </DL> <H3>Description</H3> ipa_build() takes a1 to a4 and assembles them to a single IPv6 address. It's used for example when a protocol wants to bind its socket to a hard-wired multicast address. <HR><H3>Function</H3> char * ip_ntop (ip_addr a, char * buf) -- convert IP address to textual representation  <H3>Arguments</H3>  <DL> <DT>ip_addr a<DD>IP address <DT>char * buf<DD>buffer of size at least STD_ADDRESS_P_LENGTH </DL> <H3>Description</H3> This function takes an IP address and creates its textual representation for presenting to the user. <HR><H3>Function</H3> char * ip_ntox (ip_addr a, char * buf) -- convert IP address to hexadecimal representation  <H3>Arguments</H3>  <DL> <DT>ip_addr a<DD>IP address <DT>char * buf<DD>buffer of size at least STD_ADDRESS_P_LENGTH </DL> <H3>Description</H3> This function takes an IP address and creates its hexadecimal textual representation. Primary use: debugging dumps. <HR><H3>Function</H3> int ip_pton (char * a, ip_addr * o) -- parse textual representation of IP address  <H3>Arguments</H3>  <DL> <DT>char * a<DD>textual representation <DT>ip_addr * o<DD>where to put the resulting address </DL> <H3>Description</H3> This function parses a textual IP address representation and stores the decoded address to a variable pointed to by o. Returns 0 if a parse error has occurred, else 0. <H2><A NAME="ss7.2">7.2</A> <A HREF="prog.html#toc7.2">Linked lists</A> </H2>  The BIRD library provides a set of functions for operating on linked lists. The lists are internally represented as standard doubly linked lists with synthetic head and tail which makes all the basic operations run in constant time and contain no extra end-of-list checks. Each list is described by a list structure, nodes can have any format as long as they start with a node structure. If you want your nodes to belong to multiple lists at once, you can embed multiple node structures in them and use the SKIP_BACK() macro to calculate a pointer to the start of the structure from a node pointer, but beware of obscurity. There also exist safe linked lists (slist, snode and all functions being prefixed with <CODE>s_</CODE>) which support asynchronous walking very similar to that used in the fib structure.  <HR><H3>Function</H3> LIST_INLINE void add_tail (list * l, node * n) -- append a node to a list  <H3>Arguments</H3>  <DL> <DT>list * l<DD>linked list <DT>node * n<DD>list node </DL> <H3>Description</H3> add_tail() takes a node n and appends it at the end of the list l. <HR><H3>Function</H3> LIST_INLINE void add_head (list * l, node * n) -- prepend a node to a list  <H3>Arguments</H3>  <DL> <DT>list * l<DD>linked list <DT>node * n<DD>list node </DL> <H3>Description</H3> add_head() takes a node n and prepends it at the start of the list l. <HR><H3>Function</H3> LIST_INLINE void insert_node (node * n, node * after) -- insert a node to a list  <H3>Arguments</H3>  <DL> <DT>node * n<DD>a new list node <DT>node * after<DD>a node of a list </DL> <H3>Description</H3> Inserts a node n to a linked list after an already inserted node after. <HR><H3>Function</H3> LIST_INLINE void rem_node (node * n) -- remove a node from a list  <H3>Arguments</H3>  <DL> <DT>node * n<DD>node to be removed </DL> <H3>Description</H3> Removes a node n from the list it's linked in. Afterwards, node n is cleared. <HR><H3>Function</H3> LIST_INLINE void replace_node (node * old, node * new) -- replace a node in a list with another one  <H3>Arguments</H3>  <DL> <DT>node * old<DD>node to be removed <DT>node * new<DD>node to be inserted </DL> <H3>Description</H3> Replaces node old in the list it's linked in with node new. Node old may be a copy of the original node, which is not accessed through the list. The function could be called with old == new, which just fixes neighbors' pointers in the case that the node was reallocated. <HR><H3>Function</H3> LIST_INLINE void init_list (list * l) -- create an empty list  <H3>Arguments</H3>  <DL> <DT>list * l<DD>list </DL> <H3>Description</H3> init_list() takes a list structure and initializes its fields, so that it represents an empty list. <HR><H3>Function</H3> LIST_INLINE void add_tail_list (list * to, list * l) -- concatenate two lists  <H3>Arguments</H3>  <DL> <DT>list * to<DD>destination list <DT>list * l<DD>source list </DL> <H3>Description</H3> This function appends all elements of the list l to the list to in constant time. <H2><A NAME="ss7.3">7.3</A> <A HREF="prog.html#toc7.3">Miscellaneous functions.</A> </H2>   <HR><H3>Function</H3> int ipsum_verify (void * frag, uint len, ... ...) -- verify an IP checksum  <H3>Arguments</H3>  <DL> <DT>void * frag<DD>first packet fragment <DT>uint len<DD>length in bytes <DT>... ...<DD>variable arguments </DL> <H3>Description</H3> This function verifies whether a given fragmented packet has correct one's complement checksum as used by the IP protocol. It uses all the clever tricks described in RFC 1071 to speed up checksum calculation as much as possible. <H3>Result</H3> 1 if the checksum is correct, 0 else. <HR><H3>Function</H3> u16 ipsum_calculate (void * frag, uint len, ... ...) -- compute an IP checksum  <H3>Arguments</H3>  <DL> <DT>void * frag<DD>first packet fragment <DT>uint len<DD>length in bytes <DT>... ...<DD>variable arguments </DL> <H3>Description</H3> This function calculates a one's complement checksum of a given fragmented packet. It uses all the clever tricks described in RFC 1071 to speed up checksum calculation as much as possible. <HR><H3>Function</H3> u32 u32_mkmask (uint n) -- create a bit mask  <H3>Arguments</H3>  <DL> <DT>uint n<DD>number of bits </DL> <H3>Description</H3> u32_mkmask() returns an unsigned 32-bit integer which binary representation consists of n ones followed by zeroes. <HR><H3>Function</H3> int u32_masklen (u32 x) -- calculate length of a bit mask  <H3>Arguments</H3>  <DL> <DT>u32 x<DD>bit mask </DL> <H3>Description</H3> This function checks whether the given integer x represents a valid bit mask (binary representation contains first ones, then zeroes) and returns the number of ones or -1 if the mask is invalid. <HR><H3>Function</H3> u32 u32_log2 (u32 v) -- compute a binary logarithm.  <H3>Arguments</H3>  <DL> <DT>u32 v<DD>number </DL> <H3>Description</H3> This function computes a integral part of binary logarithm of given integer v and returns it. The computed value is also an index of the most significant non-zero bit position. <HR><H3>Function</H3> int patmatch (byte * p, byte * s) -- match shell-like patterns  <H3>Arguments</H3>  <DL> <DT>byte * p<DD>pattern <DT>byte * s<DD>string </DL> <H3>Description</H3> patmatch() returns whether given string s matches the given shell-like pattern p. The patterns consist of characters (which are matched literally), question marks which match any single character, asterisks which match any (possibly empty) string of characters and backslashes which are used to escape any special characters and force them to be treated literally. The matching process is not optimized with respect to time, so please avoid using this function for complex patterns. <HR><H3>Function</H3> int bvsnprintf (char * buf, int size, const char * fmt, va_list args) -- BIRD's vsnprintf()  <H3>Arguments</H3>  <DL> <DT>char * buf<DD>destination buffer <DT>int size<DD>size of the buffer <DT>const char * fmt<DD>format string <DT>va_list args<DD>a list of arguments to be formatted </DL> <H3>Description</H3> This functions acts like ordinary sprintf() except that it checks available space to avoid buffer overflows and it allows some more <H3>format specifiers</H3> <CODE>I</CODE> for formatting of IP addresses (any non-zero width is automatically replaced by standard IP address width which depends on whether we use IPv4 or IPv6; <CODE>%#I</CODE> gives hexadecimal format), <CODE>R</CODE> for Router / Network ID (u32 value printed as IPv4 address) <CODE>lR</CODE> for 64bit Router / Network ID (u64 value printed as eight :-separated octets) and <CODE>m</CODE> resp. <CODE>M</CODE> for error messages (uses strerror() to translate errno code to message text). On the other hand, it doesn't support floating point numbers. <H3>Result</H3> number of characters of the output string or -1 if the buffer space was insufficient. <HR><H3>Function</H3> int bvsprintf (char * buf, const char * fmt, va_list args) -- BIRD's vsprintf()  <H3>Arguments</H3>  <DL> <DT>char * buf<DD>buffer <DT>const char * fmt<DD>format string <DT>va_list args<DD>a list of arguments to be formatted </DL> <H3>Description</H3> This function is equivalent to bvsnprintf() with an infinite buffer size. Please use carefully only when you are absolutely sure the buffer won't overflow. <HR><H3>Function</H3> int bsprintf (char * buf, const char * fmt, ... ...) -- BIRD's sprintf()  <H3>Arguments</H3>  <DL> <DT>char * buf<DD>buffer <DT>const char * fmt<DD>format string <DT>... ...<DD>variable arguments </DL> <H3>Description</H3> This function is equivalent to bvsnprintf() with an infinite buffer size and variable arguments instead of a va_list. Please use carefully only when you are absolutely sure the buffer won't overflow. <HR><H3>Function</H3> int bsnprintf (char * buf, int size, const char * fmt, ... ...) -- BIRD's snprintf()  <H3>Arguments</H3>  <DL> <DT>char * buf<DD>buffer <DT>int size<DD>buffer size <DT>const char * fmt<DD>format string <DT>... ...<DD>variable arguments </DL> <H3>Description</H3> This function is equivalent to bsnprintf() with variable arguments instead of a va_list. <HR><H3>Function</H3> void * xmalloc (uint size) -- malloc with checking  <H3>Arguments</H3>  <DL> <DT>uint size<DD>block size </DL> <H3>Description</H3> This function is equivalent to malloc() except that in case of failure it calls die() to quit the program instead of returning a NULL pointer. Wherever possible, please use the memory resources instead. <HR><H3>Function</H3> void * xrealloc (void * ptr, uint size) -- realloc with checking  <H3>Arguments</H3>  <DL> <DT>void * ptr<DD>original memory block <DT>uint size<DD>block size </DL> <H3>Description</H3> This function is equivalent to realloc() except that in case of failure it calls die() to quit the program instead of returning a NULL pointer. Wherever possible, please use the memory resources instead. <H2><A NAME="ss7.4">7.4</A> <A HREF="prog.html#toc7.4">Message authentication codes</A> </H2>  MAC algorithms are simple cryptographic tools for message authentication. They use shared a secret key a and message text to generate authentication code, which is then passed with the message to the other side, where the code is verified. There are multiple families of MAC algorithms based on different cryptographic primitives, BIRD implements two MAC families which use hash functions. The first family is simply a cryptographic hash camouflaged as MAC algorithm. Originally supposed to be (m|k)-hash (message is concatenated with key, and that is hashed), but later it turned out that a raw hash is more practical. This is used for cryptographic authentication in OSPFv2, RIP and BFD. The second family is the standard HMAC (RFC 2104), using inner and outer hash to process key and message. HMAC (with SHA) is used in advanced OSPF and RIP authentication (RFC 5709, RFC 4822).  <HR><H3>Function</H3> void mac_init (struct mac_context * ctx, uint id, const byte * key, uint keylen) -- initialize MAC algorithm  <H3>Arguments</H3>  <DL> <DT>struct mac_context * ctx<DD>context to initialize <DT>uint id<DD>MAC algorithm ID <DT>const byte * key<DD>MAC key <DT>uint keylen<DD>MAC key length </DL> <H3>Description</H3> Initialize MAC context ctx for algorithm id (e.g., ALG_HMAC_SHA1), with key key of length keylen. After that, message data could be added using mac_update() function. <HR><H3>Function</H3> void mac_update (struct mac_context * ctx, const byte * data, uint datalen) -- add more data to MAC algorithm  <H3>Arguments</H3>  <DL> <DT>struct mac_context * ctx<DD>MAC context <DT>const byte * data<DD>data to add <DT>uint datalen<DD>length of data </DL> <H3>Description</H3> Push another datalen bytes of data pointed to by data into the MAC algorithm currently in ctx. Can be called multiple times for the same MAC context. It has the same effect as concatenating all the data together and passing them at once. <HR><H3>Function</H3> byte * mac_final (struct mac_context * ctx) -- finalize MAC algorithm  <H3>Arguments</H3>  <DL> <DT>struct mac_context * ctx<DD>MAC context </DL> <H3>Description</H3> Finish MAC computation and return a pointer to the result. No more mac_update() calls could be done, but the context may be reinitialized later. Note that the returned pointer points into data in the ctx context. If it ceases to exist, the pointer becomes invalid. <HR><H3>Function</H3> void mac_cleanup (struct mac_context * ctx) -- cleanup MAC context  <H3>Arguments</H3>  <DL> <DT>struct mac_context * ctx<DD>MAC context </DL> <H3>Description</H3> Cleanup MAC context after computation (by filling with zeros). Not strictly necessary, just to erase sensitive data from stack. This also invalidates the pointer returned by mac_final(). <HR><H3>Function</H3> void mac_fill (uint id, const byte * key, uint keylen, const byte * data, uint datalen, byte * mac) -- compute and fill MAC  <H3>Arguments</H3>  <DL> <DT>uint id<DD>MAC algorithm ID <DT>const byte * key<DD>secret key <DT>uint keylen<DD>key length <DT>const byte * data<DD>message data <DT>uint datalen<DD>message length <DT>byte * mac<DD>place to fill MAC </DL> <H3>Description</H3> Compute MAC for specified key key and message data using algorithm id and copy it to buffer mac. mac_fill() is a shortcut function doing all usual steps for transmitted messages. <HR><H3>Function</H3> int mac_verify (uint id, const byte * key, uint keylen, const byte * data, uint datalen, const byte * mac) -- compute and verify MAC  <H3>Arguments</H3>  <DL> <DT>uint id<DD>MAC algorithm ID <DT>const byte * key<DD>secret key <DT>uint keylen<DD>key length <DT>const byte * data<DD>message data <DT>uint datalen<DD>message length <DT>const byte * mac<DD>received MAC </DL> <H3>Description</H3> Compute MAC for specified key key and message data using algorithm id and compare it with received mac, return whether they are the same. mac_verify() is a shortcut function doing all usual steps for received messages.  <HR> <A HREF="prog-8.html">Next</A> <A HREF="prog-6.html">Previous</A> <A HREF="prog.html#toc7">Contents</A> </BODY> </HTML>