manifest.h@ 46080

Last change on this file since 46080 was 45227, checked in by vboxsync, 12 years ago
Main: OVF 2.0 support. Part 1 - SHA256 digest is supported.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 20.9 KB

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

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

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

Download in other formats: