OpenVAS Libraries  4.0+rc3.SVN
Defines | Functions
omp/omp.c File Reference

OMP client interface. More...

#include <string.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
#include "omp.h"
#include "xml.h"
#include "openvas_server.h"

Defines

#define G_LOG_DOMAIN   "lib omp"
 GLib log domain.
#define DO_CHILDREN(entity, child, temp, body)
 Do something for each child of an entity.

Functions

const char * omp_task_status (entity_t response)
 Get the task status from an OMP GET_TASKS response.
int omp_ping (gnutls_session_t *session, int timeout)
 "Ping" the manager.
int omp_authenticate (gnutls_session_t *session, const char *username, const char *password)
 Authenticate with the manager.
int omp_authenticate_env (gnutls_session_t *session)
 Authenticate, getting credentials from the environment.
int omp_create_task (gnutls_session_t *session, const char *name, const char *config, const char *target, const char *comment, char **id)
 Create a task given a config and target.
int omp_create_task_rc (gnutls_session_t *session, const char *config, unsigned int config_len, const char *name, const char *comment, char **id)
 Create a task, given the task description as an RC file.
int omp_create_task_rc_file (gnutls_session_t *session, const char *file_name, const char *name, const char *comment, char **id)
 Create a task, given the task description as an RC file.
int omp_start_task_report (gnutls_session_t *session, const char *task_id, char **report_id)
 Start a task and read the manager response.
int omp_start_task (gnutls_session_t *session, const char *task_id)
 Start a task and read the manager response.
int omp_resume_or_start_task_report (gnutls_session_t *session, const char *task_id, char **report_id)
 Resume or start a task and read the manager response.
int omp_resume_or_start_task (gnutls_session_t *session, const char *task_id)
 Resume or start a task and read the manager response.
int check_response (gnutls_session_t *session)
 Read response and convert status of response to a return value.
int omp_read_create_response (gnutls_session_t *session, char **uuid)
 Read response status and resource UUID.
int omp_abort_task (gnutls_session_t *session, const char *id)
 Deprecated wrapper function for /ref omp_stop_task.
int omp_stop_task (gnutls_session_t *session, const char *id)
 Stop a task and read the manager response.
int omp_pause_task (gnutls_session_t *session, const char *task_id)
 Pause a task and read the manager response.
int omp_resume_paused_task (gnutls_session_t *session, const char *task_id)
 Resume a paused task and read the manager response.
int omp_resume_stopped_task (gnutls_session_t *session, const char *task_id)
 Resume a stopped task and read the manager response.
int omp_resume_stopped_task_report (gnutls_session_t *session, const char *task_id, char **report_id)
 Resume a stopped task and read the manager response.
int omp_get_nvt_all (gnutls_session_t *session, entity_t *response)
 Issue an OMP <get_nvts\/> command and wait for the response.
int omp_get_nvt_feed_checksum (gnutls_session_t *session, entity_t *response)
 Issue an OMP <get_nvt_feed_checksum algoithm=md5/> command and.
int omp_get_dependencies_503 (gnutls_session_t *session, entity_t *response)
 Issue an OMP <get_dependencies/> command and wait for the response.
int omp_wait_for_task_start (gnutls_session_t *session, const char *id)
 Wait for a task to start running on the server.
int omp_wait_for_task_end (gnutls_session_t *session, const char *id)
 Wait for a task to finish running on the server.
int omp_wait_for_task_stop (gnutls_session_t *session, const char *id)
 Wait for a task to stop on the server.
int omp_wait_for_task_delete (gnutls_session_t *session, const char *id)
 Wait for the manager to actually remove a task.
int omp_delete_task (gnutls_session_t *session, const char *id)
 Delete a task and read the manager response.
int omp_get_status (gnutls_session_t *session, const char *id, int include_rcfile, entity_t *status)
 Deprecated wrapper function for /ref omp_get_tasks.
int omp_get_tasks (gnutls_session_t *session, const char *id, int details, int include_rcfile, entity_t *status)
 Get the status of a task.
int omp_get_targets (gnutls_session_t *session, const char *id, int tasks, int include_rcfile, entity_t *target)
 Get a target.
int omp_get_report (gnutls_session_t *session, const char *id, const char *format, int first_result_number, entity_t *response)
 Get a report.
int omp_get_report_format (gnutls_session_t *session, const char *id, const char *format, void **report, gsize *report_size)
 Get a report in a given format.
int omp_delete_report (gnutls_session_t *session, const char *id)
 Remove a report.
int omp_get_results (gnutls_session_t *session, const char *task_id, int notes, int notes_details, int overrides, int overrides_details, int apply_overrides, entity_t *response)
 Get results.
int omp_modify_task (gnutls_session_t *session, const char *id, const char *rcfile, const char *name, const char *comment)
 Modify a task.
int omp_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 omp_get_preferences (gnutls_session_t *session, entity_t *response)
 Get the manager preferences.
int omp_get_preferences_503 (gnutls_session_t *session, entity_t *response)
 Get the manager preferences, waiting for them to appear.
int omp_get_certificates (gnutls_session_t *session, entity_t *response)
 Get the manager certificates.
int omp_until_up (int(*function)(gnutls_session_t *, entity_t *), gnutls_session_t *session, entity_t *response)
 Poll an OMP service until it is up.
int omp_create_target (gnutls_session_t *session, const char *name, const char *hosts, const char *comment, const char *ssh_credential, const char *smb_credential, char **uuid)
 Create a target.
int omp_delete_target (gnutls_session_t *session, const char *id)
 Delete a target.
int omp_create_config (gnutls_session_t *session, const char *name, const char *comment, const char *config, unsigned int config_len)
 Create a config, given the config description as a string.
int omp_create_config_from_rc_file (gnutls_session_t *session, const char *name, const char *comment, const char *file_name)
 Create a config, given the config description as an RC file.
int omp_delete_config (gnutls_session_t *session, const char *id)
 Delete a config.
int omp_create_lsc_credential (gnutls_session_t *session, const char *name, const char *login, const char *password, const char *comment, char **uuid)
 Create an LSC Credential.
int omp_delete_lsc_credential (gnutls_session_t *session, const char *id)
 Delete a LSC credential.
int omp_create_agent (gnutls_session_t *session, const char *name, const char *comment)
 Create an agent.
int omp_delete_agent (gnutls_session_t *session, const char *name)
 Delete an agent.
int omp_get_nvt_details_503 (gnutls_session_t *session, const char *oid, entity_t *response)
 Get NVT Information.
int omp_get_system_reports (gnutls_session_t *session, const char *name, int brief, entity_t *reports)
 Get system reports.

Detailed Description

OMP client interface.

Todo:
Name functions consistently (perhaps omp_*).

This provides higher level, OMP-aware, facilities for working with with the OpenVAS manager.

There are examples of using this interface in the openvas-manager tests.


Define Documentation

#define DO_CHILDREN (   entity,
  child,
  temp,
  body 
)
Value:
do                                                \
    {                                               \
      GSList* temp = entity->entities;              \
      while (temp)                                  \
        {                                           \
          entity_t child = temp->data;              \
          {                                         \
            body;                                   \
          }                                         \
          temp = g_slist_next (temp);               \
        }                                           \
    }                                               \
  while (0)

Do something for each child of an entity.

Todo:
Use next_entities and first_entity instead of this.

Calling "break" during body exits the loop.

Parameters:
[in]entityThe entity.
[in]childName to use for child variable.
[in]tempName to use for internal variable.
[in]bodyThe code to run for each child.

Function Documentation

int check_response ( gnutls_session_t *  session)

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

Todo:
Use this in the other functions.
Parameters:
[in]sessionPointer to GNUTLS session.
Returns:
0 on success, 1 on failure, -1 on error.
int omp_abort_task ( gnutls_session_t *  session,
const char *  id 
)

Deprecated wrapper function for /ref omp_stop_task.

Deprecated:
Use /ref omp_stop_task instead.
Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns:
0 on success, -1 on error.
int omp_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.
int omp_authenticate_env ( gnutls_session_t *  session)

Authenticate, getting credentials from the environment.

Get the user name from environment variable OPENVAS_TEST_USER if that is set, else from USER. Get the password from OPENVAS_TEST_PASSWORD.

Parameters:
[in]sessionPointer to GNUTLS session.
Returns:
0 on success, 1 if manager closed connection, -1 on error.
int omp_create_agent ( gnutls_session_t *  session,
const char *  name,
const char *  comment 
)

Create an agent.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]nameName of agent.
[in]commentAgent comment.
Returns:
0 on success, -1 on error.
int omp_create_config ( gnutls_session_t *  session,
const char *  name,
const char *  comment,
const char *  config,
unsigned int  config_len 
)

Create a config, given the config description as a string.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]nameConfig name.
[in]commentConfig comment.
[in]configConfig configuration.
[in]config_lenLength of config.
Returns:
0 on success, -1 on error.
int omp_create_config_from_rc_file ( gnutls_session_t *  session,
const char *  name,
const char *  comment,
const char *  file_name 
)

Create a config, given the config description as an RC file.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]nameConfig name.
[in]commentConfig comment.
[in]file_nameName of RC file.
Returns:
0 on success, -1 on error.
int omp_create_lsc_credential ( gnutls_session_t *  session,
const char *  name,
const char *  login,
const char *  password,
const char *  comment,
char **  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 OMP response code on error.
int omp_create_target ( gnutls_session_t *  session,
const char *  name,
const char *  hosts,
const char *  comment,
const char *  ssh_credential,
const char *  smb_credential,
char **  uuid 
)

Create a target.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]nameName of target.
[in]hostsTarget hosts.
[in]commentTarget comment.
[in]ssh_credentialUUID of SSH LSC credential.
[in]smb_credentialUUID of SMB LSC credential.
[out]uuidEither NULL or address for UUID of created target.
Returns:
0 on success, -1 or OMP response code on error.
int omp_create_task ( gnutls_session_t *  session,
const char *  name,
const char *  config,
const char *  target,
const char *  comment,
char **  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 OMP response code on error.
int omp_create_task_rc ( gnutls_session_t *  session,
const char *  config,
unsigned int  config_len,
const char *  name,
const char *  comment,
char **  id 
)

Create a task, given the task description as an RC file.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]configTask configuration.
[in]config_lenLength of config.
[in]nameTask name.
[in]commentTask comment.
[out]idPointer for newly allocated ID of new task. Only set on successful return.
Returns:
0 on success, -1 on error.
int omp_create_task_rc_file ( gnutls_session_t *  session,
const char *  file_name,
const char *  name,
const char *  comment,
char **  id 
)

Create a task, given the task description as an RC file.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]file_nameName of the RC file.
[in]nameTask name.
[in]commentTask comment.
[out]idID of new task.
Returns:
0 on success, -1 on error.
int omp_delete_agent ( gnutls_session_t *  session,
const char *  name 
)

Delete an agent.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]nameName of agent.
Returns:
0 on success, -1 on error.
int omp_delete_config ( gnutls_session_t *  session,
const char *  id 
)

Delete a config.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idUUID of config.
Returns:
0 on success, -1 on error.
int omp_delete_lsc_credential ( gnutls_session_t *  session,
const char *  id 
)

Delete a LSC credential.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]uuidUUID of LSC credential.
Returns:
0 on success, -1 on error.
int omp_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, -1 or OMP response code on error.
int omp_delete_target ( gnutls_session_t *  session,
const char *  id 
)

Delete a target.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idUUID of target.
Returns:
0 on success, -1 on error.
int omp_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, -1 on error.
int omp_get_certificates ( gnutls_session_t *  session,
entity_t response 
)

Get the manager certificates.

Parameters:
[in]sessionPointer to GNUTLS session.
[out]responseOn success contains GET_CERTIFICATES response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_get_dependencies_503 ( gnutls_session_t *  session,
entity_t response 
)

Issue an OMP <get_dependencies/> command and wait for the response.

Parameters:
[in]sessionSession to the server.
[out]responseEntity containing the response, must be freed.
Returns:
0 in case of success. -1 otherwise (e.g. invalid session).
int omp_get_nvt_all ( gnutls_session_t *  session,
entity_t response 
)

Issue an OMP <get_nvts\/> command and wait for the response.

Parameters:
[in]sessionSession to the server.
[out]responseEntity containing the response, must be freed.
Returns:
0 in case of success. -1 otherwise (e.g. invalid session).
int omp_get_nvt_details_503 ( gnutls_session_t *  session,
const char *  oid,
entity_t response 
)

Get NVT Information.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]oidOID of NVT or NULL for all NVTs.
[out]responseStatus return. On success contains GET_TASKS response.
Returns:
0 on success, -1 on error.
int omp_get_nvt_feed_checksum ( gnutls_session_t *  session,
entity_t response 
)

Issue an OMP <get_nvt_feed_checksum algoithm=md5/> command and.

wait for the response.

Parameters:
[in]sessionSession to the server.
[out]responseEntity containing the response, must be freed.
Returns:
0 in case of success. -1 otherwise (e.g. invalid session).
int omp_get_preferences ( gnutls_session_t *  session,
entity_t response 
)

Get the manager preferences.

Parameters:
[in]sessionPointer to GNUTLS session.
[out]responseOn success contains GET_PREFERENCES response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_get_preferences_503 ( gnutls_session_t *  session,
entity_t response 
)

Get the manager preferences, waiting for them to appear.

Parameters:
[in]sessionPointer to GNUTLS session.
[out]responseOn success contains GET_PREFERENCES response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_get_report ( gnutls_session_t *  session,
const char *  id,
const char *  format,
int  first_result_number,
entity_t response 
)

Get a report.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of report.
[out]responseReport. On success contains GET_REPORT response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_get_report_format ( gnutls_session_t *  session,
const char *  id,
const char *  format,
void **  report,
gsize *  report_size 
)

Get a report in a given format.

Todo:
This now has a bad name, because there is an OMP GET_REPORT_FORMATS.
Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of report.
[in]formatRequired format.
[out]reportReport. On success contains the report.
[out]report_sizeSize of report in bytes.
Returns:
0 on success, -1 on error.
int omp_get_results ( gnutls_session_t *  session,
const char *  task_id,
int  notes,
int  notes_details,
int  overrides,
int  overrides_details,
int  apply_overrides,
entity_t response 
)

Get results.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]task_idID of task whose to get, NULL for all.
[in]notesWhether to include notes.
[in]notes_detailsIf notes, whether to include details.
[in]overridesWhether to include notes.
[in]overrides_detailsIf overrides, whether to include details.
[in]apply_overridesWhether to apply overrides.
[out]responseOn success contains the GET_RESULTS response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_get_status ( gnutls_session_t *  session,
const char *  id,
int  include_rcfile,
entity_t status 
)

Deprecated wrapper function for /ref omp_get_tasks.

Deprecated:
Use /ref omp_get_tasks instead.
Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task or NULL for all tasks.
[in]include_rcfileRequest rcfile in status if true.
[out]statusStatus return. On success contains GET_TASKS response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_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 OMP response code on error.
int omp_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.
[out]targetTarget return. On success contains GET_TARGETS response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_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_rcfileRequest rcfile in status if true.
[out]statusStatus return. On success contains GET_TASKS response.
Returns:
0 on success, -1 or OMP response code on error.
int omp_modify_task ( gnutls_session_t *  session,
const char *  id,
const char *  rcfile,
const char *  name,
const char *  comment 
)

Modify a task.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task.
[in]rcfileNULL or new RC file (as plain text).
[in]nameNULL or new name.
[in]commentNULL or new comment.
Returns:
0 on success, -1 or OMP response code on error.
int omp_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 OMP response code on error.
int omp_pause_task ( gnutls_session_t *  session,
const char *  task_id 
)

Pause a task and read the manager response.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
Returns:
0 on success, 1 on OMP failure, -1 on error.
int omp_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.
int omp_read_create_response ( gnutls_session_t *  session,
char **  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:
OMP response code on success, -1 on error.
int omp_resume_or_start_task ( gnutls_session_t *  session,
const char *  task_id 
)

Resume or start a task and read the manager response.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
Returns:
0 on success, 1 on failure, -1 on error.
int omp_resume_or_start_task_report ( gnutls_session_t *  session,
const char *  task_id,
char **  report_id 
)

Resume or 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.
int omp_resume_paused_task ( gnutls_session_t *  session,
const char *  task_id 
)

Resume a paused task and read the manager response.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
Returns:
0 on success, 1 on OMP failure, -1 on error.
int omp_resume_stopped_task ( gnutls_session_t *  session,
const char *  task_id 
)

Resume a stopped task and read the manager response.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
Returns:
0 on success, 1 on OMP failure, -1 on error.
int omp_resume_stopped_task_report ( gnutls_session_t *  session,
const char *  task_id,
char **  report_id 
)

Resume a stopped 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 OMP failure, -1 on error.
int omp_start_task ( gnutls_session_t *  session,
const char *  task_id 
)

Start a task and read the manager response.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]task_idID of task.
Returns:
0 on success, 1 on failure, -1 on error.
int omp_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.
int omp_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, -1 on error.
const char* omp_task_status ( entity_t  response)

Get the task status from an OMP GET_TASKS response.

Parameters:
[in]responseGET_TASKS response.
Returns:
The entity_text of the status entity if the entity is found, else NULL.
int omp_until_up ( int(*)(gnutls_session_t *, entity_t *)  function,
gnutls_session_t *  session,
entity_t response 
)

Poll an OMP service until it is up.

Repeatedly call a function while it returns the value 503.

Parameters:
[in]functionFunction to call to do polling.
[in]sessionPointer to GNUTLS session.
[out]responseOn success contains GET_CERTIFICATES response.
Returns:
The value returned from the function.
int omp_wait_for_task_delete ( gnutls_session_t *  session,
const char *  id 
)

Wait for the manager to actually remove a task.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns:
0 on success, -1 on error.
int omp_wait_for_task_end ( gnutls_session_t *  session,
const char *  id 
)

Wait for a task to finish running on the server.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns:
0 on success, 1 on internal error in task, -1 on error.
int omp_wait_for_task_start ( gnutls_session_t *  session,
const char *  id 
)

Wait for a task to start running on the server.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns:
0 on success, 1 on internal error in task, -1 on error.
Todo:
Reconsider this (more below).
int omp_wait_for_task_stop ( gnutls_session_t *  session,
const char *  id 
)

Wait for a task to stop on the server.

Parameters:
[in]sessionPointer to GNUTLS session.
[in]idID of task.
Returns:
0 on success, 1 on internal error in task, -1 on error, -2 on failure to find the task.