• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2013 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 /*
20  * Read-only access to Zip archives, with minimal heap allocation.
21  */
22 
23 #include <stdint.h>
24 #include <string.h>
25 #include <sys/cdefs.h>
26 #include <sys/types.h>
27 
28 #include "android-base/off64_t.h"
29 
30 /* Zip compression methods we support */
31 enum {
32   kCompressStored = 0,    // no compression
33   kCompressDeflated = 8,  // standard deflate
34 };
35 
36 struct ZipString {
37   const uint8_t* name;
38   uint16_t name_length;
39 
ZipStringZipString40   ZipString() {}
41 
42   /*
43    * entry_name has to be an c-style string with only ASCII characters.
44    */
45   explicit ZipString(const char* entry_name);
46 
47   bool operator==(const ZipString& rhs) const {
48     return name && (name_length == rhs.name_length) && (memcmp(name, rhs.name, name_length) == 0);
49   }
50 
StartsWithZipString51   bool StartsWith(const ZipString& prefix) const {
52     return name && (name_length >= prefix.name_length) &&
53            (memcmp(name, prefix.name, prefix.name_length) == 0);
54   }
55 
EndsWithZipString56   bool EndsWith(const ZipString& suffix) const {
57     return name && (name_length >= suffix.name_length) &&
58            (memcmp(name + name_length - suffix.name_length, suffix.name, suffix.name_length) == 0);
59   }
60 };
61 
62 /*
63  * Represents information about a zip entry in a zip file.
64  */
65 struct ZipEntry {
66   // Compression method: One of kCompressStored or
67   // kCompressDeflated.
68   uint16_t method;
69 
70   // Modification time. The zipfile format specifies
71   // that the first two little endian bytes contain the time
72   // and the last two little endian bytes contain the date.
73   // See `GetModificationTime`.
74   // TODO: should be overridden by extra time field, if present.
75   uint32_t mod_time;
76 
77   // Returns `mod_time` as a broken-down struct tm.
78   struct tm GetModificationTime() const;
79 
80   // Suggested Unix mode for this entry, from the zip archive if created on
81   // Unix, or a default otherwise.
82   mode_t unix_mode;
83 
84   // 1 if this entry contains a data descriptor segment, 0
85   // otherwise.
86   uint8_t has_data_descriptor;
87 
88   // Crc32 value of this ZipEntry. This information might
89   // either be stored in the local file header or in a special
90   // Data descriptor footer at the end of the file entry.
91   uint32_t crc32;
92 
93   // Compressed length of this ZipEntry. Might be present
94   // either in the local file header or in the data descriptor
95   // footer.
96   uint32_t compressed_length;
97 
98   // Uncompressed length of this ZipEntry. Might be present
99   // either in the local file header or in the data descriptor
100   // footer.
101   uint32_t uncompressed_length;
102 
103   // The offset to the start of data for this ZipEntry.
104   off64_t offset;
105 };
106 
107 struct ZipArchive;
108 typedef ZipArchive* ZipArchiveHandle;
109 
110 /*
111  * Open a Zip archive, and sets handle to the value of the opaque
112  * handle for the file. This handle must be released by calling
113  * CloseArchive with this handle.
114  *
115  * Returns 0 on success, and negative values on failure.
116  */
117 int32_t OpenArchive(const char* fileName, ZipArchiveHandle* handle);
118 
119 /*
120  * Like OpenArchive, but takes a file descriptor open for reading
121  * at the start of the file.  The descriptor must be mappable (this does
122  * not allow access to a stream).
123  *
124  * Sets handle to the value of the opaque handle for this file descriptor.
125  * This handle must be released by calling CloseArchive with this handle.
126  *
127  * If assume_ownership parameter is 'true' calling CloseArchive will close
128  * the file.
129  *
130  * This function maps and scans the central directory and builds a table
131  * of entries for future lookups.
132  *
133  * "debugFileName" will appear in error messages, but is not otherwise used.
134  *
135  * Returns 0 on success, and negative values on failure.
136  */
137 int32_t OpenArchiveFd(const int fd, const char* debugFileName, ZipArchiveHandle* handle,
138                       bool assume_ownership = true);
139 
140 int32_t OpenArchiveFromMemory(void* address, size_t length, const char* debugFileName,
141                               ZipArchiveHandle* handle);
142 /*
143  * Close archive, releasing resources associated with it. This will
144  * unmap the central directory of the zipfile and free all internal
145  * data structures associated with the file. It is an error to use
146  * this handle for any further operations without an intervening
147  * call to one of the OpenArchive variants.
148  */
149 void CloseArchive(ZipArchiveHandle archive);
150 
151 /*
152  * Find an entry in the Zip archive, by name. |entryName| must be a null
153  * terminated string, and |data| must point to a writeable memory location.
154  *
155  * Returns 0 if an entry is found, and populates |data| with information
156  * about this entry. Returns negative values otherwise.
157  *
158  * It's important to note that |data->crc32|, |data->compLen| and
159  * |data->uncompLen| might be set to values from the central directory
160  * if this file entry contains a data descriptor footer. To verify crc32s
161  * and length, a call to VerifyCrcAndLengths must be made after entry data
162  * has been processed.
163  *
164  * On non-Windows platforms this method does not modify internal state and
165  * can be called concurrently.
166  */
167 int32_t FindEntry(const ZipArchiveHandle archive, const ZipString& entryName, ZipEntry* data);
168 
169 /*
170  * Start iterating over all entries of a zip file. The order of iteration
171  * is not guaranteed to be the same as the order of elements
172  * in the central directory but is stable for a given zip file. |cookie| will
173  * contain the value of an opaque cookie which can be used to make one or more
174  * calls to Next. All calls to StartIteration must be matched by a call to
175  * EndIteration to free any allocated memory.
176  *
177  * This method also accepts optional prefix and suffix to restrict iteration to
178  * entry names that start with |optional_prefix| or end with |optional_suffix|.
179  *
180  * Returns 0 on success and negative values on failure.
181  */
182 int32_t StartIteration(ZipArchiveHandle archive, void** cookie_ptr,
183                        const ZipString* optional_prefix, const ZipString* optional_suffix);
184 
185 /*
186  * Advance to the next element in the zipfile in iteration order.
187  *
188  * Returns 0 on success, -1 if there are no more elements in this
189  * archive and lower negative values on failure.
190  */
191 int32_t Next(void* cookie, ZipEntry* data, ZipString* name);
192 
193 /*
194  * End iteration over all entries of a zip file and frees the memory allocated
195  * in StartIteration.
196  */
197 void EndIteration(void* cookie);
198 
199 /*
200  * Uncompress and write an entry to an open file identified by |fd|.
201  * |entry->uncompressed_length| bytes will be written to the file at
202  * its current offset, and the file will be truncated at the end of
203  * the uncompressed data (no truncation if |fd| references a block
204  * device).
205  *
206  * Returns 0 on success and negative values on failure.
207  */
208 int32_t ExtractEntryToFile(ZipArchiveHandle archive, ZipEntry* entry, int fd);
209 
210 /**
211  * Uncompress a given zip entry to the memory region at |begin| and of
212  * size |size|. This size is expected to be the same as the *declared*
213  * uncompressed length of the zip entry. It is an error if the *actual*
214  * number of uncompressed bytes differs from this number.
215  *
216  * Returns 0 on success and negative values on failure.
217  */
218 int32_t ExtractToMemory(ZipArchiveHandle archive, ZipEntry* entry, uint8_t* begin, uint32_t size);
219 
220 int GetFileDescriptor(const ZipArchiveHandle archive);
221 
222 const char* ErrorCodeString(int32_t error_code);
223 
224 #if !defined(_WIN32)
225 typedef bool (*ProcessZipEntryFunction)(const uint8_t* buf, size_t buf_size, void* cookie);
226 
227 /*
228  * Stream the uncompressed data through the supplied function,
229  * passing cookie to it each time it gets called.
230  */
231 int32_t ProcessZipEntryContents(ZipArchiveHandle archive, ZipEntry* entry,
232                                 ProcessZipEntryFunction func, void* cookie);
233 #endif
234 
235 namespace zip_archive {
236 
237 class Writer {
238  public:
239   virtual bool Append(uint8_t* buf, size_t buf_size) = 0;
240   virtual ~Writer();
241 
242  protected:
243   Writer() = default;
244 
245  private:
246   Writer(const Writer&) = delete;
247   void operator=(const Writer&) = delete;
248 };
249 
250 class Reader {
251  public:
252   virtual bool ReadAtOffset(uint8_t* buf, size_t len, uint32_t offset) const = 0;
253   virtual ~Reader();
254 
255  protected:
256   Reader() = default;
257 
258  private:
259   Reader(const Reader&) = delete;
260   void operator=(const Reader&) = delete;
261 };
262 
263 /*
264  * Inflates the first |compressed_length| bytes of |reader| to a given |writer|.
265  * |crc_out| is set to the CRC32 checksum of the uncompressed data.
266  *
267  * Returns 0 on success and negative values on failure, for example if |reader|
268  * cannot supply the right amount of data, or if the number of bytes written to
269  * data does not match |uncompressed_length|.
270  *
271  * If |crc_out| is not nullptr, it is set to the crc32 checksum of the
272  * uncompressed data.
273  */
274 int32_t Inflate(const Reader& reader, const uint32_t compressed_length,
275                 const uint32_t uncompressed_length, Writer* writer, uint64_t* crc_out);
276 }  // namespace zip_archive
277