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