include/onlineupdate/mar.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef MAR_H__
   8 #define MAR_H__
   9
  10 #include "mozilla/Assertions.h"
  11 #include <stdint.h>
  12
  13 #ifdef __cplusplus
  14 extern "C" {
  15 #endif
  16
  17 /* We have a MAX_SIGNATURES limit so that an invalid MAR will never
  18  * waste too much of either updater's or signmar's time.
  19  * It is also used at various places internally and will affect memory usage.
  20  * If you want to increase this value above 9 then you need to adjust parsing
  21  * code in tool/mar.c.
  22 */
  23 #define MAX_SIGNATURES 8
  24 #ifdef __cplusplus
  25 static_assert(MAX_SIGNATURES <= 9, "too many signatures");
  26 #else
  27 MOZ_STATIC_ASSERT(MAX_SIGNATURES <= 9, "too many signatures");
  28 #endif
  29
  30 struct ProductInformationBlock {
  31   const char *MARChannelID;
  32   const char *productVersion;
  33 };
  34
  35 /**
  36  * The MAR item data structure.
  37  */
  38 typedef struct MarItem_ {
  39   struct MarItem_ *next;  /* private field */
  40   uint32_t offset;        /* offset into archive */
  41   uint32_t length;        /* length of data in bytes */
  42   uint32_t flags;         /* contains file mode bits */
  43   char name[1];           /* file path */
  44 } MarItem;
  45
  46 #define TABLESIZE 256
  47
  48 struct MarFile_ {
  49   FILE *fp;
  50   MarItem *item_table[TABLESIZE];
  51 };
  52
  53 typedef struct MarFile_ MarFile;
  54
  55 /**
  56  * Signature of callback function passed to mar_enum_items.
  57  * @param mar       The MAR file being visited.
  58  * @param item      The MAR item being visited.
  59  * @param data      The data parameter passed by the caller of mar_enum_items.
  60  * @return          A non-zero value to stop enumerating.
  61  */
  62 typedef int (* MarItemCallback)(MarFile *mar, const MarItem *item, void *data);
  63
  64 /**
  65  * Open a MAR file for reading.
  66  * @param path      Specifies the path to the MAR file to open.  This path must
  67  *                  be compatible with fopen.
  68  * @return          NULL if an error occurs.
  69  */
  70 MarFile *mar_open(const char *path);
  71
  72 #ifdef _WIN32
  73 MarFile *mar_wopen(const wchar_t *path);
  74 #endif
  75
  76 /**
  77  * Close a MAR file that was opened using mar_open.
  78  * @param mar       The MarFile object to close.
  79  */
  80 void mar_close(MarFile *mar);
  81
  82 /**
  83  * Find an item in the MAR file by name.
  84  * @param mar       The MarFile object to query.
  85  * @param item      The name of the item to query.
  86  * @return          A const reference to a MAR item or NULL if not found.
  87  */
  88 const MarItem *mar_find_item(MarFile *mar, const char *item);
  89
  90 /**
  91  * Enumerate all MAR items via callback function.
  92  * @param mar       The MAR file to enumerate.
  93  * @param callback  The function to call for each MAR item.
  94  * @param data      A caller specified value that is passed along to the
  95  *                  callback function.
  96  * @return          0 if the enumeration ran to completion.  Otherwise, any
  97  *                  non-zero return value from the callback is returned.
  98  */
  99 int mar_enum_items(MarFile *mar, MarItemCallback callback, void *data);
 100
 101 /**
 102  * Read from MAR item at given offset up to bufsize bytes.
 103  * @param mar       The MAR file to read.
 104  * @param item      The MAR item to read.
 105  * @param offset    The byte offset relative to the start of the item.
 106  * @param buf       A pointer to a buffer to copy the data into.
 107  * @param bufsize   The length of the buffer to copy the data into.
 108  * @return          The number of bytes written or a negative value if an
 109  *                  error occurs.
 110  */
 111 int mar_read(MarFile *mar, const MarItem *item, int offset, char *buf,
 112              int bufsize);
 113
 114 /**
 115  * Create a MAR file from a set of files.
 116  * @param dest      The path to the file to create.  This path must be
 117  *                  compatible with fopen.
 118  * @param numfiles  The number of files to store in the archive.
 119  * @param files     The list of null-terminated file paths.  Each file
 120  *                  path must be compatible with fopen.
 121  * @param infoBlock The information to store in the product information block.
 122  * @return          A non-zero value if an error occurs.
 123  */
 124 int mar_create(const char *dest,
 125                int numfiles,
 126                char **files,
 127                struct ProductInformationBlock *infoBlock);
 128
 129 /**
 130  * Extract a MAR file to the current working directory.
 131  * @param path      The path to the MAR file to extract.  This path must be
 132  *                  compatible with fopen.
 133  * @return          A non-zero value if an error occurs.
 134  */
 135 int mar_extract(const char *path);
 136
 137 #define MAR_MAX_CERT_SIZE (16*1024) // Way larger than necessary
 138
 139 /* Read the entire file (not a MAR file) into a newly-allocated buffer.
 140  * This function does not write to stderr. Instead, the caller should
 141  * write whatever error messages it sees fit. The caller must free the returned
 142  * buffer using free().
 143  *
 144  * @param filePath The path to the file that should be read.
 145  * @param maxSize  The maximum valid file size.
 146  * @param data     On success, *data will point to a newly-allocated buffer
 147  *                 with the file's contents in it.
 148  * @param size     On success, *size will be the size of the created buffer.
 149  *
 150  * @return 0 on success, -1 on error
 151  */
 152 int mar_read_entire_file(const char * filePath,
 153                          uint32_t maxSize,
 154                          /*out*/ const uint8_t * *data,
 155                          /*out*/ uint32_t *size);
 156
 157 /**
 158  * Verifies a MAR file by verifying each signature with the corresponding
 159  * certificate. That is, the first signature will be verified using the first
 160  * certificate given, the second signature will be verified using the second
 161  * certificate given, etc. The signature count must exactly match the number of
 162  * certificates given, and all signature verifications must succeed.
 163  * We do not check that the certificate was issued by any trusted authority.
 164  * We assume it to be self-signed.  We do not check whether the certificate
 165  * is valid for this usage.
 166  *
 167  * @param mar            The already opened MAR file.
 168  * @param certData       Pointer to the first element in an array of certificate
 169  *                       file data.
 170  * @param certDataSizes  Pointer to the first element in an array for size of
 171  *                       the cert data.
 172  * @param certCount      The number of elements in certData and certDataSizes
 173  * @return 0 on success
 174  *         a negative number if there was an error
 175  *         a positive number if the signature does not verify
 176  */
 177 int mar_verify_signatures(MarFile *mar,
 178                           const uint8_t * const *certData,
 179                           const uint32_t *certDataSizes,
 180                           uint32_t certCount);
 181
 182 /**
 183  * Reads the product info block from the MAR file's additional block section.
 184  * The caller is responsible for freeing the fields in infoBlock
 185  * if the return is successful.
 186  *
 187  * @param infoBlock Out parameter for where to store the result to
 188  * @return 0 on success, -1 on failure
 189 */
 190 int
 191 mar_read_product_info_block(MarFile *mar,
 192                             struct ProductInformationBlock *infoBlock);
 193
 194 #ifdef __cplusplus
 195 }
 196 #endif
 197
 198 #endif  /* MAR_H__ */