src/liblzma/api/lzma/check.h

   1 /**
   2  * \file        lzma/check.h
   3  * \brief       Integrity checks
   4  */
   5
   6 /*
   7  * Author: Lasse Collin
   8  *
   9  * This file has been put into the public domain.
  10  * You can do whatever you want with this file.
  11  *
  12  * See ../lzma.h for information about liblzma as a whole.
  13  */
  14
  15 #ifndef LZMA_H_INTERNAL
  16 #       error Never include this file directly. Use <lzma.h> instead.
  17 #endif
  18
  19
  20 /**
  21  * \brief       Type of the integrity check (Check ID)
  22  *
  23  * The .xz format supports multiple types of checks that are calculated
  24  * from the uncompressed data. They vary in both speed and ability to
  25  * detect errors.
  26  */
  27 typedef enum {
  28         LZMA_CHECK_NONE     = 0,
  29                 /**<
  30                  * No Check is calculated.
  31                  *
  32                  * Size of the Check field: 0 bytes
  33                  */
  34
  35         LZMA_CHECK_CRC32    = 1,
  36                 /**<
  37                  * CRC32 using the polynomial from the IEEE 802.3 standard
  38                  *
  39                  * Size of the Check field: 4 bytes
  40                  */
  41
  42         LZMA_CHECK_CRC64    = 4,
  43                 /**<
  44                  * CRC64 using the polynomial from the ECMA-182 standard
  45                  *
  46                  * Size of the Check field: 8 bytes
  47                  */
  48
  49         LZMA_CHECK_SHA256   = 10
  50                 /**<
  51                  * SHA-256
  52                  *
  53                  * Size of the Check field: 32 bytes
  54                  */
  55 } lzma_check;
  56
  57
  58 /**
  59  * \brief       Maximum valid Check ID
  60  *
  61  * The .xz file format specification specifies 16 Check IDs (0-15). Some
  62  * of them are only reserved, that is, no actual Check algorithm has been
  63  * assigned. When decoding, liblzma still accepts unknown Check IDs for
  64  * future compatibility. If a valid but unsupported Check ID is detected,
  65  * liblzma can indicate a warning; see the flags LZMA_TELL_NO_CHECK,
  66  * LZMA_TELL_UNSUPPORTED_CHECK, and LZMA_TELL_ANY_CHECK in container.h.
  67  */
  68 #define LZMA_CHECK_ID_MAX 15
  69
  70
  71 /**
  72  * \brief       Test if the given Check ID is supported
  73  *
  74  * Return true if the given Check ID is supported by this liblzma build.
  75  * Otherwise false is returned. It is safe to call this with a value that
  76  * is not in the range [0, 15]; in that case the return value is always false.
  77  *
  78  * You can assume that LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always
  79  * supported (even if liblzma is built with limited features).
  80  */
  81 extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
  82                 lzma_nothrow lzma_attr_const;
  83
  84
  85 /**
  86  * \brief       Get the size of the Check field with the given Check ID
  87  *
  88  * Although not all Check IDs have a check algorithm associated, the size of
  89  * every Check is already frozen. This function returns the size (in bytes) of
  90  * the Check field with the specified Check ID. The values are:
  91  * { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }
  92  *
  93  * If the argument is not in the range [0, 15], UINT32_MAX is returned.
  94  */
  95 extern LZMA_API(uint32_t) lzma_check_size(lzma_check check)
  96                 lzma_nothrow lzma_attr_const;
  97
  98
  99 /**
 100  * \brief       Maximum size of a Check field
 101  */
 102 #define LZMA_CHECK_SIZE_MAX 64
 103
 104
 105 /**
 106  * \brief       Calculate CRC32
 107  *
 108  * Calculate CRC32 using the polynomial from the IEEE 802.3 standard.
 109  *
 110  * \param       buf     Pointer to the input buffer
 111  * \param       size    Size of the input buffer
 112  * \param       crc     Previously returned CRC value. This is used to
 113  *                      calculate the CRC of a big buffer in smaller chunks.
 114  *                      Set to zero when starting a new calculation.
 115  *
 116  * \return      Updated CRC value, which can be passed to this function
 117  *              again to continue CRC calculation.
 118  */
 119 extern LZMA_API(uint32_t) lzma_crc32(
 120                 const uint8_t *buf, size_t size, uint32_t crc)
 121                 lzma_nothrow lzma_attr_pure;
 122
 123
 124 /**
 125  * \brief       Calculate CRC64
 126  *
 127  * Calculate CRC64 using the polynomial from the ECMA-182 standard.
 128  *
 129  * This function is used similarly to lzma_crc32(). See its documentation.
 130  */
 131 extern LZMA_API(uint64_t) lzma_crc64(
 132                 const uint8_t *buf, size_t size, uint64_t crc)
 133                 lzma_nothrow lzma_attr_pure;
 134
 135
 136 /*
 137  * SHA-256 functions are currently not exported to public API.
 138  * Contact Lasse Collin if you think it should be.
 139  */
 140
 141
 142 /**
 143  * \brief       Get the type of the integrity check
 144  *
 145  * This function can be called only immediately after lzma_code() has
 146  * returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK.
 147  * Calling this function in any other situation has undefined behavior.
 148  */
 149 extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm)
 150                 lzma_nothrow;