From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on archive.lwn.net X-Spam-Level: X-Spam-Status: No, score=-6.1 required=5.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham autolearn_force=no version=3.4.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by archive.lwn.net (Postfix) with ESMTP id 7CFB37D082 for ; Wed, 17 Oct 2018 02:17:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727178AbeJQKKc (ORCPT ); Wed, 17 Oct 2018 06:10:32 -0400 Received: from mail-pl1-f195.google.com ([209.85.214.195]:42692 "EHLO mail-pl1-f195.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727053AbeJQKKc (ORCPT ); Wed, 17 Oct 2018 06:10:32 -0400 Received: by mail-pl1-f195.google.com with SMTP id c8-v6so11884162plo.9 for ; Tue, 16 Oct 2018 19:17:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=date:from:to:cc:subject:message-id:mime-version:content-disposition; bh=DCVmlSjP07MR/1l2OcfmI69av54uWU4+X7+FEqXRDu4=; b=DUHKFz759mSuPyWK2AWmYQatTLCnnFmVLYf1RFeXhfuXGEx3O4r791tzBYDsYeCb6E KmiNAoDorCdqoAI85NXZWttiYTYgIaYy8jcXdSYkyHY+GftlEufSnZR5bybIzfyL1Lmp epdl0TxNcuIDcydpRr5rygNAxrnducYFO9xpE= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition; bh=DCVmlSjP07MR/1l2OcfmI69av54uWU4+X7+FEqXRDu4=; b=to+9EaTiE5g9To10ioVugVX0CxWI+6OUSGA0PSVzukROFDwPTFAkNnX4K/Ga5Uqh7T l4PXYPfBqJzXYoNwODnClD7iZSIGGpy4Qi5BSm5Lk7SfwHRknEWl1FnJYiD4w7cPMX+H tGcZGynlXkLbkG8QTQcuLznkPFL0nSsxEPjZmS7rUHVaS8fYjz4Wt0Blks4zgw2e6I0p hfDFic1uRzcp2QSw1omAzXO4hxtNHHWfcAKNoQiTU7n1oMVVC0j9wYZJSbaDHwxk2a98 qsNFOLrlAeFHbIqX9YeklQrbA5q1AX5bTgXIGv9o1eTwKK2zVNBlPQsxpo5wrtbKpw/U PdqA== X-Gm-Message-State: ABuFfohiH5rjMY9b90ek7jeiWTjwWiocq0kKp1cmXX9YzsN9d6ZxpQRD IzjEeOu8L3R7ZPbmko5g7cxSKA== X-Google-Smtp-Source: ACcGV60uqpSy+TqB2iYqbcuXkUGuq1ue5MaGG8JDp11NKPCe62fvKQbvYY8umLod6GBMvgUwVI8aBw== X-Received: by 2002:a17:902:6546:: with SMTP id d6-v6mr23894309pln.139.1539742630866; Tue, 16 Oct 2018 19:17:10 -0700 (PDT) Received: from www.outflux.net (173-164-112-133-Oregon.hfc.comcastbusiness.net. [173.164.112.133]) by smtp.gmail.com with ESMTPSA id b14-v6sm19756230pgn.49.2018.10.16.19.17.09 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 16 Oct 2018 19:17:09 -0700 (PDT) Date: Tue, 16 Oct 2018 19:17:08 -0700 From: Kees Cook To: Jonathan Corbet Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Stephen Rothwell Subject: [PATCH] docs: Introduce deprecated APIs list Message-ID: <20181017021708.GA22211@beast> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org As discussed in the "API replacement/deprecation" thread[1], this makes an effort to document what things shouldn't get (re)added to the kernel, by introducing Documentation/process/deprecated.rst. It also adds the overflow kerndoc to ReST output, and tweaks the struct_size() documentation to parse correctly. [1] https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2018-September/005282.html Signed-off-by: Kees Cook --- Documentation/driver-api/basics.rst | 3 + Documentation/process/deprecated.rst | 99 ++++++++++++++++++++++++++++ Documentation/process/index.rst | 1 + include/linux/overflow.h | 2 +- 4 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 Documentation/process/deprecated.rst diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 826e85d50a16..e970fadf4d1a 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -121,6 +121,9 @@ Kernel utility functions .. kernel-doc:: kernel/rcu/update.c :export: +.. kernel-doc:: include/linux/overflow.h + :internal: + Device Resource Management -------------------------- diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst new file mode 100644 index 000000000000..95e261224a81 --- /dev/null +++ b/Documentation/process/deprecated.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================================================== +Deprecated Interfaces, Language Features, Attributes, and Conventions +===================================================================== + +In a perfect world, it would be possible to convert all instances of +some deprecated API into the new API and entirely remove the old API in +a single development cycle. However, due to the size of the kernel, the +maintainership hierarchy, and timing, it's not always feasible to do these +kinds of conversions at once. This means that new instances may sneak into +the kernel while old ones are being removed, only making the amount of +work to remove the API grow. In order to educate developers about what +has been deprecated and why, this list has been created as a place to +point when uses of deprecated things are proposed for inclusion in the +kernel. + +__deprecated +------------ +While this attribute does visually mark an interface as deprecated, +it `does not produce warnings during builds any more +`_ +because one of the standing goals of the kernel is to build without +warnings and no one was actually doing anything to remove these deprecated +interfaces. While using `__deprecated` is nice to note an old API in +a header file, it isn't the full solution. Such interfaces must either +be fully removed from the kernel, or added to this file to discourage +others from using them in the future. + +open-coded arithmetic in allocator arguments +-------------------------------------------- +Dynamic size calculations (especially multiplication) +should not be performed in memory allocator (or similar) +function arguments. + +For example, do not use ``rows * cols`` as an argument, as in: +``kmalloc(rows * cols, GFP_KERNEL)``. +Instead, the 2-factor form of the allocator should be used: +``kmalloc_array(rows, cols, GFP_KERNEL)``. +If no 2-factor form is available, the saturate-on-overflow helpers should +be used: +``vmalloc(array_size(rows, cols))``. + +See :c:func:`array_size`, :c:func:`array3_size`, and :c:func:`struct_size`, +for more details as well as the related :c:func:`check_add_overflow` and +:c:func:`check_mul_overflow` family of functions. + +simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() +---------------------------------------------------------------------- +The :c:func:`simple_strtol`, :c:func:`simple_strtoll`, +:c:func:`simple_strtoul`, and :c:func:`simple_strtoull` functions +explicitly ignore overflows, which may lead to unexpected results +in callers. The respective :c:func:`kstrtol`, :c:func:`kstrtoll`, +:c:func:`kstrtoul`, and :c:func:`kstrtoull` functions tend to be the +correct replacements, though note that those require the string to be +NUL or newline terminated. + +strcpy() +-------- +:c:func:`strcpy` performs no bounds checking on the destination +buffer. This could result in linear overflows beyond the +end of the buffer, leading to all kinds of misbehaviors. While +`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the +risk of using this function, there is no good reason to add new uses of +this function. The safe replacement is :c:func:`strscpy`. + +strncpy() on NUL-terminated strings +----------------------------------- +Use of :c:func:`strncpy` does not guarantee that the destination buffer +will be NUL terminated. This can lead to various linear read overflows +and other misbehavior due to the missing termination. It also NUL-pads the +destination buffer if the source contents are shorter than the destination +buffer size, which may be a needless performance penalty for callers using +only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. +(Users of :c:func:`strscpy` still needing NUL-padding will need an +explicit :c:func:`memset` added.) + +If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can +still be used, but destinations should be marked with the `__nonstring +`_ +attribute to avoid future compiler warnings. + +strlcpy() +--------- +:c:func:`strlcpy` reads the entire source buffer first, possibly exceeding +the given limit of bytes to copy. This is inefficient and can lead to +linear read overflows if a source string is not NUL-terminated. The +safe replacement is :c:func:`strscpy`. + +Variable Length Arrays (VLAs) +----------------------------- +Using stack VLAs produces much worse machine code than statically +sized stack arrays. While these non-trivial `performance issues +`_ are reason enough to +eliminate VLAs, they are also a security risk. Dynamic growth of a stack +array may exceed the remaining memory in the stack segment. This could +lead to a crash, possible overwriting sensitive contents at the end of the +stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting +memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 9ae3e317bddf..b4de2c682255 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -41,6 +41,7 @@ Other guides to the community that are of interest to most developers are: stable-kernel-rules submit-checklist kernel-docs + deprecated These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/include/linux/overflow.h b/include/linux/overflow.h index 40b48e2133cb..2f224f43dd06 100644 --- a/include/linux/overflow.h +++ b/include/linux/overflow.h @@ -291,7 +291,7 @@ static inline __must_check size_t __ab_c_size(size_t n, size_t size, size_t c) } /** - * struct_size() - Calculate size of structure with trailing array. + * function struct_size() - Calculate size of structure with trailing array. * @p: Pointer to the structure. * @member: Name of the array member. * @n: Number of elements in the array. -- 2.17.1 -- Kees Cook Pixel Security