doc: update printk documentation
Subsystems (3)
v3 cover doc: update printk documentation
This set converts printk-formats.txt -> core-api/printk-formats.rst
We also update the documentation around printing kernel addresses.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _really_ correct so that future conversions will require less review effort. Also if there are any peculiarities to patching docs (as apposed to C files) please say so.
Thank you for the time already given to reviewing previous versions.
thanks,
Tobin.
v3:
- Update filename .txt -> .rst in lib/vsnprintf.c comment (Joe Perches)
- Remove unnecessary commas (as suggested by Randy Dunlap)
- Re-apply theory 'make as few changes as possible to complete the conversion'
v2:
- Remove conversion/inclusion of kernel-docs from lib/vsprintf.c
- Add '<>' around file name (in section 'Thanks').
- Remove a few more double back ticks.
- Apply theory 'make as few changes as possible to complete the conversion'
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} | 229 +++++++++++----------
Documentation/security/self-protection.rst | 15 ++
Documentation/sysctl/kernel.txt | 3 +-
lib/vsprintf.c | 3 +-
6 files changed, 139 insertions(+), 114 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)Signature · 1 line
2.7.4
PATCH v3 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).
- Remove extraneous double backticks (suggested by Jonathan Corbet).
- Simplify documentation for kobject.
---
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 229 +++++++++++----------
lib/vsprintf.c | 3 +-
4 files changed, 122 insertions(+), 113 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)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
@@ -22,6 +22,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 +119 -110
485 lines not on this page · raw message
lib/vsprintf.c +2 -1
@@ -1834,7 +1834,8 @@ static char *ptr_to_id(char *buf, char *end, void *ptr, struct printf_spec spec)* * - 'x' For printing the address. Equivalent to "%lx". * -* ** Please update also Documentation/printk-formats.txt when making changes ** +* ** When making changes please also update: +* Documentation/core-api/printk-formats.rst * * Note: The difference between 'S' and 'F' is that on ia64 and ppc64 * function pointers are really function descriptors, which contain a
Signature · 1 line
2.7.4
PATCH v3 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
@@ -391,7 +391,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
Randy Dunlap
reviewerRe: [PATCH v3 2/3] doc: update kpt_restrict documentation
Quoted 4 lines · Tobin C. Harding
Recently the behaviour of printk specifier %pK was changed. The documentation does not currently mirror this.
Update documentation for sysctl
kpt_restrict.
Fix subject and here ............ ^^^^^^^^^^^^.
Quoted 21 lines
Signed-off-by Tobin C. Harding <[email protected]>--- Documentation/sysctl/kernel.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/sysctl/kernel.txt +2
-1@@ -391,7 +391,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
~Randy
Re: [PATCH v3 2/3] doc: update kpt_restrict documentation
Quoted 7 lines · Randy Dunlap
Quoted 4 lines · Tobin C. Harding
Recently the behaviour of printk specifier %pK was changed. The documentation does not currently mirror this.
Update documentation for sysctl
kpt_restrict.Fix subject and here ............ ^^^^^^^^^^^^.
Oh thanks. Took quite a few minutes of staring to see the mistake ;)
Will fix and re-spin.
thanks,
Tobin.
PATCH v3 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 +printed. If KALLSYMS is not enabled the raw address is printed. + Unique identifiers ------------------
Signature · 1 line
2.7.4