include/lzma/check.h

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