Header file dealing with the corsaro geolocation subsystem. More...

This graph shows which files directly or indirectly include this file:

Data Structures
struct	corsaro_geo_record
	Structure which contains a geolocation record. More...

struct	corsaro_geo_provider
	Structure which represents a geolocation provider. More...

struct	corsaro_geo_datastructure
	Structure which represents a geolocation datastructure. More...

Typedefs
typedef struct corsaro_geo_record	corsaro_geo_record_t
	Structure which contains a geolocation record. More...

typedef enum corsaro_geo_provider_default	corsaro_geo_provider_default_t
	Should this provider be set to be the default geolocation result provider. More...

typedef enum corsaro_geo_provider_id	corsaro_geo_provider_id_t
	A unique identifier for each geolocation provider that corsaro supports. More...

typedef struct corsaro_geo_provider	corsaro_geo_provider_t
	Structure which represents a geolocation provider. More...

typedef enum corsaro_geo_datastructure_id	corsaro_geo_datastructure_id_t
	A unique identifier for each geolocation datastructure that corsaro supports. More...

typedef struct corsaro_geo_datastructure	corsaro_geo_datastructure_t
	Structure which represents a geolocation datastructure. More...

Enumerations
enum	corsaro_geo_provider_default { CORSARO_GEO_PROVIDER_DEFAULT_NO = 0, CORSARO_GEO_PROVIDER_DEFAULT_YES = 1 }
	Should this provider be set to be the default geolocation result provider. More...

enum	corsaro_geo_provider_id { CORSARO_GEO_PROVIDER_MAXMIND = 1, CORSARO_GEO_PROVIDER_NETACQ_EDGE = 2, CORSARO_GEO_PROVIDER_PFX2AS = 3, CORSARO_GEO_PROVIDER_MAX = CORSARO_GEO_PROVIDER_PFX2AS }
	A unique identifier for each geolocation provider that corsaro supports. More...

enum	corsaro_geo_datastructure_id { CORSARO_GEO_DATASTRUCTURE_PATRICIA = 1, CORSARO_GEO_DATASTRUCTURE_MAX = CORSARO_GEO_DATASTRUCTURE_PATRICIA, CORSARO_GEO_DATASTRUCTURE_DEFAULT = CORSARO_GEO_DATASTRUCTURE_PATRICIA }
	A unique identifier for each geolocation datastructure that corsaro supports. More...

Functions
const char *	corsaro_geo_get_provider_name (corsaro_geo_provider_id_t id)
	Get the provider name for the given ID. More...

const char **	corsaro_geo_get_provider_names ()
	Get an array of provider names. More...

corsaro_geo_provider_t *	corsaro_geo_init_provider (corsaro_t *corsaro, corsaro_geo_provider_id_t provider_id, corsaro_geo_datastructure_id_t ds_id, corsaro_geo_provider_default_t set_default)
	Allocate a geolocation provider object in the packet state. More...

void	corsaro_geo_free_provider (corsaro_t corsaro, corsaro_geo_provider_t provider)
	Free the given geolocation provider object. More...

corsaro_geo_record_t *	corsaro_geo_init_record (corsaro_geo_provider_t *provider, uint32_t id)
	Allocate an empty geolocation record for the given id. More...

corsaro_geo_record_t *	corsaro_geo_get_record (corsaro_geo_provider_t *provider, uint32_t id)
	Get the geolocation record for the given id. More...

int	corsaro_geo_get_all_records (corsaro_geo_provider_t provider, corsaro_geo_record_t **records)
	Get an array of all the geolocation records registered with the given provider. More...

int	corsaro_geo_provider_associate_record (corsaro_t corsaro, corsaro_geo_provider_t provider, uint32_t addr, uint8_t mask, corsaro_geo_record_t *record)
	Register a new prefix to record mapping for the given provider. More...

corsaro_geo_record_t *	corsaro_geo_provider_lookup_record (corsaro_t corsaro, corsaro_geo_provider_t provider, uint32_t addr)
	Look up the given address in the provider's datastructure. More...

int	corsaro_geo_provider_clear (corsaro_geo_provider_t *provider)
	Remove all the existing records from the given geolocation provider. More...

void	corsaro_geo_provider_add_record (corsaro_geo_provider_t provider, corsaro_geo_record_t record)
	Add the given geolocation record to the head of the given geolocation provider object. More...

corsaro_geo_provider_t *	corsaro_geo_get_default (corsaro_t *corsaro)
	Retrieve the provider object for the default geolocation provider. More...

corsaro_geo_provider_t *	corsaro_geo_get_by_id (corsaro_t *corsaro, corsaro_geo_provider_id_t id)
	Retrieve the provider object for the given provider ID. More...

corsaro_geo_provider_t *	corsaro_geo_get_by_name (corsaro_t corsaro, const char name)
	Retrieve the provider object for the given provider name. More...

corsaro_geo_record_t *	corsaro_geo_next_record (corsaro_geo_provider_t provider, corsaro_geo_record_t record)
	Retrieve the next geolocation provider record in the list. More...

void	corsaro_geo_dump_record (corsaro_geo_record_t *record)
	Dump the given geolocation record to stdout (for debugging) More...

Provider-specific helper functions
These are class functions that can be used to retrieve meta-data about specific providers
const char *	corsaro_geo_get_maxmind_iso2 (int country_id)
	Get the ISO-3166-1 2 character country code for the given maxmind country id. More...

int	corsaro_geo_get_maxmind_iso2_list (const char ***countries)
	Get a list of all possible ISO-3166-1 2 character country codes that maxmind uses. More...

const char *	corsaro_geo_get_maxmind_iso3 (int country_id)
	Get the ISO-3166-1 3 character country code for the given maxmind country id. More...

int	corsaro_geo_get_maxmind_iso3_list (const char ***countries)
	Get a list of all possible ISO-3166-1 3 character country codes that maxmind uses. More...

const char *	corsaro_geo_get_maxmind_country_name (int country_id)
	Get the country name for the given maxmind country id. More...

int	corsaro_geo_get_maxmind_country_name_list (const char ***countries)
	Get a list of all possible country names that maxmind uses. More...

const char *	corsaro_geo_get_maxmind_continent (int country_id)
	Get the continent code for the given maxmind country id. More...

int	corsaro_geo_get_maxmind_country_continent_list (const char ***continents)
	Get a mapping of continent codes that maxmind uses. More...

Detailed Description

Header file dealing with the corsaro geolocation subsystem.

Author: Alistair King

Definition in file corsaro_geo.h.

Typedef Documentation

typedef enum corsaro_geo_datastructure_id corsaro_geo_datastructure_id_t

A unique identifier for each geolocation datastructure that corsaro supports.

typedef struct corsaro_geo_datastructure corsaro_geo_datastructure_t

Structure which represents a geolocation datastructure.

typedef enum corsaro_geo_provider_default corsaro_geo_provider_default_t

Should this provider be set to be the default geolocation result provider.

typedef enum corsaro_geo_provider_id corsaro_geo_provider_id_t

A unique identifier for each geolocation provider that corsaro supports.

Note: Remember to add the provider name to provider_names in corsaro_geo.c when you add a new provider ID above

Todo:: move the provider names into an array matched by their ID

typedef struct corsaro_geo_provider corsaro_geo_provider_t

Structure which represents a geolocation provider.

typedef struct corsaro_geo_record corsaro_geo_record_t

Structure which contains a geolocation record.

Enumeration Type Documentation

enum corsaro_geo_datastructure_id

A unique identifier for each geolocation datastructure that corsaro supports.

Enumerator

CORSARO_GEO_DATASTRUCTURE_PATRICIA

Patricia Trie.

CORSARO_GEO_DATASTRUCTURE_MAX

Highest numbered datastructure ID.

Todo:: add Huge Array implementation

CORSARO_GEO_DATASTRUCTURE_DEFAULT

Default Geolocation data-structure.

Definition at line 159 of file corsaro_geo.h.

enum corsaro_geo_provider_default

Should this provider be set to be the default geolocation result provider.

Enumerator
CORSARO_GEO_PROVIDER_DEFAULT_NO	This provider should not be the default geolocation result.
CORSARO_GEO_PROVIDER_DEFAULT_YES	This provider should be the default geolocation result.

Definition at line 104 of file corsaro_geo.h.

enum corsaro_geo_provider_id

A unique identifier for each geolocation provider that corsaro supports.

Note: Remember to add the provider name to provider_names in corsaro_geo.c when you add a new provider ID above

Todo:: move the provider names into an array matched by their ID

Enumerator
CORSARO_GEO_PROVIDER_MAXMIND	Geolocation data from Maxmind (Geo or GeoLite)
CORSARO_GEO_PROVIDER_NETACQ_EDGE	Geolocation data from Net Acuity Edge.
CORSARO_GEO_PROVIDER_PFX2AS	'Geolocation' data from CAIDA pfx2as
CORSARO_GEO_PROVIDER_MAX	Highest numbered geolocation provider ID.

Definition at line 120 of file corsaro_geo.h.

Function Documentation

void corsaro_geo_dump_record ( corsaro_geo_record_t * record )

Dump the given geolocation record to stdout (for debugging)

Parameters

record The record to dump

Definition at line 536 of file corsaro_geo.c.

References corsaro_geo_record::area_code, corsaro_geo_record::asn, corsaro_geo_record::asn_cnt, corsaro_geo_record::city, corsaro_geo_record::conn_speed, corsaro_geo_record::continent_code, corsaro_geo_record::country_code, corsaro_geo_record::id, corsaro_geo_record::latitude, corsaro_geo_record::longitude, corsaro_geo_record::metro_code, corsaro_geo_record::post_code, and corsaro_geo_record::region.

Referenced by process_generic().

void corsaro_geo_free_provider	(	corsaro_t *	corsaro,
		corsaro_geo_provider_t *	provider
	)

Free the given geolocation provider object.

Parameters

corsaro	The corsaro object to remove the provider from
provider	The geolocation provider object to free

Note: if this provider was the default, there will be no default provider set after this function returns

Definition at line 299 of file corsaro_geo.c.

References corsaro_geo_provider_clear(), corsaro_geo_provider::ds, corsaro_geo_datastructure::free, corsaro_packet::geo_provider_default, corsaro_packet::geo_providers, corsaro_geo_provider::id, and corsaro::packet.

Referenced by corsaro_geodb_close_output(), and corsaro_pfx2as_close_output().

int corsaro_geo_get_all_records	(	corsaro_geo_provider_t *	provider,
		corsaro_geo_record_t ***	records
	)

Get an array of all the geolocation records registered with the given provider.

Parameters

	provider	The geolocation provider to retrieve the records from
[out]	records	Returns an array of geolocation objects

Returns: the number of records in the array, -1 if an error occurs

Note: This function allocates and populates the array dynamically, so do not call repeatedly. Also, it is the caller's responsibility to free the array. DO NOT free the records contained in the array.

Definition at line 386 of file corsaro_geo.c.

corsaro_geo_provider_t* corsaro_geo_get_by_id	(	corsaro_t *	corsaro,
		corsaro_geo_provider_id_t	id
	)

Retrieve the provider object for the given provider ID.

Parameters

corsaro	The corsaro object to retrieve the provider object from
id	The geolocation provider ID to retrieve

Returns: the provider object for the given ID, NULL if there are no matches

Definition at line 495 of file corsaro_geo.c.

References CORSARO_GEO_PROVIDER_MAX, corsaro_packet::geo_providers, and corsaro::packet.

Referenced by corsaro_geo_get_by_name(), and process_generic().

corsaro_geo_provider_t* corsaro_geo_get_by_name	(	corsaro_t *	corsaro,
		const char *	name
	)

Retrieve the provider object for the given provider name.

Parameters

corsaro	The corsaro object to retrieve the provider object from
name	The geolocation provider name to retrieve

Returns: the provider object for the given name, NULL if there are no matches

Definition at line 503 of file corsaro_geo.c.

References corsaro_geo_get_by_id(), CORSARO_GEO_PROVIDER_MAX, and corsaro_geo_provider::name.

corsaro_geo_provider_t* corsaro_geo_get_default ( corsaro_t * corsaro )

Retrieve the provider object for the default geolocation provider.

Parameters

corsaro The corsaro object to retrieve the provider object from

Returns: the provider object for the default provider, NULL if there is no default provider

Definition at line 489 of file corsaro_geo.c.

References corsaro_packet::geo_provider_default, and corsaro::packet.

Referenced by process_generic().

const char* corsaro_geo_get_maxmind_continent ( int country_id )

Get the continent code for the given maxmind country id.

Parameters

country_id The maxmind country id to get the continent for

Returns: the 2 character name of the continent

Definition at line 764 of file corsaro_geo.c.

int corsaro_geo_get_maxmind_country_continent_list ( const char *** continents )

Get a mapping of continent codes that maxmind uses.

Parameters

[out] continents Returns a pointer to an array of continent codes

Returns: the number of countries in the array

Note: The returned array should be used to map from the country array to continents

Definition at line 770 of file corsaro_geo.c.

Referenced by corsaro_geodb_init_output().

const char* corsaro_geo_get_maxmind_country_name ( int country_id )

Get the country name for the given maxmind country id.

Parameters

country_id The maxmind country id to get the name for

Returns: the name of the country

Definition at line 752 of file corsaro_geo.c.

int corsaro_geo_get_maxmind_country_name_list ( const char *** countries )

Get a list of all possible country names that maxmind uses.

Parameters

[out] countries Returns a pointer to an array of country codes

Returns: the number of countries in the array

Definition at line 758 of file corsaro_geo.c.

const char* corsaro_geo_get_maxmind_iso2 ( int country_id )

Get the ISO-3166-1 2 character country code for the given maxmind country id.

Parameters

country_id The maxmind country id to get the code for

Returns: the 2 character country code

Definition at line 728 of file corsaro_geo.c.

int corsaro_geo_get_maxmind_iso2_list ( const char *** countries )

Get a list of all possible ISO-3166-1 2 character country codes that maxmind uses.

Parameters

[out] countries Returns a pointer to an array of country codes

Returns: the number of countries in the array

Definition at line 734 of file corsaro_geo.c.

Referenced by corsaro_geodb_init_output().

const char* corsaro_geo_get_maxmind_iso3 ( int country_id )

Get the ISO-3166-1 3 character country code for the given maxmind country id.

Parameters

country_id The maxmind country id to get the code for

Returns: the 3 character country code

Definition at line 740 of file corsaro_geo.c.

int corsaro_geo_get_maxmind_iso3_list ( const char *** countries )

Get a list of all possible ISO-3166-1 3 character country codes that maxmind uses.

Parameters

[out] countries Returns a pointer to an array of country codes

Returns: the number of countries in the array

Definition at line 746 of file corsaro_geo.c.

const char* corsaro_geo_get_provider_name ( corsaro_geo_provider_id_t id )

Get the provider name for the given ID.

Parameters

id	The provider ID to retrieve the name for

Returns: the name of the provider, NULL if an invalid ID was provided

Definition at line 203 of file corsaro_geo.c.

References ARR_CNT, and CORSARO_GEO_PROVIDER_MAX.

Referenced by corsaro_geo_init_provider().

const char** corsaro_geo_get_provider_names ( )

Get an array of provider names.

Returns: an array of provider names

Note: the number of elements in the array will be exactly CORSARO_GEO_PROVIDER_MAX+1. The [0] element will be NULL.

Definition at line 215 of file corsaro_geo.c.

References ARR_CNT, and CORSARO_GEO_PROVIDER_MAX.

corsaro_geo_record_t* corsaro_geo_get_record	(	corsaro_geo_provider_t *	provider,
		uint32_t	id
	)

Get the geolocation record for the given id.

Parameters

provider	The geolocation provider to retrieve the record from
id	The id of the record to retrieve

Returns: the corresponding geolocation record, NULL if an error occurred

Definition at line 372 of file corsaro_geo.c.

corsaro_geo_provider_t* corsaro_geo_init_provider	(	corsaro_t *	corsaro,
		corsaro_geo_provider_id_t	provider_id,
		corsaro_geo_datastructure_id_t	ds_id,
		corsaro_geo_provider_default_t	set_default
	)

Allocate a geolocation provider object in the packet state.

Parameters

corsaro	The corsaro object to alloc the provider for
provider_id	The unique ID of the geolocation provider
ds_id	The type of datastructure to use
set_default	Set this provider as the default

Returns: the provider object created, NULL if an error occurred

Plugins which implement a geolocation provider should call this function inside their init_output function to allocate a provider object

Note: Default provider status overrides the requests of previous plugins. Thus, the order in which users request the plugins to be run in can have an effect on plugins which make use of the default provider (e.g. corsaro_report).

Todo:: fix this to be more dynamic?

init the datastructure

Definition at line 222 of file corsaro_geo.c.

References CORSARO_GEO_DATASTRUCTURE_PATRICIA, corsaro_geo_get_provider_name(), CORSARO_GEO_PROVIDER_DEFAULT_YES, CORSARO_GEO_PROVIDER_MAX, corsaro_log(), corsaro_geo_provider::ds, corsaro_geo_datastructure::free, corsaro_packet::geo_provider_default, corsaro_packet::geo_providers, corsaro_geo_provider::id, corsaro_geo_datastructure::init, malloc_zero(), corsaro_geo_provider::name, corsaro::packet, and corsaro_geo_provider::records.

Referenced by corsaro_geodb_init_output(), and corsaro_pfx2as_init_output().

corsaro_geo_record_t* corsaro_geo_init_record	(	corsaro_geo_provider_t *	provider,
		uint32_t	id
	)

Allocate an empty geolocation record for the given id.

Parameters

provider	The geolocation provider to associate the record with
id	The id to use to inialize the record

Returns: the new geolocation record, NULL if an error occurred

Note: Most geolocation providers will not want to allocate a record on the fly for every packet, instead they will allocate all needed records at init time, and then use corsaro_geo_provider_add_record to add the appropriate record to the packet state structure. These records are stored in the provider, and free'd when corsaro_geo_free_provider is called. Also ALL char pointers in this structure will be free'd.

Definition at line 346 of file corsaro_geo.c.

References corsaro_geo_record::id, malloc_zero(), and record.

Referenced by parse_maxmind_location_row(), parse_netacq_edge_location_row(), and read_routeviews().

corsaro_geo_record_t* corsaro_geo_next_record	(	corsaro_geo_provider_t *	provider,
		corsaro_geo_record_t *	record
	)

Retrieve the next geolocation provider record in the list.

Parameters

provider	The geolocation provider to get the next record for
record	The current record

Returns: the record which follows the current record, NULL if the end of the record list has been reached. If record is NULL, the first record will be returned.

Definition at line 521 of file corsaro_geo.c.

References corsaro_geo_record::next, and corsaro_geo_provider::records.

Referenced by process_generic().

void corsaro_geo_provider_add_record	(	corsaro_geo_provider_t *	provider,
		corsaro_geo_record_t *	record
	)

Add the given geolocation record to the head of the given geolocation provider object.

Parameters

provider	The geolocation provider object to add the record to
record	The geolocation record to add

Note: This function can be called multiple times to add multiple records to the provider object. For example, there may be multiple ASes which a packet could belong to.

Warning: with great power comes great responsibility. If you add a record more than once, it will cause a loop in the record list. Be careful.

Definition at line 465 of file corsaro_geo.c.

References corsaro_geo_record::next, record, and corsaro_geo_provider::records.

Referenced by process_generic().

int corsaro_geo_provider_associate_record	(	corsaro_t *	corsaro,
		corsaro_geo_provider_t *	provider,
		uint32_t	addr,
		uint8_t	mask,
		corsaro_geo_record_t *	record
	)

Register a new prefix to record mapping for the given provider.

Parameters

corsaro	The corsaro object associated with the provider
provider	The provider to register the mapping with
addr	The network byte-ordered component of the prefix
mask	The mask component of the prefix
record	The record to associate with the prefix

Returns: 0 if the prefix is successfully associated with the prefix, -1 if an error occurs

Definition at line 425 of file corsaro_geo.c.

References corsaro_geo_datastructure::add_prefix, and corsaro_geo_provider::ds.

Referenced by read_routeviews().

int corsaro_geo_provider_clear ( corsaro_geo_provider_t * provider )

Remove all the existing records from the given geolocation provider.

Parameters

provider The geolocation provider to clear records for

Returns: the number of records cleared, -1 if an error occurs

Note: Typically this will be called by a geolocation provider for each packet, before it calls corsaro_geo_provider_add_record to add the appropriate record

Definition at line 447 of file corsaro_geo.c.

References corsaro_geo_record::next, and corsaro_geo_provider::records.

Referenced by corsaro_geo_free_provider(), and process_generic().

corsaro_geo_record_t* corsaro_geo_provider_lookup_record	(	corsaro_t *	corsaro,
		corsaro_geo_provider_t *	provider,
		uint32_t	addr
	)

Look up the given address in the provider's datastructure.

Parameters

corsaro	The corsaro object associated with the provider
provider	The provider to perform the lookup with
addr	The address to retrieve the record for (network byte ordering)

Returns: the record which best matches the address, NULL if no record is found

Definition at line 437 of file corsaro_geo.c.

References corsaro_geo_provider::ds, and corsaro_geo_datastructure::lookup_record.

Referenced by process_generic().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation