1 /*        $NetBSD: edit_file.c,v 1.4 2022/10/08 16:12:50 christos Exp $         */
2 
3 /*++
4 /* NAME
5 /*        edit_file 3
6 /* SUMMARY
7 /*        simple cooperative file updating protocol
8 /* SYNOPSIS
9 /*        #include <edit_file.h>
10 /*
11 /*        typedef struct {
12 /* .in +4
13 /*                  char      *tmp_path;          /* temp. pathname */
14 /*                  VSTREAM *tmp_fp;    /* temp. stream */
15 /*                  /* private members... */
16 /* .in -4
17 /*        } EDIT_FILE;
18 /*
19 /*        EDIT_FILE *edit_file_open(original_path, output_flags, output_mode)
20 /*        const char *original_path;
21 /*        int       output_flags;
22 /*        mode_t    output_mode;
23 /*
24 /*        int       edit_file_close(edit_file)
25 /*        EDIT_FILE *edit_file;
26 /*
27 /*        void      edit_file_cleanup(edit_file)
28 /*        EDIT_FILE *edit_file;
29 /* DESCRIPTION
30 /*        This module implements a simple protocol for cooperative
31 /*        processes to update one file. The idea is to 1) create a
32 /*        new file under a deterministic temporary pathname, 2)
33 /*        populate the new file with updated information, and 3)
34 /*        rename the new file into the place of the original file.
35 /*        This module provides 1) and 3), and leaves 2) to the
36 /*        application. The temporary pathname is deterministic to
37 /*        avoid accumulation of thrash after program crashes.
38 /*
39 /*        edit_file_open() implements the first phase of the protocol.
40 /*        It creates or opens an output file with a deterministic
41 /*        temporary pathname, obtained by appending the suffix defined
42 /*        with EDIT_FILE_SUFFIX to the specified original file pathname.
43 /*        The original file itself is not opened.  edit_file_open()
44 /*        then locks the output file for exclusive access, and verifies
45 /*        that the file still exists under the temporary pathname.
46 /*        At this point in the protocol, the current process controls
47 /*        both the output file content and its temporary pathname.
48 /*
49 /*        In the second phase, the application opens the original
50 /*        file if needed, and updates the output file via the
51 /*        \fBtmp_fp\fR member of the EDIT_FILE data structure.  This
52 /*        phase is not implemented by the edit_file() module.
53 /*
54 /*        edit_file_close() implements the third and final phase of
55 /*        the protocol.  It flushes the output file to persistent
56 /*        storage, and renames the output file from its temporary
57 /*        pathname into the place of the original file. When any of
58 /*        these operations fails, edit_file_close() behaves as if
59 /*        edit_file_cleanup() was called. Regardless of whether these
60 /*        operations succeed, edit_file_close() releases the exclusive
61 /*        lock, closes the output file, and frees up memory that was
62 /*        allocated by edit_file_open().
63 /*
64 /*        edit_file_cleanup() aborts the protocol. It discards the
65 /*        output file, releases the exclusive lock, closes the output
66 /*        file, and frees up memory that was allocated by edit_file_open().
67 /*
68 /*        Arguments:
69 /* .IP original_path
70 /*        The pathname of the original file that will be replaced by
71 /*        the output file. The temporary pathname for the output file
72 /*        is obtained by appending the suffix defined with EDIT_FILE_SUFFIX
73 /*        to a copy of the specified original file pathname, and is
74 /*        made available via the \fBtmp_path\fR member of the EDIT_FILE
75 /*        data structure.
76 /* .IP output_flags
77 /*        Flags for opening the output file. These are as with open(2),
78 /*        except that the O_TRUNC flag is ignored.  edit_file_open()
79 /*        always truncates the output file after it has obtained
80 /*        exclusive control over the output file content and temporary
81 /*        pathname.
82 /* .IP output_mode
83 /*        Permissions for the output file. These are as with open(2),
84 /*        except that the output file is initially created with no
85 /*        group or other access permissions. The specified output
86 /*        file permissions are applied by edit_file_close().
87 /* .IP edit_file
88 /*        Pointer to data structure that is returned upon successful
89 /*        completion by edit_file_open(), and that must be passed to
90 /*        edit_file_close() or edit_file_cleanup().
91 /* DIAGNOSTICS
92 /*        Fatal errors: memory allocation failure, fstat() failure,
93 /*        unlink() failure, lock failure, ftruncate() failure.
94 /*
95 /*        edit_file_open() immediately returns a null pointer when
96 /*        it cannot open the output file.
97 /*
98 /*        edit_file_close() returns zero on success, VSTREAM_EOF on
99 /*        failure.
100 /*
101 /*        With both functions, the global errno variable indicates
102 /*        the nature of the problem.  All errors are relative to the
103 /*        temporary output's pathname. With both functions, this
104 /*        pathname is not available via the EDIT_FILE data structure,
105 /*        because that structure was already destroyed, or not created.
106 /* BUGS
107 /*        In the non-error case, edit_file_open() will not return
108 /*        until it obtains exclusive control over the output file
109 /*        content and temporary pathname.  Applications that are
110 /*        concerned about deadlock should protect the edit_file_open()
111 /*        call with a watchdog timer.
112 /*
113 /*        When interrupted, edit_file_close() may leave behind a
114 /*        world-readable output file under the temporary pathname.
115 /*        On some systems this can be used to inflict a shared-lock
116 /*        DOS on the protocol.  Applications that are concerned about
117 /*        maximal safety should protect the edit_file_close() call
118 /*        with sigdelay() and sigresume() calls, but this introduces
119 /*        the risk that the program will get stuck forever.
120 /* LICENSE
121 /* .ad
122 /* .fi
123 /*        The Secure Mailer license must be distributed with this software.
124 /* AUTHOR(S)
125 /*        Based on code originally by:
126 /*        Victor Duchovni
127 /*        Morgan Stanley
128 /*
129 /*        Packaged into one module with minor improvements by:
130 /*        Wietse Venema
131 /*        IBM T.J. Watson Research
132 /*        P.O. Box 704
133 /*        Yorktown Heights, NY 10598, USA
134 /*--*/
135 
136 /* System library. */
137 
138 #include <sys_defs.h>
139 #include <sys/stat.h>
140 #include <stdio.h>                      /* rename(2) */
141 #include <errno.h>
142 
143  /*
144   * This mask selects all permission bits in the st_mode stat data. There is
145   * no portable definition (unlike S_IFMT, which is defined for the file type
146   * bits). For example, BSD / Linux have ALLPERMS, while Solaris has S_IAMB.
147   */
148 #define FILE_PERM_MASK \
149           (S_ISUID | S_ISGID | S_ISVTX | S_IRWXU | S_IRWXG | S_IRWXO)
150 
151 /* Utility Library. */
152 
153 #include <msg.h>
154 #include <vstream.h>
155 #include <mymalloc.h>
156 #include <stringops.h>
157 #include <myflock.h>
158 #include <edit_file.h>
159 #include <warn_stat.h>
160 
161  /*
162   * Do we reuse and truncate an output file that persists after a crash, or
163   * do we unlink it and create a new file?
164   */
165 #define EDIT_FILE_REUSE_AFTER_CRASH
166 
167  /*
168   * Protocol internals: the temporary file permissions.
169   */
170 #define EDIT_FILE_MODE        (S_IRUSR | S_IWUSR) /* temp file mode */
171 
172  /*
173   * Make complex operations more readable. We could use functions, instead.
174   * The main thing is that we keep the _alloc and _free code together.
175   */
176 #define EDIT_FILE_ALLOC(ep, path, mode) do { \
177           (ep) = (EDIT_FILE *) mymalloc(sizeof(EDIT_FILE)); \
178           (ep)->final_path = mystrdup(path); \
179           (ep)->final_mode = (mode); \
180           (ep)->tmp_path = concatenate((path), EDIT_FILE_SUFFIX, (char *) 0); \
181           (ep)->tmp_fp = 0; \
182     } while (0)
183 
184 #define EDIT_FILE_FREE(ep) do { \
185           myfree((ep)->final_path); \
186           myfree((ep)->tmp_path); \
187           myfree((void *) (ep)); \
188     } while (0)
189 
190 /* edit_file_open - open and lock file with deterministic temporary pathname */
191 
edit_file_open(const char * path,int flags,mode_t mode)192 EDIT_FILE *edit_file_open(const char *path, int flags, mode_t mode)
193 {
194     struct stat before_lock;
195     struct stat after_lock;
196     int     saved_errno;
197     EDIT_FILE *ep;
198 
199     /*
200      * Initialize. Do not bother to optimize for the error case.
201      */
202     EDIT_FILE_ALLOC(ep, path, mode);
203 
204     /*
205      * As long as the output file can be opened under the temporary pathname,
206      * this code can loop or block forever.
207      *
208      * Applications that are concerned about deadlock should protect the
209      * edit_file_open() call with a watchdog timer.
210      */
211     for ( /* void */ ; /* void */ ; (void) vstream_fclose(ep->tmp_fp)) {
212 
213           /*
214            * Try to open the output file under the temporary pathname. This
215            * succeeds or fails immediately. To avoid creating a shared-lock DOS
216            * opportunity after we crash, we create the output file with no
217            * group or other permissions, and set the final permissions at the
218            * end (this is one reason why we try to get exclusive control over
219            * the output file instead of the original file). We postpone file
220            * truncation until we have obtained exclusive control over the file
221            * content and temporary pathname. If the open operation fails, we
222            * give up immediately. The caller can retry the call if desirable.
223            *
224            * XXX If we replace the vstream_fopen() call by safe_open(), then we
225            * should replace the stat() call below by lstat().
226            */
227           if ((ep->tmp_fp = vstream_fopen(ep->tmp_path, flags & ~(O_TRUNC),
228                                                   EDIT_FILE_MODE)) == 0) {
229               saved_errno = errno;
230               EDIT_FILE_FREE(ep);
231               errno = saved_errno;
232               return (0);
233           }
234 
235           /*
236            * At this point we may have opened an existing output file that was
237            * already locked. Try to lock the open file exclusively. This may
238            * take some time.
239            */
240           if (myflock(vstream_fileno(ep->tmp_fp), INTERNAL_LOCK,
241                         MYFLOCK_OP_EXCLUSIVE) < 0)
242               msg_fatal("lock %s: %m", ep->tmp_path);
243 
244           /*
245            * At this point we have an exclusive lock, but some other process
246            * may have renamed or removed the output file while we were waiting
247            * for the lock. If that is the case, back out and try again.
248            */
249           if (fstat(vstream_fileno(ep->tmp_fp), &before_lock) < 0)
250               msg_fatal("open %s: %m", ep->tmp_path);
251           if (stat(ep->tmp_path, &after_lock) < 0
252               || before_lock.st_dev != after_lock.st_dev
253               || before_lock.st_ino != after_lock.st_ino
254 #ifdef HAS_ST_GEN
255               || before_lock.st_gen != after_lock.st_gen
256 #endif
257           /* No need to compare st_rdev or st_nlink here. */
258               ) {
259               continue;
260           }
261 
262           /*
263            * At this point we have exclusive control over the output file
264            * content and its temporary pathname (within the rules of the
265            * cooperative protocol). But wait, there is more.
266            *
267            * There are many opportunities for trouble when opening a pre-existing
268            * output file. Here are just a few.
269            *
270            * - Victor observes that a system crash in the middle of the
271            * final-phase rename() operation may result in the output file
272            * having both the temporary pathname and the final pathname. In that
273            * case we must not write to the output file.
274            *
275            * - Wietse observes that crashes may also leave the output file in
276            * other inconsistent states. To avoid permission-related trouble, we
277            * simply refuse to work with an output file that has the wrong
278            * temporary permissions. This won't stop the shared-lock DOS if we
279            * crash after changing the file permissions, though.
280            *
281            * To work around these crash-related problems, remove the temporary
282            * pathname, back out, and try again.
283            */
284           if (!S_ISREG(after_lock.st_mode)
285 #ifndef EDIT_FILE_REUSE_AFTER_CRASH
286               || after_lock.st_size > 0
287 #endif
288               || after_lock.st_nlink > 1
289               || (after_lock.st_mode & FILE_PERM_MASK) != EDIT_FILE_MODE) {
290               if (unlink(ep->tmp_path) < 0 && errno != ENOENT)
291                     msg_fatal("unlink %s: %m", ep->tmp_path);
292               continue;
293           }
294 
295           /*
296            * Settle the final details.
297            */
298 #ifdef EDIT_FILE_REUSE_AFTER_CRASH
299           if (ftruncate(vstream_fileno(ep->tmp_fp), 0) < 0)
300               msg_fatal("truncate %s: %m", ep->tmp_path);
301 #endif
302           return (ep);
303     }
304 }
305 
306 /* edit_file_cleanup - clean up without completing the protocol */
307 
edit_file_cleanup(EDIT_FILE * ep)308 void    edit_file_cleanup(EDIT_FILE *ep)
309 {
310 
311     /*
312      * Don't touch the file after we lose the exclusive lock!
313      */
314     if (unlink(ep->tmp_path) < 0 && errno != ENOENT)
315           msg_fatal("unlink %s: %m", ep->tmp_path);
316     (void) vstream_fclose(ep->tmp_fp);
317     EDIT_FILE_FREE(ep);
318 }
319 
320 /* edit_file_close - rename the file into place and close the file */
321 
edit_file_close(EDIT_FILE * ep)322 int     edit_file_close(EDIT_FILE *ep)
323 {
324     VSTREAM *fp = ep->tmp_fp;
325     int     fd = vstream_fileno(fp);
326     int     saved_errno;
327 
328     /*
329      * The rename/unlock portion of the protocol is relatively simple. The
330      * only things that really matter here are that we change permissions as
331      * late as possible, and that we rename the file to its final pathname
332      * before we lose the exclusive lock.
333      *
334      * Applications that are concerned about maximal safety should protect the
335      * edit_file_close() call with sigdelay() and sigresume() calls. It is
336      * not safe for us to call these functions directly, because the calls do
337      * not nest. It is also not nice to force every caller to run with
338      * interrupts turned off.
339      */
340     if (vstream_fflush(fp) < 0
341           || fchmod(fd, ep->final_mode) < 0
342 #ifdef HAS_FSYNC
343           || fsync(fd) < 0
344 #endif
345           || rename(ep->tmp_path, ep->final_path) < 0) {
346           saved_errno = errno;
347           edit_file_cleanup(ep);
348           errno = saved_errno;
349           return (VSTREAM_EOF);
350     } else {
351           (void) vstream_fclose(ep->tmp_fp);
352           EDIT_FILE_FREE(ep);
353           return (0);
354     }
355 }
356