minizip-ng Documentation

Table of Contents

• API
• Limitations
• Xcode Instructions
• Zlib Configuration
• Upgrading from 1.x
• Security Considerations
• Using Streams
  • Memory Stream
  • Buffered Stream
  • Disk Splitting Stream
  • Additional Code Examples

API

Constants

Interfaces

Structures

Extrafield Proposals

The zip reader and writer interface provides support for extended hash algorithms for zip entries, compression of the central directory, and the adding and verifying of CMS signatures for each entry. In order to add support for these features, extrafields were added and are described in the minizip extrafield documentation.

Limitations

• Archives are required to have a central directory unless recovery mode is enabled.
• Central directory header values should be correct and it is necessary for the compressed size to be accurate for encryption.
• Central directory is the only data stored on the last disk of a split-disk archive and doesn't follow disk size restrictions.

Third-Party Limitations

• Windows Explorer zip extraction utility does not support disk splitting. 1
• macOS archive utility does not properly support ZIP files over 4GB. 1 2

Xcode Instructions

To create an Xcode project with CMake use:

cmake -G Xcode .

Zlib Configuration

By default, if zlib is not found, it will be pulled as an external project and installed. This requires Git to be installed and available to your command interpreter.

• To specify your own zlib repository use ZLIB_REPOSITORY and/or ZLIB_TAG.
• To specify your own zlib installation use ZLIB_LIBRARY and ZLIB_INCLUDE_DIR.

Compiling with Zlib-ng

To compile using zlib-ng use the following cmake args:

-DZLIB_REPOSITORY=https://github.com/zlib-ng/zlib-ng -DZLIB_TAG=develop

Compiling and Installing Zlib (Windows)

To compile and install zlib to the Program Files directory with an Administrator command prompt:

cmake -DCMAKE_INSTALL_PREFIX="C:\Program Files (x86)\zlib" .
cmake --build . --config Release --target INSTALL

Configure Existing Zlib Installation (Windows)

To configure cmake with an existing zlib installation point cmake to your install directories:

cmake -DZLIB_LIBRARY:FILEPATH="C:\Program Files (x86)\zlib\lib\zlibstaticd.lib" .
cmake -DZLIB_INCLUDE_DIR:PATH="C:\Program Files (x86)\zlib\include" .

Upgrading from 1.x

If you are using CMAKE it will automatically include all the files and define all the #defines required based on your configuration and it will also build the project files necessary for your platform.

However, for some projects it may be necessary to drop in the new files into an existing project. In that instance, some #defines will have to be set as they have changed.

At a minimum HAVE_ZLIB and HAVE_PKCRYPT will be necessary to be defined for drop-in replacement. To determine which files to drop in, see the Contents section of the README.

Security Considerations

WinZip AES

When compressing an archive with WinZIP AES enabled, by default it uses 256 bit encryption. During decompression whatever bit encryption was specified when the entry was added to the archive will be used.

WinZip AES encryption uses CTR on top of ECB which prevents identical ciphertext blocks that might occur when using ECB by itself. More details about the WinZIP AES format can be found in the winzip documentation.

How to Create a Secure Zip

In order to create a secure zip file you must:

• Use WinZIP AES encryption
• Zip the central directory
• Sign the zip file using a certificate

The combination of using AES encryption and zipping the central directory prevents data leakage through filename exposure.

Using Streams

All input/output operations are done through the use of streams.

Memory Stream

To unzip from a zip file in memory pass the memory stream to the open function.

uint8_t *zip_buffer = NULL;
int32_t zip_buffer_size = 0;
void *mem_stream = NULL;
void *zip_handle = NULL;

/* TODO: fill zip_buffer with zip contents.. */

mz_stream_mem_create(&mem_stream);
mz_stream_mem_set_buffer(mem_stream, zip_buffer, zip_buffer_size);
mz_stream_open(mem_stream, NULL, MZ_OPEN_MODE_READ);

mz_zip_create(&zip_handle);
err = mz_zip_open(zip_handle, mem_stream, MZ_OPEN_MODE_READ);

/* TODO: unzip operations.. */

mz_zip_close(zip_handle);
mz_zip_delete(&zip_handle);

mz_stream_mem_delete(&mem_stream);

To create a zip file in memory first create a growable memory stream and pass it to the open function.

void *mem_stream = NULL;
void *zip_handle = NULL;

mz_stream_mem_create(&mem_stream);
mz_stream_mem_set_grow_size(mem_stream, (128 * 1024));
mz_stream_open(mem_stream, NULL, MZ_OPEN_MODE_CREATE);

mz_zip_create(&zip_handle);
err = mz_zip_open(zip_handle, mem_stream, MZ_OPEN_MODE_WRITE);

/* TODO: unzip operations.. */

mz_zip_close(zip_handle);
mz_zip_delete(&zip_handle);

mz_stream_mem_delete(&mem_stream);

For a complete example, see test_stream_mem() in test.c.

Buffered Stream

By default the library will read bytes typically one at a time. The buffered stream allows for buffered read and write operations to improve I/O performance.

void *stream = NULL;
void *buf_stream = NULL;
void *zip_handle = NULL;

mz_stream_os_create(&stream)

/* TODO: open os stream.. */

mz_stream_buffered_create(&buf_stream);
mz_stream_buffered_open(buf_stream, NULL, MZ_OPEN_MODE_READ);
mz_stream_buffered_set_base(buf_stream, stream);

mz_zip_create(&zip_handle);
err = mz_zip_open(zip_handle, buf_stream, MZ_OPEN_MODE_READ);

/* TODO: unzip operation.. */

mz_zip_close(zip_handle);
mz_zip_delete(&zip_handle);

mz_stream_buffered_delete(&buf_stream);

Disk Splitting Stream

To create an archive with multiple disks use the disk splitting stream and supply a disk size value in bytes.

void *stream = NULL;
void *split_stream = NULL;
void *zip_handle = NULL;

mz_stream_os_create(&stream);

mz_stream_split_create(&split_stream);
mz_stream_split_set_prop_int64(split_stream, MZ_STREAM_PROP_DISK_SIZE, 64 * 1024);
mz_stream_set_base(split_stream, stream);
mz_stream_open(split_stream, path..

mz_zip_create(&zip_handle);
err = mz_zip_open(zip_handle, split_stream, MZ_OPEN_MODE_WRITE);

/* TODO: unzip operation.. */

mz_zip_close(zip_handle);
mz_zip_delete(&zip_handle);

mz_stream_buffered_delete(&split_stream);

Additional Code Examples

Some of these may be out of date, but they can also be helpful.

• Compressed stream tests
• Code to copy raw entries from one zip file to another by chenxiaolong
• Buffered streaming by chenxiaolong