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