aurorafw.android.platform.fdsan source code

1 /*
2                                     __
3                                    / _|
4   __ _ _   _ _ __ ___  _ __ __ _  | |_ ___  ___ ___
5  / _` | | | | '__/ _ \| '__/ _` | |  _/ _ \/ __/ __|
6 | (_| | |_| | | | (_) | | | (_| | | || (_) \__ \__ \
7  \__,_|\__,_|_|  \___/|_|  \__,_| |_| \___/|___/___/
8 
9 Copyright (C) 2018 The Android Open Source Project.
10 Copyright (C) 2018-2019 Aurora Free Open Source Software.
11 
12 This file is part of the Aurora Free Open Source Software. This
13 organization promote free and open source software that you can
14 redistribute and/or modify under the terms of the GNU Lesser General
15 Public License Version 3 as published by the Free Software Foundation or
16 (at your option) any later version approved by the Aurora Free Open Source
17 Software Organization. The license is available in the package root path
18 as 'LICENSE' file. Please review the following information to ensure the
19 GNU Lesser General Public License version 3 requirements will be met:
20 https://www.gnu.org/licenses/lgpl.html .
21 
22 Alternatively, this file may be used under the terms of the GNU General
23 Public License version 3 or later as published by the Free Software
24 Foundation. Please review the following information to ensure the GNU
25 General Public License requirements will be met:
26 https://www.gnu.org/licenses/gpl-3.0.html.
27 
28 NOTE: All products, services or anything associated to trademarks and
29 service marks used or referenced on this file are the property of their
30 respective companies/owners or its subsidiaries. Other names and brands
31 may be claimed as the property of others.
32 
33 For more info about intellectual property visit: aurorafoss.org or
34 directly send an email to: contact (at) aurorafoss.org .
35 
36 This file has bindings for an existing code, part of The Android Open Source
37 Project implementation. Check it out at android.googlesource.com .
38 */
39 
40 module aurorafw.android.platform.fdsan;
41 
42 version (Android):
43 extern (C):
44 @system:
45 nothrow:
46 @nogc:
47 
48 /*
49  * Error checking for close(2).
50  *
51  * Mishandling of file descriptor ownership is a common source of errors that
52  * can be extremely difficult to diagnose. Mistakes like the following can
53  * result in seemingly 'impossible' failures showing up on other threads that
54  * happened to try to open a file descriptor between the buggy code's close and
55  * fclose:
56  *
57  *     int print(int fd) {
58  *         int rc;
59  *         char buf[128];
60  *         while ((rc = read(fd, buf, sizeof(buf))) > 0) {
61  *             printf("%.*s", rc);
62  *         }
63  *         close(fd);
64  *     }
65  *
66  *     int bug() {
67  *         FILE* f = fopen("foo", "r");
68  *         print(fileno(f));
69  *         fclose(f);
70  *     }
71  *
72  * To make it easier to find this class of bugs, bionic provides a method to
73  * require that file descriptors are closed by their owners. File descriptors
74  * can be associated with tags with which they must be closed. This allows
75  * objects that conceptually own an fd (FILE*, unique_fd, etc.) to use their
76  * own address at the tag, to enforce that closure of the fd must come as a
77  * result of their own destruction (fclose, ~unique_fd, etc.)
78  *
79  * By default, a file descriptor's tag is 0, and close(fd) is equivalent to
80  * closing fd with the tag 0.
81  */
82 
83 /*
84  * For improved diagnostics, the type of a file descriptors owner can be
85  * encoded in the most significant byte of the owner tag. Values of 0 and 0xff
86  * are ignored, which allows for raw pointers to be used as owner tags without
87  * modification.
88  */
89 enum android_fdsan_owner_type
90 {
91     /*
92      * Generic Java or native owners.
93      *
94      * Generic Java objects always use 255 as their type, using identityHashCode
95      * as the value of the tag, leaving bits 33-56 unset. Native pointers are sign
96      * extended from 48-bits of virtual address space, and so can have the MSB
97      * set to 255 as well. Use the value of bits 49-56 to distinguish between
98      * these cases.
99      */
100     ANDROID_FDSAN_OWNER_TYPE_GENERIC_00 = 0,
101     ANDROID_FDSAN_OWNER_TYPE_GENERIC_FF = 255,
102 
103     /* FILE* */
104     ANDROID_FDSAN_OWNER_TYPE_FILE = 1,
105 
106     /* DIR* */
107     ANDROID_FDSAN_OWNER_TYPE_DIR = 2,
108 
109     /* android::base::unique_fd */
110     ANDROID_FDSAN_OWNER_TYPE_UNIQUE_FD = 3,
111 
112     /* java.io.FileInputStream */
113     ANDROID_FDSAN_OWNER_TYPE_FILEINPUTSTREAM = 251,
114 
115     /* java.io.FileOutputStream */
116     ANDROID_FDSAN_OWNER_TYPE_FILEOUTPUTSTREAM = 252,
117 
118     /* java.io.RandomAccessFile */
119     ANDROID_FDSAN_OWNER_TYPE_RANDOMACCESSFILE = 253,
120 
121     /* android.os.ParcelFileDescriptor */
122     ANDROID_FDSAN_OWNER_TYPE_PARCELFILEDESCRIPTOR = 254
123 }
124 
125 /*
126  * Create an owner tag with the specified type and least significant 56 bits of tag.
127  */
128 
129 ulong android_fdsan_create_owner_tag (android_fdsan_owner_type type, ulong tag);
130 
131 /*
132  * Exchange a file descriptor's tag.
133  *
134  * Logs and aborts if the fd's tag does not match expected_tag.
135  */
136 void android_fdsan_exchange_owner_tag (int fd, ulong expected_tag, ulong new_tag);
137 
138 /*
139  * Close a file descriptor with a tag, and resets the tag to 0.
140  *
141  * Logs and aborts if the tag is incorrect.
142  */
143 int android_fdsan_close_with_tag (int fd, ulong tag);
144 /* __ANDROID_API__ >= __ANDROID_API_FUTURE__ */
145 
146 enum android_fdsan_error_level
147 {
148     // No errors.
149     ANDROID_FDSAN_ERROR_LEVEL_DISABLED = 0,
150 
151     // Warn once(ish) on error, and then downgrade to ANDROID_FDSAN_ERROR_LEVEL_DISABLED.
152     ANDROID_FDSAN_ERROR_LEVEL_WARN_ONCE = 1,
153 
154     // Warn always on error.
155     ANDROID_FDSAN_ERROR_LEVEL_WARN_ALWAYS = 2,
156 
157     // Abort on error.
158     ANDROID_FDSAN_ERROR_LEVEL_FATAL = 3
159 }
160 
161 /*
162  * Get the error level.
163  */
164 
165 android_fdsan_error_level android_fdsan_get_error_level ();
166 
167 /*
168  * Set the error level and return the previous state.
169  *
170  * Error checking is automatically disabled in the child of a fork, to maintain
171  * compatibility with code that forks, blindly closes FDs, and then execs.
172  *
173  * In cases such as the zygote, where the child has no intention of calling
174  * exec, call this function to reenable fdsan checks.
175  *
176  * This function is not thread-safe and does not synchronize with checks of the
177  * value, and so should probably only be called in single-threaded contexts
178  * (e.g. postfork).
179  */
180 android_fdsan_error_level android_fdsan_set_error_level (android_fdsan_error_level new_level);
181 /* __ANDROID_API__ >= __ANDROID_API_FUTURE__ */
182