Skip to contentSkip to conversation

doc: update printk documentation

PATCH Superseded Tobin C. Harding 1 participant 5 messages Dec 7, 2017

Subsystems (3)

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
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 d5bbe035316d..2f9df634a726 100644
@@ -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
#2 lore raw

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.

#3 lore raw

PATCH 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 694968c7523c..1698cd2ef16b 100644
@@ -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
#4 lore raw

PATCH 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..392b5660337e 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
+currently printed. If KALLSYMS is not enabled the address is printed.
+
 Unique identifiers
 ------------------
 
Signature · 1 line
2.7.4