streamvalidator.h File Reference

Data stream validation headers. More...

#include <stdio.h>

Include dependency graph for streamvalidator.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	GVM_STREAM_VALIDATOR_NO_SIZE   ((size_t) - 1)

Typedefs
typedef struct gvm_stream_validator *	gvm_stream_validator_t
	Pointer to an opaque stream validator data structure.

Enumerations
enum	gvm_stream_validator_return_t {   GVM_STREAM_VALIDATOR_INTERNAL_ERROR = -1 , GVM_STREAM_VALIDATOR_OK = 0 , GVM_STREAM_VALIDATOR_DATA_TOO_SHORT = 1 , GVM_STREAM_VALIDATOR_DATA_TOO_LONG ,   GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX , GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM , GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE , GVM_STREAM_VALIDATOR_HASH_MISMATCH }

Functions
const char *	gvm_stream_validator_return_str (gvm_stream_validator_return_t)
	Gets a string representation of a gvm_stream_validator_return_t.
gvm_stream_validator_return_t	gvm_stream_validator_new (const char *, gvm_stream_validator_t *)
	Allocate and initialize a checksum-only stream validator.
gvm_stream_validator_return_t	gvm_stream_validator_with_size_new (const char *, size_t, gvm_stream_validator_t *)
	Allocate and initialize a new data stream validator.
void	gvm_stream_validator_rewind (gvm_stream_validator_t)
	Rewind the validation state of a stream validator while keeping the expected hash and data size.
void	gvm_stream_validator_free (gvm_stream_validator_t)
	Free a stream validator and all of its fields.
gvm_stream_validator_return_t	gvm_stream_validator_write (gvm_stream_validator_t, const char *, size_t)
	Write data to a validator, updating the hash state and current size.
gvm_stream_validator_return_t	gvm_stream_validator_end (gvm_stream_validator_t)
	Signal the end of data input into a validator and produce the result of the validation.

Detailed Description

Data stream validation headers.

Definition in file streamvalidator.h.

Macro Definition Documentation

GVM_STREAM_VALIDATOR_NO_SIZE

#define GVM_STREAM_VALIDATOR_NO_SIZE   ((size_t) - 1)

Definition at line 11 of file streamvalidator.h.

Referenced by Ensure(), Ensure(), Ensure(), Ensure(), gvm_stream_validator_new(), and gvm_stream_validator_with_size_new().

Typedef Documentation

gvm_stream_validator_t

typedef struct gvm_stream_validator* gvm_stream_validator_t

Pointer to an opaque stream validator data structure.

Definition at line 42 of file streamvalidator.h.

Enumeration Type Documentation

gvm_stream_validator_return_t

enum gvm_stream_validator_return_t

Enumerator
GVM_STREAM_VALIDATOR_INTERNAL_ERROR	An internal error ocurred.
GVM_STREAM_VALIDATOR_OK	Action successful / data is valid.
GVM_STREAM_VALIDATOR_DATA_TOO_SHORT	Not enough data received.
GVM_STREAM_VALIDATOR_DATA_TOO_LONG	Too much data received.
GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX	Syntax error in hash string (not using "algo:hex" format).
GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM	Invalid or unsupported hash algorithm.
GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE	Hash value is not valid. (e.g. not hexadecimal or length does not match algorithm)
GVM_STREAM_VALIDATOR_HASH_MISMATCH	Hash of received data does not match the expected hash

Definition at line 18 of file streamvalidator.h.

{
  GVM_STREAM_VALIDATOR_INTERNAL_ERROR = -1,
  GVM_STREAM_VALIDATOR_OK = 0,
  GVM_STREAM_VALIDATOR_DATA_TOO_SHORT = 1,
  GVM_STREAM_VALIDATOR_DATA_TOO_LONG,
  GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX,
  GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM,
  GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE,
  GVM_STREAM_VALIDATOR_HASH_MISMATCH
} gvm_stream_validator_return_t;

Function Documentation

gvm_stream_validator_end()

gvm_stream_validator_return_t gvm_stream_validator_end

(

gvm_stream_validator_t

validator

)

Signal the end of data input into a validator and produce the result of the validation.

Parameters

[in]

validator

The validator to signal the end of data input of.

Returns

The validation result.

Definition at line 260 of file streamvalidator.c.

{
  unsigned char *actual_hash_bin;
  gchar *actual_hash_hex;
 
  if (validator->size_enforced)
    {
      if (validator->current_size < validator->expected_size)
        return GVM_STREAM_VALIDATOR_DATA_TOO_SHORT;
 
      if (validator->current_size > validator->expected_size)
        return GVM_STREAM_VALIDATOR_DATA_TOO_LONG;
    }
 
  actual_hash_bin =
    gcry_md_read (validator->gcrypt_md_hd, validator->algorithm);
  actual_hash_hex = digest_hex (validator->algorithm, actual_hash_bin);
  if (strcasecmp (validator->expected_hash_hex, actual_hash_hex))
    {
      g_free (actual_hash_hex);
      return GVM_STREAM_VALIDATOR_HASH_MISMATCH;
    }
  g_free (actual_hash_hex);
 
  return GVM_STREAM_VALIDATOR_OK;
}

References gvm_stream_validator::algorithm, gvm_stream_validator::current_size, digest_hex(), gvm_stream_validator::expected_hash_hex, gvm_stream_validator::expected_size, gvm_stream_validator::gcrypt_md_hd, GVM_STREAM_VALIDATOR_DATA_TOO_LONG, GVM_STREAM_VALIDATOR_DATA_TOO_SHORT, GVM_STREAM_VALIDATOR_HASH_MISMATCH, GVM_STREAM_VALIDATOR_OK, and gvm_stream_validator::size_enforced.

Referenced by Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), and Ensure().

Here is the call graph for this function:

Here is the caller graph for this function:

gvm_stream_validator_free()

void gvm_stream_validator_free

(

gvm_stream_validator_t

validator

)

Free a stream validator and all of its fields.

Parameters

[in]

validator

The validator to free.

Definition at line 216 of file streamvalidator.c.

{
  gcry_md_close (validator->gcrypt_md_hd);
  g_free (validator->expected_hash_str);
  g_free (validator->expected_hash_hex);
  g_free (validator);
}

References gvm_stream_validator::expected_hash_hex, gvm_stream_validator::expected_hash_str, and gvm_stream_validator::gcrypt_md_hd.

Referenced by Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), and Ensure().

Here is the caller graph for this function:

gvm_stream_validator_new()

gvm_stream_validator_return_t gvm_stream_validator_new	(	const char *	expected_hash_str,
		gvm_stream_validator_t *	validator_out )

Allocate and initialize a checksum-only stream validator.

Parameters

[in]	expected_hash_str	Expected hash / checksum string consisting of an algorithm name or OID as recognized by gcrypt, followed by a colon and the hex-encoded hash, e.g. "md5:70165459812a0d38851a4a4c3e4124c9".
[out]	validator_out	Pointer to output location of the newly allocated validator.

Returns

A gvm_stream_validator_return_t code indicating success or the reason of failure.

Note

Size is NOT enforced; callers who need exact-size validation must use gvm_stream_validator_with_size_new (..., expected_size, ...).

Definition at line 87 of file streamvalidator.c.

{
  return gvm_stream_validator_with_size_new (
    expected_hash_str, GVM_STREAM_VALIDATOR_NO_SIZE, validator_out);
}

References GVM_STREAM_VALIDATOR_NO_SIZE, and gvm_stream_validator_with_size_new().

Referenced by Ensure(), Ensure(), and Ensure().

Here is the call graph for this function:

Here is the caller graph for this function:

gvm_stream_validator_return_str()

const char * gvm_stream_validator_return_str

(

gvm_stream_validator_return_t

value

)

Gets a string representation of a gvm_stream_validator_return_t.

Parameters

[in]

value

The value to get a string representation of.

Returns

Static string describing the return value or NULL if value is GVM_STREAM_VALIDATOR_OK.

Definition at line 44 of file streamvalidator.c.

{
  switch (value)
    {
    case GVM_STREAM_VALIDATOR_INTERNAL_ERROR:
      return "internal error";
    case GVM_STREAM_VALIDATOR_OK:
      return NULL;
    case GVM_STREAM_VALIDATOR_DATA_TOO_SHORT:
      return "too short";
    case GVM_STREAM_VALIDATOR_DATA_TOO_LONG:
      return "too long";
    case GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX:
      return "invalid hash syntax";
    case GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM:
      return "invalid or unsupported hash algorithm";
    case GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE:
      return "invalid hash value";
    case GVM_STREAM_VALIDATOR_HASH_MISMATCH:
      return "hash does not match";
    default:
      return "unknown error";
    }
}

References GVM_STREAM_VALIDATOR_DATA_TOO_LONG, GVM_STREAM_VALIDATOR_DATA_TOO_SHORT, GVM_STREAM_VALIDATOR_HASH_MISMATCH, GVM_STREAM_VALIDATOR_INTERNAL_ERROR, GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM, GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX, GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE, and GVM_STREAM_VALIDATOR_OK.

Referenced by Ensure(), Ensure(), and Ensure().

Here is the caller graph for this function:

gvm_stream_validator_rewind()

void gvm_stream_validator_rewind

(

gvm_stream_validator_t

validator

)

Rewind the validation state of a stream validator while keeping the expected hash and data size.

Parameters

[in]

validator

The validator to rewind.

Definition at line 204 of file streamvalidator.c.

{
  gcry_md_reset (validator->gcrypt_md_hd);
  validator->current_size = 0;
}

References gvm_stream_validator::current_size, and gvm_stream_validator::gcrypt_md_hd.

Referenced by Ensure().

Here is the caller graph for this function:

gvm_stream_validator_with_size_new()

gvm_stream_validator_return_t gvm_stream_validator_with_size_new	(	const char *	expected_hash_str,
		size_t	expected_size,
		gvm_stream_validator_t *	validator_out )

Allocate and initialize a new data stream validator.

Parameters

[in]	expected_hash_str	Expected hash / checksum string consisting of an algorithm name or OID as recognized by gcrypt, followed by a colon and the hex-encoded hash, e.g. "md5:70165459812a0d38851a4a4c3e4124c9".
[in]	expected_size	The number of bytes expected to be sent. Pass (size_t)-1 to disable size enforcement and validate by hash only.
[out]	validator_out	Pointer to output location of the newly allocated validator.

Returns

A validator return code, returning a failure if the expected hash string is invalid or uses an unsupported algorithm.

Note

When size enforcement is enabled (expected_size != (size_t)-1), gvm_stream_validator_write() will return DATA_TOO_LONG if the stream exceeds the expected size, and gvm_stream_validator_end() will return DATA_TOO_SHORT if the stream ends early.

Definition at line 117 of file streamvalidator.c.

{
  assert (validator_out);
 
  static GRegex *hex_regex = NULL;
  gchar **parts = NULL;
  const char *algo_str = NULL;
  const char *hex_str = NULL;
  int algo;
  unsigned int expected_hex_len;
  gcry_md_hd_t gcrypt_md_hd;
  gboolean size_enforced = FALSE;
  size_t final_expected_size = 0;
 
  if (expected_hash_str == NULL)
    return GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX;
 
  if (hex_regex == NULL)
    hex_regex = g_regex_new ("^(?:[0-9A-Fa-f][0-9A-Fa-f])+$", 0, 0, NULL);
 
  *validator_out = NULL;
 
  parts = g_strsplit (expected_hash_str, ":", 2);
  guint n = g_strv_length (parts);
  if (n != 2)
    {
      g_strfreev (parts);
      return GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX;
    }
  algo_str = parts[0];
  hex_str = parts[1];
 
  if (expected_size != GVM_STREAM_VALIDATOR_NO_SIZE)
    {
      final_expected_size = expected_size;
      size_enforced = TRUE;
    }
  else
    {
      final_expected_size = 0;
      size_enforced = FALSE;
    }
 
  algo = gcry_md_map_name (algo_str);
  if (algo == GCRY_MD_NONE || gcry_md_test_algo (algo))
    {
      g_strfreev (parts);
      return GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM;
    }
 
  expected_hex_len = gcry_md_get_algo_dlen (algo) * 2;
  if (strlen (hex_str) != expected_hex_len
      || g_regex_match (hex_regex, hex_str, 0, NULL) == FALSE)
    {
      g_strfreev (parts);
      return GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE;
    }
 
  gcrypt_md_hd = NULL;
  if (gcry_md_open (&gcrypt_md_hd, algo, 0))
    {
      g_strfreev (parts);
      return GVM_STREAM_VALIDATOR_INTERNAL_ERROR;
    }
 
  *validator_out = g_malloc0 (sizeof (struct gvm_stream_validator));
  (*validator_out)->algorithm = algo;
  (*validator_out)->expected_size = final_expected_size;
  (*validator_out)->size_enforced = size_enforced;
  (*validator_out)->expected_hash_str = g_strdup (expected_hash_str);
  (*validator_out)->expected_hash_hex = g_strdup (hex_str);
  (*validator_out)->gcrypt_md_hd = gcrypt_md_hd;
  (*validator_out)->current_size = 0;
 
  g_strfreev (parts);
  return GVM_STREAM_VALIDATOR_OK;
}

References GVM_STREAM_VALIDATOR_INTERNAL_ERROR, GVM_STREAM_VALIDATOR_INVALID_HASH_ALGORITHM, GVM_STREAM_VALIDATOR_INVALID_HASH_SYNTAX, GVM_STREAM_VALIDATOR_INVALID_HASH_VALUE, GVM_STREAM_VALIDATOR_NO_SIZE, and GVM_STREAM_VALIDATOR_OK.

Referenced by Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), and gvm_stream_validator_new().

Here is the caller graph for this function:

gvm_stream_validator_write()

gvm_stream_validator_return_t gvm_stream_validator_write	(	gvm_stream_validator_t	validator,
		const char *	data,
		size_t	length )

Write data to a validator, updating the hash state and current size.

Will fail if the total data size exceeds the expected size.

Parameters

[in]	validator	The validator to handle the data
[in]	data	The data to write.
[in]	length	Length of the data.

Returns

Validator return code, either a "success" or "too long".

Definition at line 236 of file streamvalidator.c.

{
  if (validator->size_enforced)
    {
      if (length > validator->expected_size - validator->current_size)
        return GVM_STREAM_VALIDATOR_DATA_TOO_LONG;
    }
 
  gcry_md_write (validator->gcrypt_md_hd, data, length);
  validator->current_size += length;
 
  return GVM_STREAM_VALIDATOR_OK;
}

References gvm_stream_validator::current_size, gvm_stream_validator::expected_size, gvm_stream_validator::gcrypt_md_hd, GVM_STREAM_VALIDATOR_DATA_TOO_LONG, GVM_STREAM_VALIDATOR_OK, and gvm_stream_validator::size_enforced.

Referenced by Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), Ensure(), and Ensure().

Here is the caller graph for this function: