diff options
Diffstat (limited to 'modules/libmar/src/mar.h')
| -rw-r--r-- | modules/libmar/src/mar.h | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/modules/libmar/src/mar.h b/modules/libmar/src/mar.h new file mode 100644 index 0000000000..74ab7657f8 --- /dev/null +++ b/modules/libmar/src/mar.h @@ -0,0 +1,260 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* vim:set ts=2 sw=2 sts=2 et cindent: */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#ifndef MAR_H__ +#define MAR_H__ + +#include <assert.h> // for C11 static_assert +#include <stdint.h> +#include <stdio.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* We have a MAX_SIGNATURES limit so that an invalid MAR will never + * waste too much of either updater's or signmar's time. + * It is also used at various places internally and will affect memory usage. + * If you want to increase this value above 9 then you need to adjust parsing + * code in tool/mar.c. + */ +#define MAX_SIGNATURES 8 +static_assert(MAX_SIGNATURES <= 9, "too many signatures"); + +struct ProductInformationBlock { + const char* MARChannelID; + const char* productVersion; +}; + +/** + * The MAR item data structure. + */ +typedef struct MarItem_ { + struct MarItem_* next; /* private field */ + uint32_t offset; /* offset into archive */ + uint32_t length; /* length of data in bytes */ + uint32_t flags; /* contains file mode bits */ + char name[1]; /* file path */ +} MarItem; + +/** + * File offset and length for tracking access of byte indexes + */ +typedef struct SeenIndex_ { + struct SeenIndex_* next; /* private field */ + uint32_t offset; /* offset into archive */ + uint32_t length; /* length of the data in bytes */ +} SeenIndex; + +#define TABLESIZE 256 + +/** + * Mozilla ARchive (MAR) file data structure + */ +struct MarFile_ { + unsigned char* buffer; /* file buffer containing the entire MAR */ + size_t data_len; /* byte count of the data in the buffer */ + MarItem* item_table[TABLESIZE]; /* hash table of files in the archive */ + SeenIndex* index_list; /* file indexes processed */ + int item_table_is_valid; /* header and index validation flag */ +}; + +typedef struct MarFile_ MarFile; + +/** + * Signature of callback function passed to mar_enum_items. + * @param mar The MAR file being visited. + * @param item The MAR item being visited. + * @param data The data parameter passed by the caller of mar_enum_items. + * @return A non-zero value to stop enumerating. + */ +typedef int (*MarItemCallback)(MarFile* mar, const MarItem* item, void* data); + +enum MarReadResult_ { + MAR_READ_SUCCESS, + MAR_IO_ERROR, + MAR_MEM_ERROR, + MAR_FILE_TOO_BIG_ERROR, +}; + +typedef enum MarReadResult_ MarReadResult; + +/** + * Open a MAR file for reading. + * @param path Specifies the path to the MAR file to open. This path must + * be compatible with fopen. + * @param out_mar Out-parameter through which the created MarFile structure is + * returned. Guaranteed to be a valid structure if + * MAR_READ_SUCCESS is returned. Otherwise NULL will be + * assigned. + * @return NULL if an error occurs. + */ +MarReadResult mar_open(const char* path, MarFile** out_mar); + +#ifdef XP_WIN +MarReadResult mar_wopen(const wchar_t* path, MarFile** out_mar); +#endif + +/** + * Close a MAR file that was opened using mar_open. + * @param mar The MarFile object to close. + */ +void mar_close(MarFile* mar); + +/** + * Reads the specified amount of data from the buffer in MarFile that contains + * the entirety of the MAR file data. + * @param mar The MAR file to read from. + * @param dest The buffer to read into. + * @param position The byte index to start reading from the MAR at. + * On success, position will be incremented by size. + * @param size The number of bytes to read. + * @return 0 If the specified amount of data was read. + * -1 If the buffer MAR is not large enough to read the + * specified amount of data at the specified position. + */ +int mar_read_buffer(MarFile* mar, void* dest, size_t* position, size_t size); + +/** + * Reads the specified amount of data from the buffer in MarFile that contains + * the entirety of the MAR file data. If there isn't that much data remaining, + * reads as much as possible. + * @param mar The MAR file to read from. + * @param dest The buffer to read into. + * @param position The byte index to start reading from the MAR at. + * This function will increment position by the number of bytes + * copied. + * @param size The maximum number of bytes to read. + * @return The number of bytes copied into dest. + */ +int mar_read_buffer_max(MarFile* mar, void* dest, size_t* position, + size_t size); + +/** + * Increments position by distance. Checks that the resulting position is still + * within the bounds of the buffer. Much like fseek, this will allow position to + * be successfully placed just after the end of the buffer. + * @param mar The MAR file to read from. + * @param position The byte index to start reading from the MAR at. + * On success, position will be incremented by size. + * @param distance The number of bytes to move forward by. + * @return 0 If position was successfully moved. + * -1 If moving position by distance would move it outside the + * bounds of the buffer. + */ +int mar_buffer_seek(MarFile* mar, size_t* position, size_t distance); + +/** + * Find an item in the MAR file by name. + * @param mar The MarFile object to query. + * @param item The name of the item to query. + * @return A const reference to a MAR item or NULL if not found. + */ +const MarItem* mar_find_item(MarFile* mar, const char* item); + +/** + * Enumerate all MAR items via callback function. + * @param mar The MAR file to enumerate. + * @param callback The function to call for each MAR item. + * @param data A caller specified value that is passed along to the + * callback function. + * @return 0 if the enumeration ran to completion. Otherwise, any + * non-zero return value from the callback is returned. + */ +int mar_enum_items(MarFile* mar, MarItemCallback callback, void* data); + +/** + * Read from MAR item at given offset up to bufsize bytes. + * @param mar The MAR file to read. + * @param item The MAR item to read. + * @param offset The byte offset relative to the start of the item. + * @param buf A pointer to a buffer to copy the data into. + * @param bufsize The length of the buffer to copy the data into. + * @return The number of bytes written or a negative value if an + * error occurs. + */ +int mar_read(MarFile* mar, const MarItem* item, int offset, uint8_t* buf, + int bufsize); + +/** + * Create a MAR file from a set of files. + * @param dest The path to the file to create. This path must be + * compatible with fopen. + * @param numfiles The number of files to store in the archive. + * @param files The list of null-terminated file paths. Each file + * path must be compatible with fopen. + * @param infoBlock The information to store in the product information block. + * @return A non-zero value if an error occurs. + */ +int mar_create(const char* dest, int numfiles, char** files, + struct ProductInformationBlock* infoBlock); + +/** + * Extract a MAR file to the current working directory. + * @param path The path to the MAR file to extract. This path must be + * compatible with fopen. + * @return A non-zero value if an error occurs. + */ +int mar_extract(const char* path); + +#define MAR_MAX_CERT_SIZE (16 * 1024) // Way larger than necessary + +/* Read the entire file (not a MAR file) into a newly-allocated buffer. + * This function does not write to stderr. Instead, the caller should + * write whatever error messages it sees fit. The caller must free the returned + * buffer using free(). + * + * @param filePath The path to the file that should be read. + * @param maxSize The maximum valid file size. + * @param data On success, *data will point to a newly-allocated buffer + * with the file's contents in it. + * @param size On success, *size will be the size of the created buffer. + * + * @return 0 on success, -1 on error + */ +int mar_read_entire_file(const char* filePath, uint32_t maxSize, + /*out*/ const uint8_t** data, + /*out*/ uint32_t* size); + +/** + * Verifies a MAR file by verifying each signature with the corresponding + * certificate. That is, the first signature will be verified using the first + * certificate given, the second signature will be verified using the second + * certificate given, etc. The signature count must exactly match the number of + * certificates given, and all signature verifications must succeed. + * We do not check that the certificate was issued by any trusted authority. + * We assume it to be self-signed. We do not check whether the certificate + * is valid for this usage. + * + * @param mar The already opened MAR file. + * @param certData Pointer to the first element in an array of certificate + * file data. + * @param certDataSizes Pointer to the first element in an array for size of + * the cert data. + * @param certCount The number of elements in certData and certDataSizes + * @return 0 on success + * a negative number if there was an error + * a positive number if the signature does not verify + */ +int mar_verify_signatures(MarFile* mar, const uint8_t* const* certData, + const uint32_t* certDataSizes, uint32_t certCount); + +/** + * Reads the product info block from the MAR file's additional block section. + * The caller is responsible for freeing the fields in infoBlock + * if the return is successful. + * + * @param infoBlock Out parameter for where to store the result to + * @return 0 on success, -1 on failure + */ +int mar_read_product_info_block(MarFile* mar, + struct ProductInformationBlock* infoBlock); + +#ifdef __cplusplus +} +#endif + +#endif /* MAR_H__ */ |