protection-keys.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ======================
  3. Memory Protection Keys
  4. ======================
  5. Memory Protection Keys for Userspace (PKU aka PKEYs) is a feature
  6. which is found on Intel's Skylake (and later) "Scalable Processor"
  7. Server CPUs. It will be available in future non-server Intel parts
  8. and future AMD processors.
  9. For anyone wishing to test or use this feature, it is available in
  10. Amazon's EC2 C5 instances and is known to work there using an Ubuntu
  11. 17.04 image.
  12. Memory Protection Keys provides a mechanism for enforcing page-based
  13. protections, but without requiring modification of the page tables
  14. when an application changes protection domains. It works by
  15. dedicating 4 previously ignored bits in each page table entry to a
  16. "protection key", giving 16 possible keys.
  17. There is also a new user-accessible register (PKRU) with two separate
  18. bits (Access Disable and Write Disable) for each key. Being a CPU
  19. register, PKRU is inherently thread-local, potentially giving each
  20. thread a different set of protections from every other thread.
  21. There are two new instructions (RDPKRU/WRPKRU) for reading and writing
  22. to the new register. The feature is only available in 64-bit mode,
  23. even though there is theoretically space in the PAE PTEs. These
  24. permissions are enforced on data access only and have no effect on
  25. instruction fetches.
  26. Syscalls
  27. ========
  28. There are 3 system calls which directly interact with pkeys::
  29. int pkey_alloc(unsigned long flags, unsigned long init_access_rights)
  30. int pkey_free(int pkey);
  31. int pkey_mprotect(unsigned long start, size_t len,
  32. unsigned long prot, int pkey);
  33. Before a pkey can be used, it must first be allocated with
  34. pkey_alloc(). An application calls the WRPKRU instruction
  35. directly in order to change access permissions to memory covered
  36. with a key. In this example WRPKRU is wrapped by a C function
  37. called pkey_set().
  38. ::
  39. int real_prot = PROT_READ|PROT_WRITE;
  40. pkey = pkey_alloc(0, PKEY_DISABLE_WRITE);
  41. ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0);
  42. ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey);
  43. ... application runs here
  44. Now, if the application needs to update the data at 'ptr', it can
  45. gain access, do the update, then remove its write access::
  46. pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE
  47. *ptr = foo; // assign something
  48. pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again
  49. Now when it frees the memory, it will also free the pkey since it
  50. is no longer in use::
  51. munmap(ptr, PAGE_SIZE);
  52. pkey_free(pkey);
  53. .. note:: pkey_set() is a wrapper for the RDPKRU and WRPKRU instructions.
  54. An example implementation can be found in
  55. tools/testing/selftests/x86/protection_keys.c.
  56. Behavior
  57. ========
  58. The kernel attempts to make protection keys consistent with the
  59. behavior of a plain mprotect(). For instance if you do this::
  60. mprotect(ptr, size, PROT_NONE);
  61. something(ptr);
  62. you can expect the same effects with protection keys when doing this::
  63. pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ);
  64. pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey);
  65. something(ptr);
  66. That should be true whether something() is a direct access to 'ptr'
  67. like::
  68. *ptr = foo;
  69. or when the kernel does the access on the application's behalf like
  70. with a read()::
  71. read(fd, ptr, 1);
  72. The kernel will send a SIGSEGV in both cases, but si_code will be set
  73. to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
  74. the plain mprotect() permissions are violated.