doc: update printk documentation
Subsystems (3)
cover doc: update printk documentation
This set merges two previous patch attempts
[PATCH v2] doc: convert printk-formats.txt to rst [PATCH] docs: add documentation on printing kernel addresses
And adds patch amending docs for sysctl kptr_restrict
Applies on top of
commit: "ae64f9bd1d36 Linux 4.15-rc2"
(Doesn't apply on top of Jon's docs-next tree (at time of writing at rc-1) because of commit made to lib/vsprintf.c)
thanks,
Tobin.
Tobin C. Harding (3):
doc: convert printk-formats.txt to rst
doc: update kpt_restrict documentation
doc: add documentation on printing kernel addresses
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 268 +++++++++++----------
Documentation/security/self-protection.rst | 15 ++
Documentation/sysctl/kernel.txt | 3 +-
lib/vsprintf.c | 155 +++++-------
6 files changed, 213 insertions(+), 231 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)Signature · 1 line
2.7.4
PATCH 1/3 doc: convert printk-formats.txt to rst
Documentation/printk-formats.txt is a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt
Changes required to complete conversion
- Move printk-formats.txt to core-api/printk-formats.rst
- Add entry to Documentation/core-api/index.rst
- Remove entry from Documentation/00-INDEX
- Fix minor grammatical errors.
- Order heading adornments as suggested by rst docs.
- Use 'Passed by reference' uniformly.
- Update pointer documentation around %px specifier.
- Fix erroneous double backticks (to commas).
- Simplify documentation for kobject.
- Convert lib/vsnprintf.c function docs to use kernel-docs and include in Documentation/printk-formats.rst
---
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 268 +++++++++++----------
lib/vsprintf.c | 155 +++++-------
4 files changed, 196 insertions(+), 230 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)Documentation/00-INDEX +0 -2
@@ -346,8 +346,6 @@ prctl/ - directory with info on the priveledge control subsystem preempt-locking.txt - info on locking under a preemptive kernel. -printk-formats.txt - - how to get printk format specifiers right process/ - how to work with the mainline kernel development process. pps/
Documentation/core-api/index.rst +1 -0
@@ -21,6 +21,7 @@ Core utilities flexible-arrays librs genalloc + printk-formats Interfaces for kernel debugging ===============================
Documentation/core-api/printk-formats.rst renamed from Documentation/printk-formats.txt +141 -127
512 lines not on this page · raw message
lib/vsprintf.c +54 -101
169 lines not on this page · raw message
Signature · 1 line
2.7.4
Re: [PATCH 1/3] doc: convert printk-formats.txt to rst
On Fri, Dec 08, 2017 at 09:27:54AM +1100, Tobin C. Harding wrote:
[snip]
New comments have come in from Kees Cook in thread for previous version. Please drop this set so Kees's suggestions can be implemented.
thanks,
Tobin.
PATCH 2/3 doc: update kpt_restrict documentation
In reply to Tobin C. HardingRecently the behaviour of printk specifier %pK was changed. The documentation does not currently mirror this.
Update documentation for sysctl kpt_restrict.
--- Documentation/sysctl/kernel.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sysctl/kernel.txt +2 -1
@@ -377,7 +377,8 @@ kptr_restrict: This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. -When kptr_restrict is set to (0), the default, there are no restrictions. +When kptr_restrict is set to (0), the default, the address is hashed before +printing. (This is the equivalent to %p.) When kptr_restrict is set to (1), kernel pointers printed using the %pK format specifier will be replaced with 0's unless the user has CAP_SYSLOG
Signature · 1 line
2.7.4
PATCH 3/3 doc: add documentation on printing kernel addresses
In reply to Tobin C. HardingHashing addresses printed with printk specifier %p was implemented recently. During development a number of issues were raised regarding leaking kernel addresses to userspace. Other documentation was updated but security/self-protection missed out.
Add self-protection documentation regarding printing kernel addresses.
--- Documentation/security/self-protection.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+)
Documentation/security/self-protection.rst +15 -0
@@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). +Kernel addresses +---------------- + +Printing kernel addresses to userspace leaks sensitive information about +the kernel memory layout. Care should be exercised when using any printk +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb] +in certain circumstances [*]). Any file written to using one of these +specifiers should be readable only by privileged processes. + +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1 +addresses printed with the specifier %p are hashed before printing. + +[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is +currently printed. If KALLSYMS is not enabled the address is printed. + Unique identifiers ------------------
Signature · 1 line
2.7.4