1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *  * Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  *  * Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in
12  *    the documentation and/or other materials provided with the
13  *    distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
18  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
19  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
21  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
22  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
23  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
25  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26  * SUCH DAMAGE.
27  */
28 
29 #pragma once
30 
31 #include <stdbool.h>
32 #include <stdint.h>
33 #include <sys/cdefs.h>
34 
35 __BEGIN_DECLS
36 
37 /*
38  * Error checking for close(2).
39  *
40  * Mishandling of file descriptor ownership is a common source of errors that
41  * can be extremely difficult to diagnose. Mistakes like the following can
42  * result in seemingly 'impossible' failures showing up on other threads that
43  * happened to try to open a file descriptor between the buggy code's close and
44  * fclose:
45  *
46  *     int print(int fd) {
47  *         int rc;
48  *         char buf[128];
49  *         while ((rc = read(fd, buf, sizeof(buf))) > 0) {
50  *             printf("%.*s", rc);
51  *         }
52  *         close(fd);
53  *     }
54  *
55  *     int bug() {
56  *         FILE* f = fopen("foo", "r");
57  *         print(fileno(f));
58  *         fclose(f);
59  *     }
60  *
61  * To make it easier to find this class of bugs, bionic provides a method to
62  * require that file descriptors are closed by their owners. File descriptors
63  * can be associated with tags with which they must be closed. This allows
64  * objects that conceptually own an fd (FILE*, unique_fd, etc.) to use their
65  * own address at the tag, to enforce that closure of the fd must come as a
66  * result of their own destruction (fclose, ~unique_fd, etc.)
67  *
68  * By default, a file descriptor's tag is 0, and close(fd) is equivalent to
69  * closing fd with the tag 0.
70  */
71 
72 /*
73  * For improved diagnostics, the type of a file descriptors owner can be
74  * encoded in the most significant byte of the owner tag. Values of 0 and 0xff
75  * are ignored, which allows for raw pointers to be used as owner tags without
76  * modification.
77  */
78 enum android_fdsan_owner_type {
79   /*
80    * Generic Java or native owners.
81    *
82    * Generic Java objects always use 255 as their type, using identityHashCode
83    * as the value of the tag, leaving bits 33-56 unset. Native pointers are sign
84    * extended from 48-bits of virtual address space, and so can have the MSB
85    * set to 255 as well. Use the value of bits 49-56 to distinguish between
86    * these cases.
87    */
88   ANDROID_FDSAN_OWNER_TYPE_GENERIC_00 = 0,
89   ANDROID_FDSAN_OWNER_TYPE_GENERIC_FF = 255,
90 
91   /* FILE* */
92   ANDROID_FDSAN_OWNER_TYPE_FILE = 1,
93 
94   /* DIR* */
95   ANDROID_FDSAN_OWNER_TYPE_DIR = 2,
96 
97   /* android::base::unique_fd */
98   ANDROID_FDSAN_OWNER_TYPE_UNIQUE_FD = 3,
99 
100   /* sqlite-owned file descriptors */
101   ANDROID_FDSAN_OWNER_TYPE_SQLITE = 4,
102 
103   /* java.io.FileInputStream */
104   ANDROID_FDSAN_OWNER_TYPE_FILEINPUTSTREAM = 5,
105 
106   /* java.io.FileOutputStream */
107   ANDROID_FDSAN_OWNER_TYPE_FILEOUTPUTSTREAM = 6,
108 
109   /* java.io.RandomAccessFile */
110   ANDROID_FDSAN_OWNER_TYPE_RANDOMACCESSFILE = 7,
111 
112   /* android.os.ParcelFileDescriptor */
113   ANDROID_FDSAN_OWNER_TYPE_PARCELFILEDESCRIPTOR = 8,
114 
115   /* ART FdFile */
116   ANDROID_FDSAN_OWNER_TYPE_ART_FDFILE = 9,
117 
118   /* java.net.DatagramSocketImpl */
119   ANDROID_FDSAN_OWNER_TYPE_DATAGRAMSOCKETIMPL = 10,
120 
121   /* java.net.SocketImpl */
122   ANDROID_FDSAN_OWNER_TYPE_SOCKETIMPL = 11,
123 
124   /* libziparchive's ZipArchive */
125   ANDROID_FDSAN_OWNER_TYPE_ZIPARCHIVE = 12,
126 
127   /* native_handle_t */
128   ANDROID_FDSAN_OWNER_TYPE_NATIVE_HANDLE = 13,
129 
130   /* android::Parcel */
131   ANDROID_FDSAN_OWNER_TYPE_PARCEL = 14,
132 };
133 
134 /*
135  * Create an owner tag with the specified type and least significant 56 bits of tag.
136  */
137 uint64_t android_fdsan_create_owner_tag(enum android_fdsan_owner_type type, uint64_t tag) __INTRODUCED_IN(29) __attribute__((__weak__));
138 
139 /*
140  * Exchange a file descriptor's tag.
141  *
142  * Logs and aborts if the fd's tag does not match expected_tag.
143  */
144 void android_fdsan_exchange_owner_tag(int fd, uint64_t expected_tag, uint64_t new_tag) __INTRODUCED_IN(29) __attribute__((__weak__));
145 
146 /*
147  * Close a file descriptor with a tag, and resets the tag to 0.
148  *
149  * Logs and aborts if the tag is incorrect.
150  */
151 int android_fdsan_close_with_tag(int fd, uint64_t tag) __INTRODUCED_IN(29) __attribute__((__weak__));
152 
153 /*
154  * Get a file descriptor's current owner tag.
155  *
156  * Returns 0 for untagged and invalid file descriptors.
157  */
158 uint64_t android_fdsan_get_owner_tag(int fd) __INTRODUCED_IN(29);
159 
160 /*
161  * Get an owner tag's string representation.
162  *
163  * The return value points to memory with static lifetime, do not attempt to modify it.
164  */
165 const char* _Nonnull android_fdsan_get_tag_type(uint64_t tag) __INTRODUCED_IN(29);
166 
167 /*
168  * Get an owner tag's value, with the type masked off.
169  */
170 uint64_t android_fdsan_get_tag_value(uint64_t tag) __INTRODUCED_IN(29);
171 
172 enum android_fdsan_error_level {
173   // No errors.
174   ANDROID_FDSAN_ERROR_LEVEL_DISABLED,
175 
176   // Warn once(ish) on error, and then downgrade to ANDROID_FDSAN_ERROR_LEVEL_DISABLED.
177   ANDROID_FDSAN_ERROR_LEVEL_WARN_ONCE,
178 
179   // Warn always on error.
180   ANDROID_FDSAN_ERROR_LEVEL_WARN_ALWAYS,
181 
182   // Abort on error.
183   ANDROID_FDSAN_ERROR_LEVEL_FATAL,
184 };
185 
186 /*
187  * Get the error level.
188  */
189 enum android_fdsan_error_level android_fdsan_get_error_level() __INTRODUCED_IN(29) __attribute__((__weak__));
190 
191 /*
192  * Set the error level and return the previous state.
193  *
194  * Error checking is automatically disabled in the child of a fork, to maintain
195  * compatibility with code that forks, closes all file descriptors, and then
196  * execs.
197  *
198  * In cases such as the zygote, where the child has no intention of calling
199  * exec, call this function to reenable fdsan checks.
200  *
201  * This function is not thread-safe and does not synchronize with checks of the
202  * value, and so should probably only be called in single-threaded contexts
203  * (e.g. postfork).
204  */
205 enum android_fdsan_error_level android_fdsan_set_error_level(enum android_fdsan_error_level new_level) __INTRODUCED_IN(29) __attribute__((__weak__));
206 
207 /*
208  * Set the error level to the global setting if available, or a default value.
209  */
210 enum android_fdsan_error_level android_fdsan_set_error_level_from_property(enum android_fdsan_error_level default_level) __INTRODUCED_IN(30) __attribute__((__weak__));
211 __END_DECLS
212