RTR connection manager

Data Structures
struct	rtr_mgr_group

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 }

Functions
int	rtr_mgr_add_group (struct rtr_mgr_config *config, const struct rtr_mgr_group *group)
bool	rtr_mgr_conf_in_sync (struct rtr_mgr_config *config)
int	rtr_mgr_for_each_group (struct rtr_mgr_config *config, void(*fp)(const struct rtr_mgr_group *group, void *data), void *data)
void	rtr_mgr_for_each_ipv4_record (struct rtr_mgr_config *config, pfx_for_each_fp fp, void *data)
void	rtr_mgr_for_each_ipv6_record (struct rtr_mgr_config *config, pfx_for_each_fp fp, void *data)
void	rtr_mgr_free (struct rtr_mgr_config *config)
struct rtr_mgr_group *	rtr_mgr_get_first_group (struct rtr_mgr_config *config)
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)
int	rtr_mgr_init (struct rtr_mgr_config **config_out, 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, const pfx_update_fp update_fp, const spki_update_fp spki_update_fp, const rtr_mgr_status_fp status_fp, void *status_fp_data)
int	rtr_mgr_remove_group (struct rtr_mgr_config *config, unsigned int preference)
int	rtr_mgr_start (struct rtr_mgr_config *config)
const char *	rtr_mgr_status_to_str (enum rtr_mgr_status status)
void	rtr_mgr_stop (struct rtr_mgr_config *config)
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)

Detailed Description

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.

Enumeration Type Documentation

enum rtr_mgr_status

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

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.

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.

bool rtr_mgr_conf_in_sync

(

struct rtr_mgr_config *

config

)

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.

Examples:

rtr_mgr.c.

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.

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.

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.

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.

void rtr_mgr_free

(

struct rtr_mgr_config *

config

)

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.

Examples:

rtr_mgr.c.

struct rtr_mgr_group* rtr_mgr_get_first_group

(

struct rtr_mgr_config *

config

)

Returns the first, thus active group.

Parameters

[in]

config

The rtr_mgr_config

Returns

rtr_mgr_group The head of the linked list.

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.

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

int rtr_mgr_init	(	struct rtr_mgr_config **	config_out,
		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,
		const pfx_update_fp	update_fp,
		const spki_update_fp	spki_update_fp,
		const rtr_mgr_status_fp	status_fp,
		void *	status_fp_data
	)

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]	update_fp	Pointer to pfx_update_fp callback, that is executed for every added and removed pfx_record.
[in]	spki_update_fp	Pointer to spki_update_fp callback, that is executed for every added and removed spki_record.
[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.

Examples:

rtr_mgr.c.

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.

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.

int rtr_mgr_start

(

struct rtr_mgr_config *

config

)

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

Examples:

rtr_mgr.c.

const char* rtr_mgr_status_to_str

(

enum rtr_mgr_status

status

)

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.

void rtr_mgr_stop

(

struct rtr_mgr_config *

config

)

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

Examples:

rtr_mgr.c.

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.

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.

Examples:

rtr_mgr.c.