184253c8bSKees Cook.. SPDX-License-Identifier: GPL-2.0 284253c8bSKees Cook 398348577SFederico Vaga.. _deprecated: 498348577SFederico Vaga 584253c8bSKees Cook===================================================================== 684253c8bSKees CookDeprecated Interfaces, Language Features, Attributes, and Conventions 784253c8bSKees Cook===================================================================== 884253c8bSKees Cook 984253c8bSKees CookIn a perfect world, it would be possible to convert all instances of 1084253c8bSKees Cooksome deprecated API into the new API and entirely remove the old API in 1184253c8bSKees Cooka single development cycle. However, due to the size of the kernel, the 1284253c8bSKees Cookmaintainership hierarchy, and timing, it's not always feasible to do these 1384253c8bSKees Cookkinds of conversions at once. This means that new instances may sneak into 1484253c8bSKees Cookthe kernel while old ones are being removed, only making the amount of 1584253c8bSKees Cookwork to remove the API grow. In order to educate developers about what 1684253c8bSKees Cookhas been deprecated and why, this list has been created as a place to 1784253c8bSKees Cookpoint when uses of deprecated things are proposed for inclusion in the 1884253c8bSKees Cookkernel. 1984253c8bSKees Cook 2084253c8bSKees Cook__deprecated 2184253c8bSKees Cook------------ 2284253c8bSKees CookWhile this attribute does visually mark an interface as deprecated, 2384253c8bSKees Cookit `does not produce warnings during builds any more 2484253c8bSKees Cook<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ 2584253c8bSKees Cookbecause one of the standing goals of the kernel is to build without 2684253c8bSKees Cookwarnings and no one was actually doing anything to remove these deprecated 2784253c8bSKees Cookinterfaces. While using `__deprecated` is nice to note an old API in 2884253c8bSKees Cooka header file, it isn't the full solution. Such interfaces must either 2984253c8bSKees Cookbe fully removed from the kernel, or added to this file to discourage 3084253c8bSKees Cookothers from using them in the future. 3184253c8bSKees Cook 3284253c8bSKees Cookopen-coded arithmetic in allocator arguments 3384253c8bSKees Cook-------------------------------------------- 3484253c8bSKees CookDynamic size calculations (especially multiplication) should not be 3584253c8bSKees Cookperformed in memory allocator (or similar) function arguments due to the 3684253c8bSKees Cookrisk of them overflowing. This could lead to values wrapping around and a 3784253c8bSKees Cooksmaller allocation being made than the caller was expecting. Using those 3884253c8bSKees Cookallocations could lead to linear overflows of heap memory and other 3984253c8bSKees Cookmisbehaviors. (One exception to this is literal values where the compiler 4084253c8bSKees Cookcan warn if they might overflow. Though using literals for arguments as 4184253c8bSKees Cooksuggested below is also harmless.) 4284253c8bSKees Cook 4384253c8bSKees CookFor example, do not use ``count * size`` as an argument, as in:: 4484253c8bSKees Cook 4584253c8bSKees Cook foo = kmalloc(count * size, GFP_KERNEL); 4684253c8bSKees Cook 4784253c8bSKees CookInstead, the 2-factor form of the allocator should be used:: 4884253c8bSKees Cook 4984253c8bSKees Cook foo = kmalloc_array(count, size, GFP_KERNEL); 5084253c8bSKees Cook 5184253c8bSKees CookIf no 2-factor form is available, the saturate-on-overflow helpers should 5284253c8bSKees Cookbe used:: 5384253c8bSKees Cook 5484253c8bSKees Cook bar = vmalloc(array_size(count, size)); 5584253c8bSKees Cook 5684253c8bSKees CookAnother common case to avoid is calculating the size of a structure with 5784253c8bSKees Cooka trailing array of others structures, as in:: 5884253c8bSKees Cook 5984253c8bSKees Cook header = kzalloc(sizeof(*header) + count * sizeof(*header->item), 6084253c8bSKees Cook GFP_KERNEL); 6184253c8bSKees Cook 6284253c8bSKees CookInstead, use the helper:: 6384253c8bSKees Cook 6484253c8bSKees Cook header = kzalloc(struct_size(header, item, count), GFP_KERNEL); 6584253c8bSKees Cook 6684253c8bSKees CookSee :c:func:`array_size`, :c:func:`array3_size`, and :c:func:`struct_size`, 6784253c8bSKees Cookfor more details as well as the related :c:func:`check_add_overflow` and 6884253c8bSKees Cook:c:func:`check_mul_overflow` family of functions. 6984253c8bSKees Cook 7084253c8bSKees Cooksimple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() 7184253c8bSKees Cook---------------------------------------------------------------------- 7284253c8bSKees CookThe :c:func:`simple_strtol`, :c:func:`simple_strtoll`, 7384253c8bSKees Cook:c:func:`simple_strtoul`, and :c:func:`simple_strtoull` functions 7484253c8bSKees Cookexplicitly ignore overflows, which may lead to unexpected results 7584253c8bSKees Cookin callers. The respective :c:func:`kstrtol`, :c:func:`kstrtoll`, 7684253c8bSKees Cook:c:func:`kstrtoul`, and :c:func:`kstrtoull` functions tend to be the 7784253c8bSKees Cookcorrect replacements, though note that those require the string to be 7884253c8bSKees CookNUL or newline terminated. 7984253c8bSKees Cook 8084253c8bSKees Cookstrcpy() 8184253c8bSKees Cook-------- 8284253c8bSKees Cook:c:func:`strcpy` performs no bounds checking on the destination 8384253c8bSKees Cookbuffer. This could result in linear overflows beyond the 8484253c8bSKees Cookend of the buffer, leading to all kinds of misbehaviors. While 8584253c8bSKees Cook`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the 8684253c8bSKees Cookrisk of using this function, there is no good reason to add new uses of 8784253c8bSKees Cookthis function. The safe replacement is :c:func:`strscpy`. 8884253c8bSKees Cook 8984253c8bSKees Cookstrncpy() on NUL-terminated strings 9084253c8bSKees Cook----------------------------------- 9184253c8bSKees CookUse of :c:func:`strncpy` does not guarantee that the destination buffer 9284253c8bSKees Cookwill be NUL terminated. This can lead to various linear read overflows 9384253c8bSKees Cookand other misbehavior due to the missing termination. It also NUL-pads the 9484253c8bSKees Cookdestination buffer if the source contents are shorter than the destination 9584253c8bSKees Cookbuffer size, which may be a needless performance penalty for callers using 9684253c8bSKees Cookonly NUL-terminated strings. The safe replacement is :c:func:`strscpy`. 9784253c8bSKees Cook(Users of :c:func:`strscpy` still needing NUL-padding will need an 9884253c8bSKees Cookexplicit :c:func:`memset` added.) 9984253c8bSKees Cook 10084253c8bSKees CookIf a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can 10184253c8bSKees Cookstill be used, but destinations should be marked with the `__nonstring 10284253c8bSKees Cook<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ 10384253c8bSKees Cookattribute to avoid future compiler warnings. 10484253c8bSKees Cook 10584253c8bSKees Cookstrlcpy() 10684253c8bSKees Cook--------- 10784253c8bSKees Cook:c:func:`strlcpy` reads the entire source buffer first, possibly exceeding 10884253c8bSKees Cookthe given limit of bytes to copy. This is inefficient and can lead to 10984253c8bSKees Cooklinear read overflows if a source string is not NUL-terminated. The 11084253c8bSKees Cooksafe replacement is :c:func:`strscpy`. 11184253c8bSKees Cook 11284253c8bSKees CookVariable Length Arrays (VLAs) 11384253c8bSKees Cook----------------------------- 11484253c8bSKees CookUsing stack VLAs produces much worse machine code than statically 11584253c8bSKees Cooksized stack arrays. While these non-trivial `performance issues 11684253c8bSKees Cook<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to 11784253c8bSKees Cookeliminate VLAs, they are also a security risk. Dynamic growth of a stack 11884253c8bSKees Cookarray may exceed the remaining memory in the stack segment. This could 11984253c8bSKees Cooklead to a crash, possible overwriting sensitive contents at the end of the 12084253c8bSKees Cookstack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting 12184253c8bSKees Cookmemory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) 122