VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 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-2023 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
45RT_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 */
81RTDECL(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 */
89RTDECL(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 */
99RTDECL(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 */
108RTDECL(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 */
128RTDECL(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 */
154RTDECL(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 */
165RTDECL(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 */
180RTDECL(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 */
191RTDECL(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 */
214RTDECL(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 */
234RTDECL(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 */
247RTDECL(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 */
272RTDECL(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 */
296RTDECL(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 */
305RTDECL(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 */
324RTDECL(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 */
334RTDECL(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 */
342RTDECL(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 */
358RTDECL(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 */
367RTDECL(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 */
380RTDECL(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 */
396RTDECL(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 */
409RTDECL(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 */
421RTDECL(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 */
430RTDECL(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 */
440typedef 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. */
448typedef 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 */
469RTR3DECL(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 */
487RTR3DECL(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 */
505RTR3DECL(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 */
520RTR3DECL(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 */
537RTR3DECL(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 */
553RTR3DECL(int) RTManifestWriteFilesBuf(void **ppvBuf, size_t *pcbSize, RTDIGESTTYPE enmDigestType, PRTMANIFESTTEST paFiles, size_t cFiles);
554
555/** @} */
556
557RT_C_DECLS_END
558
559#endif /* !IPRT_INCLUDED_manifest_h */
560
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette