1.. SPDX-License-Identifier: GPL-2.0
  2
  3=====================
  4AMD Memory Encryption
  5=====================
  6
  7Secure Memory Encryption (SME) and Secure Encrypted Virtualization (SEV) are
  8features found on AMD processors.
  9
 10SME provides the ability to mark individual pages of memory as encrypted using
 11the standard x86 page tables.  A page that is marked encrypted will be
 12automatically decrypted when read from DRAM and encrypted when written to
 13DRAM.  SME can therefore be used to protect the contents of DRAM from physical
 14attacks on the system.
 15
 16SEV enables running encrypted virtual machines (VMs) in which the code and data
 17of the guest VM are secured so that a decrypted version is available only
 18within the VM itself. SEV guest VMs have the concept of private and shared
 19memory. Private memory is encrypted with the guest-specific key, while shared
 20memory may be encrypted with hypervisor key. When SME is enabled, the hypervisor
 21key is the same key which is used in SME.
 22
 23A page is encrypted when a page table entry has the encryption bit set (see
 24below on how to determine its position).  The encryption bit can also be
 25specified in the cr3 register, allowing the PGD table to be encrypted. Each
 26successive level of page tables can also be encrypted by setting the encryption
 27bit in the page table entry that points to the next table. This allows the full
 28page table hierarchy to be encrypted. Note, this means that just because the
 29encryption bit is set in cr3, doesn't imply the full hierarchy is encrypted.
 30Each page table entry in the hierarchy needs to have the encryption bit set to
 31achieve that. So, theoretically, you could have the encryption bit set in cr3
 32so that the PGD is encrypted, but not set the encryption bit in the PGD entry
 33for a PUD which results in the PUD pointed to by that entry to not be
 34encrypted.
 35
 36When SEV is enabled, instruction pages and guest page tables are always treated
 37as private. All the DMA operations inside the guest must be performed on shared
 38memory. Since the memory encryption bit is controlled by the guest OS when it
 39is operating in 64-bit or 32-bit PAE mode, in all other modes the SEV hardware
 40forces the memory encryption bit to 1.
 41
 42Support for SME and SEV can be determined through the CPUID instruction. The
 43CPUID function 0x8000001f reports information related to SME::
 44
 45	0x8000001f[eax]:
 46		Bit[0] indicates support for SME
 47		Bit[1] indicates support for SEV
 48	0x8000001f[ebx]:
 49		Bits[5:0]  pagetable bit number used to activate memory
 50			   encryption
 51		Bits[11:6] reduction in physical address space, in bits, when
 52			   memory encryption is enabled (this only affects
 53			   system physical addresses, not guest physical
 54			   addresses)
 55
 56If support for SME is present, MSR 0xc00100010 (MSR_AMD64_SYSCFG) can be used to
 57determine if SME is enabled and/or to enable memory encryption::
 58
 59	0xc0010010:
 60		Bit[23]   0 = memory encryption features are disabled
 61			  1 = memory encryption features are enabled
 62
 63If SEV is supported, MSR 0xc0010131 (MSR_AMD64_SEV) can be used to determine if
 64SEV is active::
 65
 66	0xc0010131:
 67		Bit[0]	  0 = memory encryption is not active
 68			  1 = memory encryption is active
 69
 70Linux relies on BIOS to set this bit if BIOS has determined that the reduction
 71in the physical address space as a result of enabling memory encryption (see
 72CPUID information above) will not conflict with the address space resource
 73requirements for the system.  If this bit is not set upon Linux startup then
 74Linux itself will not set it and memory encryption will not be possible.
 75
 76The state of SME in the Linux kernel can be documented as follows:
 77
 78	- Supported:
 79	  The CPU supports SME (determined through CPUID instruction).
 80
 81	- Enabled:
 82	  Supported and bit 23 of MSR_AMD64_SYSCFG is set.
 83
 84	- Active:
 85	  Supported, Enabled and the Linux kernel is actively applying
 86	  the encryption bit to page table entries (the SME mask in the
 87	  kernel is non-zero).
 88
 89SME can also be enabled and activated in the BIOS. If SME is enabled and
 90activated in the BIOS, then all memory accesses will be encrypted and it will
 91not be necessary to activate the Linux memory encryption support.  If the BIOS
 92merely enables SME (sets bit 23 of the MSR_AMD64_SYSCFG), then Linux can activate
 93memory encryption by default (CONFIG_AMD_MEM_ENCRYPT_ACTIVE_BY_DEFAULT=y) or
 94by supplying mem_encrypt=on on the kernel command line.  However, if BIOS does
 95not enable SME, then Linux will not be able to activate memory encryption, even
 96if configured to do so by default or the mem_encrypt=on command line parameter
 97is specified.
 98
 99Secure Nested Paging (SNP)
100==========================
101
102SEV-SNP introduces new features (SEV_FEATURES[1:63]) which can be enabled
103by the hypervisor for security enhancements. Some of these features need
104guest side implementation to function correctly. The below table lists the
105expected guest behavior with various possible scenarios of guest/hypervisor
106SNP feature support.
107
108+-----------------+---------------+---------------+------------------+
109| Feature Enabled | Guest needs   | Guest has     | Guest boot       |
110| by the HV       | implementation| implementation| behaviour        |
111+=================+===============+===============+==================+
112|      No         |      No       |      No       |     Boot         |
113|                 |               |               |                  |
114+-----------------+---------------+---------------+------------------+
115|      No         |      Yes      |      No       |     Boot         |
116|                 |               |               |                  |
117+-----------------+---------------+---------------+------------------+
118|      No         |      Yes      |      Yes      |     Boot         |
119|                 |               |               |                  |
120+-----------------+---------------+---------------+------------------+
121|      Yes        |      No       |      No       | Boot with        |
122|                 |               |               | feature enabled  |
123+-----------------+---------------+---------------+------------------+
124|      Yes        |      Yes      |      No       | Graceful boot    |
125|                 |               |               | failure          |
126+-----------------+---------------+---------------+------------------+
127|      Yes        |      Yes      |      Yes      | Boot with        |
128|                 |               |               | feature enabled  |
129+-----------------+---------------+---------------+------------------+
130
131More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR
132
133[1] https://www.amd.com/system/files/TechDocs/40332.pdf