Re: [PATCH v36 04/24] x86/sgx: Add SGX microarchitectural data structures

From: Darren Kenny
Date: Thu Aug 06 2020 - 14:37:30 EST


On Thursday, 2020-07-16 at 16:52:43 +03, Jarkko Sakkinen wrote:
> Define the SGX microarchitectural data structures used by various SGX
> opcodes. This is not an exhaustive representation of all SGX data
> structures but only those needed by the kernel.
>
> The data structures are described in:
>
> Intel SDM: 37.6 INTEL® SGX DATA STRUCTURES OVERVIEW
>
> Acked-by: Jethro Beekman <jethro@xxxxxxxxxxxx>
> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@xxxxxxxxxxxxxxx>

Reviewed-by: Darren Kenny <darren.kenny@xxxxxxxxxx>

> ---
> arch/x86/kernel/cpu/sgx/arch.h | 343 +++++++++++++++++++++++++++++++++
> 1 file changed, 343 insertions(+)
> create mode 100644 arch/x86/kernel/cpu/sgx/arch.h
>
> diff --git a/arch/x86/kernel/cpu/sgx/arch.h b/arch/x86/kernel/cpu/sgx/arch.h
> new file mode 100644
> index 000000000000..ddae55e9d4d8
> --- /dev/null
> +++ b/arch/x86/kernel/cpu/sgx/arch.h
> @@ -0,0 +1,343 @@
> +/* SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause) */
> +/**
> + * Copyright(c) 2016-18 Intel Corporation.
> + *
> + * Contains data structures defined by the SGX architecture. Data structures
> + * defined by the Linux software stack should not be placed here.
> + */
> +#ifndef _ASM_X86_SGX_ARCH_H
> +#define _ASM_X86_SGX_ARCH_H
> +
> +#include <linux/bits.h>
> +#include <linux/types.h>
> +
> +#define SGX_CPUID 0x12
> +#define SGX_CPUID_FIRST_VARIABLE_SUB_LEAF 2
> +
> +/**
> + * enum sgx_return_code - The return code type for ENCLS, ENCLU and ENCLV
> + * %SGX_NOT_TRACKED: Previous ETRACK's shootdown sequence has not
> + * been completed yet.
> + * %SGX_INVALID_EINITTOKEN: EINITTOKEN is invalid and enclave signer's
> + * public key does not match IA32_SGXLEPUBKEYHASH.
> + * %SGX_UNMASKED_EVENT: An unmasked event, e.g. INTR, was received
> + */
> +enum sgx_return_code {
> + SGX_NOT_TRACKED = 11,
> + SGX_INVALID_EINITTOKEN = 16,
> + SGX_UNMASKED_EVENT = 128,
> +};
> +
> +/**
> + * enum sgx_sub_leaf_types - SGX CPUID variable sub-leaf types
> + * %SGX_CPUID_SUB_LEAF_INVALID: Indicates this sub-leaf is invalid.
> + * %SGX_CPUID_SUB_LEAF_EPC_SECTION: Sub-leaf enumerates an EPC section.
> + */
> +enum sgx_sub_leaf_types {
> + SGX_CPUID_SUB_LEAF_INVALID = 0x0,
> + SGX_CPUID_SUB_LEAF_EPC_SECTION = 0x1,
> +};
> +
> +#define SGX_CPUID_SUB_LEAF_TYPE_MASK GENMASK(3, 0)
> +
> +#define SGX_MODULUS_SIZE 384
> +
> +/**
> + * enum sgx_miscselect - additional information to an SSA frame
> + * %SGX_MISC_EXINFO: Report #PF or #GP to the SSA frame.
> + *
> + * Save State Area (SSA) is a stack inside the enclave used to store processor
> + * state when an exception or interrupt occurs. This enum defines additional
> + * information stored to an SSA frame.
> + */
> +enum sgx_miscselect {
> + SGX_MISC_EXINFO = BIT(0),
> +};
> +
> +#define SGX_MISC_RESERVED_MASK GENMASK_ULL(63, 1)
> +
> +#define SGX_SSA_GPRS_SIZE 184
> +#define SGX_SSA_MISC_EXINFO_SIZE 16
> +
> +/**
> + * enum sgx_attributes - the attributes field in &struct sgx_secs
> + * %SGX_ATTR_INIT: Enclave can be entered (is initialized).
> + * %SGX_ATTR_DEBUG: Allow ENCLS(EDBGRD) and ENCLS(EDBGWR).
> + * %SGX_ATTR_MODE64BIT: Tell that this a 64-bit enclave.
> + * %SGX_ATTR_PROVISIONKEY: Allow to use provisioning keys for remote
> + * attestation.
> + * %SGX_ATTR_KSS: Allow to use key separation and sharing (KSS).
> + * %SGX_ATTR_EINITTOKENKEY: Allow to use token signing key that is used to
> + * sign cryptographic tokens that can be passed to
> + * EINIT as an authorization to run an enclave.
> + */
> +enum sgx_attribute {
> + SGX_ATTR_INIT = BIT(0),
> + SGX_ATTR_DEBUG = BIT(1),
> + SGX_ATTR_MODE64BIT = BIT(2),
> + SGX_ATTR_PROVISIONKEY = BIT(4),
> + SGX_ATTR_EINITTOKENKEY = BIT(5),
> + SGX_ATTR_KSS = BIT(7),
> +};
> +
> +#define SGX_ATTR_RESERVED_MASK (BIT_ULL(3) | BIT_ULL(6) | GENMASK_ULL(63, 8))
> +#define SGX_ATTR_ALLOWED_MASK (SGX_ATTR_DEBUG | SGX_ATTR_MODE64BIT | \
> + SGX_ATTR_KSS)
> +
> +/**
> + * struct sgx_secs - SGX Enclave Control Structure (SECS)
> + * @size: size of the address space
> + * @base: base address of the address space
> + * @ssa_frame_size: size of an SSA frame
> + * @miscselect: additional information stored to an SSA frame
> + * @attributes: attributes for enclave
> + * @xfrm: XSave-Feature Request Mask (subset of XCR0)
> + * @mrenclave: SHA256-hash of the enclave contents
> + * @mrsigner: SHA256-hash of the public key used to sign the SIGSTRUCT
> + * @config_id: a user-defined value that is used in key derivation
> + * @isv_prod_id: a user-defined value that is used in key derivation
> + * @isv_svn: a user-defined value that is used in key derivation
> + * @config_svn: a user-defined value that is used in key derivation
> + *
> + * SGX Enclave Control Structure (SECS) is a special enclave page that is not
> + * visible in the address space. In fact, this structure defines the address
> + * range and other global attributes for the enclave and it is the first EPC
> + * page created for any enclave. It is moved from a temporary buffer to an EPC
> + * by the means of ENCLS(ECREATE) leaf.
> + */
> +struct sgx_secs {
> + u64 size;
> + u64 base;
> + u32 ssa_frame_size;
> + u32 miscselect;
> + u8 reserved1[24];
> + u64 attributes;
> + u64 xfrm;
> + u32 mrenclave[8];
> + u8 reserved2[32];
> + u32 mrsigner[8];
> + u8 reserved3[32];
> + u32 config_id[16];
> + u16 isv_prod_id;
> + u16 isv_svn;
> + u16 config_svn;
> + u8 reserved4[3834];
> +} __packed;
> +
> +/**
> + * enum sgx_tcs_flags - execution flags for TCS
> + * %SGX_TCS_DBGOPTIN: If enabled allows single-stepping and breakpoints
> + * inside an enclave. It is cleared by EADD but can
> + * be set later with EDBGWR.
> + */
> +enum sgx_tcs_flags {
> + SGX_TCS_DBGOPTIN = 0x01,
> +};
> +
> +#define SGX_TCS_RESERVED_MASK GENMASK_ULL(63, 1)
> +#define SGX_TCS_RESERVED_SIZE 4024
> +
> +/**
> + * struct sgx_tcs - Thread Control Structure (TCS)
> + * @state: used to mark an entered TCS
> + * @flags: execution flags (cleared by EADD)
> + * @ssa_offset: SSA stack offset relative to the enclave base
> + * @ssa_index: the current SSA frame index (cleard by EADD)
> + * @nr_ssa_frames: the number of frame in the SSA stack
> + * @entry_offset: entry point offset relative to the enclave base
> + * @exit_addr: address outside the enclave to exit on an exception or
> + * interrupt
> + * @fs_offset: offset relative to the enclave base to become FS
> + * segment inside the enclave
> + * @gs_offset: offset relative to the enclave base to become GS
> + * segment inside the enclave
> + * @fs_limit: size to become a new FS-limit (only 32-bit enclaves)
> + * @gs_limit: size to become a new GS-limit (only 32-bit enclaves)
> + *
> + * Thread Control Structure (TCS) is an enclave page visible in its address
> + * space that defines an entry point inside the enclave. A thread enters inside
> + * an enclave by supplying address of TCS to ENCLU(EENTER). A TCS can be entered
> + * by only one thread at a time.
> + */
> +struct sgx_tcs {
> + u64 state;
> + u64 flags;
> + u64 ssa_offset;
> + u32 ssa_index;
> + u32 nr_ssa_frames;
> + u64 entry_offset;
> + u64 exit_addr;
> + u64 fs_offset;
> + u64 gs_offset;
> + u32 fs_limit;
> + u32 gs_limit;
> + u8 reserved[SGX_TCS_RESERVED_SIZE];
> +} __packed;
> +
> +/**
> + * struct sgx_pageinfo - an enclave page descriptor
> + * @addr: address of the enclave page
> + * @contents: pointer to the page contents
> + * @metadata: pointer either to a SECINFO or PCMD instance
> + * @secs: address of the SECS page
> + */
> +struct sgx_pageinfo {
> + u64 addr;
> + u64 contents;
> + u64 metadata;
> + u64 secs;
> +} __packed __aligned(32);
> +
> +
> +/**
> + * enum sgx_page_type - bits in the SECINFO flags defining the page type
> + * %SGX_PAGE_TYPE_SECS: a SECS page
> + * %SGX_PAGE_TYPE_TCS: a TCS page
> + * %SGX_PAGE_TYPE_REG: a regular page
> + * %SGX_PAGE_TYPE_VA: a VA page
> + * %SGX_PAGE_TYPE_TRIM: a page in trimmed state
> + */
> +enum sgx_page_type {
> + SGX_PAGE_TYPE_SECS,
> + SGX_PAGE_TYPE_TCS,
> + SGX_PAGE_TYPE_REG,
> + SGX_PAGE_TYPE_VA,
> + SGX_PAGE_TYPE_TRIM,
> +};
> +
> +#define SGX_NR_PAGE_TYPES 5
> +#define SGX_PAGE_TYPE_MASK GENMASK(7, 0)
> +
> +/**
> + * enum sgx_secinfo_flags - the flags field in &struct sgx_secinfo
> + * %SGX_SECINFO_R: allow read
> + * %SGX_SECINFO_W: allow write
> + * %SGX_SECINFO_X: allow execution
> + * %SGX_SECINFO_SECS: a SECS page
> + * %SGX_SECINFO_TCS: a TCS page
> + * %SGX_SECINFO_REG: a regular page
> + * %SGX_SECINFO_VA: a VA page
> + * %SGX_SECINFO_TRIM: a page in trimmed state
> + */
> +enum sgx_secinfo_flags {
> + SGX_SECINFO_R = BIT(0),
> + SGX_SECINFO_W = BIT(1),
> + SGX_SECINFO_X = BIT(2),
> + SGX_SECINFO_SECS = (SGX_PAGE_TYPE_SECS << 8),
> + SGX_SECINFO_TCS = (SGX_PAGE_TYPE_TCS << 8),
> + SGX_SECINFO_REG = (SGX_PAGE_TYPE_REG << 8),
> + SGX_SECINFO_VA = (SGX_PAGE_TYPE_VA << 8),
> + SGX_SECINFO_TRIM = (SGX_PAGE_TYPE_TRIM << 8),
> +};
> +
> +#define SGX_SECINFO_PERMISSION_MASK GENMASK_ULL(2, 0)
> +#define SGX_SECINFO_PAGE_TYPE_MASK (SGX_PAGE_TYPE_MASK << 8)
> +#define SGX_SECINFO_RESERVED_MASK ~(SGX_SECINFO_PERMISSION_MASK | \
> + SGX_SECINFO_PAGE_TYPE_MASK)
> +
> +/**
> + * struct sgx_secinfo - describes attributes of an EPC page
> + * @flags: permissions and type
> + *
> + * Used together with ENCLS leaves that add or modify an EPC page to an
> + * enclave to define page permissions and type.
> + */
> +struct sgx_secinfo {
> + u64 flags;
> + u8 reserved[56];
> +} __packed __aligned(64);
> +
> +#define SGX_PCMD_RESERVED_SIZE 40
> +
> +/**
> + * struct sgx_pcmd - Paging Crypto Metadata (PCMD)
> + * @enclave_id: enclave identifier
> + * @mac: MAC over PCMD, page contents and isvsvn
> + *
> + * PCMD is stored for every swapped page to the regular memory. When ELDU loads
> + * the page back it recalculates the MAC by using a isvsvn number stored in a
> + * VA page. Together these two structures bring integrity and rollback
> + * protection.
> + */
> +struct sgx_pcmd {
> + struct sgx_secinfo secinfo;
> + u64 enclave_id;
> + u8 reserved[SGX_PCMD_RESERVED_SIZE];
> + u8 mac[16];
> +} __packed __aligned(128);
> +
> +#define SGX_SIGSTRUCT_RESERVED1_SIZE 84
> +#define SGX_SIGSTRUCT_RESERVED2_SIZE 20
> +#define SGX_SIGSTRUCT_RESERVED3_SIZE 32
> +#define SGX_SIGSTRUCT_RESERVED4_SIZE 12
> +
> +/**
> + * struct sgx_sigstruct_header - defines author of the enclave
> + * @header1: constant byte string
> + * @vendor: must be either 0x0000 or 0x8086
> + * @date: YYYYMMDD in BCD
> + * @header2: costant byte string
> + * @swdefined: software defined value
> + */
> +struct sgx_sigstruct_header {
> + u64 header1[2];
> + u32 vendor;
> + u32 date;
> + u64 header2[2];
> + u32 swdefined;
> + u8 reserved1[84];
> +} __packed;
> +
> +/**
> + * struct sgx_sigstruct_body - defines contents of the enclave
> + * @miscselect: additional information stored to an SSA frame
> + * @misc_mask: required miscselect in SECS
> + * @attributes: attributes for enclave
> + * @xfrm: XSave-Feature Request Mask (subset of XCR0)
> + * @attributes_mask: required attributes in SECS
> + * @xfrm_mask: required XFRM in SECS
> + * @mrenclave: SHA256-hash of the enclave contents
> + * @isvprodid: a user-defined value that is used in key derivation
> + * @isvsvn: a user-defined value that is used in key derivation
> + */
> +struct sgx_sigstruct_body {
> + u32 miscselect;
> + u32 misc_mask;
> + u8 reserved2[20];
> + u64 attributes;
> + u64 xfrm;
> + u64 attributes_mask;
> + u64 xfrm_mask;
> + u8 mrenclave[32];
> + u8 reserved3[32];
> + u16 isvprodid;
> + u16 isvsvn;
> +} __packed;
> +
> +/**
> + * struct sgx_sigstruct - an enclave signature
> + * @header: defines author of the enclave
> + * @modulus: the modulus of the public key
> + * @exponent: the exponent of the public key
> + * @signature: the signature calculated over the fields except modulus,
> + * @body: defines contents of the enclave
> + * @q1: a value used in RSA signature verification
> + * @q2: a value used in RSA signature verification
> + *
> + * Header and body are the parts that are actual signed. The remaining fields
> + * define the signature of the enclave.
> + */
> +struct sgx_sigstruct {
> + struct sgx_sigstruct_header header;
> + u8 modulus[SGX_MODULUS_SIZE];
> + u32 exponent;
> + u8 signature[SGX_MODULUS_SIZE];
> + struct sgx_sigstruct_body body;
> + u8 reserved4[12];
> + u8 q1[SGX_MODULUS_SIZE];
> + u8 q2[SGX_MODULUS_SIZE];
> +} __packed;
> +
> +#define SGX_LAUNCH_TOKEN_SIZE 304
> +
> +#endif /* _ASM_X86_SGX_ARCH_H */
> --
> 2.25.1