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