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