include/lzma/check.h

0001 /* SPDX-License-Identifier: 0BSD */
0002
0003 /**
0004  * \file        lzma/check.h
0005  * \brief       Integrity checks
0006  * \note        Never include this file directly. Use <lzma.h> instead.
0007  */
0008
0009 /*
0010  * Author: Lasse Collin
0011  */
0012
0013 #ifndef LZMA_H_INTERNAL
0014 #   error Never include this file directly. Use <lzma.h> instead.
0015 #endif
0016
0017
0018 /**
0019  * \brief       Type of the integrity check (Check ID)
0020  *
0021  * The .xz format supports multiple types of checks that are calculated
0022  * from the uncompressed data. They vary in both speed and ability to
0023  * detect errors.
0024  */
0025 typedef enum {
0026     LZMA_CHECK_NONE     = 0,
0027         /**<
0028          * No Check is calculated.
0029          *
0030          * Size of the Check field: 0 bytes
0031          */
0032
0033     LZMA_CHECK_CRC32    = 1,
0034         /**<
0035          * CRC32 using the polynomial from the IEEE 802.3 standard
0036          *
0037          * Size of the Check field: 4 bytes
0038          */
0039
0040     LZMA_CHECK_CRC64    = 4,
0041         /**<
0042          * CRC64 using the polynomial from the ECMA-182 standard
0043          *
0044          * Size of the Check field: 8 bytes
0045          */
0046
0047     LZMA_CHECK_SHA256   = 10
0048         /**<
0049          * SHA-256
0050          *
0051          * Size of the Check field: 32 bytes
0052          */
0053 } lzma_check;
0054
0055
0056 /**
0057  * \brief       Maximum valid Check ID
0058  *
0059  * The .xz file format specification specifies 16 Check IDs (0-15). Some
0060  * of them are only reserved, that is, no actual Check algorithm has been
0061  * assigned. When decoding, liblzma still accepts unknown Check IDs for
0062  * future compatibility. If a valid but unsupported Check ID is detected,
0063  * liblzma can indicate a warning; see the flags LZMA_TELL_NO_CHECK,
0064  * LZMA_TELL_UNSUPPORTED_CHECK, and LZMA_TELL_ANY_CHECK in container.h.
0065  */
0066 #define LZMA_CHECK_ID_MAX 15
0067
0068
0069 /**
0070  * \brief       Test if the given Check ID is supported
0071  *
0072  * LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always supported (even if
0073  * liblzma is built with limited features).
0074  *
0075  * \note        It is safe to call this with a value that is not in the
0076  *              range [0, 15]; in that case the return value is always false.
0077  *
0078  * \param       check   Check ID
0079  *
0080  * \return      lzma_bool:
0081  *              - true if Check ID is supported by this liblzma build.
0082  *              - false otherwise.
0083  */
0084 extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
0085         lzma_nothrow lzma_attr_const;
0086
0087
0088 /**
0089  * \brief       Get the size of the Check field with the given Check ID
0090  *
0091  * Although not all Check IDs have a check algorithm associated, the size of
0092  * every Check is already frozen. This function returns the size (in bytes) of
0093  * the Check field with the specified Check ID. The values are:
0094  * { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }
0095  *
0096  * \param       check   Check ID
0097  *
0098  * \return      Size of the Check field in bytes. If the argument is not in
0099  *              the range [0, 15], UINT32_MAX is returned.
0100  */
0101 extern LZMA_API(uint32_t) lzma_check_size(lzma_check check)
0102         lzma_nothrow lzma_attr_const;
0103
0104
0105 /**
0106  * \brief       Maximum size of a Check field
0107  */
0108 #define LZMA_CHECK_SIZE_MAX 64
0109
0110
0111 /**
0112  * \brief       Calculate CRC32
0113  *
0114  * Calculate CRC32 using the polynomial from the IEEE 802.3 standard.
0115  *
0116  * \param       buf     Pointer to the input buffer
0117  * \param       size    Size of the input buffer
0118  * \param       crc     Previously returned CRC value. This is used to
0119  *                      calculate the CRC of a big buffer in smaller chunks.
0120  *                      Set to zero when starting a new calculation.
0121  *
0122  * \return      Updated CRC value, which can be passed to this function
0123  *              again to continue CRC calculation.
0124  */
0125 extern LZMA_API(uint32_t) lzma_crc32(
0126         const uint8_t *buf, size_t size, uint32_t crc)
0127         lzma_nothrow lzma_attr_pure;
0128
0129
0130 /**
0131  * \brief       Calculate CRC64
0132  *
0133  * Calculate CRC64 using the polynomial from the ECMA-182 standard.
0134  *
0135  * This function is used similarly to lzma_crc32().
0136  *
0137  * \param       buf     Pointer to the input buffer
0138  * \param       size    Size of the input buffer
0139  * \param       crc     Previously returned CRC value. This is used to
0140  *                      calculate the CRC of a big buffer in smaller chunks.
0141  *                      Set to zero when starting a new calculation.
0142  *
0143  * \return      Updated CRC value, which can be passed to this function
0144  *              again to continue CRC calculation.
0145  */
0146 extern LZMA_API(uint64_t) lzma_crc64(
0147         const uint8_t *buf, size_t size, uint64_t crc)
0148         lzma_nothrow lzma_attr_pure;
0149
0150
0151 /**
0152  * \brief       Get the type of the integrity check
0153  *
0154  * This function can be called only immediately after lzma_code() has
0155  * returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK.
0156  * Calling this function in any other situation has undefined behavior.
0157  *
0158  * \param       strm    Pointer to lzma_stream meeting the above conditions.
0159  *
0160  * \return      Check ID in the lzma_stream, or undefined if called improperly.
0161  */
0162 extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm)
0163         lzma_nothrow;