Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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__ */