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>

8 files changed, 136 insertions, 0 deletions

diff --git a/Documentation/security/index.md b/Documentation/security/index.md
index 9ad54866c2..379375b616 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 0000000000..3d985925d9
--- /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.
diff --git a/src/security/Kconfig b/src/security/Kconfig
index 6a334ac09c..8a1531a08d 100644
--- a/src/security/Kconfig
+++ b/src/security/Kconfig
@@ -14,3 +14,4 @@
 
 source "src/security/vboot/Kconfig"
 source "src/security/tpm/Kconfig"
+source "src/security/memory/Kconfig"
diff --git a/src/security/Makefile.inc b/src/security/Makefile.inc
index a940b82613..f62413e059 100644
--- a/src/security/Makefile.inc
+++ b/src/security/Makefile.inc
@@ -1,2 +1,3 @@
 subdirs-y += vboot
 subdirs-y += tpm
+subdirs-y += memory
diff --git a/src/security/memory/Kconfig b/src/security/memory/Kconfig
new file mode 100644
index 0000000000..5436119ba5
--- /dev/null
+++ b/src/security/memory/Kconfig
@@ -0,0 +1,34 @@
+## This file is part of the coreboot project.
+##
+## Copyright (C) 2019 Facebook Inc.
+## Copyright (C) 2019 9elements Agency GmbH
+##
+## This program is free software; you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation; version 2 of the License.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+
+menu "Memory initialization"
+
+config PLATFORM_HAS_DRAM_CLEAR
+	bool
+	default n
+	help
+	  Selected by platforms that support clearing all DRAM
+	  after DRAM initialization.
+
+config SECURITY_CLEAR_DRAM_ON_REGULAR_BOOT
+	depends on PLATFORM_HAS_DRAM_CLEAR
+	bool "Always clear all DRAM on regular boot"
+	help
+	  Always clear the DRAM after DRAM initialization regardless
+	  of additional security implementations in use.
+	  This increases boot time depending on the amount of DRAM
+	  installed.
+
+endmenu #Memory initialization
diff --git a/src/security/memory/Makefile.inc b/src/security/memory/Makefile.inc
new file mode 100644
index 0000000000..525c4dbb4d
--- /dev/null
+++ b/src/security/memory/Makefile.inc
@@ -0,0 +1,3 @@
+romstage-$(CONFIG_PLATFORM_HAS_DRAM_CLEAR) += memory.c
+postcar-$(CONFIG_PLATFORM_HAS_DRAM_CLEAR) += memory.c
+ramstage-$(CONFIG_PLATFORM_HAS_DRAM_CLEAR) += memory.c
diff --git a/src/security/memory/memory.c b/src/security/memory/memory.c
new file mode 100644
index 0000000000..14f28578b5
--- /dev/null
+++ b/src/security/memory/memory.c
@@ -0,0 +1,33 @@
+/*
+ * This file is part of the coreboot project.
+ *
+ * Copyright (C) 2019 9elements Agency GmbH
+ * Copyright (C) 2019 Facebook Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#include <stdint.h>
+#include "memory.h"
+
+/**
+ * To be called after DRAM init.
+ * Tells the caller if DRAM must be cleared as requested by the user,
+ * firmware or security framework.
+ */
+bool security_clear_dram_request(void)
+{
+	if (CONFIG(SECURITY_CLEAR_DRAM_ON_REGULAR_BOOT))
+		return true;
+
+	/* TODO: Add TEE environments here */
+
+	return false;
+}
diff --git a/src/security/memory/memory.h b/src/security/memory/memory.h
new file mode 100644
index 0000000000..ccb07d76ad
--- /dev/null
+++ b/src/security/memory/memory.h
@@ -0,0 +1,19 @@
+/*
+ * This file is part of the coreboot project.
+ *
+ * Copyright (C) 2019 9elements Agency GmbH
+ * Copyright (C) 2019 Facebook Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#include <stdint.h>
+
+bool security_clear_dram_request(void);