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; 165