Greenbone Vulnerability Management Libraries 22.10.0
hosts.h File Reference

Protos and data structures for Hosts collections and single hosts objects. More...

#include <glib.h>
#include <netinet/in.h>

Go to the source code of this file.

Data Structures

struct  gvm_host
 The structure for a single host object. More...
 
struct  gvm_vhost
 The structure for a single vhost object. More...
 
struct  gvm_hosts
 The structure for Hosts collection. More...
 

Macros

#define FEATURE_HOSTS_ALLOWED_ONLY   1
 Flag that indecates that this version includes the function gvm_hosts_allowed_only()
 
#define FEATURE_REVERSE_LOOKUP_EXCLUDED   1
 Flag that indecates that this version includes the functions gvm_reverse_lookup_only_excluded() and gvm_reverse_lookup_unify_excluded()
 

Typedefs

typedef struct gvm_host gvm_host_t
 
typedef struct gvm_vhost gvm_vhost_t
 
typedef struct gvm_hosts gvm_hosts_t
 

Enumerations

enum  host_type {
  HOST_TYPE_NAME = 0 , HOST_TYPE_IPV4 , HOST_TYPE_CIDR_BLOCK , HOST_TYPE_RANGE_SHORT ,
  HOST_TYPE_RANGE_LONG , HOST_TYPE_IPV6 , HOST_TYPE_CIDR6_BLOCK , HOST_TYPE_RANGE6_LONG ,
  HOST_TYPE_RANGE6_SHORT , HOST_TYPE_MAX
}
 

Functions

gvm_hosts_tgvm_hosts_new (const gchar *)
 Creates a new gvm_hosts_t structure and the associated hosts objects from the provided hosts_str.
 
gvm_hosts_tgvm_hosts_new_with_max (const gchar *, unsigned int)
 Creates a new gvm_hosts_t structure and the associated hosts objects from the provided hosts_str.
 
gvm_host_tgvm_hosts_next (gvm_hosts_t *)
 Gets the next gvm_host_t from a gvm_hosts_t structure. The state of iteration is kept internally within the gvm_hosts structure.
 
void gvm_hosts_move_current_host_to_end (gvm_hosts_t *)
 Move the current gvm_host_t from a gvm_hosts_t structure to the end of the hosts list.
 
void gvm_hosts_free (gvm_hosts_t *)
 Frees memory occupied by an gvm_hosts_t structure.
 
void gvm_hosts_shuffle (gvm_hosts_t *)
 Randomizes the order of the hosts objects in the collection. Not to be used while iterating over the single hosts as it resets the iterator.
 
void gvm_hosts_reverse (gvm_hosts_t *)
 Reverses the order of the hosts objects in the collection. Not to be used while iterating over the single hosts as it resets the iterator.
 
void gvm_hosts_add (gvm_hosts_t *, gvm_host_t *)
 Inserts a host object at the end of a hosts collection.
 
GSList * gvm_hosts_resolve (gvm_hosts_t *)
 Resolves host objects of type name in a hosts collection, replacing hostnames with IPv4 values. Not to be used while iterating over the single hosts as it resets the iterator.
 
int gvm_hosts_exclude (gvm_hosts_t *, const char *)
 Excludes a set of hosts provided as a string from a hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.
 
int gvm_vhosts_exclude (gvm_host_t *, const char *)
 Exclude a list of vhosts from a host's vhosts list.
 
int gvm_hosts_exclude_with_max (gvm_hosts_t *, const char *, unsigned int)
 Excludes a set of hosts provided as a string from a hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.
 
GSList * gvm_hosts_allowed_only (gvm_hosts_t *, const char *, const char *)
 Returns a list of hosts after a host authorization check.
 
char * gvm_host_reverse_lookup (gvm_host_t *)
 Checks for a host object reverse dns lookup existence.
 
int gvm_hosts_reverse_lookup_only (gvm_hosts_t *)
 Removes hosts that don't reverse-lookup from the hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.
 
int gvm_hosts_reverse_lookup_unify (gvm_hosts_t *)
 Removes hosts duplicates that reverse-lookup to the same value. Not to be used while iterating over the single hosts as it resets the iterator.
 
gvm_hosts_tgvm_hosts_reverse_lookup_only_excluded (gvm_hosts_t *)
 Removes hosts that don't reverse-lookup from the hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.
 
gvm_hosts_tgvm_hosts_reverse_lookup_unify_excluded (gvm_hosts_t *)
 Removes hosts duplicates that reverse-lookup to the same value. Not to be used while iterating over the single hosts as it resets the iterator.
 
unsigned int gvm_hosts_count (const gvm_hosts_t *)
 Gets the count of single hosts objects in a hosts collection.
 
unsigned int gvm_hosts_removed (const gvm_hosts_t *)
 Gets the count of single values in hosts string that were removed (duplicates / excluded.)
 
unsigned int gvm_hosts_duplicated (const gvm_hosts_t *)
 Gets the count of single values in hosts string that were duplicated and therefore removed from the list.
 
gvm_host_tgvm_host_from_str (const gchar *hosts_str)
 Creates a new gvm_host_t from a host string.
 
int gvm_host_in_hosts (const gvm_host_t *, const struct in6_addr *, const gvm_hosts_t *)
 Returns whether a host has an equal host in a hosts collection. eg. 192.168.10.1 has an equal in list created from "192.168.10.1-5, 192.168.10.10-20" string while 192.168.10.7 doesn't.
 
gvm_host_tgvm_host_find_in_hosts (const gvm_host_t *, const struct in6_addr *, const gvm_hosts_t *)
 Find the gvm_host_t from a gvm_hosts_t structure.
 
gchar * gvm_host_type_str (const gvm_host_t *)
 Gets a host's type in printable format.
 
enum host_type gvm_host_type (const gvm_host_t *)
 Gets a host object's type.
 
gchar * gvm_host_value_str (const gvm_host_t *)
 Gets a host's value in printable format.
 
int gvm_host_resolve (const gvm_host_t *, void *, int)
 Resolves a host object's name to an IPv4 or IPv6 address. Host object should be of type HOST_TYPE_NAME.
 
int gvm_host_get_addr6 (const gvm_host_t *, struct in6_addr *)
 Gives a host object's value as an IPv6 address. If the host type is hostname, it resolves the IPv4 address then gives an IPv4-mapped IPv6 address (eg. ::ffff:192.168.1.1 .) If the host type is IPv4, it gives an IPv4-mapped IPv6 address. If the host's type is IPv6, it gives the value directly.
 
void gvm_host_add_reverse_lookup (gvm_host_t *)
 Add a host's reverse-lookup name to the vhosts list.
 
void gvm_host_free (gpointer)
 Frees the memory occupied by an gvm_host_t object.
 
gpointer gvm_duplicate_vhost (gconstpointer, gpointer)
 Creates a deep copy of a gvm_vhost_t object.
 
gvm_host_tgvm_duplicate_host (gvm_host_t *)
 Creates a deep copy of a host. gvm_host_free has to be called on it.
 
gvm_vhost_tgvm_vhost_new (char *, char *)
 Creates a new gvm_vhost_t object.
 
int gvm_get_host_type (const gchar *)
 Determines the host type in a buffer.
 

Detailed Description

Protos and data structures for Hosts collections and single hosts objects.

This file contains the protos for hosts.c

Macro Definition Documentation

◆ FEATURE_HOSTS_ALLOWED_ONLY

#define FEATURE_HOSTS_ALLOWED_ONLY   1

Flag that indecates that this version includes the function gvm_hosts_allowed_only()

◆ FEATURE_REVERSE_LOOKUP_EXCLUDED

#define FEATURE_REVERSE_LOOKUP_EXCLUDED   1

Flag that indecates that this version includes the functions gvm_reverse_lookup_only_excluded() and gvm_reverse_lookup_unify_excluded()

Typedef Documentation

◆ gvm_host_t

typedef struct gvm_host gvm_host_t

◆ gvm_hosts_t

typedef struct gvm_hosts gvm_hosts_t

◆ gvm_vhost_t

typedef struct gvm_vhost gvm_vhost_t

Enumeration Type Documentation

◆ host_type

enum host_type
Enumerator
HOST_TYPE_NAME 
HOST_TYPE_IPV4 
HOST_TYPE_CIDR_BLOCK 
HOST_TYPE_RANGE_SHORT 
HOST_TYPE_RANGE_LONG 
HOST_TYPE_IPV6 
HOST_TYPE_CIDR6_BLOCK 
HOST_TYPE_RANGE6_LONG 
HOST_TYPE_RANGE6_SHORT 
HOST_TYPE_MAX 

Function Documentation

◆ gvm_duplicate_host()

gvm_host_t * gvm_duplicate_host ( gvm_host_t * host)

Creates a deep copy of a host. gvm_host_free has to be called on it.

Parameters
hostsource host
Returns
gvm_host_t* copy of host

◆ gvm_duplicate_vhost()

gpointer gvm_duplicate_vhost ( gconstpointer vhost,
gpointer data )

Creates a deep copy of a gvm_vhost_t object.

Parameters
vhostsource vhost
datadummy for g_slist_copy_deep
Returns
gpointer copy of vhost

◆ gvm_get_host_type()

int gvm_get_host_type ( const gchar * str_stripped)

Determines the host type in a buffer.

Parameters
[in]str_strippedBuffer that contains host definition, could a be hostname, single IPv4 or IPv6, CIDR-expressed block etc,.
Returns
Host_TYPE_*, -1 if error.

◆ gvm_host_add_reverse_lookup()

void gvm_host_add_reverse_lookup ( gvm_host_t * host)

Add a host's reverse-lookup name to the vhosts list.

Parameters
[in]hostThe host to which we add the vhost.

◆ gvm_host_find_in_hosts()

gvm_host_t * gvm_host_find_in_hosts ( const gvm_host_t * host,
const struct in6_addr * addr,
const gvm_hosts_t * hosts )

Find the gvm_host_t from a gvm_hosts_t structure.

Parameters
[in]hostThe host object.
[in]addrOptional pointer to ip address. Could be used so that host isn't resolved multiple times when type is HOST_TYPE_NAME.
[in]hostsHosts collection.
Returns
Pointer to host if found. NULL if error or host not found

◆ gvm_host_free()

void gvm_host_free ( gpointer host)

Frees the memory occupied by an gvm_host_t object.

Parameters
[in]hostHost to free.

◆ gvm_host_from_str()

gvm_host_t * gvm_host_from_str ( const gchar * host_str)

Creates a new gvm_host_t from a host string.

Parameters
[in]host_strThe host string can consist of a hostname, IPv4 address or IPv6 address.
Returns
NULL if error. Otherwise, a single host structure that should be put into a gvm_hosts_t structure for freeing with gvm_hosts_free or freed directly via gvm_host_free.

◆ gvm_host_get_addr6()

int gvm_host_get_addr6 ( const gvm_host_t * host,
struct in6_addr * ip6 )

Gives a host object's value as an IPv6 address. If the host type is hostname, it resolves the IPv4 address then gives an IPv4-mapped IPv6 address (eg. ::ffff:192.168.1.1 .) If the host type is IPv4, it gives an IPv4-mapped IPv6 address. If the host's type is IPv6, it gives the value directly.

Parameters
[in]hostThe host object whose value to get as IPv6.
[out]ip6Buffer to store the IPv6 address.
Returns
-1 if error, 0 otherwise.

◆ gvm_host_in_hosts()

int gvm_host_in_hosts ( const gvm_host_t * host,
const struct in6_addr * addr,
const gvm_hosts_t * hosts )

Returns whether a host has an equal host in a hosts collection. eg. 192.168.10.1 has an equal in list created from "192.168.10.1-5, 192.168.10.10-20" string while 192.168.10.7 doesn't.

Parameters
[in]hostThe host object.
[in]addrOptional pointer to ip address. Could be used so that host isn't resolved multiple times when type is HOST_TYPE_NAME.
[in]hostsHosts collection.
Returns
1 if host has equal in hosts, 0 otherwise.

◆ gvm_host_resolve()

int gvm_host_resolve ( const gvm_host_t * host,
void * dst,
int family )

Resolves a host object's name to an IPv4 or IPv6 address. Host object should be of type HOST_TYPE_NAME.

Parameters
[in]hostThe host object whose name to resolve.
[out]dstBuffer to store resolved address. Size must be at least 4 bytes for AF_INET and 16 bytes for AF_INET6.
[in]familyEither AF_INET or AF_INET6.
Returns
-1 if error, 0 otherwise.

◆ gvm_host_reverse_lookup()

char * gvm_host_reverse_lookup ( gvm_host_t * host)

Checks for a host object reverse dns lookup existence.

Parameters
[in]hostThe host to reverse-lookup.
Returns
Result of look-up, NULL otherwise.

◆ gvm_host_type()

enum host_type gvm_host_type ( const gvm_host_t * host)

Gets a host object's type.

Parameters
[in]hostThe host object.
Returns
Host type.

◆ gvm_host_type_str()

gchar * gvm_host_type_str ( const gvm_host_t * host)

Gets a host's type in printable format.

Parameters
[in]hostThe host object.
Returns
String representing host type. Statically allocated, thus, not to be freed.

◆ gvm_host_value_str()

gchar * gvm_host_value_str ( const gvm_host_t * host)

Gets a host's value in printable format.

Parameters
[in]hostThe host object.
Returns
String representing host value. To be freed with g_free().

◆ gvm_hosts_add()

void gvm_hosts_add ( gvm_hosts_t * hosts,
gvm_host_t * host )

Inserts a host object at the end of a hosts collection.

Parameters
[in]hostsHosts in which to insert the host.
[in]hostHost to insert.

◆ gvm_hosts_allowed_only()

GSList * gvm_hosts_allowed_only ( gvm_hosts_t * hosts,
const char * deny_hosts_str,
const char * allow_hosts_str )

Returns a list of hosts after a host authorization check.

Parameters
[in,out]hostsThe hosts collection from which to exclude.
[in]deny_hosts_strString of denied hosts. This hosts will be removed from the hosts list
[in]allow_hosts_strString of allow hosts. This hosts will be kept in the hosts list
Returns
List of non-authorized hosts if any, otherwise Null. The returned list must be free()'d by the caller functions.

Uses a hash table in order to exclude hosts in O(N+M) time.

◆ gvm_hosts_count()

unsigned int gvm_hosts_count ( const gvm_hosts_t * hosts)

Gets the count of single hosts objects in a hosts collection.

Parameters
[in]hostsThe hosts collection to count hosts of.
Returns
The number of single hosts.

◆ gvm_hosts_duplicated()

unsigned int gvm_hosts_duplicated ( const gvm_hosts_t * hosts)

Gets the count of single values in hosts string that were duplicated and therefore removed from the list.

Parameters
[in]hostsThe hosts collection.
Returns
The number of duplicated values.

◆ gvm_hosts_exclude()

int gvm_hosts_exclude ( gvm_hosts_t * hosts,
const char * excluded_str )

Excludes a set of hosts provided as a string from a hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection from which to exclude.
[in]excluded_strString of hosts to exclude.
Returns
Number of excluded hosts, -1 if error.

◆ gvm_hosts_exclude_with_max()

int gvm_hosts_exclude_with_max ( gvm_hosts_t * hosts,
const char * excluded_str,
unsigned int max_hosts )

Excludes a set of hosts provided as a string from a hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in,out]hostsThe hosts collection from which to exclude.
[in]excluded_strString of hosts to exclude.
[in]max_hostsMax number of hosts in hosts_str. 0 means unlimited.
Returns
Number of excluded hosts, -1 if error.

Uses a hash table in order to exclude hosts in O(N+M) time.

◆ gvm_hosts_free()

void gvm_hosts_free ( gvm_hosts_t * hosts)

Frees memory occupied by an gvm_hosts_t structure.

Parameters
[in]hostsThe hosts collection to free.

◆ gvm_hosts_move_current_host_to_end()

void gvm_hosts_move_current_host_to_end ( gvm_hosts_t * hosts)

Move the current gvm_host_t from a gvm_hosts_t structure to the end of the hosts list.

Parameters
[in,out]hostsgvm_hosts_t structure which hosts must be rearange. The hosts->current index points to the last used hosts and gvm_hosts_next() must be called to get the next host in the list.

◆ gvm_hosts_new()

gvm_hosts_t * gvm_hosts_new ( const gchar * hosts_str)

Creates a new gvm_hosts_t structure and the associated hosts objects from the provided hosts_str.

Parameters
[in]hosts_strThe hosts string. A copy will be created of this within the returned struct.
Returns
NULL if error, otherwise, a hosts structure that should be released using gvm_hosts_free.

◆ gvm_hosts_new_with_max()

gvm_hosts_t * gvm_hosts_new_with_max ( const gchar * hosts_str,
unsigned int max_hosts )

Creates a new gvm_hosts_t structure and the associated hosts objects from the provided hosts_str.

Parameters
[in]hosts_strThe hosts string. A copy will be created of this within the returned struct.
[in]max_hostsMax number of hosts in hosts_str. 0 means unlimited.
Returns
NULL if error or hosts_str contains more than max hosts. Otherwise, a hosts structure that should be released using gvm_hosts_free.

◆ gvm_hosts_next()

gvm_host_t * gvm_hosts_next ( gvm_hosts_t * hosts)

Gets the next gvm_host_t from a gvm_hosts_t structure. The state of iteration is kept internally within the gvm_hosts structure.

Parameters
[in]hostsgvm_hosts_t structure to get next host from.
Returns
Pointer to host. NULL if error or end of hosts.

◆ gvm_hosts_removed()

unsigned int gvm_hosts_removed ( const gvm_hosts_t * hosts)

Gets the count of single values in hosts string that were removed (duplicates / excluded.)

Parameters
[in]hostsThe hosts collection.
Returns
The number of removed values.

◆ gvm_hosts_resolve()

GSList * gvm_hosts_resolve ( gvm_hosts_t * hosts)

Resolves host objects of type name in a hosts collection, replacing hostnames with IPv4 values. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection from which to exclude.
Returns
List of unresolved hostnames.

◆ gvm_hosts_reverse()

void gvm_hosts_reverse ( gvm_hosts_t * hosts)

Reverses the order of the hosts objects in the collection. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection to reverse.

◆ gvm_hosts_reverse_lookup_only()

int gvm_hosts_reverse_lookup_only ( gvm_hosts_t * hosts)

Removes hosts that don't reverse-lookup from the hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection to filter.
Returns
Number of hosts removed, -1 if error.

◆ gvm_hosts_reverse_lookup_only_excluded()

gvm_hosts_t * gvm_hosts_reverse_lookup_only_excluded ( gvm_hosts_t * hosts)

Removes hosts that don't reverse-lookup from the hosts collection. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection to filter.
Returns
list of hosts removed, Null on error.

◆ gvm_hosts_reverse_lookup_unify()

int gvm_hosts_reverse_lookup_unify ( gvm_hosts_t * hosts)

Removes hosts duplicates that reverse-lookup to the same value. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection to filter.
Returns
Number of hosts removed, -1 if error.

◆ gvm_hosts_reverse_lookup_unify_excluded()

gvm_hosts_t * gvm_hosts_reverse_lookup_unify_excluded ( gvm_hosts_t * hosts)

Removes hosts duplicates that reverse-lookup to the same value. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection to filter.
Returns
List of hosts removed, Null if error.

Uses a hash table in order to unify the hosts list in O(N) time.

◆ gvm_hosts_shuffle()

void gvm_hosts_shuffle ( gvm_hosts_t * hosts)

Randomizes the order of the hosts objects in the collection. Not to be used while iterating over the single hosts as it resets the iterator.

Parameters
[in]hostsThe hosts collection to shuffle.

◆ gvm_vhost_new()

gvm_vhost_t * gvm_vhost_new ( char * value,
char * source )

Creates a new gvm_vhost_t object.

Parameters
[in]valueVhost value.
[in]sourceSource of hostname.
Returns
Pointer to new vhost object.

◆ gvm_vhosts_exclude()

int gvm_vhosts_exclude ( gvm_host_t * host,
const char * excluded_str )

Exclude a list of vhosts from a host's vhosts list.

Parameters
[in]hostThe host whose vhosts are to be excluded from.
[in]excluded_strString of hosts to exclude.
Returns
Number of excluded vhosts.