Greenbone Vulnerability Management Libraries 22.18.1
gmp.c File Reference

API for Greenbone Management Protocol communication. More...

#include "gmp.h"
#include "../util/serverutils.h"
#include <errno.h>
#include <stdlib.h>
#include <strings.h>

Macros

#define G_LOG_DOMAIN   "libgvm gmp"
 GLib log domain.
 
#define GMP_FMT_BOOL_ATTRIB(var, attrib)
 
#define GMP_FMT_STRING_ATTRIB(var, attrib)
 

Functions

const char * gmp_task_status (entity_t response)
 Get the task status from a GMP GET_TASKS response.
 
static int gmp_check_response (gnutls_session_t *session, entity_t *entity)
 Read response and convert status of response to a return value.
 
static int check_response_c (gvm_connection_t *connection, int convert_99)
 Read response and convert status of response to a return value.
 
static int gmp_check_response_c (gvm_connection_t *connection)
 Read response and convert status of response to a return value.
 
int gmp_ping (gnutls_session_t *session, int timeout)
 "Ping" the manager.
 
int gmp_ping_c (gvm_connection_t *connection, int timeout, gchar **version)
 "Ping" the manager.
 
int gmp_authenticate (gnutls_session_t *session, const char *username, const char *password)
 Authenticate with the manager.
 
int gmp_authenticate_info_ext (gnutls_session_t *session, gmp_authenticate_info_opts_t opts)
 Authenticate with the manager.
 
int gmp_authenticate_info_ext_c (gvm_connection_t *connection, gmp_authenticate_info_opts_t opts)
 Authenticate with the manager.
 
int gmp_create_task_ext (gnutls_session_t *session, gmp_create_task_opts_t opts, gchar **id)
 Create a task.
 
int gmp_create_task (gnutls_session_t *session, const char *name, const char *config, const char *target, const char *comment, gchar **id)
 Create a task given a config and target.
 
int gmp_start_task_report (gnutls_session_t *session, const char *task_id, char **report_id)
 Start a task and read the manager response.
 
int gmp_start_task_report_c (gvm_connection_t *connection, const char *task_id, char **report_id)
 Start a task and read the manager response.
 
int gmp_start_task_ext_c (gvm_connection_t *connection, gmp_start_task_opts_t opts)
 Start a task and read the manager response.
 
int gmp_read_create_response (gnutls_session_t *session, gchar **uuid)
 Read response status and resource UUID.
 
int gmp_stop_task (gnutls_session_t *session, const char *id)
 Stop a task and read the manager response.
 
int gmp_stop_task_c (gvm_connection_t *connection, const char *id)
 Stop a task and read the manager response.
 
int gmp_resume_task_report (gnutls_session_t *session, const char *task_id, char **report_id)
 Resume a task and read the manager response.
 
int gmp_resume_task_report_c (gvm_connection_t *connection, const char *task_id, char **report_id)
 Resume a task and read the manager response.
 
int gmp_delete_task_ext (gnutls_session_t *session, const char *id, gmp_delete_opts_t opts)
 Delete a task and read the manager response.
 
int gmp_get_tasks (gnutls_session_t *session, const char *id, int details, int include_rcfile, entity_t *status)
 Get the status of a task.
 
int gmp_get_task_ext (gnutls_session_t *session, gmp_get_task_opts_t opts, entity_t *response)
 Get a task (generic version).
 
int gmp_get_tasks_ext (gnutls_session_t *session, gmp_get_tasks_opts_t opts, entity_t *response)
 Get all tasks (generic version).
 
int gmp_modify_task_file (gnutls_session_t *session, const char *id, const char *name, const void *content, gsize content_len)
 Modify a file on a task.
 
int gmp_delete_task (gnutls_session_t *session, const char *id)
 Delete a task and read the manager response.
 
int gmp_get_targets (gnutls_session_t *session, const char *id, int tasks, int include_rcfile, entity_t *target)
 Get a target.
 
int gmp_get_report_ext (gnutls_session_t *session, gmp_get_report_opts_t opts, entity_t *response)
 Get a report (generic version).
 
int gmp_delete_port_list_ext (gnutls_session_t *session, const char *id, gmp_delete_opts_t opts)
 Delete a port list.
 
int gmp_delete_report (gnutls_session_t *session, const char *id)
 Remove a report.
 
int gmp_create_target_ext (gnutls_session_t *session, gmp_create_target_opts_t opts, gchar **id)
 Create a target.
 
int gmp_delete_target_ext (gnutls_session_t *session, const char *id, gmp_delete_opts_t opts)
 Delete a target.
 
int gmp_delete_config_ext (gnutls_session_t *session, const char *id, gmp_delete_opts_t opts)
 Delete a config.
 
int gmp_create_lsc_credential (gnutls_session_t *session, const char *name, const char *login, const char *password, const char *comment, gchar **uuid)
 Create an LSC Credential.
 
int gmp_create_lsc_credential_key (gnutls_session_t *session, const char *name, const char *login, const char *passphrase, const char *private_key, const char *comment, gchar **uuid)
 Create an LSC Credential with a key.
 
int gmp_create_lsc_credential_ext (gnutls_session_t *session, gmp_create_lsc_credential_opts_t opts, gchar **id)
 Create an LSC credential.
 
int gmp_delete_lsc_credential_ext (gnutls_session_t *session, const char *id, gmp_delete_opts_t opts)
 Delete a LSC credential.
 
int gmp_get_system_reports (gnutls_session_t *session, const char *name, int brief, entity_t *reports)
 Get system reports.
 
int gmp_get_system_reports_ext (gnutls_session_t *session, gmp_get_system_reports_opts_t opts, entity_t *reports)
 Get system reports.
 

Detailed Description

API for Greenbone Management Protocol communication.

This provides higher level, GMP-aware, facilities for working with with the Greenbone Vulnerability Manager.

There are examples of using this interface in the gvm tests.

Macro Definition Documentation

◆ G_LOG_DOMAIN

#define G_LOG_DOMAIN   "libgvm gmp"

GLib log domain.

◆ GMP_FMT_BOOL_ATTRIB

#define GMP_FMT_BOOL_ATTRIB ( var,
attrib )
Value:
(var.attrib == 0 ? " " #attrib "=\"0\"" : " " #attrib "=\"1\"")

◆ GMP_FMT_STRING_ATTRIB

#define GMP_FMT_STRING_ATTRIB ( var,
attrib )
Value:
(var.attrib ? " " #attrib "= \"" : ""), (var.attrib ? var.attrib : ""), \
(var.attrib ? "\"" : "")

Function Documentation

◆ check_response_c()

static int check_response_c ( gvm_connection_t * connection,
int convert_99 )
static

Read response and convert status of response to a return value.

Parameters
[in]connectionConnection.
[in]convert_99If true, return will be 99 if response was 400 with status_text "Permission Denied".
Returns
0 on success, 99 if convert_99 and permission denied, -1 or GMP response code on error.

◆ gmp_authenticate()

int gmp_authenticate ( gnutls_session_t * session,
const char * username,
const char * password )

Authenticate with the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[in]usernameUsername.
[in]passwordPassword.
Returns
0 on success, 1 if manager closed connection, 2 if auth failed, -1 on error.

◆ gmp_authenticate_info_ext()

int gmp_authenticate_info_ext ( gnutls_session_t * session,
gmp_authenticate_info_opts_t opts )

Authenticate with the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[in,out]optsIn: Struct containing the options to apply. Out: Additional account information if authentication was successful.
Returns
0 on success, 1 if manager closed connection, 2 if auth failed, 3 on timeout, -1 on error.

◆ gmp_authenticate_info_ext_c()

int gmp_authenticate_info_ext_c ( gvm_connection_t * connection,
gmp_authenticate_info_opts_t opts )

Authenticate with the manager.

Parameters
[in]connectionConnection
[in]optsStruct containing the options to apply.
Returns
0 on success, 1 if manager closed connection, 2 if auth failed, 3 on timeout, -1 on error.

◆ gmp_check_response()

static int gmp_check_response ( gnutls_session_t * session,
entity_t * entity )
static

Read response and convert status of response to a return value.

Parameters
[in]sessionPointer to GNUTLS session.
[in]entityEntity containing response.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_check_response_c()

static int gmp_check_response_c ( gvm_connection_t * connection)
static

Read response and convert status of response to a return value.

Parameters
[in]connectionConnection.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_create_lsc_credential()

int gmp_create_lsc_credential ( gnutls_session_t * session,
const char * name,
const char * login,
const char * password,
const char * comment,
gchar ** uuid )

Create an LSC Credential.

Parameters
[in]sessionPointer to GNUTLS session.
[in]nameName of LSC Credential.
[in]loginLogin associated with name.
[in]passwordPassword, or NULL for autogenerated credentials.
[in]commentLSC Credential comment.
[out]uuidEither NULL or address for UUID of created credential.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_create_lsc_credential_ext()

int gmp_create_lsc_credential_ext ( gnutls_session_t * session,
gmp_create_lsc_credential_opts_t opts,
gchar ** id )

Create an LSC credential.

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]idPointer for newly allocated ID of new LSC credential, or NULL. Only set on successful return.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_create_lsc_credential_key()

int gmp_create_lsc_credential_key ( gnutls_session_t * session,
const char * name,
const char * login,
const char * passphrase,
const char * private_key,
const char * comment,
gchar ** uuid )

Create an LSC Credential with a key.

Parameters
[in]sessionPointer to GNUTLS session.
[in]nameName of LSC Credential.
[in]loginLogin associated with name.
[in]passphrasePassphrase for private key.
[in]private_keyPrivate key.
[in]commentLSC Credential comment.
[out]uuidEither NULL or address for UUID of created credential.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_create_target_ext()

int gmp_create_target_ext ( gnutls_session_t * session,
gmp_create_target_opts_t opts,
gchar ** id )

Create a target.

FIXME: Using the according opts it should be possible to generate any type of create_target request defined by the spec.

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]idPointer for newly allocated ID of new target, or NULL. Only set on successful return.
Returns
0 on success (GMP 201), -2 on connection error, GMP response code on GMP error, -1 other error.

◆ gmp_create_task()

int gmp_create_task ( gnutls_session_t * session,
const char * name,
const char * config,
const char * target,
const char * comment,
gchar ** id )

Create a task given a config and target.

Parameters
[in]sessionPointer to GNUTLS session.
[in]nameTask name.
[in]configTask config name.
[in]targetTask target name.
[in]commentTask comment.
[out]idPointer for newly allocated ID of new task. Only set on successful return.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_create_task_ext()

int gmp_create_task_ext ( gnutls_session_t * session,
gmp_create_task_opts_t opts,
gchar ** id )

Create a task.

FIXME: Using the according opts it should be possible to generate any type of create_task request defined by the spec.

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]idPointer for newly allocated ID of new task, or NULL. Only set on successful return.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_delete_config_ext()

int gmp_delete_config_ext ( gnutls_session_t * session,
const char * id,
gmp_delete_opts_t opts )

Delete a config.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idUUID of config.
[in]optsStruct containing the options to apply.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_delete_lsc_credential_ext()

int gmp_delete_lsc_credential_ext ( gnutls_session_t * session,
const char * id,
gmp_delete_opts_t opts )

Delete a LSC credential.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idUUID of LSC credential.
[in]optsStruct containing the options to apply.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_delete_port_list_ext()

int gmp_delete_port_list_ext ( gnutls_session_t * session,
const char * id,
gmp_delete_opts_t opts )

Delete a port list.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idUUID of port list.
[in]optsStruct containing the options to apply.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_delete_report()

int gmp_delete_report ( gnutls_session_t * session,
const char * id )

Remove a report.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of report.
Returns
0 on success, GMP response code on failure, -1 on error.

◆ gmp_delete_target_ext()

int gmp_delete_target_ext ( gnutls_session_t * session,
const char * id,
gmp_delete_opts_t opts )

Delete a target.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idUUID of target.
[in]optsStruct containing the options to apply.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_delete_task()

int gmp_delete_task ( gnutls_session_t * session,
const char * id )

Delete a task and read the manager response.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns
0 on success, GMP response code on failure, -1 on error.

◆ gmp_delete_task_ext()

int gmp_delete_task_ext ( gnutls_session_t * session,
const char * id,
gmp_delete_opts_t opts )

Delete a task and read the manager response.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of task.
[in]optsStruct containing the options to apply.
Returns
0 on success, GMP response code on failure, -1 on error.

◆ gmp_get_report_ext()

int gmp_get_report_ext ( gnutls_session_t * session,
gmp_get_report_opts_t opts,
entity_t * response )

Get a report (generic version).

FIXME: Using the according opts it should be possible to generate any type of get_reports request defined by the spec.

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]responseReport. On success contains GET_REPORT response.
Returns
0 on success, 2 on timeout, -1 or GMP response code on error.

◆ gmp_get_system_reports()

int gmp_get_system_reports ( gnutls_session_t * session,
const char * name,
int brief,
entity_t * reports )

Get system reports.

Parameters
[in]sessionPointer to GNUTLS session.
[in]nameName of system report. NULL for all.
[in]briefWhether to request brief response.
[out]reportsReports return. On success contains GET_SYSTEM_REPORTS response.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_get_system_reports_ext()

int gmp_get_system_reports_ext ( gnutls_session_t * session,
gmp_get_system_reports_opts_t opts,
entity_t * reports )

Get system reports.

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]reportsReports return. On success contains GET_SYSTEM_REPORTS response.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_get_targets()

int gmp_get_targets ( gnutls_session_t * session,
const char * id,
int tasks,
int include_rcfile,
entity_t * target )

Get a target.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of target or NULL for all targets.
[in]tasksWhether to include tasks that use the target.
[in]include_rcfileNot used.
[out]targetTarget return. On success contains GET_TARGETS response.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_get_task_ext()

int gmp_get_task_ext ( gnutls_session_t * session,
gmp_get_task_opts_t opts,
entity_t * response )

Get a task (generic version).

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]responseTask. On success contains GET_TASKS response.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_get_tasks()

int gmp_get_tasks ( gnutls_session_t * session,
const char * id,
int details,
int include_rcfile,
entity_t * status )

Get the status of a task.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of task or NULL for all tasks.
[in]detailsWhether to request task details.
[in]include_rcfileIgnored. Removed since GMP 6.0.
[out]statusStatus return. On success contains GET_TASKS response.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_get_tasks_ext()

int gmp_get_tasks_ext ( gnutls_session_t * session,
gmp_get_tasks_opts_t opts,
entity_t * response )

Get all tasks (generic version).

Parameters
[in]sessionPointer to GNUTLS session.
[in]optsStruct containing the options to apply.
[out]responseTasks. On success contains GET_TASKS response.
Returns
0 on success, 2 on timeout, -1 or GMP response code on error.

◆ gmp_modify_task_file()

int gmp_modify_task_file ( gnutls_session_t * session,
const char * id,
const char * name,
const void * content,
gsize content_len )

Modify a file on a task.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of task.
[in]nameName of file.
[in]contentNew content. NULL to remove file.
[in]content_lenLength of content.
Returns
0 on success, -1 or GMP response code on error.

◆ gmp_ping()

int gmp_ping ( gnutls_session_t * session,
int timeout )

"Ping" the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[in]timeoutServer idle time before giving up, in milliseconds. 0 to wait forever.
Returns
0 on success, 1 if manager closed connection, 2 on timeout, -1 on error.

◆ gmp_ping_c()

int gmp_ping_c ( gvm_connection_t * connection,
int timeout,
gchar ** version )

"Ping" the manager.

Parameters
[in]connectionPointer to GNUTLS session.
[in]timeoutServer idle time before giving up, in milliseconds. 0 to wait forever.
[out]versionReturn location for freshly allocated version if required, else NULL.
Returns
0 on success, 1 if manager closed connection, 2 on timeout, -1 on error.

◆ gmp_read_create_response()

int gmp_read_create_response ( gnutls_session_t * session,
gchar ** uuid )

Read response status and resource UUID.

Parameters
[in]sessionPointer to GNUTLS session.
[out]uuidEither NULL or address for freshly allocated UUID of created response.
Returns
GMP response code on success, -1 on error.

◆ gmp_resume_task_report()

int gmp_resume_task_report ( gnutls_session_t * session,
const char * task_id,
char ** report_id )

Resume a task and read the manager response.

Parameters
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
[out]report_idID of report.
Returns
0 on success, 1 on GMP failure, -1 on error.

◆ gmp_resume_task_report_c()

int gmp_resume_task_report_c ( gvm_connection_t * connection,
const char * task_id,
char ** report_id )

Resume a task and read the manager response.

Parameters
[in]connectionConnection.
[in]task_idID of task.
[out]report_idID of report.
Returns
0 on success, 1 on GMP failure, -1 on error.

◆ gmp_start_task_ext_c()

int gmp_start_task_ext_c ( gvm_connection_t * connection,
gmp_start_task_opts_t opts )

Start a task and read the manager response.

Parameters
[in]connectionConnection.
[in]optsOptions to apply.
Returns
0 on success, 99 permission denied, -1 or GMP response code on error.

◆ gmp_start_task_report()

int gmp_start_task_report ( gnutls_session_t * session,
const char * task_id,
char ** report_id )

Start a task and read the manager response.

Parameters
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
[out]report_idID of report.
Returns
0 on success, 1 on failure, -1 on error.

◆ gmp_start_task_report_c()

int gmp_start_task_report_c ( gvm_connection_t * connection,
const char * task_id,
char ** report_id )

Start a task and read the manager response.

Parameters
[in]connectionConnection.
[in]task_idID of task.
[out]report_idID of report.
Returns
0 on success, 1 on failure, -1 on error.

◆ gmp_stop_task()

int gmp_stop_task ( gnutls_session_t * session,
const char * id )

Stop a task and read the manager response.

Parameters
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns
0 on success, GMP response code on failure, -1 on error.

◆ gmp_stop_task_c()

int gmp_stop_task_c ( gvm_connection_t * connection,
const char * id )

Stop a task and read the manager response.

Parameters
[in]connectionConnection.
[in]idID of task.
Returns
0 on success, GMP response code on failure, -1 on error.

◆ gmp_task_status()

const char * gmp_task_status ( entity_t response)

Get the task status from a GMP GET_TASKS response.

Parameters
[in]responseGET_TASKS response.
Returns
The entity_text of the status entity if the entity is found, else NULL.