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 */
26typedef 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 */
85extern 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 */
102extern 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 */
126extern 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 */
147extern 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 */
163extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm)
164 lzma_nothrow;
165

source code of include/lzma/check.h