1======================================
2Secure Encrypted Virtualization (SEV)
3======================================
4
5Overview
6========
7
8Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
9
10SEV is an extension to the AMD-V architecture which supports running
11virtual machines (VMs) under the control of a hypervisor. When enabled,
12the memory contents of a VM will be transparently encrypted with a key
13unique to that VM.
14
15The hypervisor can determine the SEV support through the CPUID
16instruction. The CPUID function 0x8000001f reports information related
17to SEV::
18
19	0x8000001f[eax]:
20			Bit[1] 	indicates support for SEV
21	    ...
22		  [ecx]:
23			Bits[31:0]  Number of encrypted guests supported simultaneously
24
25If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015
26(MSR_K7_HWCR) can be used to determine if it can be enabled::
27
28	0xc001_0010:
29		Bit[23]	   1 = memory encryption can be enabled
30			   0 = memory encryption can not be enabled
31
32	0xc001_0015:
33		Bit[0]	   1 = memory encryption can be enabled
34			   0 = memory encryption can not be enabled
35
36When SEV support is available, it can be enabled in a specific VM by
37setting the SEV bit before executing VMRUN.::
38
39	VMCB[0x90]:
40		Bit[1]	    1 = SEV is enabled
41			    0 = SEV is disabled
42
43SEV hardware uses ASIDs to associate a memory encryption key with a VM.
44Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value
45defined in the CPUID 0x8000001f[ecx] field.
46
47SEV Key Management
48==================
49
50The SEV guest key management is handled by a separate processor called the AMD
51Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure
52key management interface to perform common hypervisor activities such as
53encrypting bootstrap code, snapshot, migrating and debugging the guest. For more
54information, see the SEV Key Management spec [api-spec]_
55
56KVM implements the following commands to support common lifecycle events of SEV
57guests, such as launching, running, snapshotting, migrating and decommissioning.
58
591. KVM_SEV_INIT
60---------------
61
62The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform
63context. In a typical workflow, this command should be the first command issued.
64
65Returns: 0 on success, -negative on error
66
672. KVM_SEV_LAUNCH_START
68-----------------------
69
70The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
71context. To create the encryption context, user must provide a guest policy,
72the owner's public Diffie-Hellman (PDH) key and session information.
73
74Parameters: struct  kvm_sev_launch_start (in/out)
75
76Returns: 0 on success, -negative on error
77
78::
79
80        struct kvm_sev_launch_start {
81                __u32 handle;           /* if zero then firmware creates a new handle */
82                __u32 policy;           /* guest's policy */
83
84                __u64 dh_uaddr;         /* userspace address pointing to the guest owner's PDH key */
85                __u32 dh_len;
86
87                __u64 session_addr;     /* userspace address which points to the guest session information */
88                __u32 session_len;
89        };
90
91On success, the 'handle' field contains a new handle and on error, a negative value.
92
93For more details, see SEV spec Section 6.2.
94
953. KVM_SEV_LAUNCH_UPDATE_DATA
96-----------------------------
97
98The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
99calculates a measurement of the memory contents. The measurement is a signature
100of the memory contents that can be sent to the guest owner as an attestation
101that the memory was encrypted correctly by the firmware.
102
103Parameters (in): struct  kvm_sev_launch_update_data
104
105Returns: 0 on success, -negative on error
106
107::
108
109        struct kvm_sev_launch_update {
110                __u64 uaddr;    /* userspace address to be encrypted (must be 16-byte aligned) */
111                __u32 len;      /* length of the data to be encrypted (must be 16-byte aligned) */
112        };
113
114For more details, see SEV spec Section 6.3.
115
1164. KVM_SEV_LAUNCH_MEASURE
117-------------------------
118
119The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
120data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
121wait to provide the guest with confidential information until it can verify the
122measurement. Since the guest owner knows the initial contents of the guest at
123boot, the measurement can be verified by comparing it to what the guest owner
124expects.
125
126Parameters (in): struct  kvm_sev_launch_measure
127
128Returns: 0 on success, -negative on error
129
130::
131
132        struct kvm_sev_launch_measure {
133                __u64 uaddr;    /* where to copy the measurement */
134                __u32 len;      /* length of measurement blob */
135        };
136
137For more details on the measurement verification flow, see SEV spec Section 6.4.
138
1395. KVM_SEV_LAUNCH_FINISH
140------------------------
141
142After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
143issued to make the guest ready for the execution.
144
145Returns: 0 on success, -negative on error
146
1476. KVM_SEV_GUEST_STATUS
148-----------------------
149
150The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
151SEV-enabled guest.
152
153Parameters (out): struct kvm_sev_guest_status
154
155Returns: 0 on success, -negative on error
156
157::
158
159        struct kvm_sev_guest_status {
160                __u32 handle;   /* guest handle */
161                __u32 policy;   /* guest policy */
162                __u8 state;     /* guest state (see enum below) */
163        };
164
165SEV guest state:
166
167::
168
169        enum {
170        SEV_STATE_INVALID = 0;
171        SEV_STATE_LAUNCHING,    /* guest is currently being launched */
172        SEV_STATE_SECRET,       /* guest is being launched and ready to accept the ciphertext data */
173        SEV_STATE_RUNNING,      /* guest is fully launched and running */
174        SEV_STATE_RECEIVING,    /* guest is being migrated in from another SEV machine */
175        SEV_STATE_SENDING       /* guest is getting migrated out to another SEV machine */
176        };
177
1787. KVM_SEV_DBG_DECRYPT
179----------------------
180
181The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
182firmware to decrypt the data at the given memory region.
183
184Parameters (in): struct kvm_sev_dbg
185
186Returns: 0 on success, -negative on error
187
188::
189
190        struct kvm_sev_dbg {
191                __u64 src_uaddr;        /* userspace address of data to decrypt */
192                __u64 dst_uaddr;        /* userspace address of destination */
193                __u32 len;              /* length of memory region to decrypt */
194        };
195
196The command returns an error if the guest policy does not allow debugging.
197
1988. KVM_SEV_DBG_ENCRYPT
199----------------------
200
201The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
202firmware to encrypt the data at the given memory region.
203
204Parameters (in): struct kvm_sev_dbg
205
206Returns: 0 on success, -negative on error
207
208::
209
210        struct kvm_sev_dbg {
211                __u64 src_uaddr;        /* userspace address of data to encrypt */
212                __u64 dst_uaddr;        /* userspace address of destination */
213                __u32 len;              /* length of memory region to encrypt */
214        };
215
216The command returns an error if the guest policy does not allow debugging.
217
2189. KVM_SEV_LAUNCH_SECRET
219------------------------
220
221The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
222data after the measurement has been validated by the guest owner.
223
224Parameters (in): struct kvm_sev_launch_secret
225
226Returns: 0 on success, -negative on error
227
228::
229
230        struct kvm_sev_launch_secret {
231                __u64 hdr_uaddr;        /* userspace address containing the packet header */
232                __u32 hdr_len;
233
234                __u64 guest_uaddr;      /* the guest memory region where the secret should be injected */
235                __u32 guest_len;
236
237                __u64 trans_uaddr;      /* the hypervisor memory region which contains the secret */
238                __u32 trans_len;
239        };
240
241References
242==========
243
244.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
245.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM%20API_Specification.pdf
246.. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34)
247.. [kvm-forum]  http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
248