RTR connection manager

The RTR connection manager maintains multiple groups of RTR sockets. More...

Modules
	BGPsec AS path validation
	BGPsec allows for validation of the BGPsec_PATH attribute of a BGPsec update.

Data Structures
struct	rtr_mgr_group
	A set of RTR sockets. More...
struct	rtr_mgr_config

Typedefs
typedef void(*	rtr_mgr_status_fp) (const struct rtr_mgr_group *, enum rtr_mgr_status, const struct rtr_socket *, void *)

Enumerations
enum	rtr_mgr_status { RTR_MGR_CLOSED , RTR_MGR_CONNECTING , RTR_MGR_ESTABLISHED , RTR_MGR_ERROR }
	Status of a rtr_mgr_group. More...

Functions
int	rtr_mgr_init (struct rtr_mgr_config **config_out, struct rtr_mgr_group groups[], const unsigned int groups_len, const rtr_mgr_status_fp status_fp, void *status_fp_data)
	Initializes a rtr_mgr_config.
int	rtr_mgr_setup_sockets (struct rtr_mgr_config *config, struct rtr_mgr_group groups[], const unsigned int groups_len, const unsigned int refresh_interval, const unsigned int expire_interval, const unsigned int retry_interval)
int	rtr_mgr_add_roa_support (struct rtr_mgr_config *config, const pfx_update_fp pfx_update_fp)
	Sets up ROA support.
int	rtr_mgr_add_group (struct rtr_mgr_config *config, const struct rtr_mgr_group *group)
	Adds a new rtr_mgr_group to the linked list of a initialized config.
int	rtr_mgr_remove_group (struct rtr_mgr_config *config, unsigned int preference)
	Removes an existing rtr_mgr_group from the linked list of config.
void	rtr_mgr_free (struct rtr_mgr_config *config)
	Frees all resources that were allocated from the rtr_mgr.
int	rtr_mgr_start (struct rtr_mgr_config *config)
	Establishes rtr_socket connections.
void	rtr_mgr_stop (struct rtr_mgr_config *config)
	Terminates rtr_socket connections.
bool	rtr_mgr_conf_in_sync (struct rtr_mgr_config *config)
	Check if rtr_mgr_group is fully synchronized with at least one group.
int	rtr_mgr_validate (struct rtr_mgr_config *config, const uint32_t asn, const struct lrtr_ip_addr *prefix, const uint8_t mask_len, enum pfxv_state *result)
	Validates the origin of a BGP-Route.
int	rtr_mgr_get_spki (struct rtr_mgr_config *config, const uint32_t asn, uint8_t *ski, struct spki_record **result, unsigned int *result_count)
	Returns all SPKI records which match the given ASN and SKI.
const char *	rtr_mgr_status_to_str (enum rtr_mgr_status status)
	Converts a rtr_mgr_status to a String.
void	rtr_mgr_for_each_ipv4_record (struct rtr_mgr_config *config, pfx_for_each_fp fp, void *data)
	Iterates over all IPv4 records in the pfx_table.
void	rtr_mgr_for_each_ipv6_record (struct rtr_mgr_config *config, pfx_for_each_fp fp, void *data)
	Iterates over all IPv6 records in the pfx_table.
struct rtr_mgr_group *	rtr_mgr_get_first_group (struct rtr_mgr_config *config)
	Returns the first, thus active group.
int	rtr_mgr_for_each_group (struct rtr_mgr_config *config, void(*fp)(const struct rtr_mgr_group *group, void *data), void *data)
int	rtr_mgr_add_aspa_support (struct rtr_mgr_config *config, const aspa_update_fp aspa_update_fp)
	Sets up ASPA support.
int	rtr_mgr_add_spki_support (struct rtr_mgr_config *config, const spki_update_fp spki_update_fp)
	Sets up BGPSEC support.

Variables
struct rtr_socket **	rtr_mgr_group::sockets
unsigned int	rtr_mgr_group::sockets_len
uint8_t	rtr_mgr_group::preference
enum rtr_mgr_status	rtr_mgr_group::status
struct tommy_list_wrapper *	rtr_mgr_config::groups
unsigned int	rtr_mgr_config::len
pthread_rwlock_t	rtr_mgr_config::mutex
rtr_mgr_status_fp	rtr_mgr_config::status_fp
void *	rtr_mgr_config::status_fp_data
struct pfx_table *	rtr_mgr_config::pfx_table
struct spki_table *	rtr_mgr_config::spki_table
struct aspa_table *	rtr_mgr_config::aspa_table

Detailed Description

The RTR connection manager maintains multiple groups of RTR sockets.

The RTR connection manager is initialized with one or multiple groups of rtr_sockets. Each group is configured with a preference value and contains a set of rtr_socket RTR sockets. It connects to all sockets of the group with the lowest preference value.
In case of failures, the connection manager establishes connections to RTR servers of another group with the next lowest preference value (see IETF RFC 6810 for details about error handling).
RTRlib also supports a Retry Interval (see draft-ietf-sidr-rpki-rtr-rfc6810-bis). If a more preferred group is online again, the RTR connection manager will switch back and close connections to the caches of the less preferred group.

Typedef Documentation

rtr_mgr_status_fp

typedef void(* rtr_mgr_status_fp) (const struct rtr_mgr_group *, enum rtr_mgr_status, const struct rtr_socket *, void *)

#include <rtrlib/rtr_mgr.h>

Enumeration Type Documentation

rtr_mgr_status

enum rtr_mgr_status

#include <rtrlib/rtr_mgr.h>

Status of a rtr_mgr_group.

Enumerator
RTR_MGR_CLOSED	RTR sockets are disconnected.
RTR_MGR_CONNECTING	RTR sockets trying to establish a connection.
RTR_MGR_ESTABLISHED	All RTR sockets of the group are synchronized with rtr servers.
RTR_MGR_ERROR	Error occurred on at least one RTR socket.

Function Documentation

rtr_mgr_add_aspa_support()

int rtr_mgr_add_aspa_support	(	struct rtr_mgr_config *	config,
		const aspa_update_fp	aspa_update_fp
	)

#include <rtrlib/rtr_mgr.h>

Sets up ASPA support.

Parameters

[in]	config	Pointer to the rtr_mgr_config where ROA support should be enabled.
[in]	aspa_update_fp	Pointer to aspa_update_fp callback, that is executed for every added and removed aspa_record.

Returns

RTR_ERROR If an error occurred

RTR_INVALID_PARAM If refresh_interval or expire_interval is invalid.

RTR_SUCCESS On success.

rtr_mgr_add_group()

int rtr_mgr_add_group	(	struct rtr_mgr_config *	config,
		const struct rtr_mgr_group *	group
	)

#include <rtrlib/rtr_mgr.h>

Adds a new rtr_mgr_group to the linked list of a initialized config.

A new group must have at least one rtr_socket associated with it. This socket must have at least one initialized transport socket associated with it. The new group must have a preference value that is none of the already present groups have. More than one rtr_mgr_group with the same preference is not allowed.

Parameters

config	A rtr_mgr_config struct that has been initialized previously with rtr_mgr_init
group	A rtr_mgr_group with at least one rtr_socket and a preference value that no existing group has.

Returns

RTR_INVALID_PARAM If a group with the same preference value already exists.

RTR_ERROR If an error occurred while adding the group.

RTR_SUCCESS If the group was successfully added.

rtr_mgr_add_roa_support()

int rtr_mgr_add_roa_support	(	struct rtr_mgr_config *	config,
		const pfx_update_fp	pfx_update_fp
	)

#include <rtrlib/rtr_mgr.h>

Sets up ROA support.

Parameters

[in]	config	Pointer to the rtr_mgr_config where ROA support should be enabled.
[in]	update_fp	Pointer to pfx_update_fp callback, that is executed for every added and removed pfx_record.

Returns

RTR_ERROR If an error occurred

RTR_INVALID_PARAM If refresh_interval or expire_interval is invalid.

RTR_SUCCESS On success.

rtr_mgr_add_spki_support()

int rtr_mgr_add_spki_support	(	struct rtr_mgr_config *	config,
		const spki_update_fp	spki_update_fp
	)

#include <rtrlib/rtr_mgr.h>

Sets up BGPSEC support.

Parameters

[in]	config	Pointer to the rtr_mgr_config where ROA support should be enabled.
[in]	spki_update_fp	Pointer to spki_update_fp callback, that is executed for every added and removed spki_record.

Returns

RTR_ERROR If an error occurred

RTR_INVALID_PARAM If refresh_interval or expire_interval is invalid.

RTR_SUCCESS On success.

rtr_mgr_conf_in_sync()

bool rtr_mgr_conf_in_sync

(

struct rtr_mgr_config *

config

)

#include <rtrlib/rtr_mgr.h>

Check if rtr_mgr_group is fully synchronized with at least one group.

Parameters

[in]

config

The rtr_mgr_config.

Returns

true If pfx_table stores non-outdated pfx_records

false If pfx_table isn't fully synchronized with at least one group.

rtr_mgr_for_each_group()

int rtr_mgr_for_each_group	(	struct rtr_mgr_config *	config,
		void(*)(const struct rtr_mgr_group *group, void *data)	fp,
		void *	data
	)

#include <rtrlib/rtr_mgr.h>

rtr_mgr_for_each_ipv4_record()

void rtr_mgr_for_each_ipv4_record	(	struct rtr_mgr_config *	config,
		pfx_for_each_fp	fp,
		void *	data
	)

#include <rtrlib/rtr_mgr.h>

Iterates over all IPv4 records in the pfx_table.

For every pfx_record the function fp is called. The pfx_record and the data pointer is passed to the fp.

Parameters

[in]	config	rtr_mgr_config
[in]	fp	Pointer to callback function with signature pfx_for_each_fp.
[in]	data	This parameter is forwarded to the callback function.

rtr_mgr_for_each_ipv6_record()

void rtr_mgr_for_each_ipv6_record	(	struct rtr_mgr_config *	config,
		pfx_for_each_fp	fp,
		void *	data
	)

#include <rtrlib/rtr_mgr.h>

Iterates over all IPv6 records in the pfx_table.

For every pfx_record the function fp is called. The pfx_record and the data pointer is passed to the fp.

Parameters

[in]	config	rtr_mgr_config
[in]	fp	Pointer to callback function with signature pfx_for_each_fp.
[in]	data	This parameter is forwarded to the callback function.

rtr_mgr_free()

void rtr_mgr_free

(

struct rtr_mgr_config *

config

)

#include <rtrlib/rtr_mgr.h>

Frees all resources that were allocated from the rtr_mgr.

rtr_mgr_stop must be called before, to shutdown all rtr_sockets.

Parameters

[in]

config

rtr_mgr_config.

rtr_mgr_get_first_group()

struct rtr_mgr_group * rtr_mgr_get_first_group

(

struct rtr_mgr_config *

config

)

#include <rtrlib/rtr_mgr.h>

Returns the first, thus active group.

Parameters

[in]

config

The rtr_mgr_config

Returns

rtr_mgr_group The head of the linked list.

rtr_mgr_get_spki()

int rtr_mgr_get_spki	(	struct rtr_mgr_config *	config,
		const uint32_t	asn,
		uint8_t *	ski,
		struct spki_record **	result,
		unsigned int *	result_count
	)

#include <rtrlib/rtr_mgr.h>

Returns all SPKI records which match the given ASN and SKI.

Parameters

[in]	config
[in]	asn	Autonomous system number of the Origin-AS
[in]	ski	the SKI to search for
[out]	result	a array of all matching spki_records
[out]	result_count	number of returned spki_records

Returns

SPKI_SUCCESS On success

SPKI_ERROR If an error occurred

rtr_mgr_init()

int rtr_mgr_init	(	struct rtr_mgr_config **	config_out,
		struct rtr_mgr_group	groups[],
		const unsigned int	groups_len,
		const rtr_mgr_status_fp	status_fp,
		void *	status_fp_data
	)

#include <rtrlib/rtr_mgr.h>

Initializes a rtr_mgr_config.

Parameters

[out]	config_out	The rtr_mgr_config that will be initialized by this function. On error, *config_out will be NULL!
[in]	groups	Linked list of rtr_mgr_group. Every RTR socket in an rtr_mgr_group must be assoziated with an initialized transport socket. A Transport socket is only allowed to be associated with one rtr socket. The preference values must be unique in the linked list. More than one rtr_mgr_group with the same preference value isn't allowed.
[in]	groups_len	Number of elements in the groups array. Must be >= 1.
[in]	refresh_interval	Interval in seconds between serial queries that are sent to the server. Must be >= 1 and <= 86400s (1d), recommended default is 3600s (1h).
[in]	expire_interval	Stored validation records will be deleted if cache was unable to refresh data for this period. The value should be twice the refresh_interval and must be >= 600s (10min) and <= 172800s (2d). The recommended default is 7200s (2h).
[in]	retry_interval	This parameter tells the router how long to wait (in seconds) before retrying a failed Serial Query or Reset Query. The value must be >= 1s and <= 7200s (2h). The recommended default is 600s (10min).
[in]	status_fp	Pointer to a function that is called if the connection status from one of the socket groups is changed.
[in]	status_fp_data	Pointer to a memory area that is passed to the status_fp function. Memory area can be freely used to pass user-defined data to the status_fp callback.

Returns

RTR_ERROR If an error occurred

RTR_INVALID_PARAM If refresh_interval or expire_interval is invalid.

RTR_SUCCESS On success.

rtr_mgr_remove_group()

int rtr_mgr_remove_group	(	struct rtr_mgr_config *	config,
		unsigned int	preference
	)

#include <rtrlib/rtr_mgr.h>

Removes an existing rtr_mgr_group from the linked list of config.

The group to be removed is identified by its preference value. Should the group to be removed be currently active, it will be shut down and the next best group will be spun up.

Parameters

config	A rtr_mgr_config struct that has been initialized previously with rtr_mgr_init
preference	The preference value of the group to be removed.

Returns

RTR_ERROR If no group with this preference value exists.

RTR_SUCCESS If group was successfully removed.

rtr_mgr_setup_sockets()

int rtr_mgr_setup_sockets	(	struct rtr_mgr_config *	config,
		struct rtr_mgr_group	groups[],
		const unsigned int	groups_len,
		const unsigned int	refresh_interval,
		const unsigned int	expire_interval,
		const unsigned int	retry_interval
	)

#include <rtrlib/rtr_mgr.h>

rtr_mgr_start()

int rtr_mgr_start

(

struct rtr_mgr_config *

config

)

#include <rtrlib/rtr_mgr.h>

Establishes rtr_socket connections.

Establishes the connection with the rtr_sockets of the group with the lowest preference value and handles errors as defined in the RPKI-RTR protocol.

Parameters

[in]

config

Pointer to an initialized rtr_mgr_config.

Returns

RTR_SUCCESS On success

RTR_ERROR On error

rtr_mgr_status_to_str()

const char * rtr_mgr_status_to_str

(

enum rtr_mgr_status

status

)

#include <rtrlib/rtr_mgr.h>

Converts a rtr_mgr_status to a String.

Parameters

[in]

status

state to convert to a string.

Returns

NULL If status isn't a valid rtr_mgr_status.

!=NULL The rtr_rtr_mgr_status as String.

rtr_mgr_stop()

void rtr_mgr_stop

(

struct rtr_mgr_config *

config

)

#include <rtrlib/rtr_mgr.h>

Terminates rtr_socket connections.

Terminates all rtr_socket connections defined in the config. All pfx_records received from these sockets will be purged.

Parameters

[in]

config

The rtr_mgr_config struct

rtr_mgr_validate()

int rtr_mgr_validate	(	struct rtr_mgr_config *	config,
		const uint32_t	asn,
		const struct lrtr_ip_addr *	prefix,
		const uint8_t	mask_len,
		enum pfxv_state *	result
	)

#include <rtrlib/rtr_mgr.h>

Validates the origin of a BGP-Route.

Parameters

[in]	config	The rtr_mgr_config
[in]	asn	Autonomous system number of the Origin-AS of the prefix
[in]	prefix	Announced network prefix
[in]	mask_len	Length of the network mask of the announced prefix
[out]	result	Outcome of the validation

Returns

PFX_SUCCESS On success.

PFX_ERROR If an error occurred.

Variable Documentation

aspa_table

struct aspa_table* rtr_mgr_config::aspa_table

groups

struct tommy_list_wrapper* rtr_mgr_config::groups

len

unsigned int rtr_mgr_config::len

mutex

pthread_rwlock_t rtr_mgr_config::mutex

pfx_table

struct pfx_table* rtr_mgr_config::pfx_table

preference

uint8_t rtr_mgr_group::preference

sockets

struct rtr_socket** rtr_mgr_group::sockets

sockets_len

unsigned int rtr_mgr_group::sockets_len

spki_table

struct spki_table* rtr_mgr_config::spki_table

status

enum rtr_mgr_status rtr_mgr_group::status

status_fp

rtr_mgr_status_fp rtr_mgr_config::status_fp

status_fp_data

void* rtr_mgr_config::status_fp_data