[linux-block.git] / Documentation / mm / page_table_check.rst

.. SPDX-License-Identifier: GPL-2.0

================
Page Table Check
================

Introduction
============

Page table check allows to harden the kernel by ensuring that some types of
the memory corruptions are prevented.

Page table check performs extra verifications at the time when new pages become
accessible from the userspace by getting their page table entries (PTEs PMDs
etc.) added into the table.

In case of detected corruption, the kernel is crashed. There is a small
performance and memory overhead associated with the page table check. Therefore,
it is disabled by default, but can be optionally enabled on systems where the
extra hardening outweighs the performance costs. Also, because page table check
is synchronous, it can help with debugging double map memory corruption issues,
by crashing kernel at the time wrong mapping occurs instead of later which is
often the case with memory corruptions bugs.

Double mapping detection logic
==============================

+-------------------+-------------------+-------------------+------------------+
| Current Mapping   | New mapping       | Permissions       | Rule             |
+===================+===================+===================+==================+
| Anonymous         | Anonymous         | Read              | Allow            |
+-------------------+-------------------+-------------------+------------------+
| Anonymous         | Anonymous         | Read / Write      | Prohibit         |
+-------------------+-------------------+-------------------+------------------+
| Anonymous         | Named             | Any               | Prohibit         |
+-------------------+-------------------+-------------------+------------------+
| Named             | Anonymous         | Any               | Prohibit         |
+-------------------+-------------------+-------------------+------------------+
| Named             | Named             | Any               | Allow            |
+-------------------+-------------------+-------------------+------------------+

Enabling Page Table Check
=========================

Build kernel with:

- PAGE_TABLE_CHECK=y
  Note, it can only be enabled on platforms where ARCH_SUPPORTS_PAGE_TABLE_CHECK
  is available.

- Boot with 'page_table_check=on' kernel parameter.

Optionally, build kernel with PAGE_TABLE_CHECK_ENFORCED in order to have page
table support without extra kernel parameter.
Commit	Line	Data
df4e817b PT	1	.. SPDX-License-Identifier: GPL-2.0
df4e817b PT	2
df4e817b PT	3	================
	4	Page Table Check
	5	================
	6
	7	Introduction
	8	============
	9
854d0982	10	Page table check allows to harden the kernel by ensuring that some types of
df4e817b PT	11	the memory corruptions are prevented.
	12
	13	Page table check performs extra verifications at the time when new pages become
	14	accessible from the userspace by getting their page table entries (PTEs PMDs
	15	etc.) added into the table.
	16
	17	In case of detected corruption, the kernel is crashed. There is a small
	18	performance and memory overhead associated with the page table check. Therefore,
	19	it is disabled by default, but can be optionally enabled on systems where the
	20	extra hardening outweighs the performance costs. Also, because page table check
	21	is synchronous, it can help with debugging double map memory corruption issues,
	22	by crashing kernel at the time wrong mapping occurs instead of later which is
	23	often the case with memory corruptions bugs.
	24
	25	Double mapping detection logic
	26	==============================
	27
	28	+-------------------+-------------------+-------------------+------------------+
	29	\| Current Mapping \| New mapping \| Permissions \| Rule \|
	30	+===================+===================+===================+==================+
	31	\| Anonymous \| Anonymous \| Read \| Allow \|
	32	+-------------------+-------------------+-------------------+------------------+
	33	\| Anonymous \| Anonymous \| Read / Write \| Prohibit \|
	34	+-------------------+-------------------+-------------------+------------------+
	35	\| Anonymous \| Named \| Any \| Prohibit \|
	36	+-------------------+-------------------+-------------------+------------------+
	37	\| Named \| Anonymous \| Any \| Prohibit \|
	38	+-------------------+-------------------+-------------------+------------------+
	39	\| Named \| Named \| Any \| Allow \|
	40	+-------------------+-------------------+-------------------+------------------+
	41
	42	Enabling Page Table Check
	43	=========================
	44
	45	Build kernel with:
	46
	47	- PAGE_TABLE_CHECK=y
	48	Note, it can only be enabled on platforms where ARCH_SUPPORTS_PAGE_TABLE_CHECK
	49	is available.
	50
	51	- Boot with 'page_table_check=on' kernel parameter.
	52
	53	Optionally, build kernel with PAGE_TABLE_CHECK_ENFORCED in order to have page
	54	table support without extra kernel parameter.