Greenbone Vulnerability Management Libraries 22.41.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.
int gvm_is_cidr6_block (const char *)
 Checks if a buffer points to an IPv6 CIDR-expressed block. "2620:0:2d0:200::7/120" is valid, "2620:0:2d0:200::7/129" is not.
int gvm_cidr6_get_block (const char *, unsigned int *)
 Gets the network block value from a CIDR-expressed block string. For "192.168.1.1/24" it is 24.
int gvm_cidr6_get_ip (const char *, struct in6_addr *)
 Gets the IPv4 value from a CIDR-expressed block. eg. For "192.168.1.10/24" it is "192.168.1.10".
int gvm_cidr6_block_ips (const char *str, struct in6_addr *first, struct in6_addr *last)
 Gets the first and last usable IPv4 addresses from a CIDR-expressed block. eg. "192.168.1.0/24 would give 192.168.1.1 as first and 192.168.1.254 as last. Thus, it skips the network and broadcast addresses.

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

int gvm_cidr6_block_ips ( const char * str,
struct in6_addr * first,
struct in6_addr * last )

Gets the first and last usable IPv4 addresses from a CIDR-expressed block. eg. "192.168.1.0/24 would give 192.168.1.1 as first and 192.168.1.254 as last. Thus, it skips the network and broadcast addresses.

Parameters
[in]strBuffer containing CIDR-expressed block.
[out]firstFirst IPv4 address in block.
[out]lastLast IPv4 address in block.
Returns
-1 if error, 0 else.

◆ gvm_cidr6_get_block()

int gvm_cidr6_get_block ( const char * str,
unsigned int * block )

Gets the network block value from a CIDR-expressed block string. For "192.168.1.1/24" it is 24.

Parameters
[in]strBuffer containing CIDR-expressed block.
[out]blockVariable to store block value.
Returns
-1 if error, 0 otherwise.

◆ gvm_cidr6_get_ip()

int gvm_cidr6_get_ip ( const char * str,
struct in6_addr * addr6 )

Gets the IPv4 value from a CIDR-expressed block. eg. For "192.168.1.10/24" it is "192.168.1.10".

Parameters
[in]strString containing CIDR-expressed block.
[out]addr6Variable to store the IPv4 address value.
Returns
-1 if error, 0 otherwise.

◆ 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 host 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_is_cidr6_block()

int gvm_is_cidr6_block ( const char * str)

Checks if a buffer points to an IPv6 CIDR-expressed block. "2620:0:2d0:200::7/120" is valid, "2620:0:2d0:200::7/129" is not.

Parameters
[in]strBuffer to check in.
Returns
1 if valid IPv6 CIDR-expressed block, 0 otherwise.

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