lkml.org 
[lkml]   [2020]   [Jul]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[RFC PATCH 07/15] Documentation/pkeys: Update documentation for kernel pkeys
    Date
    From: Ira Weiny <ira.weiny@intel.com>

    Future Intel CPUS will support Protection Key Supervisor (PKS).

    Update the protection key documentation to cover pkeys on supervisor
    pages.

    Signed-off-by: Ira Weiny <ira.weiny@intel.com>
    ---
    Documentation/core-api/protection-keys.rst | 81 +++++++++++++++++-----
    1 file changed, 63 insertions(+), 18 deletions(-)

    diff --git a/Documentation/core-api/protection-keys.rst b/Documentation/core-api/protection-keys.rst
    index ec575e72d0b2..5ac400a5a306 100644
    --- a/Documentation/core-api/protection-keys.rst
    +++ b/Documentation/core-api/protection-keys.rst
    @@ -4,25 +4,33 @@
    Memory Protection Keys
    ======================

    -Memory Protection Keys for Userspace (PKU aka PKEYs) is a feature
    -which is found on Intel's Skylake (and later) "Scalable Processor"
    -Server CPUs. It will be available in future non-server Intel parts
    -and future AMD processors.
    -
    -For anyone wishing to test or use this feature, it is available in
    -Amazon's EC2 C5 instances and is known to work there using an Ubuntu
    -17.04 image.
    -
    Memory Protection Keys provides a mechanism for enforcing page-based
    protections, but without requiring modification of the page tables
    -when an application changes protection domains. It works by
    -dedicating 4 previously ignored bits in each page table entry to a
    -"protection key", giving 16 possible keys.
    +when an application changes protection domains.
    +
    +PKeys Userspace (PKU) is a feature which is found on Intel's Skylake "Scalable
    +Processor" Server CPUs and later. And It will be available in future
    +non-server Intel parts and future AMD processors.
    +
    +Future Intel processors will support Protection Keys for Supervisor pages
    +(PKS).
    +
    +For anyone wishing to test or use user space pkeys, it is available in Amazon's
    +EC2 C5 instances and is known to work there using an Ubuntu 17.04 image.
    +
    +pkes work by dedicating 4 previously Reserved bits in each page table entry to
    +a "protection key", giving 16 possible keys. User and Supervisor pages are
    +treated separately.

    -There is also a new user-accessible register (PKRU) with two separate
    -bits (Access Disable and Write Disable) for each key. Being a CPU
    -register, PKRU is inherently thread-local, potentially giving each
    -thread a different set of protections from every other thread.
    +Protections for each page are controlled with per CPU registers for each type
    +of page User and Supervisor. Each of these 32 bit register stores two separate
    +bits (Access Disable and Write Disable) for each key.
    +
    +For Userspace the register is user-accessible (rdpkru/wrpkru). For
    +Supervisor, the register (MSR_IA32_PKRS) is accessible only to the kernel.
    +
    +Being a CPU register, pkes are inherently thread-local, potentially giving
    +each thread an independent set of protections from every other thread.

    There are two new instructions (RDPKRU/WRPKRU) for reading and writing
    to the new register. The feature is only available in 64-bit mode,
    @@ -30,8 +38,11 @@ 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.

    -Syscalls
    -========
    +For kernel space rdmsr/wrmsr are used to access the kernel MSRs.
    +
    +
    +Syscalls for user space keys
    +============================

    There are 3 system calls which directly interact with pkeys::

    @@ -98,3 +109,37 @@ with a read()::
    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.
    +
    +
    +Kernel API for PKS support
    +==========================
    +
    +PKS is intended to harden against unwanted access to kernel pages. But it does
    +not completely restrict access under all conditions. For example the MSR
    +setting is not saved/restored during irqs. Thus the use of PKS is a mitigation
    +strategy rather than a form of strict security.
    +
    +The following calls are used to allocate, use, and deallocate a pkey which
    +defines a 'protection domain' within the kernel. Setting a pkey value in a
    +supervisor mapping adds that mapping to the protection domain. Then calls can be
    +used to enable/disable read and/or write access to all of the pages mapped with
    +that key:
    +
    + int pks_key_alloc(const char * const pkey_user);
    + #define PAGE_KERNEL_PKEY(pkey)
    + #define _PAGE_KEY(pkey)
    + int pks_update_protection(int pkey, unsigned long protection);
    + void pks_key_free(int pkey);
    +
    +In-kernel users must be prepared to set PAGE_KERNEL_PKEY() permission in the
    +page table entries for the mappings they want to ptorect.
    +
    +WARNING: It is imperative that callers check for errors from pks_key_alloc()
    +because pkeys are a limited resource and so callers should be prepared to work
    +without PKS support.
    +
    +For admins a debugfs interface provides a list of the current keys in use at:
    +
    + /sys/kernel/debug/x86/pks_keys_allocated
    +
    +Some example code can be found in lib/pks/pks_test.c
    --
    2.25.1
    \
     
     \ /
      Last update: 2020-07-14 09:06    [W:4.176 / U:0.092 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site