Skip to contentSkip to conversation

doc: update printk documentation

PATCH Superseded Tobin C. Harding 3 participants 7 messages Dec 17, 2017 – Dec 18, 2017

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v2 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.

For v2 I have attempted to toe the line more in regards to 'make as few changes as possible to complete the conversion'.

This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _realy_ 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.

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.
- Remove unnecessary [style] edits.

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}                            | 271 +++++++++++----------
 Documentation/security/self-protection.rst         |  15 ++
 Documentation/sysctl/kernel.txt                    |   3 +-
 5 files changed, 158 insertions(+), 134 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (57%)
Signature · 1 line
2.7.4
#1 lore raw

PATCH v2 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.

---
 Documentation/00-INDEX                             |   2 -
 Documentation/core-api/index.rst                   |   1 +
 .../printk-formats.rst}                            | 271 +++++++++++----------
 3 files changed, 141 insertions(+), 133 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (57%)
Documentation/00-INDEX +0 -2
index 3bec49c33bbb..7023bfaec21c 100644
@@ -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
index d4d54b05d6c5..d55ee6b006ed 100644
@@ -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 +140 -131

515 lines not on this page · raw message

Signature · 1 line
2.7.4
#2 lore raw

PATCH v2 2/3 doc: update kpt_restrict documentation

In reply to 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.

---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sysctl/kernel.txt +2 -1
index 63663039acb7..6b039aa1427a 100644
@@ -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
reviewer
#3 lore raw

Re: [PATCH v2 2/3] doc: update kpt_restrict documentation

Quoted 15 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.

---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sysctl/kernel.txt +0 -0
index 63663039acb7..6b039aa1427a 100644

Documentation/sysctl/kernel.txt kptr_restrict: · line 394

Quoted 5 lines
Documentation/sysctl/kernel.txt +1 -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

how about:
is set to 0 (the default),
or
is set to (0) [the default],

Quoted 5 lines
Documentation/sysctl/kernel.txt +1 -0
+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
#4 lore raw

PATCH v2 3/3 doc: add documentation on printing kernel addresses

In reply to Tobin C. Harding

Hashing 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
index 60c8bd8b77bf..0f53826c78b9 100644
@@ -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
#5 lore raw
In reply to Tobin C. Harding
Quoted 3 lines · Tobin C. Harding

This set converts printk-formats.txt -> core-api/printk-formats.rst

We also update the documentation around printing kernel addresses.

Please also update the comment in lib/vsprintf.c

* ** Please update also Documentation/printk-formats.txt when making changes **

Quoted 1 line

I'd like to get it _realy_ correct so that future

sp: realy->really

#6 lore raw
Quoted 5 lines · Joe Perches
Quoted 3 lines · Tobin C. Harding

This set converts printk-formats.txt -> core-api/printk-formats.rst

We also update the documentation around printing kernel addresses.

Quoted 8 lines

Please also update the comment in lib/vsprintf.c

* ** Please update also Documentation/printk-formats.txt when making changes **

Quoted 1 line

I'd like to get it _realy_ correct so that future

sp: realy->really

Damn emphasis plays havoc with the spell checker. I do believe you have made this comment before Joe ;) I'll learn to spell one day.

Will fix as suggested and re-spin.

thanks,
Tobin