manifest.h@ 40979

Last change on this file since 40979 was 40329, checked in by vboxsync, 13 years ago
Main/Runtime/VBoxManage: SHA256 support comes with OVF 2.0
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 20.4 KB

Line
1	/** @file
2	* IPRT - Manifest file handling.
3	*/
4
5	/*
6	* Copyright (C) 2009 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_manifest_h
27	#define ___iprt_manifest_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31
32	RT_C_DECLS_BEGIN
33
34	/** @defgroup grp_rt_manifest RTManifest - Manifest file creation and checking
35	* @ingroup grp_rt
36	* @{
37	*/
38
39	/** @name Manifest attribute types.
40	* The types can be ORed together to form a set.
41	* @{ */
42	/** For use with other attributes. Representation unknown. */
43	#define RTMANIFEST_ATTR_UNKNOWN 0
44	/** The size of the content. Represented as a decimal number. */
45	#define RTMANIFEST_ATTR_SIZE RT_BIT_32(0)
46	/** The MD5 of the content. Represented as a hex string. */
47	#define RTMANIFEST_ATTR_MD5 RT_BIT_32(1)
48	/** The SHA-1 of the content. Represented as a hex string. */
49	#define RTMANIFEST_ATTR_SHA1 RT_BIT_32(2)
50	/** The SHA-256 of the content. Represented as a hex string. */
51	#define RTMANIFEST_ATTR_SHA256 RT_BIT_32(3)
52	/** The SHA-512 of the content. Represented as a hex string. */
53	#define RTMANIFEST_ATTR_SHA512 RT_BIT_32(4)
54	/** The end of the valid values. */
55	#define RTMANIFEST_ATTR_END RT_BIT_32(5)
56	/** Wildcard for use in queries. */
57	#define RTMANIFEST_ATTR_ANY UINT32_C(0xffffffff)
58	/** @} */
59
60	/** @name Digest types. */
61	typedef enum RTDIGESTTYPE
62	{
63	/** CRC32 checksum */
64	RTDIGESTTYPE_CRC32 = 1,
65	/** CRC64 checksum */
66	RTDIGESTTYPE_CRC64,
67	/** MD5 checksum (unsafe!) */
68	RTDIGESTTYPE_MD5,
69	/** SHA1 checksum (unsafe!) */
70	RTDIGESTTYPE_SHA1,
71	/** SHA256 checksum */
72	RTDIGESTTYPE_SHA256,
73	/** SHA512 checksum */
74	RTDIGESTTYPE_SHA512
75	} RTDIGESTTYPE;
76	/** @} */
77
78
79	/**
80	* Creates an empty manifest.
81	*
82	* @returns IPRT status code.
83	* @param fFlags Flags, MBZ.
84	* @param phManifest Where to return the handle to the manifest.
85	*/
86	RTDECL(int) RTManifestCreate(uint32_t fFlags, PRTMANIFEST phManifest);
87
88	/**
89	* Retains a reference to the manifest handle.
90	*
91	* @returns The new reference count, UINT32_MAX if the handle is invalid.
92	* @param hManifest The handle to retain.
93	*/
94	RTDECL(uint32_t) RTManifestRetain(RTMANIFEST hManifest);
95
96	/**
97	* Releases a reference to the manifest handle.
98	*
99	* @returns The new reference count, 0 if free. UINT32_MAX is returned if the
100	* handle is invalid.
101	* @param hManifest The handle to release.
102	* NIL is quietly ignored (returns 0).
103	*/
104	RTDECL(uint32_t) RTManifestRelease(RTMANIFEST hManifest);
105
106	/**
107	* Creates a duplicate of the specified manifest.
108	*
109	* @returns IPRT status code
110	* @param hManifestSrc The manifest to clone.
111	* @param phManifestDst Where to store the handle to the duplicate.
112	*/
113	RTDECL(int) RTManifestDup(RTMANIFEST hManifestSrc, PRTMANIFEST phManifestDst);
114
115	/**
116	* Compares two manifests for equality.
117	*
118	* @returns IPRT status code.
119	* @retval VINF_SUCCESS if equal.
120	* @retval VERR_NOT_EQUAL if not equal.
121	*
122	* @param hManifest1 The first manifest.
123	* @param hManifest2 The second manifest.
124	* @param papszIgnoreEntries Entries to ignore. Ends with a NULL entry.
125	* @param papszIgnoreAttrs Attributes to ignore. Ends with a NULL entry.
126	* @param fFlags A combination of RTMANIFEST_EQUALS_XXX values.
127	* @param pszError Where to store the name of the mismatching
128	* entry, or as much of the name as there is room
129	* for. This is always set. Optional.
130	* @param cbError The size of the buffer pointed to by @a
131	* pszError.
132	*/
133	RTDECL(int) RTManifestEqualsEx(RTMANIFEST hManifest1, RTMANIFEST hManifest2, const char * const *papszIgnoreEntries,
134	const char * const papszIgnoreAttr, uint32_t fFlags, char pszError, size_t cbError);
135
136	/** @defgroup RTMANIFEST_EQUALS_XXX RTManifestEqualsEx flags
137	* @{ */
138	/** Ignore missing attributes if there is one or more to compare. */
139	#define RTMANIFEST_EQUALS_IGN_MISSING_ATTRS RT_BIT_32(0)
140	/** Ignore attributes missing in the 1st manifest.
141	* @todo implement this */
142	#define RTMANIFEST_EQUALS_IGN_MISSING_ATTRS_1ST RT_BIT_32(1)
143	/** Mask of valid flags. */
144	#define RTMANIFEST_EQUALS_VALID_MASK UINT32_C(0x00000003)
145	/** @} */
146
147	/**
148	* Compares two manifests for equality.
149	*
150	* @returns IPRT status code.
151	* @retval VINF_SUCCESS if equal.
152	* @retval VERR_NOT_EQUAL if not equal.
153	*
154	* @param hManifest1 The first manifest.
155	* @param hManifest2 The second manifest.
156	*/
157	RTDECL(int) RTManifestEquals(RTMANIFEST hManifest1, RTMANIFEST hManifest2);
158
159	/**
160	* Sets a manifest attribute.
161	*
162	* @returns IPRT status code.
163	* @param hManifest The manifest handle.
164	* @param pszAttr The attribute name. If this already exists,
165	* its value will be replaced.
166	* @param pszValue The value string.
167	* @param fType The attribute type, pass
168	* RTMANIFEST_ATTR_UNKNOWN if not known.
169	*/
170	RTDECL(int) RTManifestSetAttr(RTMANIFEST hManifest, const char pszAttr, const char pszValue, uint32_t fType);
171
172	/**
173	* Unsets (removes) a manifest attribute if it exists.
174	*
175	* @returns IPRT status code.
176	* @retval VWRN_NOT_FOUND if not found.
177	*
178	* @param hManifest The manifest handle.
179	* @param pszAttr The attribute name.
180	*/
181	RTDECL(int) RTManifestUnsetAttr(RTMANIFEST hManifest, const char *pszAttr);
182
183	/**
184	* Query a manifest entry attribute.
185	*
186	* @returns IPRT status code.
187	* @retval VERR_BUFFER_OVERFLOW if the value buffer is too small. The @a
188	* pszValue buffer will not be modified.
189	* @retval VERR_MANIFEST_ATTR_NOT_FOUND
190	* @retval VERR_MANIFEST_ATTR_TYPE_NOT_FOUND
191	* @retval VERR_MANIFEST_ATTR_TYPE_MISMATCH
192	*
193	* @param hManifest The manifest handle.
194	* @param pszEntry The entry name.
195	* @param pszAttr The attribute name. If NULL, it will be
196	* selected by @a fType alone.
197	* @param fType The attribute types the entry should match. Pass
198	* Pass RTMANIFEST_ATTR_ANY match any. If more
199	* than one is given, the first matching one is
200	* returned.
201	* @param pszValue Where to return value.
202	* @param cbValue The size of the buffer @a pszValue points to.
203	* @param pfType Where to return the attribute type value.
204	*/
205	RTDECL(int) RTManifestQueryAttr(RTMANIFEST hManifest, const char *pszAttr, uint32_t fType,
206	char pszValue, size_t cbValue, uint32_t pfType);
207
208	/**
209	* Sets an attribute of a manifest entry.
210	*
211	* @returns IPRT status code.
212	* @param hManifest The manifest handle.
213	* @param pszEntry The entry name. This will automatically be
214	* added if there was no previous call to
215	* RTManifestEntryAdd for this name. See
216	* RTManifestEntryAdd for the entry name rules.
217	* @param pszAttr The attribute name. If this already exists,
218	* its value will be replaced.
219	* @param pszValue The value string.
220	* @param fType The attribute type, pass
221	* RTMANIFEST_ATTR_UNKNOWN if not known.
222	*/
223	RTDECL(int) RTManifestEntrySetAttr(RTMANIFEST hManifest, const char pszEntry, const char pszAttr,
224	const char *pszValue, uint32_t fType);
225
226	/**
227	* Unsets (removes) an attribute of a manifest entry if they both exist.
228	*
229	* @returns IPRT status code.
230	* @retval VWRN_NOT_FOUND if not found.
231	*
232	* @param hManifest The manifest handle.
233	* @param pszEntry The entry name.
234	* @param pszAttr The attribute name.
235	*/
236	RTDECL(int) RTManifestEntryUnsetAttr(RTMANIFEST hManifest, const char pszEntry, const char pszAttr);
237
238	/**
239	* Query a manifest entry attribute.
240	*
241	* @returns IPRT status code.
242	* @retval VERR_BUFFER_OVERFLOW if the value buffer is too small. The @a
243	* pszValue buffer will not be modified.
244	* @retval VERR_NOT_FOUND if the entry was not found.
245	* @retval VERR_MANIFEST_ATTR_NOT_FOUND
246	* @retval VERR_MANIFEST_ATTR_TYPE_NOT_FOUND
247	* @retval VERR_MANIFEST_ATTR_TYPE_MISMATCH
248	*
249	* @param hManifest The manifest handle.
250	* @param pszEntry The entry name.
251	* @param pszAttr The attribute name. If NULL, it will be
252	* selected by @a fType alone.
253	* @param fType The attribute types the entry should match. Pass
254	* Pass RTMANIFEST_ATTR_ANY match any. If more
255	* than one is given, the first matching one is
256	* returned.
257	* @param pszValue Where to return value.
258	* @param cbValue The size of the buffer @a pszValue points to.
259	* @param pfType Where to return the attribute type value.
260	*/
261	RTDECL(int) RTManifestEntryQueryAttr(RTMANIFEST hManifest, const char pszEntry, const char pszAttr, uint32_t fType,
262	char pszValue, size_t cbValue, uint32_t pfType);
263
264	/**
265	* Adds a new entry to a manifest.
266	*
267	* The entry name rules:
268	* - The entry name can contain any character defined by unicode, except
269	* control characters, ':', '(' and ')'. The exceptions are mainly there
270	* because of uncertainty around how various formats handles these.
271	* - It is considered case sensitive.
272	* - Forward (unix) and backward (dos) slashes are considered path
273	* separators and converted to forward slashes.
274	*
275	* @returns IPRT status code.
276	* @retval VWRN_ALREADY_EXISTS if the entry already exists.
277	*
278	* @param hManifest The manifest handle.
279	* @param pszEntry The entry name (UTF-8).
280	*
281	* @remarks Some manifest formats will not be able to store an entry without
282	* any attributes. So, this is just here in case it comes in handy
283	* when dealing with formats which can.
284	*/
285	RTDECL(int) RTManifestEntryAdd(RTMANIFEST hManifest, const char *pszEntry);
286
287	/**
288	* Removes an entry.
289	*
290	* @returns IPRT status code.
291	* @param hManifest The manifest handle.
292	* @param pszEntry The entry name.
293	*/
294	RTDECL(int) RTManifestEntryRemove(RTMANIFEST hManifest, const char *pszEntry);
295
296	/**
297	* Add an entry for an I/O stream using a passthru stream.
298	*
299	* The passthru I/O stream will hash all the data read from or written to the
300	* stream and automatically add an entry to the manifest with the desired
301	* attributes when it is released. Alternatively one can call
302	* RTManifestPtIosAddEntryNow() to have more control over exactly when this
303	* action is performed and which status it yields.
304	*
305	* @returns IPRT status code.
306	* @param hManifest The manifest to add the entry to.
307	* @param hVfsIos The I/O stream to pass thru to/from.
308	* @param pszEntry The entry name.
309	* @param fAttrs The attributes to create for this stream.
310	* @param fReadOrWrite Whether it's a read or write I/O stream.
311	* @param phVfsIosPassthru Where to return the new handle.
312	*/
313	RTDECL(int) RTManifestEntryAddPassthruIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry,
314	uint32_t fAttrs, bool fReadOrWrite, PRTVFSIOSTREAM phVfsIosPassthru);
315
316	/**
317	* Adds the entry to the manifest right now.
318	*
319	* @returns IPRT status code.
320	* @param hVfsPtIos The manifest passthru I/O stream returned by
321	* RTManifestEntryAddPassthruIoStream().
322	*/
323	RTDECL(int) RTManifestPtIosAddEntryNow(RTVFSIOSTREAM hVfsPtIos);
324
325	/**
326	* Adds an entry for a file with the specified set of attributes.
327	*
328	* @returns IPRT status code.
329	*
330	* @param hManifest The manifest handle.
331	* @param hVfsIos The I/O stream handle of the entry. This will
332	* be processed to its end on successful return.
333	* (Must be positioned at the start to get
334	* the expected results.)
335	* @param pszEntry The entry name.
336	* @param fAttrs The attributes to create for this stream. See
337	* RTMANIFEST_ATTR_XXX.
338	*/
339	RTDECL(int) RTManifestEntryAddIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry, uint32_t fAttrs);
340
341	/**
342	* Checks if there is a manifest entry by the given name.
343	*
344	* @returns true if there is, false if not or if the handle is invalid.
345	* @param hManifest The manifest handle.
346	* @param pszEntry The entry name.
347	*/
348	RTDECL(bool) RTManifestEntryExists(RTMANIFEST hManifest, const char *pszEntry);
349
350	/**
351	* Reads in a "standard" manifest.
352	*
353	* This reads the format used by OVF, the distinfo in FreeBSD ports, and
354	* others.
355	*
356	* @returns IPRT status code.
357	* @param hManifest The handle to the manifest where to add the
358	* manifest that's read in.
359	* @param hVfsIos The I/O stream to read the manifest from.
360	*/
361	RTDECL(int) RTManifestReadStandard(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos);
362
363	/**
364	* Reads in a "standard" manifest.
365	*
366	* This reads the format used by OVF, the distinfo in FreeBSD ports, and
367	* others.
368	*
369	* @returns IPRT status code.
370	* @param hManifest The handle to the manifest where to add the
371	* manifest that's read in.
372	* @param hVfsIos The I/O stream to read the manifest from.
373	* @param pszErr Where to return extended error info on failure.
374	* Optional.
375	* @param cbErr The size of the buffer @a pszErr points to.
376	*/
377	RTDECL(int) RTManifestReadStandardEx(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, char *pszErr, size_t cbErr);
378
379	/**
380	* Reads in a "standard" manifest from the specified file.
381	*
382	* This reads the format used by OVF, the distinfo in FreeBSD ports, and
383	* others.
384	*
385	* @returns IPRT status code.
386	* @param hManifest The handle to the manifest where to add the
387	* manifest that's read in.
388	* @param pszFilename The name of the file to read in.
389	*/
390	RTDECL(int) RTManifestReadStandardFromFile(RTMANIFEST hManifest, const char *pszFilename);
391
392	/**
393	* Writes a "standard" manifest.
394	*
395	* This writes the format used by OVF, the distinfo in FreeBSD ports, and
396	* others.
397	*
398	* @returns IPRT status code.
399	* @param hManifest The handle to the manifest to write.
400	* @param hVfsIos The I/O stream to read the manifest from.
401	*/
402	RTDECL(int) RTManifestWriteStandard(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos);
403
404	/**
405	* Writes a "standard" manifest to the specified file.
406	*
407	* @returns IPRT status code.
408	* @param hManifest The handle to the manifest to write.
409	* @param pszFilename The name of the file.
410	*/
411	RTDECL(int) RTManifestWriteStandardToFile(RTMANIFEST hManifest, const char *pszFilename);
412
413
414
415
416
417	/**
418	* Input structure for RTManifestVerify() which contains the filename & the
419	* SHA1/SHA256 digest.
420	*/
421	typedef struct RTMANIFESTTEST
422	{
423	/** The filename. */
424	const char *pszTestFile;
425	/** The SHA1/SHA256 digest of the file. */
426	const char *pszTestDigest;
427	} RTMANIFESTTEST;
428	/** Pointer to the input structure. */
429	typedef RTMANIFESTTEST* PRTMANIFESTTEST;
430
431
432	/**
433	* Verify the given SHA1 digests against the entries in the manifest file.
434	*
435	* Please note that not only the various digest have to match, but the
436	* filenames as well. If there are more or even less files listed in the
437	* manifest file than provided by paTests, VERR_MANIFEST_FILE_MISMATCH will be
438	* returned.
439	*
440	* @returns iprt status code.
441	*
442	* @param pszManifestFile Filename of the manifest file to verify.
443	* @param paTests Array of files & SHA1 sums.
444	* @param cTests Number of entries in paTests.
445	* @param piFailed A index to paTests in the
446	* VERR_MANIFEST_DIGEST_MISMATCH error case
447	* (optional).
448	*/
449	RTR3DECL(int) RTManifestVerify(const char pszManifestFile, PRTMANIFESTTEST paTests, size_t cTests, size_t piFailed);
450
451	/**
452	* This is analogous to function RTManifestVerify(), but calculates the SHA1
453	* sums of the given files itself.
454	*
455	* @returns iprt status code.
456	*
457	* @param pszManifestFile Filename of the manifest file to verify.
458	* @param papszFiles Array of files to check SHA1 sums.
459	* @param cFiles Number of entries in papszFiles.
460	* @param piFailed A index to papszFiles in the
461	* VERR_MANIFEST_DIGEST_MISMATCH error case
462	* (optional).
463	* @param pfnProgressCallback optional callback for the progress indication
464	* @param pvUser user defined pointer for the callback
465	*/
466	RTR3DECL(int) RTManifestVerifyFiles(const char pszManifestFile, const char const papszFiles, size_t cFiles, size_t piFailed,
467	PFNRTPROGRESS pfnProgressCallback, void *pvUser);
468
469	/**
470	* Creates a manifest file for a set of files. The manifest file contains SHA1
471	* sums of every provided file and could be used to verify the data integrity
472	* of them.
473	*
474	* @returns iprt status code.
475	*
476	* @param pszManifestFile Filename of the manifest file to create.
477	* @param enmDigestType The digest type (RTDIGESTTYPE_*)
478	* @param papszFiles Array of files to create SHA1 sums for.
479	* @param cFiles Number of entries in papszFiles.
480	* @param pfnProgressCallback optional callback for the progress indication
481	* @param pvUser user defined pointer for the callback
482	*/
483	RTR3DECL(int) RTManifestWriteFiles(const char *pszManifestFile, RTDIGESTTYPE enmDigestType,
484	const char * const *papszFiles, size_t cFiles,
485	PFNRTPROGRESS pfnProgressCallback, void *pvUser);
486
487	/**
488	* Verify the given SHA1 digests against the entries in the manifest file in
489	* memory.
490	*
491	* @returns iprt status code.
492	*
493	* @param pvBuf Pointer to memory buffer of the manifest file.
494	* @param cbSize Size of the memory buffer.
495	* @param paTests Array of file names and digests.
496	* @param cTest Number of entries in paTests.
497	* @param piFailed A index to paTests in the
498	* VERR_MANIFEST_DIGEST_MISMATCH error case
499	* (optional).
500	*/
501	RTR3DECL(int) RTManifestVerifyFilesBuf(void pvBuf, size_t cbSize, PRTMANIFESTTEST paTests, size_t cTests, size_t piFailed);
502
503	/**
504	* Creates a manifest file in memory for a set of files. The manifest file
505	* contains SHA1 sums of every provided file and could be used to verify the
506	* data integrity of them.
507	*
508	* @returns iprt status code.
509	*
510	* @param ppvBuf Pointer to resulting memory buffer.
511	* @param pcbSize Pointer for the size of the memory buffer.
512	* @param enmDigestType Which type of digest ("SHA1", "SHA256", ...)
513	* @param paFiles Array of file names and digests.
514	* @param cFiles Number of entries in paFiles.
515	*/
516	RTR3DECL(int) RTManifestWriteFilesBuf(void *ppvBuf, size_t pcbSize, RTDIGESTTYPE enmDigestType, PRTMANIFESTTEST paFiles, size_t cFiles);
517
518	/** @} */
519
520	RT_C_DECLS_END
521
522	#endif
523

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/manifest.h@ 40979

Download in other formats: