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