€••C      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ,/translations/zh_CN/core-api/protection-keys”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ,/translations/zh_TW/core-api/protection-keys”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ,/translations/it_IT/core-api/protection-keys”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ,/translations/ja_JP/core-api/protection-keys”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ,/translations/ko_KR/core-api/protection-keys”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ,/translations/sp_SP/core-api/protection-keys”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒF/var/lib/git/docbuild/linux/Documentation/core-api/protection-keys.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒMemory Protection Keys”h]”hŒMemory Protection Keys”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒ¶Memory Protection Keys provide a mechanism for enforcing page-based
protections, but without requiring modification of the page tables when an
application changes protection domains.”h]”hŒ¶Memory Protection Keys provide a mechanism for enforcing page-based
protections, but without requiring modification of the page tables when an
application changes protection domains.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒdefinition_list”“”)”}”(hhh]”hŒdefinition_list_item”“”)”}”(hŒõPkeys Userspace (PKU) is a feature which can be found on:
* Intel server CPUs, Skylake and later
* Intel client CPUs, Tiger Lake (11th Gen Core) and later
* Future AMD CPUs
* arm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE)
”h]”(hŒterm”“”)”}”(hŒ9Pkeys Userspace (PKU) is a feature which can be found on:”h]”hŒ9Pkeys Userspace (PKU) is a feature which can be found on:”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähŸh³h KhhàubhŒ
definition”“”)”}”(hhh]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ$Intel server CPUs, Skylake and later”h]”hÊ)”}”(hj  h]”hŒ$Intel server CPUs, Skylake and later”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj   ubah}”(h]”h ]”h"]”h$]”h&]”uh1hþhhûubhÿ)”}”(hŒ7Intel client CPUs, Tiger Lake (11th Gen Core) and later”h]”hÊ)”}”(hj  h]”hŒ7Intel client CPUs, Tiger Lake (11th Gen Core) and later”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hþhhûubhÿ)”}”(hŒFuture AMD CPUs”h]”hÊ)”}”(hj0  h]”hŒFuture AMD CPUs”…””}”(hj2  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj.  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hþhhûubhÿ)”}”(hŒFarm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE)
”h]”hÊ)”}”(hŒEarm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE)”h]”hŒEarm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE)”…””}”(hjI  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhjE  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hþhhûubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1hùhŸh³h Khhöubah}”(h]”h ]”h"]”h$]”h&]”uh1hôhhàubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÞhŸh³h KhhÛubah}”(h]”h ]”h"]”h$]”h&]”uh1hÙhh¶hžhhŸNh Nubhµ)”}”(hhh]”(hº)”}”(hŒx86_64”h]”hŒx86_64”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjw  hžhhŸh³h KubhÊ)”}”(hŒ|Pkeys work by dedicating 4 previously Reserved bits in each page table entry to
a "protection key", giving 16 possible keys.”h]”hŒ€Pkeys work by dedicating 4 previously Reserved bits in each page table entry to
a â€œprotection keyâ€, giving 16 possible keys.”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khjw  hžhubhÊ)”}”(hŒÁProtections for each key are defined with a per-CPU user-accessible register
(PKRU).  Each of these is a 32-bit register storing two bits (Access Disable
and Write Disable) for each of 16 keys.”h]”hŒÁProtections for each key are defined with a per-CPU user-accessible register
(PKRU).  Each of these is a 32-bit register storing two bits (Access Disable
and Write Disable) for each of 16 keys.”…””}”(hj–  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khjw  hžhubhÊ)”}”(hŒBeing a CPU register, PKRU is inherently thread-local, potentially giving each
thread a different set of protections from every other thread.”h]”hŒBeing a CPU register, PKRU is inherently thread-local, potentially giving each
thread a different set of protections from every other thread.”…””}”(hj¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khjw  hžhubhÊ)”}”(hX  There are two instructions (RDPKRU/WRPKRU) for reading and writing to the
register.  The feature is only available in 64-bit mode, even though there is
theoretically space in the PAE PTEs.  These permissions are enforced on data
access only and have no effect on instruction fetches.”h]”hX  There are two instructions (RDPKRU/WRPKRU) for reading and writing to the
register.  The feature is only available in 64-bit mode, even though there is
theoretically space in the PAE PTEs.  These permissions are enforced on data
access only and have no effect on instruction fetches.”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khjw  hžhubeh}”(h]”Œx86-64”ah ]”h"]”Œx86_64”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒarm64”h]”hŒarm64”…””}”(hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÈ  hžhhŸh³h K#ubhÊ)”}”(hŒfPkeys use 3 bits in each page table entry, to encode a "protection key index",
giving 8 possible keys.”h]”hŒjPkeys use 3 bits in each page table entry, to encode a â€œprotection key indexâ€,
giving 8 possible keys.”…””}”(hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K%hjÈ  hžhubhÊ)”}”(hŒËProtections for each key are defined with a per-CPU user-writable system
register (POR_EL0).  This is a 64-bit register encoding read, write and execute
overlay permissions for each protection key index.”h]”hŒËProtections for each key are defined with a per-CPU user-writable system
register (POR_EL0).  This is a 64-bit register encoding read, write and execute
overlay permissions for each protection key index.”…””}”(hjç  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K(hjÈ  hžhubhÊ)”}”(hŒBeing a CPU register, POR_EL0 is inherently thread-local, potentially giving
each thread a different set of protections from every other thread.”h]”hŒBeing a CPU register, POR_EL0 is inherently thread-local, potentially giving
each thread a different set of protections from every other thread.”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K,hjÈ  hžhubhÊ)”}”(hŒPUnlike x86_64, the protection key permissions also apply to instruction
fetches.”h]”hŒPUnlike x86_64, the protection key permissions also apply to instruction
fetches.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hjÈ  hžhubeh}”(h]”Œarm64”ah ]”h"]”Œarm64”ah$]”h&]”uh1h´hh¶hžhhŸh³h K#ubhµ)”}”(hhh]”(hº)”}”(hŒSyscalls”h]”hŒSyscalls”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K3ubhÊ)”}”(hŒ=There are 3 system calls which directly interact with pkeys::”h]”hŒ<There are 3 system calls which directly interact with pkeys:”…””}”(hj*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K5hj  hžhubhŒliteral_block”“”)”}”(hŒÂint pkey_alloc(unsigned long flags, unsigned long init_access_rights)
int pkey_free(int pkey);
int pkey_mprotect(unsigned long start, size_t len,
                  unsigned long prot, int pkey);”h]”hŒÂint pkey_alloc(unsigned long flags, unsigned long init_access_rights)
int pkey_free(int pkey);
int pkey_mprotect(unsigned long start, size_t len,
                  unsigned long prot, int pkey);”…””}”hj:  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h K7hj  hžhubhÊ)”}”(hX  Before a pkey can be used, it must first be allocated with pkey_alloc().  An
application writes to the architecture specific CPU register directly in order
to change access permissions to memory covered with a key.  In this example
this is wrapped by a C function called pkey_set().
::”h]”hX  Before a pkey can be used, it must first be allocated with pkey_alloc().  An
application writes to the architecture specific CPU register directly in order
to change access permissions to memory covered with a key.  In this example
this is wrapped by a C function called pkey_set().”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K<hj  hžhubj9  )”}”(hŒéint real_prot = PROT_READ|PROT_WRITE;
pkey = pkey_alloc(0, PKEY_DISABLE_WRITE);
ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0);
ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey);
... application runs here”h]”hŒéint real_prot = PROT_READ|PROT_WRITE;
pkey = pkey_alloc(0, PKEY_DISABLE_WRITE);
ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0);
ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey);
... application runs here”…””}”hjV  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h KBhj  hžhubhÊ)”}”(hŒ|Now, if the application needs to update the data at 'ptr', it can
gain access, do the update, then remove its write access::”h]”hŒNow, if the application needs to update the data at â€˜ptrâ€™, it can
gain access, do the update, then remove its write access:”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KHhj  hžhubj9  )”}”(hŒ’pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE
*ptr = foo; // assign something
pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again”h]”hŒ’pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE
*ptr = foo; // assign something
pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again”…””}”hjr  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h KKhj  hžhubhÊ)”}”(hŒWNow when it frees the memory, it will also free the pkey since it
is no longer in use::”h]”hŒVNow when it frees the memory, it will also free the pkey since it
is no longer in use:”…””}”(hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KOhj  hžhubj9  )”}”(hŒ(munmap(ptr, PAGE_SIZE);
pkey_free(pkey);”h]”hŒ(munmap(ptr, PAGE_SIZE);
pkey_free(pkey);”…””}”hjŽ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h KRhj  hžhubhŒnote”“”)”}”(hŒ™pkey_set() is a wrapper around writing to the CPU register.
Example implementations can be found in
tools/testing/selftests/mm/pkey-{arm64,powerpc,x86}.h”h]”hÊ)”}”(hŒ™pkey_set() is a wrapper around writing to the CPU register.
Example implementations can be found in
tools/testing/selftests/mm/pkey-{arm64,powerpc,x86}.h”h]”hŒ™pkey_set() is a wrapper around writing to the CPU register.
Example implementations can be found in
tools/testing/selftests/mm/pkey-{arm64,powerpc,x86}.h”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KUhjž  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jœ  hj  hžhhŸh³h Nubeh}”(h]”Œsyscalls”ah ]”h"]”Œsyscalls”ah$]”h&]”uh1h´hh¶hžhhŸh³h K3ubhµ)”}”(hhh]”(hº)”}”(hŒBehavior”h]”hŒBehavior”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¾  hžhhŸh³h KZubhÊ)”}”(hŒ~The kernel attempts to make protection keys consistent with the
behavior of a plain mprotect().  For instance if you do this::”h]”hŒ}The kernel attempts to make protection keys consistent with the
behavior of a plain mprotect().  For instance if you do this:”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K\hj¾  hžhubj9  )”}”(hŒ/mprotect(ptr, size, PROT_NONE);
something(ptr);”h]”hŒ/mprotect(ptr, size, PROT_NONE);
something(ptr);”…””}”hjÝ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h K_hj¾  hžhubhÊ)”}”(hŒFyou can expect the same effects with protection keys when doing this::”h]”hŒEyou can expect the same effects with protection keys when doing this:”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kbhj¾  hžhubj9  )”}”(hŒƒpkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ);
pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey);
something(ptr);”h]”hŒƒpkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ);
pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey);
something(ptr);”…””}”hjù  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h Kdhj¾  hžhubhÊ)”}”(hŒJThat should be true whether something() is a direct access to 'ptr'
like::”h]”hŒMThat should be true whether something() is a direct access to â€˜ptrâ€™
like:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khhj¾  hžhubj9  )”}”(hŒ*ptr = foo;”h]”hŒ*ptr = foo;”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h Kkhj¾  hžhubhÊ)”}”(hŒSor when the kernel does the access on the application's behalf like
with a read()::”h]”hŒTor when the kernel does the access on the applicationâ€™s behalf like
with a read():”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kmhj¾  hžhubj9  )”}”(hŒread(fd, ptr, 1);”h]”hŒread(fd, ptr, 1);”…””}”hj1  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j8  hŸh³h Kphj¾  hžhubhÊ)”}”(hŒ¹The kernel will send a SIGSEGV in both cases, but si_code will be set
to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
the plain mprotect() permissions are violated.”h]”hŒ¹The kernel will send a SIGSEGV in both cases, but si_code will be set
to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
the plain mprotect() permissions are violated.”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Krhj¾  hžhubhÊ)”}”(hŒÈNote that kernel accesses from a kthread (such as io_uring) will use a default
value for the protection key register and so will not be consistent with
userspace's value of the register or mprotect().”h]”hŒÊNote that kernel accesses from a kthread (such as io_uring) will use a default
value for the protection key register and so will not be consistent with
userspaceâ€™s value of the register or mprotect().”…””}”(hjM  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kvhj¾  hžhubeh}”(h]”Œbehavior”ah ]”h"]”Œbehavior”ah$]”h&]”uh1h´hh¶hžhhŸh³h KZubeh}”(h]”Œmemory-protection-keys”ah ]”h"]”Œmemory protection keys”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jŽ  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jh  je  jÅ  jÂ  j  j  j»  j¸  j`  j]  uŒ	nametypes”}”(jh  ‰jÅ  ‰j  ‰j»  ‰j`  ‰uh}”(je  h¶jÂ  jw  j  jÈ  j¸  j  j]  j¾  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.