acst

Tracks changes and corruption in files using xattr-based checksums.
git clone https://noxz.tech/git/acst.git
Log | Files | Tags | LICENSE

acst.h
1/**
2 * Copyright (C) 2022 Chris Noxz
3 * Author(s): Chris Noxz <chris@noxz.tech>
4 *
5 * This program is free software: you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the Free
7 * Software Foundation, either version 3 of the License, or (at your option)
8 * any later version.
9 *
10 * This program is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
13 * more details.
14 *
15 * You should have received a copy of the GNU General Public License along with
16 * this program. If not, see <https://www.gnu.org/licenses/>.
17 */
18
19#ifndef ACST_H
20#define ACST_H
21
22#include <limits.h>         // for PATH_MAX
23#include <stdbool.h>        // for bool
24#include <stdio.h>          // for printf
25#include <stdlib.h>         // for exit, EXIT_SUCCESS, size_t
26
27#define BUFSZ               8192    /* buffer size to use in hash computation */
28#define SHA256_BYTES        32      /* byte size of SHA256 hash */
29#define CSSZ                64      /* size of SHA256 hash stored as hex */
30#define TSSZ                32      /* allocation size for timespan holder */
31#define XATTR_CS            "user.acst.cs"  /* name of checksum xattr */
32#define XATTR_TS            "user.acst.ts"  /* name of timestamp xattr */
33#define FRMT_TS             "%010llu.%09lu" /* format of timestamp xattr */
34
35/* string values used in program, could be changes for language compliance */
36#define STR_CMP_FRMT        " stored: %s "FRMT_TS"\n"                       \
37                            " actual: %s "FRMT_TS"\n"
38#define STR_DPN_FRMT        " %s\n"
39#define STR_DPH_FRMT        "<dup> %s\n"STR_DPN_FRMT
40#define STR_DPS_FRMT        "Found %d files with duplicates.\n"
41#define STR_ERR_OOM         "Error: out of memory\n"
42#define STR_ERR_PMAX        "Error: PATH_MAX reached before end\n"
43#define STR_ERR_ABNO        "Error: abnormal changes detected \"%s\"\n"
44#define STR_ERR_OPNF        "Error: could not open file \"%s\"\n"
45#define STR_ERR_REGF        "Error: not a regular file \"%s\"\n"
46#define STR_ERR_HASH        "Error: could not compute hash \"%s\"\n"
47#define STR_ERR_XARM        "Error: could not remove extended attributes from file \"%s\": %s\n"
48#define STR_ERR_XAWR        "Error: could not write extended attributes to file \"\%s\"\n"
49#define STR_OUT_STAT        "<%s> %s\n"
50#define STR_OUT_NEW         "new"
51#define STR_OUT_OK          "ok"
52#define STR_OUT_TOUC        "hash ok"
53#define STR_OUT_OUTD        "outdated"
54#define STR_OUT_BACK        "backdated"
55#define STR_OUT_CORR        "corrupt"
56#define STR_OUT_MALF        "malformed"
57#define STR_OUT_DISR        "disrupted"
58#define STR_OUT_REMO        "xattr removed"
59
60#define MIN(X, Y)           (((X) < (Y)) ? (X) : (Y))
61#define USAGE(code)                                                         \
62        {                                                                   \
63          printf("Usage: %s [OPTION]... <FILE>...\n", gl.prg);              \
64          if ((code) == EXIT_SUCCESS)                                       \
65            printf(                                                         \
66    "\n"                                                                    \
67    "Tracks changes and corruption in files using xattr-based checksums.\n" \
68    "\n"                                                                    \
69    "Positional arguments:\n"                                               \
70    "  FILE                  file(s) to track\n"                            \
71    "\n"                                                                    \
72    "Optional arguments:\n"                                                 \
73    "  -h                    show this help message and exit\n"             \
74    "  -m                    summarize information at end of execution\n"   \
75    "  -n                    don't create or update any file attributes\n"  \
76    "  -q                    quiet mode, lowers verbosity\n"                \
77    "  -V                    output version information and exit\n"         \
78    "  -x                    remove extended attributes from file(s)\n"     \
79    "\n"                                                                    \
80    "Full documentation <https://noxz.tech/software/acst>\n"                \
81            );                                                              \
82          exit(code);                                                       \
83        }
84#define VER()                                                               \
85        {                                                                   \
86          printf("%s " VERSION "\n", gl.prg);                               \
87          exit(EXIT_SUCCESS);                                               \
88        }
89#define SUMMERIZE()                                                         \
90        {                                                                   \
91          if (arg.remove)                                                   \
92            printf(         "\n"                                            \
93                            "Total files processed      : %d\n"             \
94                            "  Xattr removed            : %d\n"             \
95                            "Total errors               : %d\n"             \
96                            "  Opening files            : %d\n"             \
97                            "  Non-regular files        : %d\n"             \
98                            "  Xattr operations         : %d\n"             \
99                            "  Generic                  : %d\n"             \
100              , cnt.total, cnt.ok                                           \
101              , cnt.errs, cnt.errOpening, cnt.errNotRegular                 \
102              , cnt.errWritingXattr, cnt.errGeneric);                       \
103          else                                                              \
104            printf(         "\n"                                            \
105                            "Total files processed      : %d\n"             \
106                            "  New                      : %d\n"             \
107                            "  Ok                       : %d\n"             \
108                            "  Hash ok                  : %d\n"             \
109                            "  Outdated                 : %d\n"             \
110                            "  Backdated                : %d\n"             \
111                            "  Corrupt                  : %d\n"             \
112                            "  Malformed                : %d\n"             \
113                            "  Disrupted                : %d\n"             \
114                            "Total errors               : %d\n"             \
115                            "  Opening files            : %d\n"             \
116                            "  Non-regular files        : %d\n"             \
117                            "  Xattr operations         : %d\n"             \
118                            "  Generic                  : %d\n"             \
119              , cnt.total, cnt.new, cnt.ok, cnt.touched                     \
120              , cnt.outdated, cnt.backdated, cnt.corrupt                    \
121              , cnt.malformed, cnt.disrupted                                \
122              , cnt.errs, cnt.errOpening, cnt.errNotRegular                 \
123              , cnt.errWritingXattr, cnt.errGeneric);                       \
124        }
125
126/* helper variables used by various functions */
127static char ts[TSSZ];                               /* timestamp holder */
128static const char hextab[]  = "0123456789abcdef";   /* hex digit table */
129static const char zSHA256[] = "0000000000000000"    /* zeroed out SHA256 */
130                              "0000000000000000"    /* why 4 lines?... */
131                              "0000000000000000"
132                              "0000000000000000";   /* ...it looks better! */
133
134enum Error {
135	ER_NOT_REGULAR,         /* not a regular file error */
136	ER_OPENING,             /* error opening file */
137	ER_XATTR_OPERATION,     /* error when performing xattr operations */
138	ER_GENERIC,             /* generic error */
139	ER_FATAL                /* fatal error, should result in program ending */
140};
141
142enum FileState {
143	FS_OK,                  /* checksum and mtime both match */
144	FS_DISRUPTED,           /* file was changed during hash computation */
145	FS_CORRUPT,             /* checksum differs while mtime matches */
146	FS_MALFORMED,           /* xattrs cannot be read in its intended format */
147	FS_TOUCHED,             /* checksum matches but mtime doesn't */
148	FS_NEW,                 /* file has no prior checksum or mtime stored */
149	FS_OUTDATED,            /* checksum differs and mtime is newer */
150	FS_BACKDATED,           /* checksum differs and mtime is older */
151	FS_REMOVED,             /* xattrs have been removed from file */
152	FS_REMOVED_ERROR,       /* removal of xattrs failed */
153	FS_ERROR                /* general error */
154};
155
156typedef struct DuplicateNode {
157	unsigned char           cs[SHA256_BYTES];   /* checksum */
158	char                    fn[PATH_MAX + 1];   /* file name */
159	struct DuplicateNode   *next;               /* reference pointer to next dup */
160} dn_t;
161
162/* extended attribute/metadata structure */
163typedef struct ExtendedAttribute {
164	unsigned long long      s;                  /* seconds */
165	unsigned long           ns;                 /* nanoseconds */
166	char                    hex[CSSZ + 1];      /* checksum (hex) */
167	unsigned char           cs[SHA256_BYTES];   /* checksum (binary) */
168	int                     tcmp;               /* timespan comparison holder */
169} xa_t;
170
171/* arguments collected from command line */
172struct Arguments {
173	bool                    dryrun;             /* make a dry run */
174	int                     quiet;              /* level of quietness */
175	bool                    remove;             /* remove xattrs */
176	bool                    summarize;          /* show summery at end of program */
177	bool                    duplicates;         /* use xattrs to find duplicates */
178} arg;
179
180/* counters */
181struct Counters {
182	int                     errs;               /* all errors */
183	int                     errNotRegular;      /* not a regular file errors  */
184	int                     errOpening;         /* errors opening file */
185	int                     errWritingXattr;    /* errors when performing xattr operations */
186	int                     errGeneric;         /* generic errors */
187
188	int                     total;              /* all non error counters */
189	int                     ok;                 /* checksum and mtime both match */
190	int                     disrupted;          /* file was changed during hash computation */
191	int                     corrupt;            /* checksum differs while mtime matches */
192	int                     malformed;          /* xattrs cannot be read in its intended format */
193	int                     outdated;           /* checksum differs and mtime is newer */
194	int                     backdated;          /* checksum differs and mtime is older */
195	int                     touched;            /* checksum matches but mtime doesn't */
196	int                     new;                /* file has no prior checksum or mtime stored */
197} cnt;
198
199/* global variables */
200struct Global {
201	const char             *prg;                /* program name */
202	dn_t                   *dup_head;           /* head of Duplicate nodes */
203} gl;
204
205/**
206 * Converts binary data into hex format.
207 *
208 * @param bin               The binary data
209 * @param len               The size of the data
210 * @param hex               The result of the converted data
211 */
212static void bin2hex(unsigned char *bin, size_t len, char *hex);
213
214/**
215 * Compares two checksums (binary SHA256) to see if they are equal or not.
216 *
217 * @param cs1               The first checksum
218 * @param cs2               The second checksum
219 *
220 * @returns                 Value < 0 to indicate that cs1 is less than cs2
221 * @returns                 Value > 0 to indicate that cs1 is greater than cs2
222 * @returns                 Value = 0 to indicate that cs1 is equal to cs2
223 */
224static int cscmp(const unsigned char *cs1, const unsigned char *cs2);
225
226/**
227 * Recursively deallocates the memory previously allocated by a linked
228 * duplicate list.
229 *
230 * @param head_ref          Reference to first (initial call) or current node
231 */
232static void dup_free(dn_t **head_ref);
233
234/**
235 * Divides the nodes in the given linked list into front and back halves
236 * referenced by the two reference pointers. If the length is odd, the extra
237 * node ends by design up in the front list. As list length is unknown a double
238 * step pointer is used together with a single step pointer resulting in
239 * the single step pointer referencing the midpoint of the list as the double
240 * step pointer reaches the end of the list.
241 *
242 * @param src               Pointer to the source list to be split
243 * @param front_ref         Reference pointer to the resulting front list
244 * @param back_ref          Retrieves pointer to the resulting back list
245 */
246static void dup_front_back_split(dn_t *src, dn_t **front_ref, dn_t **back_ref);
247
248/**
249 * Recursively performs the merge sort by first splitting lists, starting from
250 * the head of the list, into length of 1 or 0, then by comparing nodes in
251 * lists merges them together into one list once again.
252 *
253 * see: https://en.wikipedia.org/wiki/Merge_sort
254 *
255 * @param head_ref          Reference to head of each list
256 */
257static void dup_merge_sort(dn_t **head_ref);
258
259/**
260 * Print a linked list of duplicate nodes by first sorting it to then iterate
261 * and comparing the current node with the previous to identify duplicates of
262 * file content.
263 *
264 * @param head_ref          Reference to head of list to print
265 *
266 * @returns                 Returns EXIT_SUCCESS when done
267 */
268static int dup_print(dn_t **head_ref);
269
270/**
271 * Inserts a new node at the beginning of the linked duplicate list with
272 * attached filename and checksum from extended file attribute.
273 *
274 * @param head_ref          Reference to head of linked list
275 * @param fn                Name of the file
276 * @param fd                File descriptor of the file
277 * @param xa                Extended attribute of file
278 */
279static void dup_push(dn_t **head_ref, const char *fn, int fd, xa_t *xa);
280
281/**
282 * Recursively performs the sorting part of the merge sort, where checksums of
283 * nodes are compared from two lists being merged together based on comparison.
284 *
285 * see: https://en.wikipedia.org/wiki/Merge_sort
286 *
287 * @param a                 One of the lists being compared
288 * @param b                 The other list being compared to the first one
289 *
290 * @returns                 The resulting list from the sorted merge
291 */
292static dn_t* dup_sorted_merge(dn_t *a, dn_t *b);
293
294/**
295 * Retrieves and reports error types and messages. If error type is of fatal
296 * nature, the program will exit with EXIT_FAILURE.
297 *
298 * @param er                The type of error (see enum Error above)
299 * @param fmt               The output format of the error message
300 * @param ...               Various arguments to output in the message
301 */
302static void error(enum Error er, const char *fmt, ...);
303
304/**
305 * Final stage of processing a file which returns the state of the file being
306 * processed meanwhile metadata holders are being populated.
307 *
308 * @param fd                File descriptor of the file
309 * @param xa_s              Metadata holder of (stored) extended attributes
310 * @param xa_a              Metadata holder of (actual) extended attributes
311 *
312 * @returns                 The file state of the file being processed
313 */
314static enum FileState file_state(int fd, xa_t *xa_s, xa_t *xa_a);
315
316/**
317 * Processes arguments (file names) from command line
318 * output.
319 *
320 * @param fn                Name of the file
321 */
322static void process_argument(const char *fn);
323
324/**
325 * Processes files and returns either error messages or other output if stated
326 * to do so (see arg.quiet) based on their file state (see enum FileState
327 * above).
328 *
329 * @param fn                Name of the file
330 */
331static void process_file(const char *fn);
332
333/**
334 * Reports on files and their file state.
335 *
336 * @param fn                Name of the file
337 * @param st                The state of the file
338 */
339static void report(const char *fn, enum FileState st);
340
341/**
342 * Compute and retrieve metadata for the checksum based on file content
343 * together with the date modified.
344 *
345 * @param fd                File descriptor of the file
346 * @param xa                Metadata holder of extended attributes
347 *
348 * @returns                 True if no error occurred
349 * @returns                 False if an error occurred
350 */
351static bool xa_compute(int fd, xa_t *xa);
352
353/**
354 * Computes the hash checksum of a file based on the SHA256 hashing algorithm.
355 *
356 * @param fd                File descriptor of the file
357 * @param cs                Pointer for the checksum
358 */
359static void xa_hash(int fd, unsigned char *cs);
360
361/**
362 * Reads and retrieves extended attributes as metadata from a file.
363 *
364 * @param fd                File descriptor of the file
365 * @param xa                Metadata holder of extended attributes
366 *
367 * @returns                 True if no error occurred
368 * @returns                 False if an error occurred (malformed data)
369 */
370static bool xa_read(int fd, xa_t *xa);
371
372/**
373 *  Writes, or removes if stated (see arg.remove), extended attributes as
374 *  metadata to a file.
375 *
376 * @param fd               File descriptor of the file
377 * @param xa                Metadata holder of extended attributes
378 *
379 * @returns                 True if no error occurred
380 * @returns                 False if an error occurred (write error)
381 */
382static bool xa_write(int fd, const xa_t *xa);
383
384#endif /* !ACST_H */