clamav/libclamav/unzip.h

/*
 *  Copyright (C) 2013-2025 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
 *  Copyright (C) 2007-2013 Sourcefire, Inc.
 *
 *  Authors: Alberto Wu
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License version 2 as
 *  published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 *  MA 02110-1301, USA.
 */

/*
 * General Structure for PKZIP files:
 * +---------------------------------------------------------------+
 * | Local file header 1                                           |
 * +---------------------------------------------------------------+
 * | File data 1                                                   |
 * +---------------------------------------------------------------+
 * | Data descriptor 1 (optional)                                  |
 * +---------------------------------------------------------------+
 * | Local file header 2                                           |
 * +---------------------------------------------------------------+
 * | File data 2                                                   |
 * +---------------------------------------------------------------+
 * | Data descriptor 2 (optional)                                  |
 * +---------------------------------------------------------------+
 * | ...                                                           |
 * +---------------------------------------------------------------+
 * | Local file header N                                           |
 * +---------------------------------------------------------------+
 * | File data N                                                   |
 * +---------------------------------------------------------------+
 * | Data descriptor N (optional)                                  |
 * +---------------------------------------------------------------+
 * | Archive Decryption Header (optional, v6.2+)                   |
 * +---------------------------------------------------------------+
 * | Archive Extra Data Record (optional, v6.2+)                   |
 * +---------------------------------------------------------------+
 * | Central directory                                             |
 * +---------------------------------------------------------------+
 *
 * This and additional diagrams from courtesy of:
 * https://users.cs.jmu.edu/buchhofp/forensics/formats/pkzip.html
 *
 * See also:
 * https://www.pkware.com/documents/casestudies/APPNOTE.TXT
 *
 * And see also: unzip.h
 *
 * Note the diagrams and current implemementation do not implement all features.
 */

#ifndef __UNZIP_H
#define __UNZIP_H

#if HAVE_CONFIG_H
#include "clamav-config.h"
#endif

#include "others.h"

/**
 * @brief Callback function type for handling extracted files.
 *
 * The `unzip_single_internal` function lets you specify a callback function to handle the extracted file.
 * Other functions like `cli_unzip` and `cli_unzip_single` use `zip_scan_cb` as the default callback and
 * thus just scan the file.
 *
 * Note: The callback function must match the signature of `cli_magic_scan_desc`.
 */
typedef cl_error_t (*zip_cb)(int fd, const char *filepath, cli_ctx *ctx, const char *name, uint32_t attributes);
#define zip_scan_cb cli_magic_scan_desc

#define MAX_ZIP_REQUESTS 10

/**
 * @brief Structure to hold zip file search requests.
 *
 * This structure is used to hold multiple file names that we want to search for in a zip archive.
 * It is used by the `unzip_search` function.
 */
struct zip_requests {
    const char *names[MAX_ZIP_REQUESTS];
    size_t namelens[MAX_ZIP_REQUESTS];
    int namecnt;

    uint32_t loff;
    int found, match;
};

/**
 * @brief Unzip a zip file.
 *
 * Scan each extracted file.
 *
 * @param ctx                   The scan context containing the file map and other scan parameters.
 * @return cl_error_t           Returns CL_SUCCESS on success, or an error code on failure.
 */
cl_error_t cli_unzip(cli_ctx *ctx);

/**
 * @brief Unzip a single file from a zip archive.
 *
 * Scan the file after extracting it.
 *
 * @param ctx                   The scan context containing the file map and other scan parameters.
 * @param local_header_offset   The offset of the local file header in the zip archive.
 * @return cl_error_t           Returns CL_SUCCESS on success, or an error code on failure.
 */
cl_error_t cli_unzip_single(cli_ctx *ctx, size_t local_header_offset);

/**
 * @brief Verify a single local file header.
 *
 * Does not extract or scan the file.
 *
 * @param[in,out] ctx           Scan context
 * @param offset                Offset of the local file header
 * @param[out] size             Will be set to the size of the file header + file data.
 * @return cl_error_t           CL_SUCCESS on success, or an error code on failure.
 */
cl_error_t cli_unzip_single_header_check(cli_ctx *ctx, uint32_t offset, size_t *size);

/**
 * @brief Unzip a single file from a zip archive.
 *
 * Different from `cli_unzip_single`, this function allows for a custom callback to be used after extraction.
 * In other words, it can be used to extract a file without scanning it immediately.
 * This is useful for cases where you want to handle the file differently.
 *
 * @param ctx                   The scan context containing the file map and other scan parameters.
 * @param local_header_offset   The offset of the local file header in the zip archive.
 * @param zcb                   The callback function to invoke after extraction. See `zip_scan_cb`.
 * @return cl_error_t           Returns CL_SUCCESS on success, or an error code on failure.
 */
cl_error_t unzip_single_internal(cli_ctx *ctx, size_t local_header_offset, zip_cb zcb);

/**
 * @brief Add a file a bundle of files to search for in a zip archive.
 *
 * @param requests              The `zip_requests` structure to modify.
 * @param name                  The name of the file to add.
 * @param nlen                  The length of the file name.
 * @return cl_error_t           Returns CL_SUCCESS on success, or an error code on failure.
 */
cl_error_t unzip_search_add(struct zip_requests *requests, const char *name, size_t nlen);

/**
 * @brief Search for files in a zip archive.
 *
 * This function searches for one or more files in a zip archive and scans them.
 *
 * Disclaimer: As compared with `cli_unzip`, this function depends on the central directory header.
 *             It will not work correctly if the zip archive does not have a central directory header
 *             or the file you're looking for is not listed in the central directory.
 *
 * @param ctx                   The scan context containing the file map and other scan parameters.
 * @param requests              The `zip_requests` structure containing the files to search for.
 * @return cl_error_t           Returns CL_SUCCESS if nothing was found.
 *                              Returns CL_VIRUS if a match was found.
 *                              Returns a CL_E* error code on failure.
 */
cl_error_t unzip_search(cli_ctx *ctx, struct zip_requests *requests);

/**
 * @brief Search for a single file in a zip archive.
 *
 * This function searches for a single file in a zip archive.
 *
 * Disclaimer: As compared with `cli_unzip`, this function depends on the central directory header.
 *             It will not work correctly if the zip archive does not have a central directory header
 *             or the file you're looking for is not listed in the central directory.
 *
 * @param ctx                   The scan context containing the file map and other scan parameters.
 * @param name                  The name of the file to search for.
 * @param nlen                  The length of the file name.
 * @param loff                  The offset of the file in the zip archive.
 * @return cl_error_t           Returns CL_SUCCESS if nothing was found.
 *                              Returns CL_VIRUS if a match was found.
 *                              Returns a CL_E* error code on failure.
 */
cl_error_t unzip_search_single(cli_ctx *ctx, const char *name, size_t nlen, uint32_t *loff);

// clang-format off
#ifdef UNZIP_PRIVATE

#define F_ENCR  (1<<0)
#define F_ALGO1 (1<<1)
#define F_ALGO2 (1<<2)
#define F_USEDD (1<<3)
#define F_RSVD1 (1<<4)
#define F_PATCH (1<<5)
#define F_STRNG (1<<6)
#define F_UNUS1 (1<<7)
#define F_UNUS2 (1<<8)
#define F_UNUS3 (1<<9)
#define F_UNUS4 (1<<10)
#define F_UTF8  (1<<11)
#define F_RSVD2 (1<<12)
#define F_MSKED (1<<13)
#define F_RSVD3 (1<<14)
#define F_RSVD4 (1<<15)
// clang-format on

enum ALGO {
    ALG_STORED,
    ALG_SHRUNK,
    ALG_REDUCE1,
    ALG_REDUCE2,
    ALG_REDUCE3,
    ALG_REDUCE4,
    ALG_IMPLODE,
    ALG_TOKENZD,
    ALG_DEFLATE,
    ALG_DEFLATE64,
    ALG_OLDTERSE,
    ALG_RSVD1,
    ALG_BZIP2,
    ALG_RSVD2,
    ALG_LZMA,
    ALG_RSVD3,
    ALG_RSVD4,
    ALG_RSVD5,
    ALG_NEWTERSE,
    ALG_LZ77,
    ALG_WAVPACK = 97,
    ALG_PPMD
};

/*
 * Local File Header Structure:
 *
 *  0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
 * +---------------+-------+-------+-------+-------+-------+-------+
 * | P K 0x03 0x04 | Vers  | Flags | Compr |Mod Tm |Mod Dt | CRC 32|
 * +-------+-------+-------+-------+-------+-------+-------+-------+
 * | CRC 32| Compr Size    | Uncompr Size  |FName L|Extra L|       |
 * +-------+---------------+---------------+-------+-------+       +
 * | File Name (variable)                                          |
 * +---------------------------------------------------------------+
 * | Extra field (variable)                                        |
 * +---------------------------------------------------------------+
 */

// struct LH {
//   uint32_t magic;
//   uint16_t version;
//   uint16_t flags;
//   uint16_t method;
//   uint32_t mtime;
//   uint32_t crc32;
//   uint32_t csize;
//   uint32_t usize;
//   uint16_t flen;
//   uint16_t elen;
//   char fname[flen]
//   char extra[elen]
// } __attribute__((packed));

/*
 * Local File Header convenience macros:
 */
// clang-format off
#define LOCAL_HEADER_magic   ((uint32_t)cli_readint32((uint8_t *)(local_header)+0))
#define LOCAL_HEADER_version ((uint16_t)cli_readint16((uint8_t *)(local_header)+4))
#define LOCAL_HEADER_flags   ((uint16_t)cli_readint16((uint8_t *)(local_header)+6))
#define LOCAL_HEADER_method  ((uint16_t)cli_readint16((uint8_t *)(local_header)+8))
#define LOCAL_HEADER_mtime   ((uint32_t)cli_readint32((uint8_t *)(local_header)+10))
#define LOCAL_HEADER_crc32   ((uint32_t)cli_readint32((uint8_t *)(local_header)+14))
#define LOCAL_HEADER_csize   ((uint32_t)cli_readint32((uint8_t *)(local_header)+18))
#define LOCAL_HEADER_usize   ((uint32_t)cli_readint32((uint8_t *)(local_header)+22))
#define LOCAL_HEADER_flen    ((uint16_t)cli_readint16((uint8_t *)(local_header)+26))
#define LOCAL_HEADER_elen    ((uint16_t)cli_readint16((uint8_t *)(local_header)+28))
#define SIZEOF_LOCAL_HEADER 30
// clang-format on

/*
 * Central Directory Structure:
 *
 * +---------------------------------------------------------------+
 * | Central directory file header 1                               |
 * +---------------------------------------------------------------+
 * | Central directory file header 2                               |
 * +---------------------------------------------------------------+
 * | ...                                                           |
 * +---------------------------------------------------------------+
 * | Central directory file header N                               |
 * +---------------------------------------------------------------+
 * | Digital Signature                                             |
 * +---------------------------------------------------------------+
 * | Data descriptor N (optional)                                  |
 * +---------------------------------------------------------------+
 * | Zip64 end of central directory Record                         |
 * +---------------------------------------------------------------+
 * | Zip64 end of central directory locator                        |
 * +---------------------------------------------------------------+
 * | End of central directory record                               |
 * +---------------------------------------------------------------+
 *
 * Central Directory File Header structure:
 *
 *  0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
 * +---------------+-------+-------+-------+-------+-------+-------+
 * | P K 0x01 0x02 | Vers  |Vers Nd| Flags | Compr |Mod Tm |Mod Dt |
 * +---------------+-------+-------+-------+-------+-------+-------+
 * | CRC 32        | Compr Size    | Uncompr Size  |FName L|Extra L|
 * +---------------+-------+-------+-------+-------+-------+-------+
 * |F Com L|D #strt|IntAttr|Ext Attributes |Offset L Header|       |
 * +---------------+-----------------------+---------------+       +
 * | File Name (variable)                                          |
 * +---------------------------------------------------------------+
 * | Extra field (variable)                                        |
 * +---------------------------------------------------------------+
 * | File comment (variable)                                       |
 * +---------------------------------------------------------------+
 *
 * End of central directory record structure:
 *
 *  0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
 * +---------------+-------+-------+-------+-------+---------------+
 * | P K 0x05 0x06 |Disk # |Dsk#cd |DskEnts|T.Entrs|Central Dir Sz |
 * +---------------+-------+-------+-------+-------+---------------+
 * | Offset of CD  |CommLen| ZIP file comment (variable)           |
 * +---------------+-------+-------+-------+-------+-------+-------+
 */

// struct CH {
//   uint32_t magic;
//   uint16_t vermade;
//   uint16_t verneed;
//   uint16_t flags;
//   uint16_t method;
//   uint32_t mtime;
//   uint32_t crc32;
//   uint32_t csize;
//   uint32_t usize;
//   uint16_t flen;
//   uint16_t elen;
//   uint16_t clen;
//   uint16_t dsk;
//   uint16_t iattrib;
//   uint32_t eattrib;
//   uint32_t off;
//   char fname[flen]
//   char extra[elen]
//   char comment[clen]
// } __attribute__((packed));

/*
 * Central Directory File Header convenience macro's.
 */
// clang-format off
#define CENTRAL_HEADER_magic        ((uint32_t)cli_readint32((uint8_t *)(central_header)+0))
#define CENTRAL_HEADER_vermade      ((uint16_t)cli_readint16((uint8_t *)(central_header)+4))
#define CENTRAL_HEADER_verneed      ((uint16_t)cli_readint16((uint8_t *)(central_header)+6))
#define CENTRAL_HEADER_flags        ((uint16_t)cli_readint16((uint8_t *)(central_header)+8))
#define CENTRAL_HEADER_method       ((uint16_t)cli_readint16((uint8_t *)(central_header)+10))
#define CENTRAL_HEADER_mtime        ((uint32_t)cli_readint32((uint8_t *)(central_header)+12))
#define CENTRAL_HEADER_crc32        ((uint32_t)cli_readint32((uint8_t *)(central_header)+16))
#define CENTRAL_HEADER_csize        ((uint32_t)cli_readint32((uint8_t *)(central_header)+20))
#define CENTRAL_HEADER_usize        ((uint32_t)cli_readint32((uint8_t *)(central_header)+24))
#define CENTRAL_HEADER_flen         ((uint16_t)cli_readint16((uint8_t *)(central_header)+28))
#define CENTRAL_HEADER_extra_len    ((uint16_t)cli_readint16((uint8_t *)(central_header)+30))
#define CENTRAL_HEADER_comment_len  ((uint16_t)cli_readint16((uint8_t *)(central_header)+32))
#define CENTRAL_HEADER_disk_num     ((uint16_t)cli_readint16((uint8_t *)(central_header)+34))
#define CENTRAL_HEADER_iattrib      ((uint16_t)cli_readint16((uint8_t *)(central_header)+36))
#define CENTRAL_HEADER_eattrib      ((uint32_t)cli_readint32((uint8_t *)(central_header)+38))
#define CENTRAL_HEADER_off          ((uint32_t)cli_readint32((uint8_t *)(central_header)+42))
// clang-format on

#define SIZEOF_CENTRAL_HEADER 46    // Excluding variable size fields
#define SIZEOF_ENCRYPTION_HEADER 12 // Excluding variable size fields
#define SIZEOF_END_OF_CENTRAL 22    // Excluding variable size fields

#endif /* UNZIP_PRIVATE */

#endif /* __UNZIP_H */