check.h revision 259065
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 */ 27typedef 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 */ 81extern 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 */ 95extern 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 */ 119extern 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 */ 131extern 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 */ 149extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm) 150 lzma_nothrow; 151