]>
Commit | Line | Data |
---|---|---|
84253c8b KC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
98348577 FV |
3 | .. _deprecated: |
4 | ||
84253c8b KC |
5 | ===================================================================== |
6 | Deprecated Interfaces, Language Features, Attributes, and Conventions | |
7 | ===================================================================== | |
8 | ||
9 | In a perfect world, it would be possible to convert all instances of | |
10 | some deprecated API into the new API and entirely remove the old API in | |
11 | a single development cycle. However, due to the size of the kernel, the | |
12 | maintainership hierarchy, and timing, it's not always feasible to do these | |
13 | kinds of conversions at once. This means that new instances may sneak into | |
14 | the kernel while old ones are being removed, only making the amount of | |
15 | work to remove the API grow. In order to educate developers about what | |
16 | has been deprecated and why, this list has been created as a place to | |
17 | point when uses of deprecated things are proposed for inclusion in the | |
18 | kernel. | |
19 | ||
20 | __deprecated | |
21 | ------------ | |
22 | While this attribute does visually mark an interface as deprecated, | |
23 | it `does not produce warnings during builds any more | |
24 | <https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ | |
25 | because one of the standing goals of the kernel is to build without | |
26 | warnings and no one was actually doing anything to remove these deprecated | |
27 | interfaces. While using `__deprecated` is nice to note an old API in | |
28 | a header file, it isn't the full solution. Such interfaces must either | |
29 | be fully removed from the kernel, or added to this file to discourage | |
30 | others from using them in the future. | |
31 | ||
32 | open-coded arithmetic in allocator arguments | |
33 | -------------------------------------------- | |
34 | Dynamic size calculations (especially multiplication) should not be | |
35 | performed in memory allocator (or similar) function arguments due to the | |
36 | risk of them overflowing. This could lead to values wrapping around and a | |
37 | smaller allocation being made than the caller was expecting. Using those | |
38 | allocations could lead to linear overflows of heap memory and other | |
39 | misbehaviors. (One exception to this is literal values where the compiler | |
40 | can warn if they might overflow. Though using literals for arguments as | |
41 | suggested below is also harmless.) | |
42 | ||
43 | For example, do not use ``count * size`` as an argument, as in:: | |
44 | ||
45 | foo = kmalloc(count * size, GFP_KERNEL); | |
46 | ||
47 | Instead, the 2-factor form of the allocator should be used:: | |
48 | ||
49 | foo = kmalloc_array(count, size, GFP_KERNEL); | |
50 | ||
51 | If no 2-factor form is available, the saturate-on-overflow helpers should | |
52 | be used:: | |
53 | ||
54 | bar = vmalloc(array_size(count, size)); | |
55 | ||
56 | Another common case to avoid is calculating the size of a structure with | |
57 | a trailing array of others structures, as in:: | |
58 | ||
59 | header = kzalloc(sizeof(*header) + count * sizeof(*header->item), | |
60 | GFP_KERNEL); | |
61 | ||
62 | Instead, use the helper:: | |
63 | ||
64 | header = kzalloc(struct_size(header, item, count), GFP_KERNEL); | |
65 | ||
66 | See :c:func:`array_size`, :c:func:`array3_size`, and :c:func:`struct_size`, | |
67 | for more details as well as the related :c:func:`check_add_overflow` and | |
68 | :c:func:`check_mul_overflow` family of functions. | |
69 | ||
70 | simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() | |
71 | ---------------------------------------------------------------------- | |
72 | The :c:func:`simple_strtol`, :c:func:`simple_strtoll`, | |
73 | :c:func:`simple_strtoul`, and :c:func:`simple_strtoull` functions | |
74 | explicitly ignore overflows, which may lead to unexpected results | |
75 | in callers. The respective :c:func:`kstrtol`, :c:func:`kstrtoll`, | |
76 | :c:func:`kstrtoul`, and :c:func:`kstrtoull` functions tend to be the | |
77 | correct replacements, though note that those require the string to be | |
78 | NUL or newline terminated. | |
79 | ||
80 | strcpy() | |
81 | -------- | |
82 | :c:func:`strcpy` performs no bounds checking on the destination | |
83 | buffer. This could result in linear overflows beyond the | |
84 | end of the buffer, leading to all kinds of misbehaviors. While | |
85 | `CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the | |
86 | risk of using this function, there is no good reason to add new uses of | |
87 | this function. The safe replacement is :c:func:`strscpy`. | |
88 | ||
89 | strncpy() on NUL-terminated strings | |
90 | ----------------------------------- | |
91 | Use of :c:func:`strncpy` does not guarantee that the destination buffer | |
92 | will be NUL terminated. This can lead to various linear read overflows | |
93 | and other misbehavior due to the missing termination. It also NUL-pads the | |
94 | destination buffer if the source contents are shorter than the destination | |
95 | buffer size, which may be a needless performance penalty for callers using | |
96 | only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. | |
97 | (Users of :c:func:`strscpy` still needing NUL-padding will need an | |
98 | explicit :c:func:`memset` added.) | |
99 | ||
100 | If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can | |
101 | still be used, but destinations should be marked with the `__nonstring | |
102 | <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ | |
103 | attribute to avoid future compiler warnings. | |
104 | ||
105 | strlcpy() | |
106 | --------- | |
107 | :c:func:`strlcpy` reads the entire source buffer first, possibly exceeding | |
108 | the given limit of bytes to copy. This is inefficient and can lead to | |
109 | linear read overflows if a source string is not NUL-terminated. The | |
110 | safe replacement is :c:func:`strscpy`. | |
111 | ||
d8401f50 KC |
112 | %p format specifier |
113 | ------------------- | |
114 | Traditionally, using "%p" in format strings would lead to regular address | |
115 | exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to | |
116 | be exploitable, all "%p" uses in the kernel are being printed as a hashed | |
117 | value, rendering them unusable for addressing. New uses of "%p" should not | |
118 | be added to the kernel. For text addresses, using "%pS" is likely better, | |
119 | as it produces the more useful symbol name instead. For nearly everything | |
120 | else, just do not add "%p" at all. | |
121 | ||
122 | Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_: | |
123 | ||
124 | - If the hashed "%p" value is pointless, ask yourself whether the pointer | |
125 | itself is important. Maybe it should be removed entirely? | |
126 | - If you really think the true pointer value is important, why is some | |
127 | system state or user privilege level considered "special"? If you think | |
128 | you can justify it (in comments and commit log) well enough to stand | |
129 | up to Linus's scrutiny, maybe you can use "%px", along with making sure | |
130 | you have sensible permissions. | |
131 | ||
132 | And finally, know that a toggle for "%p" hashing will `not be accepted <https://lore.kernel.org/lkml/CA+55aFwieC1-nAs+NFq9RTwaR8ef9hWa4MjNBWL41F-8wM49eA@mail.gmail.com/>`_. | |
133 | ||
84253c8b KC |
134 | Variable Length Arrays (VLAs) |
135 | ----------------------------- | |
136 | Using stack VLAs produces much worse machine code than statically | |
137 | sized stack arrays. While these non-trivial `performance issues | |
138 | <https://git.kernel.org/linus/02361bc77888>`_ are reason enough to | |
139 | eliminate VLAs, they are also a security risk. Dynamic growth of a stack | |
140 | array may exceed the remaining memory in the stack segment. This could | |
141 | lead to a crash, possible overwriting sensitive contents at the end of the | |
142 | stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting | |
143 | memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) | |
a035d552 GS |
144 | |
145 | Implicit switch case fall-through | |
146 | --------------------------------- | |
b9918bdc JP |
147 | The C language allows switch cases to "fall-through" when a "break" statement |
148 | is missing at the end of a case. This, however, introduces ambiguity in the | |
149 | code, as it's not always clear if the missing break is intentional or a bug. | |
150 | ||
151 | As there have been a long list of flaws `due to missing "break" statements | |
a035d552 | 152 | <https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow |
b9918bdc JP |
153 | "implicit fall-through". |
154 | ||
155 | In order to identify intentional fall-through cases, we have adopted a | |
156 | pseudo-keyword macro 'fallthrough' which expands to gcc's extension | |
157 | __attribute__((__fallthrough__)). `Statement Attributes | |
158 | <https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_ | |
159 | ||
160 | When the C17/C18 [[fallthrough]] syntax is more commonly supported by | |
161 | C compilers, static analyzers, and IDEs, we can switch to using that syntax | |
162 | for the macro pseudo-keyword. | |
163 | ||
164 | All switch/case blocks must end in one of: | |
165 | ||
166 | break; | |
167 | fallthrough; | |
168 | continue; | |
169 | goto <label>; | |
170 | return [expression]; |