Loading...
Searching...
No Matches
Generic Hashing API
libavutil » Crypto and Hashing » Hash Functions

An abstraction layer for all hash functions supported by libavutil. More...

## Files

file | hash.h
| Generic hashing API.

## Macros

#define | AV_HASH_MAX_SIZE 64
| Maximum value that av_hash_get_size() will currently return.

## Functions

int | av_hash_alloc (struct AVHashContext **ctx, const char *name)
| Allocate a hash context for the algorithm specified by name.
const char * | av_hash_names (int i)
| Get the names of available hash algorithms.
const char * | av_hash_get_name (const struct AVHashContext *ctx)
| Get the name of the algorithm corresponding to the given hash context.
int | av_hash_get_size (const struct AVHashContext *ctx)
| Get the size of the resulting hash value in bytes.
void | av_hash_init (struct AVHashContext *ctx)
| Initialize or reset a hash context.
void | av_hash_update (struct AVHashContext *ctx, const uint8_t *src, size_t len)
| Update a hash context with additional data.
void | av_hash_final (struct AVHashContext *ctx, uint8_t *dst)
| Finalize a hash context and compute the actual hash value.
void | av_hash_final_bin (struct AVHashContext *ctx, uint8_t *dst, int size)
| Finalize a hash context and store the actual hash value in a buffer.
void | av_hash_final_hex (struct AVHashContext *ctx, uint8_t *dst, int size)
| Finalize a hash context and store the hexadecimal representation of the actual hash value as a string.
void | av_hash_final_b64 (struct AVHashContext *ctx, uint8_t *dst, int size)
| Finalize a hash context and store the Base64 representation of the actual hash value as a string.
void | av_hash_freep (struct AVHashContext **ctx)
| Free hash context and set hash context pointer to NULL.

## Detailed Description

An abstraction layer for all hash functions supported by libavutil.

If your application needs to support a wide range of different hash functions, then the Generic Hashing API is for you. It provides a generic, reusable API for all hash functions implemented in libavutil. If you just need to use one particular hash function, use the individual hash directly.

# Code

A basic template for using the Generic Hashing API follows:

struct AVHashContext *ctx = NULL;
const char *hash_name = NULL;
uint8_t *output_buf = NULL;
// Select from a string returned by av_hash_names()
hash_name = ...;
// Allocate a hash context
ret = av_hash_alloc(&ctx, hash_name);
if (ret < 0)
return ret;
// Initialize the hash context
av_hash_init(ctx);
// Update the hash context with data
while (data_left) {
av_hash_update(ctx, data, size);
}
// Now we have no more data, so it is time to finalize the hash and get the
// output. But we need to first allocate an output buffer. Note that you can
// use any memory allocation function, including malloc(), not just
// av_malloc().
output_buf = av_malloc(av_hash_get_size(ctx));
if (!output_buf)
return AVERROR(ENOMEM);
// Finalize the hash context.
// You can use any of the av_hash_final*() functions provided, for other
// output formats. If you do so, be sure to adjust the memory allocation
// above. See the function documentation below for the exact amount of extra
// memory needed.
av_hash_final(ctx, output_buffer);
// Free the context
av_hash_freep(&ctx);
AVERROR
#define AVERROR(e)
Definition error.h:45
av_hash_freep
void av_hash_freep(struct AVHashContext **ctx)
Free hash context and set hash context pointer to NULL.
av_hash_init
void av_hash_init(struct AVHashContext *ctx)
Initialize or reset a hash context.
av_hash_get_size
int av_hash_get_size(const struct AVHashContext *ctx)
Get the size of the resulting hash value in bytes.
av_hash_update
void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, size_t len)
Update a hash context with additional data.
av_hash_alloc
int av_hash_alloc(struct AVHashContext **ctx, const char *name)
Allocate a hash context for the algorithm specified by name.
av_hash_final
void av_hash_final(struct AVHashContext *ctx, uint8_t *dst)
Finalize a hash context and compute the actual hash value.
av_malloc
void * av_malloc(size_t size) av_malloc_attrib
Allocate a memory block with alignment suitable for all memory accesses (including vectors if availab...

# Function-Specific Information

If the CRC32 hash is selected, the AV_CRC_32_IEEE polynomial will be used.

If the Murmur3 hash is selected, the default seed will be used. See Murmur3 for more information.

## Macro Definition Documentation

## AV_HASH_MAX_SIZE

#define AV_HASH_MAX_SIZE 64

Maximum value that av_hash_get_size() will currently return.

You can use this if you absolutely want or need to use static allocation for the output buffer and are fine with not supporting hashes newly added to libavutil without recompilation.

Warning
  Adding new hashes with larger sizes, and increasing the macro while doing so, will not be considered an ABI change. To prevent your code from overflowing a buffer, either dynamically allocate the output buffer with av_hash_get_size(), or limit your use of the Hashing API to hashes that are already in FFmpeg during the time of compilation.

Examples
  ffhash.c.

Definition at line 156 of file hash.h.

## Function Documentation

## av_hash_alloc()

int av_hash_alloc | ( | struct AVHashContext ** | ctx,
|  | const char * | name )

Allocate a hash context for the algorithm specified by name.

Returns
  >= 0 for success, a negative error code for failure

Note
  The context is not initialized after a call to this function; you must call av_hash_init() to do so.

Examples
  ffhash.c.

## av_hash_names()

const char * av_hash_names | ( | int | i | ) |

Get the names of available hash algorithms.

This function can be used to enumerate the algorithms.

Parameters

  [in] | i | Index of the hash algorithm, starting from 0

Returns
  Pointer to a static string or NULL if i is out of range

Examples
  ffhash.c.

## av_hash_get_name()

const char * av_hash_get_name | ( | const struct AVHashContext * | ctx | ) |

Get the name of the algorithm corresponding to the given hash context.

Examples
  ffhash.c.

## av_hash_get_size()

int av_hash_get_size | ( | const struct AVHashContext * | ctx | ) |

Get the size of the resulting hash value in bytes.

The maximum value this function will currently return is available as macro AV_HASH_MAX_SIZE.

Parameters

  [in] | ctx | Hash context

Returns
  Size of the hash value in bytes

## av_hash_init()

void av_hash_init | ( | struct AVHashContext * | ctx | ) |

Initialize or reset a hash context.

Parameters

  [in,out] | ctx | Hash context

Examples
  ffhash.c.

## av_hash_update()

void av_hash_update | ( | struct AVHashContext * | ctx,
|  | const uint8_t * | src,
|  | size_t | len )

Update a hash context with additional data.

Parameters

  [in,out] | ctx | Hash context
  [in] | src | Data to be added to the hash context
  [in] | len | Size of the additional data

Examples
  ffhash.c.

## av_hash_final()

void av_hash_final | ( | struct AVHashContext * | ctx,
|  | uint8_t * | dst )

Finalize a hash context and compute the actual hash value.

The minimum size of dst buffer is given by av_hash_get_size() or AV_HASH_MAX_SIZE. The use of the latter macro is discouraged.

It is not safe to update or finalize a hash context again, if it has already been finalized.

Parameters

  [in,out] | ctx | Hash context
  [out] | dst | Where the final hash value will be stored

See also
  av_hash_final_bin() provides an alternative API

## av_hash_final_bin()

void av_hash_final_bin | ( | struct AVHashContext * | ctx,
|  | uint8_t * | dst,
|  | int | size )

Finalize a hash context and store the actual hash value in a buffer.

It is not safe to update or finalize a hash context again, if it has already been finalized.

If size is smaller than the hash size (given by av_hash_get_size()), the hash is truncated; if size is larger, the buffer is padded with 0.

Parameters

  [in,out] | ctx | Hash context
  [out] | dst | Where the final hash value will be stored
  [in] | size | Number of bytes to write to dst

## av_hash_final_hex()

void av_hash_final_hex | ( | struct AVHashContext * | ctx,
|  | uint8_t * | dst,
|  | int | size )

Finalize a hash context and store the hexadecimal representation of the actual hash value as a string.

It is not safe to update or finalize a hash context again, if it has already been finalized.

The string is always 0-terminated.

If size is smaller than 2 * hash_size + 1, where hash_size is the value returned by av_hash_get_size(), the string will be truncated.

Parameters

  [in,out] | ctx | Hash context
  [out] | dst | Where the string will be stored
  [in] | size | Maximum number of bytes to write to dst

Examples
  ffhash.c.

## av_hash_final_b64()

void av_hash_final_b64 | ( | struct AVHashContext * | ctx,
|  | uint8_t * | dst,
|  | int | size )

Finalize a hash context and store the Base64 representation of the actual hash value as a string.

It is not safe to update or finalize a hash context again, if it has already been finalized.

The string is always 0-terminated.

If size is smaller than AV_BASE64_SIZE(hash_size), where hash_size is the value returned by av_hash_get_size(), the string will be truncated.

Parameters

  [in,out] | ctx | Hash context
  [out] | dst | Where the final hash value will be stored
  [in] | size | Maximum number of bytes to write to dst

Examples
  ffhash.c.

## av_hash_freep()

void av_hash_freep | ( | struct AVHashContext ** | ctx | ) |

Free hash context and set hash context pointer to NULL.

Parameters

  [in,out] | ctx | Pointer to hash context

Examples
  ffhash.c.