include/vlc_hash.h

   1 /*****************************************************************************
   2  * vlc_hash.h: Hash functions
   3  *****************************************************************************
   4  * Copyright © 2004-2020 VLC authors and VideoLAN
   5  *
   6  * Authors: Rémi Denis-Courmont
   7  *          Rafaël Carré
   8  *          Marvin Scholz
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef VLC_HASH_H
  26 # define VLC_HASH_H
  27
  28 /**
  29  * \defgroup vlc_hash  Hash functions
  30  * APIs for simple and frequently used hash algorithms in VLC
  31  *
  32  * Each hash algorithm has a context object which stores all data needed for the
  33  * hash calculation, this context is not supposed to be modified directly by the
  34  * called but only with the functions listed here.
  35  *
  36  * Supported hash algorithms:
  37  *   - \ref vlc_hash_md5 "MD5"
  38  *
  39  * @{
  40  */
  41
  42 /**
  43  * \defgroup vlc_hash_utils  Helper functions
  44  * Functions commonly used together with hashing functions
  45  * @{
  46  */
  47
  48 /**
  49  * Finish hash computation and return hex representation
  50  *
  51  * Finishes the hash computation and provides the hash for the
  52  * concatenation of all provided data in hex encoded format.
  53  * The result is written to the buffer pointed to by output, which
  54  * must be larger than twice the size of the hash output.
  55  *
  56  * \param[in,out] ctx    Hash context to finish
  57  * \param[out]    output Output buffer to write the string to
  58  */
  59 #ifndef __cplusplus
  60 #define vlc_hash_FinishHex(ctx, output)                             \
  61     do {                                                            \
  62         char out_tmp[_Generic((ctx),                                \
  63             vlc_hash_md5_t *: VLC_HASH_MD5_DIGEST_SIZE)];           \
  64         _Generic((ctx),                                             \
  65             vlc_hash_md5_t *: vlc_hash_md5_Finish)                  \
  66         (ctx, out_tmp, sizeof(out_tmp));                            \
  67         vlc_hex_encode_binary(out_tmp, sizeof(out_tmp), output);    \
  68     } while (0)
  69 #endif
  70
  71 /**
  72  * @}
  73  */
  74
  75 /**
  76  * \defgroup vlc_hash_md5  MD5 hashing
  77  * APIs to hash data using the Message-Digest Algorithm 5 (MD5)
  78  * @{
  79  */
  80
  81 /**
  82  * MD5 hash context
  83  */
  84 typedef struct vlc_hash_md5_ctx
  85 {
  86     struct md5_s {
  87         uint32_t A, B, C, D; /* chaining variables */
  88         uint32_t nblocks;
  89         uint8_t buf[64];
  90         int count;
  91     } priv; /**< \internal Private */
  92 } vlc_hash_md5_t;
  93
  94 /**
  95  * MD5 digest output size
  96  */
  97 #define VLC_HASH_MD5_DIGEST_SIZE 16
  98
  99 /**
 100  * MD5 digest hex representation size
 101  */
 102 #define VLC_HASH_MD5_DIGEST_HEX_SIZE 33 // 2 chars per byte + null
 103
 104 /**
 105  * Initialize MD5 context
 106  *
 107  * Initializes the given MD5 hash function context, if the context is
 108  * already initialized, it is reset.
 109  *
 110  * \param[out] ctx  MD5 hash context to init
 111  */
 112 VLC_API void vlc_hash_md5_Init(vlc_hash_md5_t *ctx);
 113
 114 /**
 115  * Update MD5 hash computation with new data
 116  *
 117  * Updates the context with provided data which is used for the hash
 118  * calculation. Can be called repeatedly with new data. The final
 119  * hash represents the hash for the concatenation of all data.
 120  *
 121  * \param[in,out] ctx    MD5 hash context to update
 122  * \param         data   Data to add
 123  * \param         size   Size of the data to add
 124  */
 125 VLC_API void vlc_hash_md5_Update(vlc_hash_md5_t *ctx, const void *data, size_t size);
 126
 127 /**
 128  * Finish MD5 hash computation
 129  *
 130  * Finishes the MD5 hash computation and provides the hash for the
 131  * concatenation of all provided data by previous calls to \ref vlc_hash_md5_Update.
 132  * The result is written to the buffer pointed to by output, which must be at
 133  * least \ref VLC_HASH_MD5_DIGEST_SIZE big.
 134  *
 135  * \param[in,out] ctx    MD5 hash context to finish
 136  * \param[out]    output Output buffer to write to
 137  * \param         size   Output buffer size
 138  */
 139 VLC_API void vlc_hash_md5_Finish(vlc_hash_md5_t *ctx, void *output, size_t size);
 140
 141 /**
 142  * @}
 143  */
 144
 145 /**
 146  * @}
 147  */
 148
 149 #endif