Skip to contentSkip to conversation

doc: update printk documentation

PATCH Superseded Tobin C. Harding 2 participants 6 messages Dec 18, 2017 – Dec 19, 2017

Subsystems (3)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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

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
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 +119 -110

485 lines not on this page · raw message

lib/vsprintf.c +2 -1
index 01c3957b2de6..6ec0844ab5d1 100644
@@ -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
#2 lore raw

PATCH v3 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..412314eebda6 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 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
---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sysctl/kernel.txt +2 -1
index 63663039acb7..412314eebda6 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
~Randy
#4 lore raw

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.

#5 lore raw

PATCH v3 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