diff options
25 files changed, 712 insertions, 51 deletions
diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index f2bebff6a733..eb9452668909 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -356,5 +356,5 @@ instructions at 'Documentation/admin-guide/reporting-issues.rst'. Hints on understanding kernel bug reports are in 'Documentation/admin-guide/bug-hunting.rst'. More on debugging the kernel -with gdb is in 'Documentation/dev-tools/gdb-kernel-debugging.rst' and -'Documentation/dev-tools/kgdb.rst'. +with gdb is in 'Documentation/process/debugging/gdb-kernel-debugging.rst' and +'Documentation/process/debugging/kgdb.rst'. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index dc663c0ca670..5d0092c335b7 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -7469,7 +7469,7 @@ vt.cur_default= [VT] Default cursor shape. Format: 0xCCBBAA, where AA, BB, and CC are the same as the parameters of the <Esc>[?A;B;Cc escape sequence; - see VGA-softcursor.txt. Default: 2 = underline. + see vga-softcursor.rst. Default: 2 = underline. vt.default_blu= [VT] Format: <blue0>,<blue1>,<blue2>,...,<blue15> diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst index f08149bc53f8..07cfd8863b46 100644 --- a/Documentation/admin-guide/quickly-build-trimmed-linux.rst +++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst @@ -733,7 +733,7 @@ can easily happen that your self-built kernel will lack modules for tasks you did not perform before utilizing this make target. That's because those tasks require kernel modules that are normally autoloaded when you perform that task for the first time; if you didn't perform that task at least once before using -localmodonfig, the latter will thus assume these modules are superfluous and +localmodconfig, the latter will thus assume these modules are superfluous and disable them. You can try to avoid this by performing typical tasks that often will autoload diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index 6281eae9e6bc..03c55151346c 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -1431,7 +1431,7 @@ can easily happen that your self-built kernels will lack modules for tasks you did not perform at least once before utilizing this make target. That happens when a task requires kernel modules which are only autoloaded when you execute it for the first time. So when you never performed that task since starting your -kernel the modules will not have been loaded -- and from localmodonfig's point +kernel the modules will not have been loaded -- and from localmodconfig's point of view look superfluous, which thus disables them to reduce the amount of code to be compiled. diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst index 27a9cccc792c..06f766a6aab2 100644 --- a/Documentation/core-api/symbol-namespaces.rst +++ b/Documentation/core-api/symbol-namespaces.rst @@ -41,9 +41,9 @@ entries. In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and -EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace. -Please note that due to macro expansion that argument needs to be a -preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the +EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a +string constant. Note that this string must not contain whitespaces. +E.g. to export the symbol ``usb_stor_suspend`` into the namespace ``USB_STORAGE``, use:: EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE"); @@ -78,11 +78,10 @@ as this argument has preference over a default symbol namespace. A second option to define the default namespace is directly in the compilation unit as preprocessor statement. The above example would then read:: - #undef DEFAULT_SYMBOL_NAMESPACE #define DEFAULT_SYMBOL_NAMESPACE "USB_COMMON" -within the corresponding compilation unit before any EXPORT_SYMBOL macro is -used. +within the corresponding compilation unit before the #include for +<linux/export.h>. Typically it's placed before the first #include statement. 3. How to use Symbols exported in Namespaces ============================================ diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 3c0ac08b2709..65c54b27a60b 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -10,6 +10,9 @@ whole; patches welcome! A brief overview of testing-specific tools can be found in Documentation/dev-tools/testing-overview.rst +Tools that are specific to debugging can be found in +Documentation/process/debugging/index.rst + .. toctree:: :caption: Table of contents :maxdepth: 2 @@ -27,8 +30,6 @@ Documentation/dev-tools/testing-overview.rst kmemleak kcsan kfence - gdb-kernel-debugging - kgdb kselftest kunit/index ktap diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index d2a277e3976e..6245b67ae9e0 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -266,7 +266,7 @@ Non-directories Objects that are not directories (files, symlinks, device-special files etc.) are presented either from the upper or lower filesystem as appropriate. When a file in the lower filesystem is accessed in a way -the requires write-access, such as opening for write access, changing +that requires write-access, such as opening for write access, changing some metadata etc., the file is first copied from the lower filesystem to the upper filesystem (copy_up). Note that creating a hard-link also requires copy_up, though of course creation of a symlink does @@ -549,8 +549,8 @@ Nesting overlayfs mounts It is possible to use a lower directory that is stored on an overlayfs mount. For regular files this does not need any special care. However, files -that have overlayfs attributes, such as whiteouts or "overlay.*" xattrs will be -interpreted by the underlying overlayfs mount and stripped out. In order to +that have overlayfs attributes, such as whiteouts or "overlay.*" xattrs, will +be interpreted by the underlying overlayfs mount and stripped out. In order to allow the second overlayfs mount to see the attributes they must be escaped. Overlayfs specific xattrs are escaped by using a special prefix of diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst index 895285c037c7..895285c037c7 100644 --- a/Documentation/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/process/debugging/gdb-kernel-debugging.rst diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst index f6e4a00dfee3..387d33d16f5e 100644 --- a/Documentation/process/debugging/index.rst +++ b/Documentation/process/debugging/index.rst @@ -11,6 +11,8 @@ general guides :maxdepth: 1 driver_development_debugging_guide + gdb-kernel-debugging + kgdb userspace_debugging_guide .. only:: subproject and html diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/process/debugging/kgdb.rst index b29b0aac2717..b29b0aac2717 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/process/debugging/kgdb.rst diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index e374b67b3277..41d5855700cd 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -270,7 +270,7 @@ Ordering of commit tags To have a uniform view of the commit tags, the tip maintainers use the following tag ordering scheme: - - Fixes: 12char-SHA1 ("sub/sys: Original subject line") + - Fixes: 12+char-SHA1 ("sub/sys: Original subject line") A Fixes tag should be added even for changes which do not need to be backported to stable kernels, i.e. when addressing a recently introduced diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 1518bd57adab..816bdb037e02 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -143,10 +143,10 @@ also track such tags and take certain actions. Private bug trackers and invalid URLs are forbidden. If your patch fixes a bug in a specific commit, e.g. you found an issue using -``git bisect``, please use the 'Fixes:' tag with the first 12 characters of -the SHA-1 ID, and the one line summary. Do not split the tag across multiple -lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify -parsing scripts. For example:: +``git bisect``, please use the 'Fixes:' tag with at least the first 12 +characters of the SHA-1 ID, and the one line summary. Do not split the tag +across multiple lines, tags are exempt from the "wrap at 75 columns" rule in +order to simplify parsing scripts. For example:: Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") @@ -610,6 +610,9 @@ that, if you have your patches stored in a ``git`` repository, proper patch formatting can be had with ``git format-patch``. The tools cannot create the necessary text, though, so read the instructions below anyway. +Subject Line +^^^^^^^^^^^^ + The canonical patch subject line is:: Subject: [PATCH 001/123] subsystem: summary phrase @@ -683,6 +686,9 @@ Here are some good example Subjects:: Subject: [PATCH v2] sub/sys: Condensed patch summary Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary +From Line +^^^^^^^^^ + The ``from`` line must be the very first line in the message body, and has the form: @@ -693,6 +699,9 @@ patch in the permanent changelog. If the ``from`` line is missing, then the ``From:`` line from the email header will be used to determine the patch author in the changelog. +Explanation Body +^^^^^^^^^^^^^^^^ + The explanation body will be committed to the permanent source changelog, so should make sense to a competent reader who has long since forgotten the immediate details of the discussion that might have led to @@ -708,6 +717,31 @@ _all_ of the compile failures; just enough that it is likely that someone searching for the patch can find it. As in the ``summary phrase``, it is important to be both succinct as well as descriptive. +.. _backtraces: + +Backtraces in commit messages +""""""""""""""""""""""""""""" + +Backtraces help document the call chain leading to a problem. However, +not all backtraces are helpful. For example, early boot call chains are +unique and obvious. Copying the full dmesg output verbatim, however, +adds distracting information like timestamps, module lists, register and +stack dumps. + +Therefore, the most useful backtraces should distill the relevant +information from the dump, which makes it easier to focus on the real +issue. Here is an example of a well-trimmed backtrace:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +Commentary +^^^^^^^^^^ + The ``---`` marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. @@ -746,28 +780,6 @@ patch:: See more details on the proper patch format in the following references. -.. _backtraces: - -Backtraces in commit messages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Backtraces help document the call chain leading to a problem. However, -not all backtraces are helpful. For example, early boot call chains are -unique and obvious. Copying the full dmesg output verbatim, however, -adds distracting information like timestamps, module lists, register and -stack dumps. - -Therefore, the most useful backtraces should distill the relevant -information from the dump, which makes it easier to focus on the real -issue. Here is an example of a well-trimmed backtrace:: - - unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) - at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) - Call Trace: - mba_wrmsr - update_domains - rdtgroup_mkdir - .. _explicit_in_reply_to: Explicit In-Reply-To headers diff --git a/Documentation/translations/zh_CN/security/IMA-templates.rst b/Documentation/translations/zh_CN/security/IMA-templates.rst new file mode 100644 index 000000000000..b391c9d03882 --- /dev/null +++ b/Documentation/translations/zh_CN/security/IMA-templates.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/IMA-templates.rst + +:翻译: + 赵硕 Shuo Zhao <zhaoshuo@cqsoftware.com.cn> + +=============== +IMA模板管理机制 +=============== + + +介绍 +==== + +原始的 ``ima`` 模板是固定长度的，包含文件数据的哈希值和路径名。文件数据 +哈希值限制为20字节(md5/sha1)。路径名是一个以空字符终止的字符串，长度限 +制为255个字符内。 +为了克服这些限制并添加额外的文件元数据，通过定义额外的模板来扩展当前版本 +的IMA这是有必要的。例如，可能报告的信息包括索引节点的 UID/GID或索引节点 +及访问它进程的LSM标签。 + +然而，引入这个功能的主要问题是，每次定义一个新模板时，生成和显示度量列表 +的函数都需要包含处理新格式的代码，因此，这些函数的规模随着时间的推移会 +显著增长。 + +提出的解决方案通过将模板管理与其余IMA代码分离来解决这个问题。该解决方案 +的核心是定义两个新的数据结构：一个是模板描述符，用于确定度量列表中应包含 +哪些信息；另一个是模板字段，用于生成和显示给定类型的数据。 + +使用这些结构管理模板非常简单。为了支持一种新的数据类型，开发人员定义字段 +标识符，并实现两个函数，分别为init()和show()，用于生成和显示度量条目。 +定义一个新的模板描述符需要通过 ``ima_template_fmt`` 内核命令行参数指定 +模板格式(一个由 ``|`` 字符分隔的字段标识符字符串)。在启动时，IMA通过将格 +式转换从支持的模板字段集合中选取模板字段数组，来初始化所选的模板描述符。 + +在初始化步骤之后，IMA将调用 ``ima_alloc_init_template()`` (这是为新模板 +管理机制所打补丁中定义的新函数)，通过使用在内核配置选择的模板描述符或者新引 +入的 ``ima_template`` 和 ``ima_template_fmt`` 内核命令行参数，生成一个新 +的度量条目。在这一阶段，新架构的优势得以清晰展示：后一个函数将不会包含处理给 +定模板的特定代码，而是简单地调用与所选模板描述符关联的模板字段的 ``init()`` +方法，并将结果(指向已分配数据的指针和数据长度)存储在度量条目结构中。 + +相同的机制也用于显示度量条目。函数 ``ima[_ascii]_measurements_show()`` 会为 +每个条目检索用于生成该条目的模板描述符，并为模板字段结构数组中的每一项调用show() +方法。 + + + +支持的模板字段和描述符 +====================== + +下面是支持的模板字段列表 ``('<identifier>': description)`` ，可以通过将其标识符 +添加到格式字符串中用于定义新的模板描述符(后续将添加对更多数据类型的支持): + + - 'd'：事件的摘要(即测量文件的摘要)，通过SHA1或MD5哈希算法计算； + - 'n'：事件的名称(即文件名)，大小至多255字节； + - 'd-ng'：事件的摘要，通过任意哈希算法计算(字段格式：<hash algo>:digest)； + - 'd-ngv2'：与d-ng相同，但以"ima"或"verity"摘要类型为前缀 + (字段格式：<digest type>:<hash algo>:digest)； + - 'd-modsig'：不含附加modsig的事件摘要； + - 'n-ng'：事件的名称，没有大小限制； + - 'sig'：文件签名，基于文件的/文件系统验证的摘要[1]，或EVM便携式签名， + 如果'security.ima'包含文件哈希； + - 'modsig'：附加的文件签名； + - 'buf'：用于生成哈希的缓冲区数据，没有大小限制； + - 'evmsig'：EVM便携式签名； + - 'iuid'：索引节点的UID； + - 'igid'：索引节点的GID； + - 'imode'：索引节点的模式； + - 'xattrnames'：xattr名称的列表(由``|``分隔)，仅当xattr存在时； + - 'xattrlengths'：xattr长度的列表(u32)，仅当xattr存在时； + - 'xattrvalues'：xattr值的列表； + + +下面是已定义的模板描述符列表： + + - "ima"：其格式是 ``d|n`` ； + - "ima-ng"(默认)：其格式是 ``d-ng|n-ng`` ； + - "ima-ngv2"：其格式是 ``d-ngv2|n-ng`` ； + - "ima-sig"：其格式是 ``d-ng|n-ng|sig`` ； + - "ima-sigv2"：其格式是 ``d-ngv2|n-ng|sig`` ； + - "ima-buf"：其格式是 ``d-ng|n-ng|buf`` ； + - "ima-modsig"：其格式是 ``d-ng|n-ng|sig|d-modsig|modsig`` ； + - "evm-sig"：其格式是 ``d-ng|n-ng|evmsig|xattrnames|xattrlengths|xattrvalues|iuid|igid|imode`` ； + + + +使用 +==== + +要指定用于生成度量条目的模板描述符，目前支持以下方法: + + - 从内核配置所支持模板描述符中选择一个模板描述符( ``ima-ng`` 是默认选择)； + - 通过 ``ima_template=`` 参数从内核命令行指定模板描述符名称； + - 通过内核命令行参数 ``ima_template_fmt=`` 注册一个具有自定义格式的新模板描述符。 diff --git a/Documentation/translations/zh_CN/security/digsig.rst b/Documentation/translations/zh_CN/security/digsig.rst new file mode 100644 index 000000000000..3e690b504ec5 --- /dev/null +++ b/Documentation/translations/zh_CN/security/digsig.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/digsig.rst + +:翻译: + 赵硕 Shuo Zhao <zhaoshuo@cqsoftware.com.cn> + +=============== +数字签名验证API +=============== + +:作者: Dmitry Kasatkin +:日期: 2011.06.10 + + +.. 内容 + + 1.介绍 + 2.API + 3.用户空间工具 + + +介绍 +==== + +数字签名验证API提供了一种验证数字签名的方法。 +目前，数字签名被IMA/EVM完整性保护子系统使用。 + +数字签名验证是通过精简的GnuPG多精度整数(MPI)库的内核移植来实现的。 +该内核版本提供了内存分配错误处理，已根据内核编码风格进行重构，并修复 +了checkpatch.pl报告的错误和警告。 + +公钥和签名由头部和MPIs组成:: + + struct pubkey_hdr { + uint8_t version; /* 密钥格式版本 */ + time_t timestamp; /* 密钥时间戳，目前为0 */ + uint8_t algo; + uint8_t nmpi; + char mpi[0]; + } __packed; + + struct signature_hdr { + uint8_t version; /* 签名格式版本 */ + time_t timestamp; /* 签名时间戳 */ + uint8_t algo; + uint8_t hash; + uint8_t keyid[8]; + uint8_t nmpi; + char mpi[0]; + } __packed; + +keyid等同对整个密钥的内容进行SHA1哈希运算后的第12到19字节。 +签名头部用于生成签名的输入。这种方法确保了密钥或签名头部无法更改。 +它保护时间戳不被更改，并可以用于回滚保护。 + +API +=== + +目前API仅包含一个函数:: + + digsig_verify() - 使用公钥进行数字签名验证 + + /** + * digsig_verify() - 使用公钥进行数字签名验证 + * @keyring: 查找密钥的密钥环 + * @sig: 数字签名 + * @sigen: 签名的长度 + * @data: 数据 + * @datalen: 数据的长度 + * @return: 成功时返回0，失败时返回 -EINVAL + * + * 验证数据相对于数字签名的完整性。 + * 目前仅支持RSA算法。 + * 通常将内容的哈希值作为此函数的数据。 + * + */ + int digsig_verify(struct key *keyring, const char *sig, int siglen, + const char *data, int datalen); + +用户空间工具 +============ + +签名和密钥管理实用工具evm-utils提供了生成签名、加载密钥到内核密钥环中的功能。 +密钥可以是PEM格式，或转换为内核格式。 +当把密钥添加到内核密钥环时，keyid定义该密钥的名称：下面的示例中为5D2B05FC633EE3E8。 + +以下是keyctl实用工具的示例输出:: + + $ keyctl show + Session Keyring + -3 --alswrv 0 0 keyring: _ses + 603976250 --alswrv 0 -1 \_ keyring: _uid.0 + 817777377 --alswrv 0 0 \_ user: kmk + 891974900 --alswrv 0 0 \_ encrypted: evm-key + 170323636 --alswrv 0 0 \_ keyring: _module + 548221616 --alswrv 0 0 \_ keyring: _ima + 128198054 --alswrv 0 0 \_ keyring: _evm + + $ keyctl list 128198054 + 1 key in keyring: + 620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8 diff --git a/Documentation/translations/zh_CN/security/index.rst b/Documentation/translations/zh_CN/security/index.rst new file mode 100644 index 000000000000..3f68e3145322 --- /dev/null +++ b/Documentation/translations/zh_CN/security/index.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/index.rst + +:翻译: + + 赵岳辉 Yuehui Zhao <zhaoyuehui@cqsoftware.com.cn> + +======== +安全文档 +======== + +.. toctree:: + :maxdepth: 1 + + lsm + siphash + digsig + landlock + +TODOLIST: +* credentials +* snp-tdx-threat-model +* IMA-templates +* keys/index +* lsm-development +* sak +* SCTP +* self-protection +* tpm/index +* secrets/index +* ipe diff --git a/Documentation/translations/zh_CN/security/landlock.rst b/Documentation/translations/zh_CN/security/landlock.rst new file mode 100644 index 000000000000..53b449b637b2 --- /dev/null +++ b/Documentation/translations/zh_CN/security/landlock.rst @@ -0,0 +1,123 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright ? 2017-2020 Micka?l Salaün <mic@digikod.net> +.. Copyright ? 2019-2020 ANSSI +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/landlock.rst + +:翻译: + + 毛玉贤 Yuxian Mao <maoyuxian@cqsoftware.com.cn> + +====================== +Landlock LSM: 内核文档 +====================== + +:作者: Mickaël Salaün +:日期: 2022年12月 + +Landlock的目标是创建有范围的访问控制（即沙箱机制）。为了增强整个 +系统的安全性，此功能应适用于任何进程，包括非特权进程。因为这些进 +程可能被攻击或植入后门（即不可信任的），所以从内核和其他进程的角 +度来看，Landlock的功能必须安全可用。因此，Landlock 的接口设计应当 +尽量减少可能的攻击点。 + +Landlock 旨在为非特权进程使用，同时遵循由其他访问控制机制（例如 DAC、LSM） +强制执行的系统安全策略。Landlock 规则不应与系统上强制执行的其他访问 +控制相冲突，而只能添加额外的限制。 + +任何用户都可以在其进程上强制执行Landlock规则集。这些规则集会以一种 +确保只能添加更多约束的方式与继承的规则集合并和评估。 + + +用户空间文档如下： +Documentation/userspace-api/landlock.rst. + +安全访问控制机制指导原则 +======================== + +* Landlock规则应侧重于对内核对象的访问控制，而非系统调用过滤（即 + 系统调用参数），后者是seccomp-bpf要侧重的。 +* 为了避免多种侧信道攻击（例如安全策略泄露、基于CPU的攻击），Landlock + 规则不应与用户空间进行程序化通信。 +* 内核访问检查不应降低未沙盒化进程的访问请求速度。 +* 与 Landlock 操作相关的计算（例如强制执行规则集）应仅影响请求这些 + 操作的进程。 +* 由沙盒化进程直接从内核中获得的资源（例如文件描述符）在被任何进程 + 使用时，都应保留其获取时的作用域访问权限。 + Cf. `文件描述符访问权限`_. + +设计选择 +======== + +inode访问权限 +------------- + +所有访问权限都与inode以及通过inode所访问到的内容相关。读取目录的 +内容并不意味着有权读取该目录中列出的 inode 所对应文件的内容。实际 +上，文件名是相对于其父目录而言的 ，一个 inode 可以通过多个文件名 +（通过硬链接）来引用。删除文件链接这一操作仅直接影响对应目录，而 +对被移除链接的inode并无影响。这就是“LANDLOCK_ACCESS_FS_REMOVE_FILE” +（文件系统移除文件访问权限）或“LANDLOCK_ACCESS_FS_REFER” （文件系 +统引用访问权限）不能与文件绑定，而只能与目录绑定的原因。 + +文件描述符访问权限 +------------------ + +在打开文件时，会检查访问权限并将其与文件描述符绑定。其基本原则是， +当在相同的 Landlock 域下执行时，等效的操作序列会产生相同的结果。 +以LANDLOCK_ACCESS_FS_TRUNCATE权限为例，如果相关的文件层次结构没有 +授予该访问权限，那么可能允许打开一个文件进行写操作，但不允许使用 +ftruncate调用截断由此产生的文件描述符。 +以下操作序列具有相同的语义，因此会产生相同的结果： + +* ``truncate(path);`` +* ``int fd = open(path, O_WRONLY); ftruncate(fd); close(fd);`` + +与文件访问模式类似（例如O_RDWR），即使文件描述符在进程之间传递 +（例如通过Unix域套接字），文件描述符中的Landlock访问权限也会被保留。 +这些访问权限即使在接收进程未被 Landlock 沙盒化的情况下也会被强制执行。 +事实上，这是为了保持整个系统访问控制的一致性，避免通过文件描述符传递 +而无意中绕过安全限制（即“混淆代理攻击”）。 + +测试 +==== + +用户空间的向后兼容性测试、ptrace 限制测试和文件系统支持测试可以在这里 +找到：tools/testing/selftests/landlock/ + +内核结构 +======== + +对象 +---- + +该API在以下内核代码中： + +security/landlock/object.h + +文件系统 +-------- + +该API在以下内核代码中： + +security/landlock/fs.h + +规则集和域 +---------- + +域是与一组主体（即任务凭证）关联的只读规则集。每次在任务上执行规则集时， +都会复制当前域，并在新域中导入规则集作为新的规则层。 事实上，一旦进入 +一个域，每条规则都与一个层级绑定。要授予对对象的访问权限，每一层中至少 +有一条规则必须允许对该对象执行请求操作。然后，任务只能过渡到一个新的域， +该新域是当前域的约束和任务提供的规则集的约束的交集。任务自行沙盒化时， +主体的定义是隐式的，这使得推理变得更加简单，并有助于避免陷阱。 + +该API在以下内核代码中： + +security/landlock/ruleset.h + +.. Links +.. _tools/testing/selftests/landlock/: + +https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/ diff --git a/Documentation/translations/zh_CN/security/lsm.rst b/Documentation/translations/zh_CN/security/lsm.rst new file mode 100644 index 000000000000..e0ec4c7831da --- /dev/null +++ b/Documentation/translations/zh_CN/security/lsm.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/lsm.rst + +:翻译: + + 赵岳辉 Yuehui Zhao <zhaoyuehui@cqsoftware.com.cn> + +================================ +Linux安全模块：Linux通用安全钩子 +================================ + +:作者: Stephen Smalley +:作者: Timothy Fraser +:作者: Chris Vance + +.. note:: + + 本文中描述的api已经过时了。 + +介绍 +==== + +在2001年3月，美国国家安全局（NSA）在2.5 Linux内核峰会上做了一个关于安全 +增强Linux（SELinux）的报告。SELinux是Linux内核中一种实现灵活且细粒度的非 +自主访问控制，最初作为自己特定的内核补丁实现。其他一些安全项目（例如RSBAC、 +Medusa）也为Linux内核开发了灵活的访问控制架构，并且多个项目为Linux开发了 +特定的访问控制模型（例如LIDS、DTE、SubDomain）。每个项目都开发并维护了自 +己的内核补丁，以支持其安全需求。 + +针对美国国家安全局的报告，Linus Torvalds发表了一系列言论，描述了一个他愿 +意考虑纳入主流Linux内核的安全框架。他描述了一个通用的框架，该框架将提供 +一组安全钩子来控制对内核对象的操作，同时在内核数据结构中提供一组不透明的 +安全域来维护安全属性。这个框架可以被可加载的内核模块用来实现任何所需的安 +全模型。Linus还提出了将Linux权能代码迁移到这样一个模块中的可能性。 + +Linux安全模块（LSM）项目是由WireX发起开发的这样一个框架。LSM是几个安全 +项目共同开发的成果，包括immununix、SELinux、SGI和Janus，以及包括 +Greg Kroah-Hartman和James Morris在内的几个人，来开发一个实现这一框架的 +Linux内核补丁。这项工作在2003年12月被纳入主流内核。此技术报告概述了该框 +架和权能安全模块的内容。 + +LSM框架 +======= + +LSM框架提供了一个通用的内核框架来支持安全模块。特别地，LSM框架主要关注 +支持访问控制模块，尽管未来的开发可能会解决其他安全需求，比如沙箱。就其 +本身而言，框架不提供任何额外的安全；它仅提供了支持安全模块的基础架构。 +LSM框架是可选的，要求开启 `CONFIG_SECURITY` 配置。权能逻辑作为一个安全 +模块被实现。该权能模块将在 `LSM权能模块`_ 一节中进一步讨论。 + +LSM框架在内核数据结构中包含安全域，并在内核代码的关键点调用钩子函数来 +管理这些安全域并执行访问控制。它还增加了注册安全模块的函数。接口 +/sys/kernel/security/lsm记录了一个以逗号分隔的安全模块列表，这些模块在 +系统中是激活的。 + +LSM安全域只是 ``void*`` 指针。数据被称为blob，这些数据可以由框架或使用 +它的各个安全模块进行管理。多个安全模块共同使用的安全blob通常由框架管理。 +对于进程和程序执行的安全信息，安全域包含在 :c:type: +`struct task_struct <task_struct>` 和 :c:type: `struct cred <cred>` 中。 +对于文件系统的安全信息，安全域包含在 :c:type: +`struct super_block <super_block>` 中。对于管道、文件和套接字的安全信息， +安全域包含在 :c:type: `struct inode <inode>` 和 :c:type: `struct file <file>` +中。对于System V IPC的安全信息，安全域被添加到 :c:type: +`struct kern_ipc_perm <kern_ipc_perm>` 和 :c:type: `struct msg_msg <msg_msg>` +中；另外，:c:type: `struct msg_msg <msg_msg>` 、struct msg_queue和 +struct shmid_kernel的定义被移动到头文件中（ ``include/linux/msg.h`` 和 +``include/linux/shm.h`` 视情况而定），以允许安全模块使用这些定义。 + +对于数据包和网络设备的安全信息，安全域被添加到 :c:type: +`struct sk_buff <sk_buff>` 和 :c:type: `struct scm_cookie <scm_cookie>` 中。 +与其他安全模块数据不同，这里使用的数据是一个32位整数。安全模块需要将这些值 +进行映射或关联到真正的安全属性。 + +LSM钩子被维护在链表中。每个钩子函数都维护一个链表，这些钩子按照CONFIG_LSM中 +指定的顺序被调用。每个钩子的详细文档都包含在 `security/security.c` 源文件中。 + +LSM框架提供了一种近似通用的安全模块堆栈。它定义了security_add_hooks()，每个安 +全模块向它传递一个 :c:type: `struct security_hooks_list <security_hooks_list>` +，该结构会被添加到链表中。LSM框架没有提供移除已注册钩子的机制。SELinux安全 +模块已经实现了一种移除自身的方法，然而该特性已被弃用。 + +这些钩子可以分为两大类：用于管理安全域的钩子和用于执行访问控制的钩子。 +第一类钩子的示例包括security_inode_alloc()和security_inode_free()，这些 +钩子用于为inode对象分配和释放安全结构。第二类钩子的示例是 +security_inode_permission()钩子，该钩子在访问inode时检查权限。 + +LSM权能模块 +=========== + +POSIX.1e 权能逻辑作为一个安全模块维护，存储在文件 ``security/commoncap.c`` +中。权能模块使用 :c:type: `lsm_info` 描述中的order域来标识它为第一个注册 +的安全模块。与其他模块不同，权能安全模块不使用通用的安全blob。其原因是历史 +性的，主要基于开销、复杂性和性能的考虑。 diff --git a/Documentation/translations/zh_CN/security/siphash.rst b/Documentation/translations/zh_CN/security/siphash.rst new file mode 100644 index 000000000000..26dd8be699b3 --- /dev/null +++ b/Documentation/translations/zh_CN/security/siphash.rst @@ -0,0 +1,195 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst +:Original: Documentation/security/siphash.rst + +:翻译: + + 张巍 zhangwei <zhangwei@cqsoftware.com.cn> + +===================================== +SipHash - 一种短输入伪随机函数（PRF） +===================================== + +：作者: Jason A.Donenfeld <jason@zx2c4.com> + +SipHash是一种加密安全的伪随机函数，即一种用于生成伪随机密钥的哈 +希函数，因为其在处理短输入时表现出色，因此得名。其由密码学家 +Daniel J. Bernstein和Jean-Philippe Aumasson设计。目的主要是替 +代其他哈希函数，例如：jhash，md5_transform，sha1_transform等。 + +SipHash采用一个完全由随机数生成的密钥，以及一个输入缓冲区或者 +多个输入整数，它输出一个与随机数难以区分的整数，你可以将它作 +为安全序列、安全cookies的一部分，或者对其进行掩码处理，以便在 +哈希表中使用。 + +生成密钥 +======== + +密钥应来源于加密安全的随机数生成，要么使用get random bytes +要么使用get random once:: + + siphash_key_t key; + get_random_bytes(&key, sizeof(key)); + +如果你的密钥来源不是这两个，那么你的做法是错的。 + +使用函数 +======== + +这个函数有两个变种，一种是接受整数列表，另一种是接受缓冲区:: + + u64 siphash(const void *data, size_t len, const siphash_key_t *key); + +和:: + + u64 siphash_1u64(u64, const siphash_key_t *key); + u64 siphash_2u64(u64, u64, const siphash_key_t *key); + u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key); + u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key); + u64 siphash_1u32(u32, const siphash_key_t *key); + u64 siphash_2u32(u32, u32, const siphash_key_t *key); + u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key); + u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key); + +如果向一个通用的hsiphash函数传递一个恒定长度的常量，他将 +在编译的时候将常量折叠，并自动选择一个优化后的函数。 + +哈希表键函数的用法:: + + struct some_hashtable { + DECLARE_HASHTABLE(hashtable, 8); + siphash_key_t key; + }; + + void init_hashtable(struct some_hashtable *table) + { + get_random_bytes(&table->key, sizeof(table->key)); + } + + static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input) + { + return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)]; + } + +然后，你可以像往常一样对返回的哈希存储桶进行迭代。 + +安全性 +====== + +SipHash有着非常高的安全性,因为其有128位的密钥。只要密钥是保密的， +即使攻击者看到多个输出，也无法猜测出函数的正确输出，因为2^128次 +方个输出是非常庞大的。 + +Linux实现了SipHash的“2-4”变体 + +Struct-passing陷阱 +================== + +通常情况下，XuY函数的输出长度不够大，因此你可能需要传递一个预填充 +的结构体给SipHash，在这样做时，务必确保结构体没有填充空隙，最简单 +的方法就是将结构体的成员按照大小降序的方式排序，并且使用offsetofend() +函数代替sizeof()来获取结构体大小，出于性能的考虑，如果可以的话，最 +好将结构体按右边界对齐，示例如下:: + + const struct { + struct in6_addr saddr; + u32 counter; + u16 dport; + } __aligned(SIPHASH_ALIGNMENT) combined = { + .saddr = *(struct in6_addr *)saddr, + .counter = counter, + .dport = dport + }; + u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret); + +资源 +==== + +如果你有兴趣了解更多信息，请阅读SipHash论文: +https://131002.net/siphash/siphash.pdf + +------------------------------------------------------------------------------- + +=========================================== +HalfSipHash 是 SipHash 的一个较不安全的变种 +=========================================== + +：作者: Jason A.Donenfeld <jason@zx2c4.com> + +如果你认为SipHash的速度不够快，无法满足你的需求，那么你可以 +使用HalfSipHash，这是一种令人担忧但是有用的选择。HalfSipHash +将SipHash的轮数从“2-4”降低到“1-3”，更令人担心的是，它使用一 +个容易被穷举攻击的64位密钥(输出为32位)，而不是SipHash的128位 +密钥，不过，这对于要求高性能“jhash”用户来说这是比较好的选择。 + +HalfSipHash是通过 "hsiphash" 系列函数提供的。 + +.. warning:: + 绝对不要在作为哈希表键函数之外使用hsiphash函数，只有在你 + 能完全能确定输出永远不会从内核传输出去的情况下才能使用， + 作为缓解哈希表泛洪拒绝服务攻击的一种手段，它仅在某些情况 + 下比jhash好用。 + +在64位的内核中，hsiphash函数实际上实现的是SipHash-1-3，这是一 +种减少轮数的SipHash变形，而不是HalfSipHash-1-3。这是因为在64位 +代码中SipHash-1-3的性能与HalfSipHash-1-3相当，甚至可能更快，请 +注意，这并不意味这在64位的内核中，hsihpash函数与siphash函数相 +同，也不意味着他们是安全的；hsihash函数仍然使用一种不太安全的 +减少轮数的算法，并将输出截断为32位。 + +生成哈希密钥 +============ + +密钥应始终来源于加密安全的随机数生成，要么使用get random bytes +要么使用get random once:: + + hsiphash_key_t key; + get_random_bytes(&key, sizeof(key)); + +如果你的钥匙来源不是这两个，那么你的做法是错的。 + +使用哈希函数 +============ + +这个函数有两种变体，一个是接受整数列表，另一种是接受缓冲区:: + + u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key); + +和:: + + u32 hsiphash_1u32(u32, const hsiphash_key_t *key); + u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key); + u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key); + u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key); + +如果向一个通用的hsiphash函数传递一个恒定长度的常量，他将在编译 +的时候将常量折叠，并自动选择一个优化后的函数。 + +哈希表键函数的用法 +================== + +:: + + struct some_hashtable { + DECLARE_HASHTABLE(hashtable, 8); + hsiphash_key_t key; + }; + + void init_hashtable(struct some_hashtable *table) + { + get_random_bytes(&table->key, sizeof(table->key)); + } + + static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input) + { + return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)]; + } + +然后，你可以像往常一样对返回的哈希存储桶进行迭代。 + +性能 +==== + +hsiphash()大约比jhash()慢三倍，这是因为有许多替换，不过这些都不是问题， +因为哈希表查找不是瓶颈。而且，这些牺牲是为了hsiphash()的安全性和DoS抗 +性，这是值得的。 diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst index 47780bb0772f..8b646c1010be 100644 --- a/Documentation/translations/zh_CN/subsystem-apis.rst +++ b/Documentation/translations/zh_CN/subsystem-apis.rst @@ -88,6 +88,7 @@ TODOList: cpu-freq/index iio/index virt/index + security/index PCI/index peci/index @@ -102,7 +103,6 @@ TODOList: * watchdog/index * hwmon/index * accel/index -* security/index * crypto/index * bpf/index * usb/index diff --git a/MAINTAINERS b/MAINTAINERS index 17daa9ee9384..4006434e0155 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12811,7 +12811,7 @@ L: kgdb-bugreport@lists.sourceforge.net S: Maintained W: http://kgdb.wiki.kernel.org/ T: git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git -F: Documentation/dev-tools/kgdb.rst +F: Documentation/process/debugging/kgdb.rst F: drivers/misc/kgdbts.c F: drivers/tty/serial/kgdboc.c F: include/linux/kdb.h diff --git a/include/linux/tty_driver.h b/include/linux/tty_driver.h index dd4b31ce6d5d..d4cdc089f6c3 100644 --- a/include/linux/tty_driver.h +++ b/include/linux/tty_driver.h @@ -320,7 +320,7 @@ struct serial_struct; * * @poll_init: ``int ()(struct tty_driver *driver, int line, char *options)`` * - * kgdboc support (Documentation/dev-tools/kgdb.rst). This routine is + * kgdboc support (Documentation/process/debugging/kgdb.rst). This routine is * called to initialize the HW for later use by calling @poll_get_char or * @poll_put_char. * diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index f3d723705879..d2cf74cbbe70 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -433,7 +433,7 @@ config GDB_SCRIPTS build directory. If you load vmlinux into gdb, the helper scripts will be automatically imported by gdb as well, and additional functions are available to analyze a Linux kernel - instance. See Documentation/dev-tools/gdb-kernel-debugging.rst + instance. See Documentation/process/debugging/gdb-kernel-debugging.rst for further details. endif # DEBUG_INFO diff --git a/lib/Kconfig.kgdb b/lib/Kconfig.kgdb index 537e1b3f5734..8336b1a489a3 100644 --- a/lib/Kconfig.kgdb +++ b/lib/Kconfig.kgdb @@ -19,7 +19,7 @@ menuconfig KGDB CONFIG_FRAME_POINTER to aid in producing more reliable stack backtraces in the external debugger. Documentation of kernel debugger is available at http://kgdb.sourceforge.net - as well as in Documentation/dev-tools/kgdb.rst. If + as well as in Documentation/process/debugging/kgdb.rst. If unsure, say N. if KGDB diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 9eed3683ad76..f7087dda9ac9 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -3230,7 +3230,7 @@ sub process { my $tag_case = not ($tag eq "Fixes:"); my $tag_space = not ($line =~ /^fixes:? [0-9a-f]{5,40} ($balanced_parens)/i); - my $id_length = not ($orig_commit =~ /^[0-9a-f]{12}$/i); + my $id_length = not ($orig_commit =~ /^[0-9a-f]{12,40}$/i); my $id_case = not ($orig_commit !~ /[A-F]/); my $id = "0123456789ab"; @@ -3240,7 +3240,7 @@ sub process { if ($ctitle ne $title || $tag_case || $tag_space || $id_length || $id_case || !$title_has_quotes) { if (WARN("BAD_FIXES_TAG", - "Please use correct Fixes: style 'Fixes: <12 chars of sha1> (\"<title line>\")' - ie: 'Fixes: $cid (\"$ctitle\")'\n" . $herecurr) && + "Please use correct Fixes: style 'Fixes: <12+ chars of sha1> (\"<title line>\")' - ie: 'Fixes: $cid (\"$ctitle\")'\n" . $herecurr) && $fix) { $fixed[$fixlinenr] = "Fixes: $cid (\"$ctitle\")"; } diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4ee843d3600e..e57c5e989a0a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2085,7 +2085,7 @@ sub process_name($$) { # Look for foo() or static void foo() - description; or misspelt # identifier elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || - /^$decl_start$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) { + /^$decl_start$fn_type?(\w+[^-:]*)$parenthesis?\s*$decl_end$/) { $identifier = $1; $decl_type = 'function'; $identifier =~ s/^define\s+//; |