diff options
Diffstat (limited to 'Documentation/process')
| -rw-r--r-- | Documentation/process/4.Coding.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/changes.rst | 22 | ||||
| -rw-r--r-- | Documentation/process/coding-style.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/conf.py | 10 | ||||
| -rw-r--r-- | Documentation/process/deprecated.rst | 14 | ||||
| -rw-r--r-- | Documentation/process/email-clients.rst | 20 | ||||
| -rw-r--r-- | Documentation/process/embargoed-hardware-issues.rst | 279 | ||||
| -rw-r--r-- | Documentation/process/howto.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/process/maintainer-pgp-guide.rst | 31 | ||||
| -rw-r--r-- | Documentation/process/submit-checklist.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/submitting-drivers.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/submitting-patches.rst | 2 |
13 files changed, 331 insertions, 60 deletions
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 4b7a5ab3cec1..13dd893c9f88 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -298,7 +298,7 @@ enabled, a configurable percentage of memory allocations will be made to fail; these failures can be restricted to a specific range of code. Running with fault injection enabled allows the programmer to see how the code responds when things go badly. See -Documentation/fault-injection/fault-injection.txt for more information on +Documentation/fault-injection/fault-injection.rst for more information on how to use this facility. Other kinds of errors can be found with the "sparse" static analysis tool. diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 18735dc460a0..2284f2221f02 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -23,15 +23,15 @@ running, the suggested command should tell you. Again, keep in mind that this list assumes you are already functionally running a Linux kernel. Also, not all tools are necessary on all -systems; obviously, if you don't have any ISDN hardware, for example, -you probably needn't concern yourself with isdn4k-utils. +systems; obviously, if you don't have any PC Card hardware, for example, +you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== Program Minimal version Command to check the version ====================== =============== ======================================== GNU C 4.6 gcc --version GNU make 3.81 make --version -binutils 2.20 ld -v +binutils 2.21 ld -v flex 2.5.35 flex --version bison 2.0 bison --version util-linux 2.10o fdformat --version @@ -45,7 +45,6 @@ btrfs-progs 0.18 btrfsck pcmciautils 004 pccardctl -V quota-tools 3.09 quota -V PPP 2.4.0 pppd --version -isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version oprofile 0.9 oprofiled --version @@ -77,9 +76,7 @@ You will need GNU make 3.81 or later to build the kernel. Binutils -------- -The build system has, as of 4.13, switched to using thin archives (`ar T`) -rather than incremental linking (`ld -r`) for built-in.a intermediate steps. -This requires binutils 2.20 or newer. +Binutils 2.21 or newer is needed to build the kernel. pkg-config ---------- @@ -279,12 +276,6 @@ which can be made by:: as root. -Isdn4k-utils ------------- - -Due to changes in the length of the phone number field, isdn4k-utils -needs to be recompiled or (preferably) upgraded. - NFS-utils --------- @@ -448,11 +439,6 @@ PPP - <ftp://ftp.samba.org/pub/ppp/> -Isdn4k-utils ------------- - -- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> - NFS-utils --------- diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index fa864a51e6ea..f4a2198187f9 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -686,7 +686,7 @@ filesystems) should advertise this prominently in their prompt string:: ... For full documentation on the configuration files, see the file -Documentation/kbuild/kconfig-language.txt. +Documentation/kbuild/kconfig-language.rst. 11) Data structures diff --git a/Documentation/process/conf.py b/Documentation/process/conf.py deleted file mode 100644 index 1b01a80ad9ce..000000000000 --- a/Documentation/process/conf.py +++ /dev/null @@ -1,10 +0,0 @@ -# -*- coding: utf-8; mode: python -*- - -project = 'Linux Kernel Development Documentation' - -tags.add("subproject") - -latex_documents = [ - ('index', 'process.tex', 'Linux Kernel Development Documentation', - 'The kernel development community', 'manual'), -] diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 49e0f64a3427..053b24a6dd38 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -119,3 +119,17 @@ 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`) + +Implicit switch case fall-through +--------------------------------- +The C language allows switch cases to "fall through" when +a "break" statement is missing at the end of a case. This, +however, introduces ambiguity in the code, as it's not always +clear if the missing break is intentional or a bug. As there +have been a long list of flaws `due to missing "break" statements +<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow +"implicit fall-through". In order to identify an intentional fall-through +case, we have adopted the marking used by static analyzers: a comment +saying `/* Fall through */`. Once the C++17 `__attribute__((fallthrough))` +is more widely handled by C compilers, static analyzers, and IDEs, we can +switch to using that instead. diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 07faa5457bcb..5273d06c8ff6 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -40,7 +40,7 @@ Emailed patches should be in ASCII or UTF-8 encoding only. If you configure your email client to send emails with UTF-8 encoding, you avoid some possible charset problems. -Email clients should generate and maintain References: or In-Reply-To: +Email clients should generate and maintain "References:" or "In-Reply-To:" headers so that mail threading is not broken. Copy-and-paste (or cut-and-paste) usually does not work for patches @@ -89,7 +89,7 @@ Claws Mail (GUI) Works. Some people use this successfully for patches. -To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +To insert a patch use :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) or an external editor. If the inserted patch has to be edited in the Claws composition window @@ -132,8 +132,8 @@ wrapping. At the bottom of your email, put the commonly-used patch delimiter before inserting your patch: three hyphens (``---``). -Then from the :menuselection:`Message` menu item, select insert file and -choose your patch. +Then from the :menuselection:`Message` menu item, select +:menuselection:`insert file` and choose your patch. As an added bonus you can customise the message creation toolbar menu and put the :menuselection:`insert file` icon there. @@ -149,18 +149,16 @@ patches so do not GPG sign them. Signing patches that have been inserted as inlined text will make them tricky to extract from their 7-bit encoding. If you absolutely must send patches as attachments instead of inlining -them as text, right click on the attachment and select properties, and -highlight :menuselection:`Suggest automatic display` to make the attachment +them as text, right click on the attachment and select :menuselection:`properties`, +and highlight :menuselection:`Suggest automatic display` to make the attachment inlined to make it more viewable. When saving patches that are sent as inlined text, select the email that contains the patch from the message list pane, right click and select :menuselection:`save as`. You can use the whole email unmodified as a patch -if it was properly composed. There is no option currently to save the email -when you are actually viewing it in its own window -- there has been a request -filed at kmail's bugzilla and hopefully this will be addressed. Emails are -saved as read-write for user only so you will have to chmod them to make them -group and world readable if you copy them elsewhere. +if it was properly composed. Emails are saved as read-write for user only so +you will have to chmod them to make them group and world readable if you copy +them elsewhere. Lotus Notes (GUI) ***************** diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..402636356fbe --- /dev/null +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -0,0 +1,279 @@ +Embargoed hardware issues +========================= + +Scope +----- + +Hardware issues which result in security problems are a different category +of security bugs than pure software bugs which only affect the Linux +kernel. + +Hardware issues like Meltdown, Spectre, L1TF etc. must be treated +differently because they usually affect all Operating Systems ("OS") and +therefore need coordination across different OS vendors, distributions, +hardware vendors and other parties. For some of the issues, software +mitigations can depend on microcode or firmware updates, which need further +coordination. + +.. _Contact: + +Contact +------- + +The Linux kernel hardware security team is separate from the regular Linux +kernel security team. + +The team only handles the coordination of embargoed hardware security +issues. Reports of pure software security bugs in the Linux kernel are not +handled by this team and the reporter will be guided to contact the regular +Linux kernel security team (:ref:`Documentation/admin-guide/ +<securitybugs>`) instead. + +The team can be contacted by email at <hardware-security@kernel.org>. This +is a private list of security officers who will help you to coordinate an +issue according to our documented process. + +The list is encrypted and email to the list can be sent by either PGP or +S/MIME encrypted and must be signed with the reporter's PGP key or S/MIME +certificate. The list's PGP key and S/MIME certificate are available from +https://www.kernel.org/.... + +While hardware security issues are often handled by the affected hardware +vendor, we welcome contact from researchers or individuals who have +identified a potential hardware flaw. + +Hardware security officers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The current team of hardware security officers: + + - Linus Torvalds (Linux Foundation Fellow) + - Greg Kroah-Hartman (Linux Foundation Fellow) + - Thomas Gleixner (Linux Foundation Fellow) + +Operation of mailing-lists +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The encrypted mailing-lists which are used in our process are hosted on +Linux Foundation's IT infrastructure. By providing this service Linux +Foundation's director of IT Infrastructure security technically has the +ability to access the embargoed information, but is obliged to +confidentiality by his employment contract. Linux Foundation's director of +IT Infrastructure security is also responsible for the kernel.org +infrastructure. + +The Linux Foundation's current director of IT Infrastructure security is +Konstantin Ryabitsev. + + +Non-disclosure agreements +------------------------- + +The Linux kernel hardware security team is not a formal body and therefore +unable to enter into any non-disclosure agreements. The kernel community +is aware of the sensitive nature of such issues and offers a Memorandum of +Understanding instead. + + +Memorandum of Understanding +--------------------------- + +The Linux kernel community has a deep understanding of the requirement to +keep hardware security issues under embargo for coordination between +different OS vendors, distributors, hardware vendors and other parties. + +The Linux kernel community has successfully handled hardware security +issues in the past and has the necessary mechanisms in place to allow +community compliant development under embargo restrictions. + +The Linux kernel community has a dedicated hardware security team for +initial contact, which oversees the process of handling such issues under +embargo rules. + +The hardware security team identifies the developers (domain experts) who +will form the initial response team for a particular issue. The initial +response team can bring in further developers (domain experts) to address +the issue in the best technical way. + +All involved developers pledge to adhere to the embargo rules and to keep +the received information confidential. Violation of the pledge will lead to +immediate exclusion from the current issue and removal from all related +mailing-lists. In addition, the hardware security team will also exclude +the offender from future issues. The impact of this consequence is a highly +effective deterrent in our community. In case a violation happens the +hardware security team will inform the involved parties immediately. If you +or anyone becomes aware of a potential violation, please report it +immediately to the Hardware security officers. + + +Process +^^^^^^^ + +Due to the globally distributed nature of Linux kernel development, +face-to-face meetings are almost impossible to address hardware security +issues. Phone conferences are hard to coordinate due to time zones and +other factors and should be only used when absolutely necessary. Encrypted +email has been proven to be the most effective and secure communication +method for these types of issues. + +Start of Disclosure +""""""""""""""""""" + +Disclosure starts by contacting the Linux kernel hardware security team by +email. This initial contact should contain a description of the problem and +a list of any known affected hardware. If your organization builds or +distributes the affected hardware, we encourage you to also consider what +other hardware could be affected. + +The hardware security team will provide an incident-specific encrypted +mailing-list which will be used for initial discussion with the reporter, +further disclosure and coordination. + +The hardware security team will provide the disclosing party a list of +developers (domain experts) who should be informed initially about the +issue after confirming with the developers that they will adhere to this +Memorandum of Understanding and the documented process. These developers +form the initial response team and will be responsible for handling the +issue after initial contact. The hardware security team is supporting the +response team, but is not necessarily involved in the mitigation +development process. + +While individual developers might be covered by a non-disclosure agreement +via their employer, they cannot enter individual non-disclosure agreements +in their role as Linux kernel developers. They will, however, agree to +adhere to this documented process and the Memorandum of Understanding. + + +Disclosure +"""""""""" + +The disclosing party provides detailed information to the initial response +team via the specific encrypted mailing-list. + +From our experience the technical documentation of these issues is usually +a sufficient starting point and further technical clarification is best +done via email. + +Mitigation development +"""""""""""""""""""""" + +The initial response team sets up an encrypted mailing-list or repurposes +an existing one if appropriate. The disclosing party should provide a list +of contacts for all other parties who have already been, or should be, +informed about the issue. The response team contacts these parties so they +can name experts who should be subscribed to the mailing-list. + +Using a mailing-list is close to the normal Linux development process and +has been successfully used in developing mitigations for various hardware +security issues in the past. + +The mailing-list operates in the same way as normal Linux development. +Patches are posted, discussed and reviewed and if agreed on applied to a +non-public git repository which is only accessible to the participating +developers via a secure connection. The repository contains the main +development branch against the mainline kernel and backport branches for +stable kernel versions as necessary. + +The initial response team will identify further experts from the Linux +kernel developer community as needed and inform the disclosing party about +their participation. Bringing in experts can happen at any time of the +development process and often needs to be handled in a timely manner. + +Coordinated release +""""""""""""""""""" + +The involved parties will negotiate the date and time where the embargo +ends. At that point the prepared mitigations are integrated into the +relevant kernel trees and published. + +While we understand that hardware security issues need coordinated embargo +time, the embargo time should be constrained to the minimum time which is +required for all involved parties to develop, test and prepare the +mitigations. Extending embargo time artificially to meet conference talk +dates or other non-technical reasons is creating more work and burden for +the involved developers and response teams as the patches need to be kept +up to date in order to follow the ongoing upstream kernel development, +which might create conflicting changes. + +CVE assignment +"""""""""""""" + +Neither the hardware security team nor the initial response team assign +CVEs, nor are CVEs required for the development process. If CVEs are +provided by the disclosing party they can be used for documentation +purposes. + +Process ambassadors +------------------- + +For assistance with this process we have established ambassadors in various +organizations, who can answer questions about or provide guidance on the +reporting process and further handling. Ambassadors are not involved in the +disclosure of a particular issue, unless requested by a response team or by +an involved disclosed party. The current ambassadors list: + + ============= ======================================================== + ARM + AMD + IBM + Intel + Qualcomm Trilok Soni <tsoni@codeaurora.org> + + Microsoft Sasha Levin <sashal@kernel.org> + VMware + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical Tyler Hicks <tyhicks@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Amazon + Google Kees Cook <keescook@chromium.org> + ============= ======================================================== + +If you want your organization to be added to the ambassadors list, please +contact the hardware security team. The nominated ambassador has to +understand and support our process fully and is ideally well connected in +the Linux kernel community. + +Encrypted mailing-lists +----------------------- + +We use encrypted mailing-lists for communication. The operating principle +of these lists is that email sent to the list is encrypted either with the +list's PGP key or with the list's S/MIME certificate. The mailing-list +software decrypts the email and re-encrypts it individually for each +subscriber with the subscriber's PGP key or S/MIME certificate. Details +about the mailing-list software and the setup which is used to ensure the +security of the lists and protection of the data can be found here: +https://www.kernel.org/.... + +List keys +^^^^^^^^^ + +For initial contact see :ref:`Contact`. For incident specific mailing-lists +the key and S/MIME certificate are conveyed to the subscribers by email +sent from the specific list. + +Subscription to incident specific lists +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Subscription is handled by the response teams. Disclosed parties who want +to participate in the communication send a list of potential subscribers to +the response team so the response team can validate subscription requests. + +Each subscriber needs to send a subscription request to the response team +by email. The email must be signed with the subscriber's PGP key or S/MIME +certificate. If a PGP key is used, it must be available from a public key +server and is ideally connected to the Linux kernel's PGP web of trust. See +also: https://www.kernel.org/signature.html. + +The response team verifies that the subscriber request is valid and adds +the subscriber to the list. After subscription the subscriber will receive +email from the mailing-list which is signed either with the list's PGP key +or the list's S/MIME certificate. The subscriber's email client can extract +the PGP key or the S/MIME certificate from the signature so the subscriber +can send encrypted email to the list. + diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 6ab75c11d2c3..b6f5a379ad6c 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -123,7 +123,7 @@ required reading: https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` This file describes the rationale behind the conscious decision to diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 878ebfda7eef..e2c9ffc682c5 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -45,6 +45,7 @@ Other guides to the community that are of interest to most developers are: submit-checklist kernel-docs deprecated + embargoed-hardware-issues These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 4bab7464ff8c..17db11b7ed48 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -238,7 +238,10 @@ your new subkey:: work. If for some reason you prefer to stay with RSA subkeys, just replace - "ed25519" with "rsa2048" in the above command. + "ed25519" with "rsa2048" in the above command. Additionally, if you + plan to use a hardware device that does not support ED25519 ECC + keys, like Nitrokey Pro or a Yubikey, then you should use + "nistp256" instead or "ed25519." Back up your master key for disaster recovery @@ -432,23 +435,23 @@ Available smartcard devices Unless all your laptops and workstations have smartcard readers, the easiest is to get a specialized USB device that implements smartcard -functionality. There are several options available: +functionality. There are several options available: - `Nitrokey Start`_: Open hardware and Free Software, based on FSI - Japan's `Gnuk`_. Offers support for ECC keys, but fewest security - features (such as resistance to tampering or some side-channel - attacks). -- `Nitrokey Pro`_: Similar to the Nitrokey Start, but more - tamper-resistant and offers more security features, but no ECC - support. -- `Yubikey 4`_: proprietary hardware and software, but cheaper than + Japan's `Gnuk`_. One of the few available commercial devices that + support ED25519 ECC keys, but offer fewest security features (such as + resistance to tampering or some side-channel attacks). +- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features. Pro 2 supports ECC + cryptography (NISTP). +- `Yubikey 5`_: proprietary hardware and software, but cheaper than Nitrokey Pro and comes available in the USB-C form that is more useful with newer laptops. Offers additional security features such as FIDO - U2F, but no ECC. + U2F, among others, and now finally supports ECC keys (NISTP). `LWN has a good review`_ of some of the above models, as well as several -others. If you want to use ECC keys, your best bet among commercially -available devices is the Nitrokey Start. +others. Your choice will depend on cost, shipping availability in your +geographical region, and open/proprietary hardware considerations. .. note:: @@ -457,8 +460,8 @@ available devices is the Nitrokey Start. Foundation. .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 -.. _`Nitrokey Pro`: https://shop.nitrokey.com/shop/product/nitrokey-pro-3 -.. _`Yubikey 4`: https://www.yubico.com/product/yubikey-4-series/ +.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3 +.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: http://www.fsij.org/doc-gnuk/ .. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index c88867b173d9..8e56337d422d 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -39,7 +39,7 @@ and elsewhere regarding submitting Linux kernel patches. 6) Any new or modified ``CONFIG`` options do not muck up the config menu and default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. + ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. 7) All new ``Kconfig`` options have help text. @@ -107,7 +107,7 @@ and elsewhere regarding submitting Linux kernel patches. and why. 26) If any ioctl's are added by the patch, then also update - ``Documentation/ioctl/ioctl-number.txt``. + ``Documentation/ioctl/ioctl-number.rst``. 27) If your modified source code depends on or uses any of the kernel APIs or features that are related to the following ``Kconfig`` symbols, diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 58bc047e7b95..1acaa14903d6 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -117,7 +117,7 @@ PM support: implemented") error. You should also try to make sure that your driver uses as little power as possible when it's not doing anything. For the driver testing instructions see - Documentation/power/drivers-testing.txt and for a relatively + Documentation/power/drivers-testing.rst and for a relatively complete overview of the power management issues related to drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 9c4299293c72..fb56297f70dc 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -844,7 +844,7 @@ Andrew Morton, "The perfect patch" (tpp). <http://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". - <http://linux.yyz.us/patch-format.html> + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer.html> |