modules/libmar/src/mar.h@b8a032363ba2
modules/libmar/src/mar.h
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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/. */
7 #ifndef MAR_H__
8 #define MAR_H__
10 #include "mozilla/Assertions.h"
11 #include <stdint.h>
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
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
30 struct ProductInformationBlock {
31 const char *MARChannelID;
32 const char *productVersion;
33 };
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;
46 #define TABLESIZE 256
48 struct MarFile_ {
49 FILE *fp;
50 MarItem *item_table[TABLESIZE];
51 };
53 typedef struct MarFile_ MarFile;
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);
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);
72 #ifdef XP_WIN
73 MarFile *mar_wopen(const wchar_t *path);
74 #endif
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);
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);
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);
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);
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);
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);
137 /**
138 * Verifies a MAR file by verifying each signature with the corresponding
139 * certificate. That is, the first signature will be verified using the first
140 * certificate given, the second signature will be verified using the second
141 * certificate given, etc. The signature count must exactly match the number of
142 * certificates given, and all signature verifications must succeed.
143 * We do not check that the certificate was issued by any trusted authority.
144 * We assume it to be self-signed. We do not check whether the certificate
145 * is valid for this usage.
146 *
147 * @param mar The already opened MAR file.
148 * @param certData Pointer to the first element in an array of certificate
149 * file data.
150 * @param certDataSizes Pointer to the first element in an array for size of
151 * the cert data.
152 * @param certCount The number of elements in certData and certDataSizes
153 * @return 0 on success
154 * a negative number if there was an error
155 * a positive number if the signature does not verify
156 */
157 #ifdef XP_WIN
158 int mar_verify_signaturesW(MarFile *mar,
159 const uint8_t * const *certData,
160 const uint32_t *certDataSizes,
161 uint32_t certCount);
162 #endif
164 /**
165 * Reads the product info block from the MAR file's additional block section.
166 * The caller is responsible for freeing the fields in infoBlock
167 * if the return is successful.
168 *
169 * @param infoBlock Out parameter for where to store the result to
170 * @return 0 on success, -1 on failure
171 */
172 int
173 mar_read_product_info_block(MarFile *mar,
174 struct ProductInformationBlock *infoBlock);
176 #ifdef __cplusplus
177 }
178 #endif
180 #endif /* MAR_H__ */
