manifest.h@ 106430

Last change on this file since 106430 was 106061, checked in by vboxsync, 3 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 22.1 KB

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

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

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

Download in other formats: