src/liblzma/api/lzma/check.h

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