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