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) (var.attrib == 0 ? " " #attrib "=\"0\"" : " " #attrib "=\"1\"")
#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
| ) |  | (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] | connection | Connection.
  [in] | convert_99 | If 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] | session | Pointer to GNUTLS session.
  [in] | username | Username.
  [in] | password | Password.

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] | session | Pointer to GNUTLS session.
  [in,out] | opts | In: 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] | connection | Connection
  [in] | opts | Struct 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] | session | Pointer to GNUTLS session.
  [in] | entity | Entity 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] | connection | Connection.

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] | session | Pointer to GNUTLS session.
  [in] | name | Name of LSC Credential.
  [in] | login | Login associated with name.
  [in] | password | Password, or NULL for autogenerated credentials.
  [in] | comment | LSC Credential comment.
  [out] | uuid | Either 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | id | Pointer 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] | session | Pointer to GNUTLS session.
  [in] | name | Name of LSC Credential.
  [in] | login | Login associated with name.
  [in] | passphrase | Passphrase for private key.
  [in] | private_key | Private key.
  [in] | comment | LSC Credential comment.
  [out] | uuid | Either 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | id | Pointer 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] | session | Pointer to GNUTLS session.
  [in] | name | Task name.
  [in] | config | Task config name.
  [in] | target | Task target name.
  [in] | comment | Task comment.
  [out] | id | Pointer 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | id | Pointer 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] | session | Pointer to GNUTLS session.
  [in] | id | UUID of config.
  [in] | opts | Struct 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] | session | Pointer to GNUTLS session.
  [in] | id | UUID of LSC credential.
  [in] | opts | Struct 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] | session | Pointer to GNUTLS session.
  [in] | id | UUID of port list.
  [in] | opts | Struct 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] | session | Pointer to GNUTLS session.
  [in] | id | ID 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] | session | Pointer to GNUTLS session.
  [in] | id | UUID of target.
  [in] | opts | Struct 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] | session | Pointer to GNUTLS session.
  [in] | id | ID 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] | session | Pointer to GNUTLS session.
  [in] | id | ID of task.
  [in] | opts | Struct 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | response | Report. 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] | session | Pointer to GNUTLS session.
  [in] | name | Name of system report. NULL for all.
  [in] | brief | Whether to request brief response.
  [out] | reports | Reports 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | reports | Reports 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] | session | Pointer to GNUTLS session.
  [in] | id | ID of target or NULL for all targets.
  [in] | tasks | Whether to include tasks that use the target.
  [in] | include_rcfile | Not used.
  [out] | target | Target 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | response | Task. 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] | session | Pointer to GNUTLS session.
  [in] | id | ID of task or NULL for all tasks.
  [in] | details | Whether to request task details.
  [in] | include_rcfile | Ignored. Removed since GMP 6.0.
  [out] | status | Status 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] | session | Pointer to GNUTLS session.
  [in] | opts | Struct containing the options to apply.
  [out] | response | Tasks. 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] | session | Pointer to GNUTLS session.
  [in] | id | ID of task.
  [in] | name | Name of file.
  [in] | content | New content. NULL to remove file.
  [in] | content_len | Length 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] | session | Pointer to GNUTLS session.
  [in] | timeout | Server 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] | connection | Pointer to GNUTLS session.
  [in] | timeout | Server idle time before giving up, in milliseconds. 0 to wait forever.
  [out] | version | Return 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] | session | Pointer to GNUTLS session.
  [out] | uuid | Either 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] | session | Pointer to GNUTLS session.
  [in] | task_id | ID of task.
  [out] | report_id | ID 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] | connection | Connection.
  [in] | task_id | ID of task.
  [out] | report_id | ID 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] | connection | Connection.
  [in] | opts | Options 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] | session | Pointer to GNUTLS session.
  [in] | task_id | ID of task.
  [out] | report_id | ID 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] | connection | Connection.
  [in] | task_id | ID of task.
  [out] | report_id | ID 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] | session | Pointer to GNUTLS session.
  [in] | id | ID 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] | connection | Connection.
  [in] | id | ID 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] | response | GET_TASKS response.

Returns
  The entity_text of the status entity if the entity is found, else NULL.