1 /* 2 * Copyright (C) 2013 Reimar Döffinger <Reimar.Doeffinger@gmx.de> 3 * 4 * This file is part of FFmpeg. 5 * 6 * FFmpeg is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * FFmpeg is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with FFmpeg; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 /** 22 * @file 23 * @ingroup lavu_hash_generic 24 * Generic hashing API 25 */ 26 27 #ifndef AVUTIL_HASH_H 28 #define AVUTIL_HASH_H 29 30 #include <stddef.h> 31 #include <stdint.h> 32 33 #include "version.h" 34 35 /** 36 * @defgroup lavu_hash Hash Functions 37 * @ingroup lavu_crypto 38 * Hash functions useful in multimedia. 39 * 40 * Hash functions are widely used in multimedia, from error checking and 41 * concealment to internal regression testing. libavutil has efficient 42 * implementations of a variety of hash functions that may be useful for 43 * FFmpeg and other multimedia applications. 44 * 45 * @{ 46 * 47 * @defgroup lavu_hash_generic Generic Hashing API 48 * An abstraction layer for all hash functions supported by libavutil. 49 * 50 * If your application needs to support a wide range of different hash 51 * functions, then the Generic Hashing API is for you. It provides a generic, 52 * reusable API for @ref lavu_hash "all hash functions" implemented in libavutil. 53 * If you just need to use one particular hash function, use the @ref lavu_hash 54 * "individual hash" directly. 55 * 56 * @section Sample Code 57 * 58 * A basic template for using the Generic Hashing API follows: 59 * 60 * @code 61 * struct AVHashContext *ctx = NULL; 62 * const char *hash_name = NULL; 63 * uint8_t *output_buf = NULL; 64 * 65 * // Select from a string returned by av_hash_names() 66 * hash_name = ...; 67 * 68 * // Allocate a hash context 69 * ret = av_hash_alloc(&ctx, hash_name); 70 * if (ret < 0) 71 * return ret; 72 * 73 * // Initialize the hash context 74 * av_hash_init(ctx); 75 * 76 * // Update the hash context with data 77 * while (data_left) { 78 * av_hash_update(ctx, data, size); 79 * } 80 * 81 * // Now we have no more data, so it is time to finalize the hash and get the 82 * // output. But we need to first allocate an output buffer. Note that you can 83 * // use any memory allocation function, including malloc(), not just 84 * // av_malloc(). 85 * output_buf = av_malloc(av_hash_get_size(ctx)); 86 * if (!output_buf) 87 * return AVERROR(ENOMEM); 88 * 89 * // Finalize the hash context. 90 * // You can use any of the av_hash_final*() functions provided, for other 91 * // output formats. If you do so, be sure to adjust the memory allocation 92 * // above. See the function documentation below for the exact amount of extra 93 * // memory needed. 94 * av_hash_final(ctx, output_buffer); 95 * 96 * // Free the context 97 * av_hash_freep(&ctx); 98 * @endcode 99 * 100 * @section Hash Function-Specific Information 101 * If the CRC32 hash is selected, the #AV_CRC_32_IEEE polynomial will be 102 * used. 103 * 104 * If the Murmur3 hash is selected, the default seed will be used. See @ref 105 * lavu_murmur3_seedinfo "Murmur3" for more information. 106 * 107 * @{ 108 */ 109 110 /** 111 * @example ffhash.c 112 * This example is a simple command line application that takes one or more 113 * arguments. It demonstrates a typical use of the hashing API with allocation, 114 * initialization, updating, and finalizing. 115 */ 116 117 struct AVHashContext; 118 119 /** 120 * Allocate a hash context for the algorithm specified by name. 121 * 122 * @return >= 0 for success, a negative error code for failure 123 * 124 * @note The context is not initialized after a call to this function; you must 125 * call av_hash_init() to do so. 126 */ 127 int av_hash_alloc(struct AVHashContext **ctx, const char *name); 128 129 /** 130 * Get the names of available hash algorithms. 131 * 132 * This function can be used to enumerate the algorithms. 133 * 134 * @param[in] i Index of the hash algorithm, starting from 0 135 * @return Pointer to a static string or `NULL` if `i` is out of range 136 */ 137 const char *av_hash_names(int i); 138 139 /** 140 * Get the name of the algorithm corresponding to the given hash context. 141 */ 142 const char *av_hash_get_name(const struct AVHashContext *ctx); 143 144 /** 145 * Maximum value that av_hash_get_size() will currently return. 146 * 147 * You can use this if you absolutely want or need to use static allocation for 148 * the output buffer and are fine with not supporting hashes newly added to 149 * libavutil without recompilation. 150 * 151 * @warning 152 * Adding new hashes with larger sizes, and increasing the macro while doing 153 * so, will not be considered an ABI change. To prevent your code from 154 * overflowing a buffer, either dynamically allocate the output buffer with 155 * av_hash_get_size(), or limit your use of the Hashing API to hashes that are 156 * already in FFmpeg during the time of compilation. 157 */ 158 #define AV_HASH_MAX_SIZE 64 159 160 /** 161 * Get the size of the resulting hash value in bytes. 162 * 163 * The maximum value this function will currently return is available as macro 164 * #AV_HASH_MAX_SIZE. 165 * 166 * @param[in] ctx Hash context 167 * @return Size of the hash value in bytes 168 */ 169 int av_hash_get_size(const struct AVHashContext *ctx); 170 171 /** 172 * Initialize or reset a hash context. 173 * 174 * @param[in,out] ctx Hash context 175 */ 176 void av_hash_init(struct AVHashContext *ctx); 177 178 /** 179 * Update a hash context with additional data. 180 * 181 * @param[in,out] ctx Hash context 182 * @param[in] src Data to be added to the hash context 183 * @param[in] len Size of the additional data 184 */ 185 #if FF_API_CRYPTO_SIZE_T 186 void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, int len); 187 #else 188 void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, size_t len); 189 #endif 190 191 /** 192 * Finalize a hash context and compute the actual hash value. 193 * 194 * The minimum size of `dst` buffer is given by av_hash_get_size() or 195 * #AV_HASH_MAX_SIZE. The use of the latter macro is discouraged. 196 * 197 * It is not safe to update or finalize a hash context again, if it has already 198 * been finalized. 199 * 200 * @param[in,out] ctx Hash context 201 * @param[out] dst Where the final hash value will be stored 202 * 203 * @see av_hash_final_bin() provides an alternative API 204 */ 205 void av_hash_final(struct AVHashContext *ctx, uint8_t *dst); 206 207 /** 208 * Finalize a hash context and store the actual hash value in a buffer. 209 * 210 * It is not safe to update or finalize a hash context again, if it has already 211 * been finalized. 212 * 213 * If `size` is smaller than the hash size (given by av_hash_get_size()), the 214 * hash is truncated; if size is larger, the buffer is padded with 0. 215 * 216 * @param[in,out] ctx Hash context 217 * @param[out] dst Where the final hash value will be stored 218 * @param[in] size Number of bytes to write to `dst` 219 */ 220 void av_hash_final_bin(struct AVHashContext *ctx, uint8_t *dst, int size); 221 222 /** 223 * Finalize a hash context and store the hexadecimal representation of the 224 * actual hash value as a string. 225 * 226 * It is not safe to update or finalize a hash context again, if it has already 227 * been finalized. 228 * 229 * The string is always 0-terminated. 230 * 231 * If `size` is smaller than `2 * hash_size + 1`, where `hash_size` is the 232 * value returned by av_hash_get_size(), the string will be truncated. 233 * 234 * @param[in,out] ctx Hash context 235 * @param[out] dst Where the string will be stored 236 * @param[in] size Maximum number of bytes to write to `dst` 237 */ 238 void av_hash_final_hex(struct AVHashContext *ctx, uint8_t *dst, int size); 239 240 /** 241 * Finalize a hash context and store the Base64 representation of the 242 * actual hash value as a string. 243 * 244 * It is not safe to update or finalize a hash context again, if it has already 245 * been finalized. 246 * 247 * The string is always 0-terminated. 248 * 249 * If `size` is smaller than AV_BASE64_SIZE(hash_size), where `hash_size` is 250 * the value returned by av_hash_get_size(), the string will be truncated. 251 * 252 * @param[in,out] ctx Hash context 253 * @param[out] dst Where the final hash value will be stored 254 * @param[in] size Maximum number of bytes to write to `dst` 255 */ 256 void av_hash_final_b64(struct AVHashContext *ctx, uint8_t *dst, int size); 257 258 /** 259 * Free hash context and set hash context pointer to `NULL`. 260 * 261 * @param[in,out] ctx Pointer to hash context 262 */ 263 void av_hash_freep(struct AVHashContext **ctx); 264 265 /** 266 * @} 267 * @} 268 */ 269 270 #endif /* AVUTIL_HASH_H */ 271