| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "ZIPDETAILS 1" |
| 58 |
.TH ZIPDETAILS 1 2026-04-10 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
zipdetails \- display the internal structure of zip files |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& zipdetails [options] zipfile.zip |
| 69 |
.Ve |
| 70 |
.SH DESCRIPTION |
| 71 |
.IX Header "DESCRIPTION" |
| 72 |
This program creates a detailed report on the internal structure of zip |
| 73 |
files. For each item of metadata within a zip file the program will output |
| 74 |
.IP "the offset into the zip file where the item is located." 5 |
| 75 |
.IX Item "the offset into the zip file where the item is located." |
| 76 |
.PD 0 |
| 77 |
.IP "a textual representation for the item." 5 |
| 78 |
.IX Item "a textual representation for the item." |
| 79 |
.IP "an optional hex dump of the item." 5 |
| 80 |
.IX Item "an optional hex dump of the item." |
| 81 |
.PD |
| 82 |
.PP |
| 83 |
The program assumes a prior understanding of the internal structure of Zip |
| 84 |
files. You should have a copy of the zip file definition, |
| 85 |
APPNOTE.TXT <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>, |
| 86 |
at hand to help understand the output from this program. |
| 87 |
.SS "Default Behaviour" |
| 88 |
.IX Subsection "Default Behaviour" |
| 89 |
By default the program expects to be given a well-formed zip file. It will |
| 90 |
navigate the zip file by first parsing the zip \f(CW\*(C`Central Directory\*(C'\fR at the end |
| 91 |
of the file. If the \f(CW\*(C`Central Directory\*(C'\fR is found, it will then walk |
| 92 |
sequentally through the zip records starting at the beginning of the file. |
| 93 |
See "Advanced Analysis" for other processing options. |
| 94 |
.PP |
| 95 |
If the program finds any structural or portability issues with the zip file |
| 96 |
it will print a message at the point it finds the issue and/or in a summary |
| 97 |
at the end of the output report. Whilst the set of issues that can be |
| 98 |
detected it exhaustive, don't assume that this program can find \fIall\fR the |
| 99 |
possible issues in a zip file \- there are likely edge conditions that need |
| 100 |
to be addressed. |
| 101 |
.PP |
| 102 |
If you have suggestions for use-cases where this could be enhanced please |
| 103 |
consider creating an enhancement request (see "SUPPORT"). |
| 104 |
.PP |
| 105 |
\fIDate & Time fields\fR |
| 106 |
.IX Subsection "Date & Time fields" |
| 107 |
.PP |
| 108 |
Date/time fields found in zip files are displayed in local time. Use the |
| 109 |
\&\f(CW\*(C`\-\-utc\*(C'\fR option to display these fields in Coordinated Universal Time (UTC). |
| 110 |
.PP |
| 111 |
\fIFilenames & Comments\fR |
| 112 |
.IX Subsection "Filenames & Comments" |
| 113 |
.PP |
| 114 |
Filenames and comments are decoded/encoded using the default system |
| 115 |
encoding of the host running \f(CW\*(C`zipdetails\*(C'\fR. When the sytem encoding cannot |
| 116 |
be determined \f(CW\*(C`cp437\*(C'\fR will be used. |
| 117 |
.PP |
| 118 |
The exceptions are |
| 119 |
.IP \(bu 5 |
| 120 |
when the \f(CW\*(C`Language Encoding Flag\*(C'\fR is set in the zip file, the |
| 121 |
filename/comment fields are assumed to be encoded in UTF\-8. |
| 122 |
.IP \(bu 5 |
| 123 |
the definition for the metadata field implies UTF\-8 charset encoding |
| 124 |
.PP |
| 125 |
See "Filename Encoding Issues" and "Filename & Comment Encoding |
| 126 |
Options" for ways to control the encoding of filename/comment fields. |
| 127 |
.SS OPTIONS |
| 128 |
.IX Subsection "OPTIONS" |
| 129 |
\fIGeneral Options\fR |
| 130 |
.IX Subsection "General Options" |
| 131 |
.ie n .IP """\-h"", ""\-\-help""" 5 |
| 132 |
.el .IP "\f(CW\-h\fR, \f(CW\-\-help\fR" 5 |
| 133 |
.IX Item "-h, --help" |
| 134 |
Display help |
| 135 |
.ie n .IP """\-\-redact""" 5 |
| 136 |
.el .IP \f(CW\-\-redact\fR 5 |
| 137 |
.IX Item "--redact" |
| 138 |
Obscure filenames and payload data in the output. Handy for the use case |
| 139 |
where the zip files contains sensitive data that cannot be shared. |
| 140 |
.ie n .IP """\-\-scan""" 5 |
| 141 |
.el .IP \f(CW\-\-scan\fR 5 |
| 142 |
.IX Item "--scan" |
| 143 |
Pessimistically scan the zip file loking for possible zip records. Can be |
| 144 |
error-prone. For very large zip files this option is slow. Consider using |
| 145 |
the \f(CW\*(C`\-\-walk\*(C'\fR option first. See "Advanced Analysis Options" |
| 146 |
.ie n .IP """\-\-utc""" 5 |
| 147 |
.el .IP \f(CW\-\-utc\fR 5 |
| 148 |
.IX Item "--utc" |
| 149 |
By default, date/time fields are displayed in local time. Use this option to |
| 150 |
display them in in Coordinated Universal Time (UTC). |
| 151 |
.ie n .IP """\-v""" 5 |
| 152 |
.el .IP \f(CW\-v\fR 5 |
| 153 |
.IX Item "-v" |
| 154 |
Enable Verbose mode. See "Verbose Output". |
| 155 |
.ie n .IP """\-\-version""" 5 |
| 156 |
.el .IP \f(CW\-\-version\fR 5 |
| 157 |
.IX Item "--version" |
| 158 |
Display version number of the program and exit. |
| 159 |
.ie n .IP """\-\-walk""" 5 |
| 160 |
.el .IP \f(CW\-\-walk\fR 5 |
| 161 |
.IX Item "--walk" |
| 162 |
Optimistically walk the zip file looking for possible zip records. |
| 163 |
See "Advanced Analysis Options" |
| 164 |
.PP |
| 165 |
\fIFilename & Comment Encoding Options\fR |
| 166 |
.IX Subsection "Filename & Comment Encoding Options" |
| 167 |
.PP |
| 168 |
See "Filename Encoding Issues" |
| 169 |
.ie n .IP """\-\-encoding name""" 5 |
| 170 |
.el .IP "\f(CW\-\-encoding name\fR" 5 |
| 171 |
.IX Item "--encoding name" |
| 172 |
Use encoding "name" when reading filenames/comments from the zip file. |
| 173 |
.Sp |
| 174 |
When this option is not specified the default the system encoding is used. |
| 175 |
.ie n .IP """ \-\-no\-encoding""" 5 |
| 176 |
.el .IP "\f(CW \-\-no\-encoding\fR" 5 |
| 177 |
.IX Item " --no-encoding" |
| 178 |
Disable all filename & comment encoding/decoding. Filenames/comments are |
| 179 |
processed as byte streams. |
| 180 |
.Sp |
| 181 |
This option is not enabled by default. |
| 182 |
.ie n .IP """\-\-output\-encoding name""" 5 |
| 183 |
.el .IP "\f(CW\-\-output\-encoding name\fR" 5 |
| 184 |
.IX Item "--output-encoding name" |
| 185 |
Use encoding "name" when writing filename/comments to the display. By |
| 186 |
default the system encoding will be used. |
| 187 |
.ie n .IP """\-\-language\-encoding"", ""\-\-no\-language\-encoding""" 5 |
| 188 |
.el .IP "\f(CW\-\-language\-encoding\fR, \f(CW\-\-no\-language\-encoding\fR" 5 |
| 189 |
.IX Item "--language-encoding, --no-language-encoding" |
| 190 |
Modern zip files set a metadata entry in zip files, called the "Language |
| 191 |
encoding flag", when they write filenames/comments encoded in UTF\-8. |
| 192 |
.Sp |
| 193 |
Occasionally some applications set the \f(CW\*(C`Language Encoding Flag\*(C'\fR but write |
| 194 |
data that is not UTF\-8 in the filename/comment fields of the zip file. This |
| 195 |
will usually result in garbled text being output for the |
| 196 |
filenames/comments. |
| 197 |
.Sp |
| 198 |
To deal with this use-case, set the \f(CW\*(C`\-\-no\-language\-encoding\*(C'\fR option and, |
| 199 |
if needed, set the \f(CW\*(C`\-\-encoding name\*(C'\fR option to encoding actually used. |
| 200 |
.Sp |
| 201 |
Default is \f(CW\*(C`\-\-language\-encoding\*(C'\fR. |
| 202 |
.ie n .IP """\-\-debug\-encoding""" 5 |
| 203 |
.el .IP \f(CW\-\-debug\-encoding\fR 5 |
| 204 |
.IX Item "--debug-encoding" |
| 205 |
Display extra debugging info when a filename/comment encoding has changed. |
| 206 |
.PP |
| 207 |
\fIMessage Control Options\fR |
| 208 |
.IX Subsection "Message Control Options" |
| 209 |
.ie n .IP """\-\-messages"", ""\-\-no\-messages""" 5 |
| 210 |
.el .IP "\f(CW\-\-messages\fR, \f(CW\-\-no\-messages\fR" 5 |
| 211 |
.IX Item "--messages, --no-messages" |
| 212 |
Enable/disable the output of all info/warning/error messages. |
| 213 |
.Sp |
| 214 |
Disabling messages means that no checks are carried out to check that the |
| 215 |
zip file is well-formed. |
| 216 |
.Sp |
| 217 |
Default is enabled. |
| 218 |
.ie n .IP """\-\-exit\-bitmask"", ""\-\-no\-exit\-bitmask""" 5 |
| 219 |
.el .IP "\f(CW\-\-exit\-bitmask\fR, \f(CW\-\-no\-exit\-bitmask\fR" 5 |
| 220 |
.IX Item "--exit-bitmask, --no-exit-bitmask" |
| 221 |
Enable/disable exit status bitmask for messages. Default disabled. |
| 222 |
Bitmask values are: 1 for info, 2 for warning and 4 for error. |
| 223 |
.SS "Default Output" |
| 224 |
.IX Subsection "Default Output" |
| 225 |
By default \f(CW\*(C`zipdetails\*(C'\fR will output each metadata field from the zip file |
| 226 |
in three columns. |
| 227 |
.IP 1. 5 |
| 228 |
The offset, in hex, to the start of the field relative to the beginning of |
| 229 |
the file. |
| 230 |
.IP 2. 5 |
| 231 |
The name of the field. |
| 232 |
.IP 3. 5 |
| 233 |
Detailed information about the contents of the field. The format depends on |
| 234 |
the type of data: |
| 235 |
.RS 5 |
| 236 |
.IP \(bu 5 |
| 237 |
Numeric Values |
| 238 |
.Sp |
| 239 |
If the field contains an 8\-bit, 16\-bit, 32\-bit or 64\-bit numeric value, it |
| 240 |
will be displayed in both hex and decimal \-\- for example "\f(CW\*(C`002A (42)\*(C'\fR". |
| 241 |
.Sp |
| 242 |
Note that Zip files store most numeric values in \fIlittle-endian\fR encoding |
| 243 |
(there area few rare instances where \fIbig-endian\fR is used). The value read |
| 244 |
from the zip file will have the \fIendian\fR encoding removed before being |
| 245 |
displayed. |
| 246 |
.Sp |
| 247 |
Next, is an optional description of what the numeric value means. |
| 248 |
.IP \(bu 5 |
| 249 |
String |
| 250 |
.Sp |
| 251 |
If the field corresponds to a printable string, it will be output enclosed |
| 252 |
in single quotes. |
| 253 |
.IP \(bu 5 |
| 254 |
Binary Data |
| 255 |
.Sp |
| 256 |
The term \fIBinary Data\fR is just a catch-all for all other metadata in the |
| 257 |
zip file. This data is displayed as a series of ascii-hex byte values in |
| 258 |
the same order they are stored in the zip file. |
| 259 |
.RE |
| 260 |
.RS 5 |
| 261 |
.RE |
| 262 |
.PP |
| 263 |
For example, assuming you have a zip file, \f(CW\*(C`test,zip\*(C'\fR, with one entry |
| 264 |
.PP |
| 265 |
.Vb 7 |
| 266 |
\& $ unzip \-l test.zip |
| 267 |
\& Archive: test.zip |
| 268 |
\& Length Date Time Name |
| 269 |
\& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\- |
| 270 |
\& 446 2023\-03\-22 20:03 lorem.txt |
| 271 |
\& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- |
| 272 |
\& 446 1 file |
| 273 |
.Ve |
| 274 |
.PP |
| 275 |
Running \f(CW\*(C`zipdetails\*(C'\fR will gives this output |
| 276 |
.PP |
| 277 |
.Vb 1 |
| 278 |
\& $ zipdetails test.zip |
| 279 |
\& |
| 280 |
\& 0000 LOCAL HEADER #1 04034B50 (67324752) |
| 281 |
\& 0004 Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq |
| 282 |
\& 0005 Extract OS 00 (0) \*(AqMS\-DOS\*(Aq |
| 283 |
\& 0006 General Purpose Flag 0000 (0) |
| 284 |
\& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq |
| 285 |
\& 0008 Compression Method 0008 (8) \*(AqDeflated\*(Aq |
| 286 |
\& 000A Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq |
| 287 |
\& 000E CRC F90EE7FF (4178503679) |
| 288 |
\& 0012 Compressed Size 0000010E (270) |
| 289 |
\& 0016 Uncompressed Size 000001BE (446) |
| 290 |
\& 001A Filename Length 0009 (9) |
| 291 |
\& 001C Extra Length 0000 (0) |
| 292 |
\& 001E Filename \*(Aqlorem.txt\*(Aq |
| 293 |
\& 0027 PAYLOAD |
| 294 |
\& |
| 295 |
\& 0135 CENTRAL HEADER #1 02014B50 (33639248) |
| 296 |
\& 0139 Created Zip Spec 1E (30) \*(Aq3.0\*(Aq |
| 297 |
\& 013A Created OS 03 (3) \*(AqUnix\*(Aq |
| 298 |
\& 013B Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq |
| 299 |
\& 013C Extract OS 00 (0) \*(AqMS\-DOS\*(Aq |
| 300 |
\& 013D General Purpose Flag 0000 (0) |
| 301 |
\& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq |
| 302 |
\& 013F Compression Method 0008 (8) \*(AqDeflated\*(Aq |
| 303 |
\& 0141 Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq |
| 304 |
\& 0145 CRC F90EE7FF (4178503679) |
| 305 |
\& 0149 Compressed Size 0000010E (270) |
| 306 |
\& 014D Uncompressed Size 000001BE (446) |
| 307 |
\& 0151 Filename Length 0009 (9) |
| 308 |
\& 0153 Extra Length 0000 (0) |
| 309 |
\& 0155 Comment Length 0000 (0) |
| 310 |
\& 0157 Disk Start 0000 (0) |
| 311 |
\& 0159 Int File Attributes 0001 (1) |
| 312 |
\& [Bit 0] 1 \*(AqText Data\*(Aq |
| 313 |
\& 015B Ext File Attributes 81ED0000 (2179792896) |
| 314 |
\& [Bits 16\-24] 01ED (493) \*(AqUnix attrib: rwxr\-xr\-x\*(Aq |
| 315 |
\& [Bits 28\-31] 08 (8) \*(AqRegular File\*(Aq |
| 316 |
\& 015F Local Header Offset 00000000 (0) |
| 317 |
\& 0163 Filename \*(Aqlorem.txt\*(Aq |
| 318 |
\& |
| 319 |
\& 016C END CENTRAL HEADER 06054B50 (101010256) |
| 320 |
\& 0170 Number of this disk 0000 (0) |
| 321 |
\& 0172 Central Dir Disk no 0000 (0) |
| 322 |
\& 0174 Entries in this disk 0001 (1) |
| 323 |
\& 0176 Total Entries 0001 (1) |
| 324 |
\& 0178 Size of Central Dir 00000037 (55) |
| 325 |
\& 017C Offset to Central Dir 00000135 (309) |
| 326 |
\& 0180 Comment Length 0000 (0) |
| 327 |
\& # |
| 328 |
\& # Done |
| 329 |
.Ve |
| 330 |
.SS "Verbose Output" |
| 331 |
.IX Subsection "Verbose Output" |
| 332 |
If the \f(CW\*(C`\-v\*(C'\fR option is present, the metadata output is split into the |
| 333 |
following columns: |
| 334 |
.IP 1. 5 |
| 335 |
The offset, in hex, to the start of the field relative to the beginning of |
| 336 |
the file. |
| 337 |
.IP 2. 5 |
| 338 |
The offset, in hex, to the end of the field relative to the beginning of |
| 339 |
the file. |
| 340 |
.IP 3. 5 |
| 341 |
The length, in hex, of the field. |
| 342 |
.IP 4. 5 |
| 343 |
A hex dump of the bytes in field in the order they are stored in the zip file. |
| 344 |
.IP 5. 5 |
| 345 |
A textual description of the field. |
| 346 |
.IP 6. 5 |
| 347 |
Information about the contents of the field. See the description in the |
| 348 |
"Default Output" for more details. |
| 349 |
.PP |
| 350 |
Here is the same zip file, \f(CW\*(C`test.zip\*(C'\fR, dumped using the \f(CW\*(C`zipdetails\*(C'\fR |
| 351 |
\&\f(CW\*(C`\-v\*(C'\fR option: |
| 352 |
.PP |
| 353 |
.Vb 1 |
| 354 |
\& $ zipdetails \-v test.zip |
| 355 |
\& |
| 356 |
\& 0000 0003 0004 50 4B 03 04 LOCAL HEADER #1 04034B50 (67324752) |
| 357 |
\& 0004 0004 0001 14 Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq |
| 358 |
\& 0005 0005 0001 00 Extract OS 00 (0) \*(AqMS\-DOS\*(Aq |
| 359 |
\& 0006 0007 0002 00 00 General Purpose Flag 0000 (0) |
| 360 |
\& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq |
| 361 |
\& 0008 0009 0002 08 00 Compression Method 0008 (8) \*(AqDeflated\*(Aq |
| 362 |
\& 000A 000D 0004 72 A0 76 56 Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq |
| 363 |
\& 000E 0011 0004 FF E7 0E F9 CRC F90EE7FF (4178503679) |
| 364 |
\& 0012 0015 0004 0E 01 00 00 Compressed Size 0000010E (270) |
| 365 |
\& 0016 0019 0004 BE 01 00 00 Uncompressed Size 000001BE (446) |
| 366 |
\& 001A 001B 0002 09 00 Filename Length 0009 (9) |
| 367 |
\& 001C 001D 0002 00 00 Extra Length 0000 (0) |
| 368 |
\& 001E 0026 0009 6C 6F 72 65 Filename \*(Aqlorem.txt\*(Aq |
| 369 |
\& 6D 2E 74 78 |
| 370 |
\& 74 |
| 371 |
\& 0027 0134 010E ... PAYLOAD |
| 372 |
\& |
| 373 |
\& 0135 0138 0004 50 4B 01 02 CENTRAL HEADER #1 02014B50 (33639248) |
| 374 |
\& 0139 0139 0001 1E Created Zip Spec 1E (30) \*(Aq3.0\*(Aq |
| 375 |
\& 013A 013A 0001 03 Created OS 03 (3) \*(AqUnix\*(Aq |
| 376 |
\& 013B 013B 0001 14 Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq |
| 377 |
\& 013C 013C 0001 00 Extract OS 00 (0) \*(AqMS\-DOS\*(Aq |
| 378 |
\& 013D 013E 0002 00 00 General Purpose Flag 0000 (0) |
| 379 |
\& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq |
| 380 |
\& 013F 0140 0002 08 00 Compression Method 0008 (8) \*(AqDeflated\*(Aq |
| 381 |
\& 0141 0144 0004 72 A0 76 56 Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq |
| 382 |
\& 0145 0148 0004 FF E7 0E F9 CRC F90EE7FF (4178503679) |
| 383 |
\& 0149 014C 0004 0E 01 00 00 Compressed Size 0000010E (270) |
| 384 |
\& 014D 0150 0004 BE 01 00 00 Uncompressed Size 000001BE (446) |
| 385 |
\& 0151 0152 0002 09 00 Filename Length 0009 (9) |
| 386 |
\& 0153 0154 0002 00 00 Extra Length 0000 (0) |
| 387 |
\& 0155 0156 0002 00 00 Comment Length 0000 (0) |
| 388 |
\& 0157 0158 0002 00 00 Disk Start 0000 (0) |
| 389 |
\& 0159 015A 0002 01 00 Int File Attributes 0001 (1) |
| 390 |
\& [Bit 0] 1 \*(AqText Data\*(Aq |
| 391 |
\& 015B 015E 0004 00 00 ED 81 Ext File Attributes 81ED0000 (2179792896) |
| 392 |
\& [Bits 16\-24] 01ED (493) \*(AqUnix attrib: rwxr\-xr\-x\*(Aq |
| 393 |
\& [Bits 28\-31] 08 (8) \*(AqRegular File\*(Aq |
| 394 |
\& 015F 0162 0004 00 00 00 00 Local Header Offset 00000000 (0) |
| 395 |
\& 0163 016B 0009 6C 6F 72 65 Filename \*(Aqlorem.txt\*(Aq |
| 396 |
\& 6D 2E 74 78 |
| 397 |
\& 74 |
| 398 |
\& |
| 399 |
\& 016C 016F 0004 50 4B 05 06 END CENTRAL HEADER 06054B50 (101010256) |
| 400 |
\& 0170 0171 0002 00 00 Number of this disk 0000 (0) |
| 401 |
\& 0172 0173 0002 00 00 Central Dir Disk no 0000 (0) |
| 402 |
\& 0174 0175 0002 01 00 Entries in this disk 0001 (1) |
| 403 |
\& 0176 0177 0002 01 00 Total Entries 0001 (1) |
| 404 |
\& 0178 017B 0004 37 00 00 00 Size of Central Dir 00000037 (55) |
| 405 |
\& 017C 017F 0004 35 01 00 00 Offset to Central Dir 00000135 (309) |
| 406 |
\& 0180 0181 0002 00 00 Comment Length 0000 (0) |
| 407 |
\& # |
| 408 |
\& # Done |
| 409 |
.Ve |
| 410 |
.SS "Advanced Analysis" |
| 411 |
.IX Subsection "Advanced Analysis" |
| 412 |
If you have a corrupt or non-standard zip file, particulatly one where the |
| 413 |
\&\f(CW\*(C`Central Directory\*(C'\fR metadata at the end of the file is absent/incomplete, you |
| 414 |
can use either the \f(CW\*(C`\-\-walk\*(C'\fR option or the \f(CW\*(C`\-\-scan\*(C'\fR option to search for |
| 415 |
any zip metadata that is still present in the file. |
| 416 |
.PP |
| 417 |
When either of these options is enabled, this program will bypass the |
| 418 |
initial step of reading the \f(CW\*(C`Central Directory\*(C'\fR at the end of the file and |
| 419 |
simply scan the zip file sequentially from the start of the file looking |
| 420 |
for zip metedata records. Although this can be error prone, for the most |
| 421 |
part it will find any zip file metadata that is still present in the file. |
| 422 |
.PP |
| 423 |
The difference between the two options is how aggressive the sequential |
| 424 |
scan is: \f(CW\*(C`\-\-walk\*(C'\fR is optimistic, while \f(CW\*(C`\-\-scan\*(C'\fR is pessimistic. |
| 425 |
.PP |
| 426 |
To understand the difference in more detail you need to know a bit about |
| 427 |
how zip file metadata is structured. Under the hood, a zip file uses a |
| 428 |
series of 4\-byte signatures to flag the start of a each of the metadata |
| 429 |
records it uses. When the \f(CW\*(C`\-\-walk\*(C'\fR or the \f(CW\*(C`\-\-scan\*(C'\fR option is enabled both |
| 430 |
work identically by scanning the file from the beginning looking for any |
| 431 |
the of these valid 4\-byte metadata signatures. When a 4\-byte signature is |
| 432 |
found both options will blindly assume that it has found a vald metadata |
| 433 |
record and display it. |
| 434 |
.PP |
| 435 |
\fR\f(CI\*(C`\-\-walk\*(C'\fR\fI\fR |
| 436 |
.IX Subsection "--walk" |
| 437 |
.PP |
| 438 |
The \f(CW\*(C`\-\-walk\*(C'\fR option optimistically assumes that it has found a real zip |
| 439 |
metatada record and so starts the scan for the next record directly after |
| 440 |
the record it has just output. |
| 441 |
.PP |
| 442 |
\fR\f(CI\*(C`\-\-scan\*(C'\fR\fI\fR |
| 443 |
.IX Subsection "--scan" |
| 444 |
.PP |
| 445 |
The \f(CW\*(C`\-\-scan\*(C'\fR option is pessimistic and assumes the 4\-byte signature |
| 446 |
sequence may have been a false-positive, so before starting the scan for |
| 447 |
the next resord, it will rewind to the location in the file directly after |
| 448 |
the 4\-byte sequecce it just processed. This means it will rescan data that |
| 449 |
has already been processed. For very lage zip files the \f(CW\*(C`\-\-scan\*(C'\fR option |
| 450 |
can be really realy slow, so trying the \f(CW\*(C`\-\-walk\*(C'\fR option first. |
| 451 |
.PP |
| 452 |
\&\fBImportant Note\fR: If the zip file being processed contains one or more |
| 453 |
nested zip files, and the outer zip file uses the \f(CW\*(C`STORE\*(C'\fR compression |
| 454 |
method, the \f(CW\*(C`\-\-scan\*(C'\fR option will display the zip metadata for both the |
| 455 |
outer & inner zip files. |
| 456 |
.SS "Filename Encoding Issues" |
| 457 |
.IX Subsection "Filename Encoding Issues" |
| 458 |
Sometimes when displaying the contents of a zip file the filenames (or |
| 459 |
comments) appear to be garbled. This section walks through the reasons and |
| 460 |
mitigations that can be applied to work around these issues. |
| 461 |
.PP |
| 462 |
\fIBackground\fR |
| 463 |
.IX Subsection "Background" |
| 464 |
.PP |
| 465 |
When zip files were first created in the 1980's, there was no Unicode or |
| 466 |
UTF\-8. Issues around character set encoding interoperability were not a |
| 467 |
major concern. |
| 468 |
.PP |
| 469 |
Initially, the only official encoding supported in zip files was IBM Code |
| 470 |
Page 437 (AKA \f(CW\*(C`CP437\*(C'\fR). As time went on users in locales where \f(CW\*(C`CP437\*(C'\fR |
| 471 |
wasn't appropriate stored filenames in the encoding native to their locale. |
| 472 |
If you were running a system that matched the locale of the zip file, all |
| 473 |
was well. If not, you had to post-process the filenames after unzipping the |
| 474 |
zip file. |
| 475 |
.PP |
| 476 |
Fast forward to the introduction of Unicode and UTF\-8 encoding. The |
| 477 |
approach now used by all major zip implementations is to set the \f(CW\*(C`Language |
| 478 |
encoding flag\*(C'\fR (also known as \f(CW\*(C`EFS\*(C'\fR) in the zip file metadata to signal |
| 479 |
that a filename/comment is encoded in UTF\-8. |
| 480 |
.PP |
| 481 |
To ensure maximum interoperability when sharing zip files store 7\-bit |
| 482 |
filenames as-is in the zip file. For anything else the \f(CW\*(C`EFS\*(C'\fR bit needs to |
| 483 |
be set and the filename is encoded in UTF\-8. Although this rule is kept to |
| 484 |
for the most part, there are exceptions out in the wild. |
| 485 |
.PP |
| 486 |
\fIDealing with Encoding Errors\fR |
| 487 |
.IX Subsection "Dealing with Encoding Errors" |
| 488 |
.PP |
| 489 |
The most common filename encoding issue is where the \f(CW\*(C`EFS\*(C'\fR bit is not set and |
| 490 |
the filename is stored in a character set that doesnt't match the system |
| 491 |
encoding. This mostly impacts legacy zip files that predate the |
| 492 |
introduction of Unicode. |
| 493 |
.PP |
| 494 |
To deal with this issue you first need to know what encoding was used in |
| 495 |
the zip file. For example, if the filename is encoded in \f(CW\*(C`ISO\-8859\-1\*(C'\fR you |
| 496 |
can display the filenames using the \f(CW\*(C`\-\-encoding\*(C'\fR option |
| 497 |
.PP |
| 498 |
.Vb 1 |
| 499 |
\& zipdetails \-\-encoding ISO\-8859\-1 myfile.zip |
| 500 |
.Ve |
| 501 |
.PP |
| 502 |
A less common variation of this is where the \f(CW\*(C`EFS\*(C'\fR bit is set, signalling |
| 503 |
that the filename will be encoded in UTF\-8, but the filename is not encoded |
| 504 |
in UTF\-8. To deal with this scenarion, use the \f(CW\*(C`\-\-no\-language\-encoding\*(C'\fR |
| 505 |
option along with the \f(CW\*(C`\-\-encoding\*(C'\fR option. |
| 506 |
.SH LIMITATIONS |
| 507 |
.IX Header "LIMITATIONS" |
| 508 |
The following zip file features are not supported by this program: |
| 509 |
.IP \(bu 5 |
| 510 |
Multi\-part/Split/Spanned Zip Archives. |
| 511 |
.Sp |
| 512 |
This program cannot give an overall report on the combined parts of a |
| 513 |
multi-part zip file. |
| 514 |
.Sp |
| 515 |
The best you can do is run with either the \f(CW\*(C`\-\-scan\*(C'\fR or \f(CW\*(C`\-\-walk\*(C'\fR options |
| 516 |
against individual parts. Some will contains zipfile metadata which will be |
| 517 |
detected and some will only contain compressed payload data. |
| 518 |
.IP \(bu 5 |
| 519 |
Encrypted Central Directory |
| 520 |
.Sp |
| 521 |
When pkzip \fIStrong Encryption\fR is enabled in a zip file this program can |
| 522 |
still parse most of the metadata in the zip file. The exception is when the |
| 523 |
\&\f(CW\*(C`Central Directory\*(C'\fR of a zip file is also encrypted. This program cannot |
| 524 |
parse any metadata from an encrypted \f(CW\*(C`Central Directory\*(C'\fR. |
| 525 |
.IP \(bu 5 |
| 526 |
Corrupt Zip files |
| 527 |
.Sp |
| 528 |
When \f(CW\*(C`zipdetails\*(C'\fR encounters a corrupt zip file, it will do one or more of |
| 529 |
the following |
| 530 |
.RS 5 |
| 531 |
.IP \(bu 5 |
| 532 |
Display details of the corruption and carry on |
| 533 |
.IP \(bu 5 |
| 534 |
Display details of the corruption and terminate |
| 535 |
.IP \(bu 5 |
| 536 |
Terminate with a generic message |
| 537 |
.RE |
| 538 |
.RS 5 |
| 539 |
.Sp |
| 540 |
Which of the above is output is dependent in the severity of the |
| 541 |
corruption. |
| 542 |
.RE |
| 543 |
.SH TODO |
| 544 |
.IX Header "TODO" |
| 545 |
.SS "JSON/YML Output" |
| 546 |
.IX Subsection "JSON/YML Output" |
| 547 |
Output some of the zip file metadata as a JSON or YML document. |
| 548 |
.SS "Corrupt Zip files" |
| 549 |
.IX Subsection "Corrupt Zip files" |
| 550 |
Although the detection and reporting of most of the common corruption use-cases is |
| 551 |
present in \f(CW\*(C`zipdetails\*(C'\fR, there are likely to be other edge cases that need |
| 552 |
to be supported. |
| 553 |
.PP |
| 554 |
If you have a corrupt Zip file that isn't being processed properly, please |
| 555 |
report it (see "SUPPORT"). |
| 556 |
.SH SUPPORT |
| 557 |
.IX Header "SUPPORT" |
| 558 |
General feedback/questions/bug reports should be sent to |
| 559 |
<https://github.com/pmqs/zipdetails/issues>. |
| 560 |
.SH "SEE ALSO" |
| 561 |
.IX Header "SEE ALSO" |
| 562 |
The primary reference for Zip files is |
| 563 |
APPNOTE.TXT <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>. |
| 564 |
.PP |
| 565 |
An alternative reference is the Info-Zip appnote. This is available from |
| 566 |
<ftp://ftp.info\-zip.org/pub/infozip/doc/> |
| 567 |
.PP |
| 568 |
For details of WinZip AES encryption see AES Encryption Information: |
| 569 |
Encryption Specification AE\-1 and |
| 570 |
AE\-2 <https://www.winzip.com/en/support/aes-encryption/>. |
| 571 |
.PP |
| 572 |
The \f(CW\*(C`zipinfo\*(C'\fR program that comes with the info-zip distribution |
| 573 |
(<http://www.info\-zip.org/>) can also display details of the structure of a zip |
| 574 |
file. |
| 575 |
.SH AUTHOR |
| 576 |
.IX Header "AUTHOR" |
| 577 |
Paul Marquess \[email protected]\fR. |
| 578 |
.SH COPYRIGHT |
| 579 |
.IX Header "COPYRIGHT" |
| 580 |
Copyright (c) 2011\-2024 Paul Marquess. All rights reserved. |
| 581 |
.PP |
| 582 |
This program is free software; you can redistribute it and/or modify it under |
| 583 |
the same terms as Perl itself. |