security: Add memory subfolder

Add files to introduce a memory clearing framework.
Introduce Kconfig PLATFORM_HAS_DRAM_CLEAR that is to be selected by
platforms, that are able to clear all DRAM.

Introduce Kconfig SECURITY_CLEAR_DRAM_ON_REGULAR_BOOT that is user
selectable to always clear DRAM on non S3 boot.

The function security_clear_dram_request tells the calling platform when
to wipe all DRAM. Will be extended by TEE frameworks.

Add Documentation for the new security API.

Change-Id: Ifba25bfdd1057049f5cbae8968501bd9be487110
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/31548
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
Reviewed-by: Christian Walter <christian.walter@9elements.com>

2 files changed, 45 insertions, 0 deletions

diff --git a/Documentation/security/index.md b/Documentation/security/index.md
index 9ad54866c2a5..379375b6168a 100644
--- a/Documentation/security/index.md
+++ b/Documentation/security/index.md
@@ -6,3 +6,4 @@ This section describes documentation about the security architecture of coreboot
 
 - [Verified Boot](vboot/index.md)
 - [Measured Boot](vboot/measured_boot.md)
+- [Memory clearing](memory_clearing.md)
diff --git a/Documentation/security/memory_clearing.md b/Documentation/security/memory_clearing.md
new file mode 100644
index 000000000000..3d985925d926
--- /dev/null
+++ b/Documentation/security/memory_clearing.md
@@ -0,0 +1,44 @@
+# Memory clearing
+
+The main memory on computer platforms in high security environments contains
+sensible data. On unexpected reboot the data might persist and could be
+read by a malicious application in the bootflow or userspace.
+
+In order to prevent leaking information from pre-reset, the boot firmware can
+clear the main system memory on boot, wiping all information.
+
+A common API indicates if the main memory has to be cleared. That could be
+on user request or by a Trusted Execution Environment indicating that secrets
+are in memory.
+
+As every platform has different bring-up mechanisms and memory-layouts, every
+The device must indicate support for memory clearing as part of the boot
+process.
+
+## Requirements
+
+1. The platform must clear all platform memory (DRAM) if requested
+2. Code that is placed in DRAM might be skipped (as workaround)
+3. Stack that is placed in DRAM might be skipped (as workaround)
+4. All DRAM is cleared with zeros
+
+## Implementation
+
+A platform that supports memory clearing selects Kconfig
+``PLATFORM_HAS_DRAM_CLEAR`` and calls
+
+```C
+bool security_clear_dram_request(void);
+```
+
+to detect if memory should be cleared.
+
+The memory is cleared in ramstage as part of `DEV_INIT` stage. It's possible to
+clear it earlier on some platforms, but on x86 MTRRs needs to be programmed
+first, which happens in `DEV_INIT`.
+
+Without MTRRs (and caches enabled) clearing memory takes multiple seconds.
+## Exceptions
+
+As some platforms place code and stack in DRAM (FSP1.0), the regions can be
+skipped.