The BIRD Internet Routing Daemon Project

Next Previous Contents

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.

Function

char * ip_scope_text (uint scope) -- get textual representation of address scope

Arguments

uint scope: scope (SCOPE_xxx)

Description

Returns a pointer to a textual name of the scope given.

Function

int ipa_equal (ip_addr x, ip_addr y) -- compare two IP addresses for equality

Arguments

ip_addr x: IP address
ip_addr y: IP address

Description

ipa_equal() returns 1 if x and y represent the same IP address, else 0.

Function

int ipa_nonzero (ip_addr x) -- test if an IP address is defined

Arguments

ip_addr x: IP address

Description

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 IPA_NONE macro.

Function

ip_addr ipa_and (ip_addr x, ip_addr y) -- compute bitwise and of two IP addresses

Arguments

ip_addr x: IP address
ip_addr y: IP address

Description

This function returns a bitwise and of x and y. It's primarily used for network masking.

Function

ip_addr ipa_or (ip_addr x, ip_addr y) -- compute bitwise or of two IP addresses

Arguments

ip_addr x: IP address
ip_addr y: IP address

Description

This function returns a bitwise or of x and y.

Function

ip_addr ipa_xor (ip_addr x, ip_addr y) -- compute bitwise xor of two IP addresses

Arguments

ip_addr x: IP address
ip_addr y: IP address

Description

This function returns a bitwise xor of x and y.

Function

ip_addr ipa_not (ip_addr x) -- compute bitwise negation of two IP addresses

Arguments

ip_addr x: IP address

Description

This function returns a bitwise negation of x.

Function

ip_addr ipa_mkmask (int x) -- create a netmask

Arguments

int x: prefix length

Description

This function returns an ip_addr corresponding of a netmask of an address prefix of size x.

Function

int ipa_masklen (ip_addr x) -- calculate netmask length

Arguments

ip_addr x: IP address

Description

This function checks whether x represents a valid netmask and returns the size of the associate network prefix or -1 for invalid mask.

Function

int ipa_hash (ip_addr x) -- hash IP addresses

Arguments

ip_addr x: IP address

Description

ipa_hash() returns a 16-bit hash value of the IP address x.

Function

void ipa_hton (ip_addr x) -- convert IP address to network order

Arguments

ip_addr x: IP address

Description

Converts the IP address x to the network byte order.

Beware, this is a macro and it alters the argument!

Function

void ipa_ntoh (ip_addr x) -- convert IP address to host order

Arguments

ip_addr x: IP address

Description

Converts the IP address x from the network byte order.

Beware, this is a macro and it alters the argument!

Function

int ipa_classify (ip_addr x) -- classify an IP address

Arguments

ip_addr x: IP address

Description

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.

Function

ip4_addr ip4_class_mask (ip4_addr x) -- guess netmask according to address class

Arguments

ip4_addr x: IPv4 address

Description

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.

Function

u32 ipa_from_u32 (ip_addr x) -- convert IPv4 address to an integer

Arguments

ip_addr x: IP address

Description

This function takes an IPv4 address and returns its numeric representation.

Function

ip_addr ipa_to_u32 (u32 x) -- convert integer to IPv4 address

Arguments

u32 x: a 32-bit integer

Description

ipa_to_u32() takes a numeric representation of an IPv4 address and converts it to the corresponding ip_addr.

Function

int ipa_compare (ip_addr x, ip_addr y) -- compare two IP addresses for order

Arguments

ip_addr x: IP address
ip_addr y: IP address

Description

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.

Function

ip_addr ipa_build6 (u32 a1, u32 a2, u32 a3, u32 a4) -- build an IPv6 address from parts

Arguments

u32 a1: part #1
u32 a2: part #2
u32 a3: part #3
u32 a4: part #4

Description

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.

Function

char * ip_ntop (ip_addr a, char * buf) -- convert IP address to textual representation

Arguments

ip_addr a: IP address
char * buf: buffer of size at least STD_ADDRESS_P_LENGTH

Description

This function takes an IP address and creates its textual representation for presenting to the user.

Function

char * ip_ntox (ip_addr a, char * buf) -- convert IP address to hexadecimal representation

Arguments

ip_addr a: IP address
char * buf: buffer of size at least STD_ADDRESS_P_LENGTH

Description

This function takes an IP address and creates its hexadecimal textual representation. Primary use: debugging dumps.

Function

int ip_pton (char * a, ip_addr * o) -- parse textual representation of IP address

Arguments

char * a: textual representation
ip_addr * o: where to put the resulting address

Description

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.

7.2 Linked lists

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 s_) which support asynchronous walking very similar to that used in the fib structure.

Function

LIST_INLINE void add_tail (list * l, node * n) -- append a node to a list

Arguments

list * l: linked list
node * n: list node

Description

add_tail() takes a node n and appends it at the end of the list l.

Function

LIST_INLINE void add_head (list * l, node * n) -- prepend a node to a list

Arguments

list * l: linked list
node * n: list node

Description

add_head() takes a node n and prepends it at the start of the list l.

Function

LIST_INLINE void insert_node (node * n, node * after) -- insert a node to a list

Arguments

node * n: a new list node
node * after: a node of a list

Description

Inserts a node n to a linked list after an already inserted node after.

Function

LIST_INLINE void rem_node (node * n) -- remove a node from a list

Arguments

node * n: node to be removed

Description

Removes a node n from the list it's linked in. Afterwards, node n is cleared.

Function

LIST_INLINE void update_node (node * n) -- update node after calling realloc on it

Arguments

node * n: node to be updated

Description

Fixes neighbor pointers.

Function

LIST_INLINE void init_list (list * l) -- create an empty list

Arguments

list * l: list

Description

init_list() takes a list structure and initializes its fields, so that it represents an empty list.

Function

LIST_INLINE void add_tail_list (list * to, list * l) -- concatenate two lists

Arguments

list * to: destination list
list * l: source list

Description

This function appends all elements of the list l to the list to in constant time.

7.3 Miscellaneous functions.

Function

int ipsum_verify (void * frag, uint len, ... ...) -- verify an IP checksum

Arguments

void * frag: first packet fragment
uint len: length in bytes
... ...: variable arguments

Description

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.

Result

1 if the checksum is correct, 0 else.

Function

u16 ipsum_calculate (void * frag, uint len, ... ...) -- compute an IP checksum

Arguments

void * frag: first packet fragment
uint len: length in bytes
... ...: variable arguments

Description

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.

Function

u32 u32_mkmask (uint n) -- create a bit mask

Arguments

uint n: number of bits

Description

u32_mkmask() returns an unsigned 32-bit integer which binary representation consists of n ones followed by zeroes.

Function

uint u32_masklen (u32 x) -- calculate length of a bit mask

Arguments

u32 x: bit mask

Description

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 255 if the mask is invalid.

Function

u32 u32_log2 (u32 v) -- compute a binary logarithm.

Arguments

u32 v: number

Description

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.

Function

u32 u32_bitflip (u32 n) -- flips bits in number.

Arguments

u32 n: number

Description

This function flips bits in the given number such that MSB becomes LSB and vice versa.

Function

int patmatch (byte * p, byte * s) -- match shell-like patterns

Arguments

byte * p: pattern
byte * s: string

Description

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.

Function

int bvsnprintf (char * buf, int size, const char * fmt, va_list args) -- BIRD's vsnprintf()

Arguments

char * buf: destination buffer
int size: size of the buffer
const char * fmt: format string
va_list args: a list of arguments to be formatted

Description

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.

Function

void * xrealloc (void * ptr, uint size) -- realloc with checking

Arguments

void * ptr: original memory block
uint size: block size

Description

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.

7.4 Message authentication codes

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).

Function

void mac_init (struct mac_context * ctx, uint id, const byte * key, uint keylen) -- initialize MAC algorithm

Arguments

struct mac_context * ctx: context to initialize
uint id: MAC algorithm ID
const byte * key: MAC key
uint keylen: MAC key length

Description

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.

Function

void mac_update (struct mac_context * ctx, const byte * data, uint datalen) -- add more data to MAC algorithm

Arguments

struct mac_context * ctx: MAC context
const byte * data: data to add
uint datalen: length of data

Description

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.

Function

byte * mac_final (struct mac_context * ctx) -- finalize MAC algorithm

Arguments

struct mac_context * ctx: MAC context

Description

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.

Function

void mac_cleanup (struct mac_context * ctx) -- cleanup MAC context

Arguments

struct mac_context * ctx: MAC context

Description

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().

Function

void mac_fill (uint id, const byte * key, uint keylen, const byte * data, uint datalen, byte * mac) -- compute and fill MAC

Arguments

uint id: MAC algorithm ID
const byte * key: secret key
uint keylen: key length
const byte * data: message data
uint datalen: message length
byte * mac: place to fill MAC

Description

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.

Function

int mac_verify (uint id, const byte * key, uint keylen, const byte * data, uint datalen, const byte * mac) -- compute and verify MAC

Arguments

uint id: MAC algorithm ID
const byte * key: secret key
uint keylen: key length
const byte * data: message data
uint datalen: message length
const byte * mac: received MAC

Description

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.

7.5 Flow specification (flowspec)

Flowspec are rules (RFC 5575) for firewalls disseminated using BGP protocol. The flowspec.c is a library for handling flowspec binary streams and flowspec data structures. You will find there functions for validation incoming flowspec binary streams, iterators for jumping over components, functions for handling a length and functions for formatting flowspec data structure into user-friendly text representation.

In this library, you will find also flowspec builder. In confbase.Y, there are grammar's rules for parsing and building new flowspec data structure from BIRD's configuration files and from BIRD's command line interface. Finalize function will assemble final net_addr_flow4 or net_addr_flow6 data structure.

The data structures net_addr_flow4 and net_addr_flow6 are defined in net.h file. The attribute length is size of whole data structure plus binary stream representation of flowspec including a compressed encoded length of flowspec.

Sometimes in code, it is used expression flowspec type, it should mean flowspec component type.

Function

const char * flow_type_str (enum flow_type type, int ipv6) -- get stringified flowspec name of component

Arguments

enum flow_type type: flowspec component type
int ipv6: IPv4/IPv6 decide flag, use zero for IPv4 and one for IPv6

Description

This function returns flowspec name of component type in string.

Function

uint flow_write_length (byte * data, u16 len) -- write compressed length value

Arguments

byte * data: destination buffer to write
u16 len: the value of the length (0 to 0xfff) for writing

Description

This function writes appropriate as (1- or 2-bytes) the value of len into buffer data. The function returns number of written bytes, thus 1 or 2 bytes.

Function

const byte * flow4_first_part (const net_addr_flow4 * f) -- get position of the first flowspec component

Arguments

const net_addr_flow4 * f: flowspec data structure net_addr_flow4

Description

This function return a position to the beginning of the first flowspec component in IPv4 flowspec f.

Function

const byte * flow6_first_part (const net_addr_flow6 * f) -- get position of the first flowspec component

Arguments

const net_addr_flow6 * f: flowspec data structure net_addr_flow6

Description

This function return a position to the beginning of the first flowspec component in IPv6 flowspec f.

Function

const byte * flow4_next_part (const byte * pos, const byte * end) -- an iterator over flowspec components in flowspec binary stream

Arguments

const byte * pos: the beginning of a previous or the first component in flowspec binary stream
const byte * end: the last valid byte in scanned flowspec binary stream

Description

This function returns a position to the beginning of the next component (to a component type byte) in flowspec binary stream or NULL for the end.

Function

const byte * flow6_next_part (const byte * pos, const byte * end) -- an iterator over flowspec components in flowspec binary stream

Arguments

const byte * pos: the beginning of a previous or the first component in flowspec binary stream
const byte * end: the last valid byte in scanned flowspec binary stream

Description

This function returns a position to the beginning of the next component (to a component type byte) in flowspec binary stream or NULL for the end.

Function

const char * flow_validated_state_str (enum flow_validated_state code) -- return a textual description of validation process

Arguments

enum flow_validated_state code: validation result

Description

This function return well described validation state in string.

Function

void flow_check_cf_bmk_values (struct flow_builder * fb, u8 neg, u32 val, u32 mask) -- check value/bitmask part of flowspec component

Arguments

struct flow_builder * fb: flow builder instance
u8 neg: negation operand
u32 val: value from value/mask pair
u32 mask: bitmap mask from value/mask pair

Description

This function checks value/bitmask pair. If some problem will appear, the function calls cf_error() function with a textual description of reason to failing of validation.

Function

void flow_check_cf_value_length (struct flow_builder * fb, u32 val) -- check value by flowspec component type

Arguments

struct flow_builder * fb: flow builder instance
u32 val: value

Description

This function checks if the value is in range of component's type support. If some problem will appear, the function calls cf_error() function with a textual description of reason to failing of validation.

Function

enum flow_validated_state flow4_validate (const byte * nlri, uint len) -- check untrustworthy IPv4 flowspec data stream

Arguments

const byte * nlri: flowspec data stream without compressed encoded length value
uint len: length of nlri

Description

This function checks meaningfulness of binary flowspec. It should return FLOW_ST_VALID or FLOW_ST_UNKNOWN_COMPONENT. If some problem appears, it returns some other FLOW_ST_xxx state.

Function

enum flow_validated_state flow6_validate (const byte * nlri, uint len) -- check untrustworthy IPv6 flowspec data stream

Arguments

const byte * nlri: flowspec binary stream without encoded length value
uint len: length of nlri

Description

This function checks meaningfulness of binary flowspec. It should return FLOW_ST_VALID or FLOW_ST_UNKNOWN_COMPONENT. If some problem appears, it returns some other FLOW_ST_xxx state.

Function

void flow4_validate_cf (net_addr_flow4 * f) -- validate flowspec data structure net_addr_flow4 in parsing time

Arguments

net_addr_flow4 * f: flowspec data structure net_addr_flow4

Description

Check if f is valid flowspec data structure. Can call cf_error() function with a textual description of reason to failing of validation.

Function

void flow6_validate_cf (net_addr_flow6 * f) -- validate flowspec data structure net_addr_flow6 in parsing time

Arguments

net_addr_flow6 * f: flowspec data structure net_addr_flow6

Description

Check if f is valid flowspec data structure. Can call cf_error() function with a textual description of reason to failing of validation.

Function

struct flow_builder * flow_builder_init (pool * pool) -- constructor for flowspec builder instance

Arguments

pool * pool: memory pool

Description

This function prepares flowspec builder instance using memory pool pool.

Function

int flow_builder4_add_pfx (struct flow_builder * fb, const net_addr_ip4 * n4) -- add IPv4 prefix

Arguments

struct flow_builder * fb: flowspec builder instance
const net_addr_ip4 * n4: net address of type IPv4

Description

This function add IPv4 prefix into flowspec builder instance.

Function

int flow_builder6_add_pfx (struct flow_builder * fb, const net_addr_ip6 * n6, u32 pxoffset) -- add IPv6 prefix

Arguments

struct flow_builder * fb: flowspec builder instance
const net_addr_ip6 * n6: net address of type IPv4
u32 pxoffset: prefix offset for n6

Description

This function add IPv4 prefix into flowspec builder instance. This function should return 1 for successful adding, otherwise returns 0.

Function

int flow_builder_add_op_val (struct flow_builder * fb, byte op, u32 value) -- add operator/value pair

Arguments

struct flow_builder * fb: flowspec builder instance
byte op: operator
u32 value: value

Description

This function add operator/value pair as a part of a flowspec component. It is required to set appropriate flowspec component type using function flow_builder_set_type(). This function should return 1 for successful adding, otherwise returns 0.

Function

int flow_builder_add_val_mask (struct flow_builder * fb, byte op, u32 value, u32 mask) -- add value/bitmask pair

Arguments

struct flow_builder * fb: flowspec builder instance
byte op: operator
u32 value: value
u32 mask: bitmask

Description

It is required to set appropriate flowspec component type using function flow_builder_set_type(). Note that for negation, value must be zero or equal to bitmask.

Function

void flow_builder_set_type (struct flow_builder * fb, enum flow_type type) -- set type of next flowspec component

Arguments

struct flow_builder * fb: flowspec builder instance
enum flow_type type: flowspec component type

Description

This function sets type of next flowspec component. It is necessary to call this function before each changing of adding flowspec component.

Function

net_addr_flow4 * flow_builder4_finalize (struct flow_builder * fb, linpool * lpool) -- assemble final flowspec data structure net_addr_flow4

Arguments

struct flow_builder * fb: flowspec builder instance
linpool * lpool: linear memory pool

Description

This function returns final flowspec data structure net_addr_flow4 allocated onto lpool linear memory pool.

Function

net_addr_flow6 * flow_builder6_finalize (struct flow_builder * fb, linpool * lpool) -- assemble final flowspec data structure net_addr_flow6

Arguments

struct flow_builder * fb: flowspec builder instance
linpool * lpool: linear memory pool for allocation of

Description

This function returns final flowspec data structure net_addr_flow6 allocated onto lpool linear memory pool.

Function

void flow_builder_clear (struct flow_builder * fb) -- flush flowspec builder instance for another flowspec creation

Arguments

struct flow_builder * fb: flowspec builder instance

Description

This function flushes all data from builder but it maintains pre-allocated buffer space.

Function

uint flow_explicate_buffer_size (const byte * part) -- return buffer size needed for explication

Arguments

const byte * part: flowspec part to explicate

Description

This function computes and returns a required buffer size that has to be preallocated and passed to flow_explicate_part(). Note that it returns number of records, not number of bytes.

Function

uint flow_explicate_part (const byte * part, uint (*buf) -- compute explicit interval list from flowspec part

Arguments

const byte * part: flowspec part to explicate
uint (*buf: -- undescribed --

Description

This function analyzes a flowspec part with numeric operators (e.g. port) and computes an explicit interval list of allowed values. The result is written to provided buffer buf, which must have space for enough interval records as returned by flow_explicate_buffer_size(). The intervals are represented as two-sized arrays of lower and upper bound, both including. The return value is the number of intervals in the buffer.

Function

uint flow4_net_format (char * buf, uint blen, const net_addr_flow4 * f) -- stringify flowspec data structure net_addr_flow4

Arguments

char * buf: pre-allocated buffer for writing a stringify net address flowspec
uint blen: free allocated space in buf
const net_addr_flow4 * f: flowspec data structure net_addr_flow4 for stringify

Description

This function writes stringified f into buf. The function returns number of written chars. If final string is too large, the string will ends the with ' ...}' sequence and zero-terminator.

Function

uint flow6_net_format (char * buf, uint blen, const net_addr_flow6 * f) -- stringify flowspec data structure net_addr_flow6

Arguments

char * buf: pre-allocated buffer for writing a stringify net address flowspec
uint blen: free allocated space in buf
const net_addr_flow6 * f: flowspec data structure net_addr_flow4 for stringify

Description

This function writes stringified f into buf. The function returns number of written chars. If final string is too large, the string will ends the with ' ...}' sequence and zero-terminator.

Next Previous Contents

Web created by Feela

7. Library functions

7.1 IP addresses

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

7.2 Linked lists

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments

Description

Function

Arguments