streamvalidator.c File Reference

Data stream validation. More...

`#include "streamvalidator.h"`
`#include "authutils.h"`
`#include <assert.h>`
`#include <gcrypt.h>`
`#include <glib.h>`
`#include <stdint.h>`
`#include <string.h>`

## Data Structures

struct | gvm_stream_validator
| Data stream validator structure. More...

## Functions

const char * | gvm_stream_validator_return_str (gvm_stream_validator_return_t value)
| Gets a string representation of a gvm_stream_validator_return_t.
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.
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.
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.
void | gvm_stream_validator_free (gvm_stream_validator_t validator)
| Free a stream validator and all of its fields.
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.
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.

## Detailed Description

Data stream validation.

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

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

## 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, ...).

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

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

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

## 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".