{{Header}}
{{#seo:
|description=ram-wipe - Implementation notes.
|image=Ram-wipe-developer.png
}}
{{title|title=
Warm Boot Attack Defense - RAM Wipe Design Documentation
}}
{{fde-mininav}}
[[File:Ram-wipe-developer.png|200px|thumb|ram-wipe logo (development)]]
{{intro|
[[ram-wipe]] wipes the RAM twice during poweroff/reboot.

* '''1.''' RAM Wipe Pass 1/2: During Linux kernel poweroff/reboot sequences.
* '''2.''' RAM Wipe Pass 2/2: It kexec's into a new kernel and performs a second RAM wipe pass for the purpose of overwriting the first kernel's memory and any other leftovers in RAM.
}}
= Design =
== cold-boot-attack-defense ==
Implemented by dracut module [https://github.com/{{project_name_short}}/ram-wipe/tree/master/usr/lib/dracut/modules.d/ <code>cold-boot-attack-defense</code>] (by [[ram-wipe]]).

# <code>/usr/lib/dracut/modules.d/90crypt/cryptroot-ask.sh</code> runs <code>need_shutdown</code>.
# [https://github.com/dracut-ng/dracut-ng/pull/293 <code>dracut-ng</code> <code>dm-shutdown.sh</code> runs <code>cryptsetup close</code> to release the full disk encryption key during the shutdown process.]
# A dracut <code>cleanup</code> hook is declared in [https://github.com/{{project_name_short}}/ram-wipe/blob/master/usr/lib/dracut/modules.d/40cold-boot-attack-defense/module-setup.sh <code>/usr/lib/dracut/modules.d/40cold-boot-attack-defense/module-setup.sh</code>] (by ram-wipe): <code>inst_hook cleanup 80 "$moddir/wipe-ram-needshutdown.sh"</code>. Priority is <code>80</code>. TODO
# During boot, that dracut <code>cleanup</code> hook [https://github.com/{{project_name_short}}/ram-wipe/blob/master/usr/lib/dracut/modules.d/40cold-boot-attack-defense/wipe-ram-needshutdown.sh <code>/usr/lib/dracut/modules.d/40cold-boot-attack-defense/wipe-ram-needshutdown.sh</code>] (by ram-wipe) is calling dracut API function <code>need_shutdown</code> which results in file <code>/run/initramfs/.need_shutdown</code> being created.
# As a result, at shutdown time when <code>/lib/systemd/system/dracut-shutdown.service</code> (by dracut) runs, <code>/usr/lib/dracut/dracut-initramfs-restore</code> (by dracut) will restore the initramfs and pivot into it.
# During shutdown, dracut will run its usual cleanup tasks such as unmounting the root (main) drive.
# The <code>shutdown</code> module (by dracut) will <code>source</code> and execute other shutdown hooks set up by other dracut modules.
# At the time of writing, there were no other dracut modules using the dracut shutdown hook known to the author of this website.
# [https://github.com/{{project_name_short}}/ram-wipe/blob/master/usr/lib/dracut/modules.d/40cold-boot-attack-defense/wipe-ram.sh <code>wipe-ram.sh</code>] (by ram-wipe) is the dracut shutdown hook.
# An alternative description of the mechanism of dropping back to the initramfs during shutdown can be found under [https://systemd.io/INITRD_INTERFACE/ The initrd Interface of systemd].
# At a very late stage during the shutdown process, when all disks have already been unmounted by dracut, the <code>wipe-ram.sh</code> dracut shutdown hook is executed.
# The shutdown hook runs:

* <code>echo 3 > /proc/sys/vm/drop_caches</code>
** To ensure any remaining disk cache is erased by Linux's memory poisoning. <ref>Inspired by Tails.
https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/lib/initramfs-pre-shutdown-hook
</ref>
* <code>sdmem -l -l -v</code>: To wipe the RAM using <code>sdmem</code>.
** The parameters <code>-l -l</code> result in a single pass of RAM wiping using zeros.
*** This is optimized for speed. Otherwise, RAM wiping could take several minutes. However, the longer the shutdown process is delayed, the more likely users are to disable this feature. Also, after wiping the RAM, it could be more important to shut down to aid decay of RAM contents rather than repeatedly wiping RAM for minutes before removing power.
*** When run manually, <code>sdmem</code> with these command-line parameters will show "Wipe mode is insecure (one pass with 0x00)," but no evidence suggests this is actually insecure. The sdmem manpage refers to Peter Gutmann, but the Gutmann method is for hard drives, not RAM. No research indicating how many times RAM must be wiped to be unrecoverable has been found by the author of this website.
** The parameter <code>-v</code> is for verbose output, which provides only a progress indicator.
** Any output (default or verbose) is only visible if a [[Recovery#Serial_Console|serial console]] is connected. This is because dracut by default hides output of the commands it runs. Redirecting the output of <code>sdmem</code> to <code>/dev/kmsg</code> would result in hundreds or thousands of separate <code>*</code> characters being written to the console, each on its own line, which would not be helpful. For a better progress meter of the RAM wipe process, a buffer mechanism might have to be implemented after user feedback.
* <code>dmsetup ls --target crypt</code>: To check if all encrypted disks are unmounted.
** Only if all encrypted disks are unmounted will it be possible for the kernel to wipe the [[Full Disk Encryption]] (FDE) key from the kernel.
** Deletion of the FDE key is considered among the most crucial pieces of information to be wiped from RAM because if the FDE key can be recovered from RAM, then FDE can be compromised.
** Informs the user if all encrypted disks are unmounted in console output. Otherwise, it shows a warning.

Quote [https://tails.boum.org/contribute/design/memory_erasure/ Tails' Memory erasure]:

<blockquote>
First, most memory is erased at the end of a normal shutdown/reboot sequence. This is implemented by the [https://tails.boum.org/contribute/design/kernel_hardening/ Linux kernel's freed memory poisoning feature], more specifically:

* page_poison
* passing "P" to slub_debug
* zeroing heap memory at free time (init_on_free=1)
</blockquote>

These kernel parameters are implemented in the [[security-misc]] file [https://github.com/{{project_name_short}}/security-misc/blob/master/etc/default/grub.d/40_kernel_hardening.cfg <code>/etc/default/grub.d/40_kernel_hardening.cfg</code>].

The kernel parameter <code>wiperam=skip</code> is available to disable RAM wiping at shutdown, which can be useful to speed up shutdown or in case any issues arise.

For potential limitations, the same limitations described under the "Limitations" chapter of [https://tails.boum.org/contribute/design/memory_erasure/ Tails' Memory erasure] apply.

== ram-wipe-exit ==
dracut module <code>ram-wipe-exit</code>:

* The other dracut module <code>cold-boot-attack-defense</code> is independent.
** The first RAM wiping mechanism is useful regardless of this supplemental kexec-based RAM wipe, which might be more prone to bugs.
** The <code>cold-boot-attack-defense</code> module, in its main source code file <code>wipe-ram.sh</code>, uses <code>kexec</code> to boot into a new kernel.
** That new kernel is actually the same kernel image, but thanks to <code>kexec</code>, the old kernel stops and a new kernel runs.
** <code>kexec</code> is used with the <code>--reuse-cmdline</code> parameter for simplicity and to preserve already existing RAM wipe-related kernel parameters (the Linux kernel's freed memory poisoning feature mentioned above).
** Additionally, the kernel parameter <code>wiperamexit=1</code> is appended by the <code>cold-boot-attack-defense</code> module.
* The kernel parameter <code>wiperamexit=1</code> in the <code>ram-wipe-exit</code> module results in wiping the RAM and then rebooting or powering off.
* It does not mount the root image.
** In other words, <code>ram-wipe-exit</code> runs at a very early boot stage before mounting the root image. This is done using the dracut hook <code>pre-udev</code> (because that hook runs before <code>pre-mount</code>).
** Therefore, the full disk encryption (FDE) password entry is not required.
** The RAM wipe is performed during the dracut initramfs stage, before the FDE password is requested or the root disk is mounted.
** The root image is not mounted at all when the kernel parameter <code>wiperamexit=1</code> is set.
* When the kernel parameter <code>wiperamexit=1</code> is set, after the RAM wipe at the early dracut initramfs stage, the system is rebooted or powered off, depending on the <code>wiperamaction</code> setting, which was set by the previous kernel.
* A <code>kexec</code>-based wipe cannot rely on <code>systemd</code> with <code>Before=unmount.target</code> because unmounting the root disk and using <code>cryptsetup luksClose</code> to wipe the FDE key from RAM is one of the most critical steps of RAM wipe. It would require <code>After=unmount.target</code>, but at that point, no disks remain mounted with the necessary tools. Hence, dropping back to initramfs at shutdown is the correct design.
* Executes <code>reboot</code>, <code>poweroff</code>, or <code>halt</code> as instructed by the previous kernel.

{{Anchor|Differences of security-misc Wipe RAM versus Tails Memory Erasure}}

= Differences of ram-wipe versus Tails Memory Erasure =

Tails memory erasure:

* Based on Linux memory poisoning
* Requires <code>initramfs-tools</code>
* Based on <code>systemd-shutdown</code> <code>/lib/systemd/system-shutdown</code>
* Requires Tails-specific hook scripts such as [https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/lib/initramfs-restore <code>/usr/local/lib/initramfs-restore</code>] / <code>/usr/local/lib/udev-watchdog-wrapper</code>
* ISO-specific / Live boot-specific / squashfs-specific
** https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/lib/udev-watchdog-wrapper
** https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/lib/initramfs-pre-shutdown-hook
* Mixes the panic button / emergency shutdown / ISO removal trigger into the same scripts
* Blueprints:
** https://gitlab.tails.boum.org/tails/blueprints/-/wikis/more_efficient_memory_wipe
** https://gitlab.tails.boum.org/tails/blueprints/-/wikis/more_efficient_memory_wipe/grub
** https://gitlab.tails.boum.org/tails/blueprints/-/wikis/more_efficient_memory_wipe/memtest86plus

ram-wipe:

* Based on Linux memory poisoning, execution of <code>sdmem</code> and <code>kexec</code>
* Requires <code>dracut</code>
* More generic
* Should work on any Debian
* Should be relatively easy to port to any Linux distribution since it is implemented as a <code>dracut</code> module
* Should work equally for persistent boot from hard drive, [[grub-live|live boot from hard drive]], or ISO live boot
* A [https://forums.whonix.org/t/panic-button-panic-shutdown-buskill-the-usb-kill-cord-for-your-laptop/13755 panic button / panic shutdown / USB kill cord for your laptop] feature is not mixed with this feature. It should be implemented separately as a standalone feature.

= Debugging =

* A Kicksecure or Whonix VM using VirtualBox with a virtual [[Recovery#Serial_Console|serial console]] (<-- see this already existing, fully tested, and functional documentation on how to set that up), as this can display and persist <code>echo</code> messages even after the VM has already been powered off or rebooted.
* A boot menu entry to run the dracut module <code>ram-wipe-exit</code> without needing to power off or reboot (similar to [https://github.com/{{project_name_short}}/grub-live/blob/master/etc/grub.d/10_20_linux_live grub-live <code>10_20_linux_live</code>]). File: <code>/etc/grub.d/12_linux_wiperamexit</code>
* In Kicksecure / Whonix, the package [https://github.com/{{project_name_short}}/debug-misc debug-misc] might be useful (<code>sudo apt update && sudo apt install debug-misc</code>) due to:
** https://github.com/{{project_name_short}}/debug-misc/blob/master/etc/default/grub.d/45_debug-misc.cfg
** https://github.com/{{project_name_short}}/debug-misc/blob/master/etc/sysctl.d/40_debug-misc.conf
** https://github.com/{{project_name_short}}/debug-misc/blob/master/etc/dracut.conf.d/40_debug-misc.conf
** (These files can be used standalone, manually installed, or "bulk" installed by installing the debug-misc package.)

(This file would be shipped out commented by default. Only useful for development / debugging.)

<pre>
#!/bin/sh

## Copyright (C) 2022 - 2025 ENCRYPTED SUPPORT LLC <adrelanos@whonix.org>
## See the file COPYING for copying conditions.

## Untested!

set -e

#GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX wiperamexit=1 wiperamaction=reboot"
#GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX wiperamexit=1 wiperamaction=poweroff"
#GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX wiperamexit=1 wiperamaction=halt"

GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX wiperamexit=1 wiperamaction=debug"

export GRUB_CMDLINE_LINUX

if test -x /etc/grub.d/10_00_linux_dist ; then
	/etc/grub.d/10_00_linux_dist
fi
</pre>

<pre>
sudo update-grub
</pre>

Maybe useful during development:

* <code>grep -r pre-udev --color /usr/lib/dracut</code>

A [https://forums.whonix.org/t/panic-button-panic-shutdown-buskill-the-usb-kill-cord-for-your-laptop/13755 panic button / panic shutdown / USB kill cord for your laptop] feature is not integrated with this feature. It should be implemented separately as a standalone feature.

= Status of initramfs-tools Support =

Support for <code>initramfs-tools</code> is not planned by the authors of [[ram-wipe]]. No progress on <code>initramfs-tools</code> support should be expected.

The problem with <code>initramfs-tools</code> support is that, in contrast to <code>dracut</code>, while <code>initramfs-tools</code> supports <code>initrd</code> (initial ramdisk), it does not support <code>exitrd</code> (exit ramdisk).

<code>dracut</code> supports both <code>initrd</code> (initial ramdisk at boot time) as well as <code>exitrd</code> (dropping back to the initial ramdisk at shutdown time). A feature request has been posted against the [https://packages.debian.org/search?keywords=initramfs-tools Debian initramfs-tools] package: [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=778849 Support restoring initrd on shutdown and pivoting into it].

Contributors wishing to add <code>initramfs-tools</code> support to [[ram-wipe]] should first add <code>exitrd</code> support to upstream, original <code>initramfs-tools</code>.

As a starting point, Tails has implemented [https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/lib/initramfs-restore <code>initramfs-restore</code>], which might be helpful to examine and use as inspiration when developing <code>exitrd</code> functionality for <code>initramfs-tools</code>. The Tails <code>initramfs-tools</code> <code>exitrd</code> implementation would have to be made generic - meaning not specific to Tails (i.e., no code references to other Tails-specific code) - and made acceptable for the <code>initramfs-tools</code> developers for inclusion into the upstream source code. However, using the Tails implementation as a starting point is not a strict requirement.

Once <code>initramfs-tools</code> gains <code>exitrd</code> support, it might then be straightforward to add <code>initramfs-tools</code> support to [[ram-wipe]].

= Development TODO =

* Security testing: similar to https://gitlab.tails.boum.org/tails/blueprints/-/wikis/more_efficient_memory_wipe/memtest86plus
* A number of [[Ram-wipe#ram-wipe_Known_Issues|ram-wipe known issues]] require fixing.
* <s>SecureBoot breaks kexec</s> (Fixed.)

= ram-wipe Testing inside a VM =

'''1.''' Platform-specific notice.

* {{project_name_short}}: No special notice.
* Qubes OS: ram-wipe is unavailable for Qubes OS. <ref>
[https://github.com/QubesOS/qubes-issues/issues/1562 Wipe RAM on shutdown #1562]
</ref>

'''2.''' Install <code>ram-wipe</code>.

<code>ram-wipe</code> is not installed by default in VMs because it is usually not needed there, except for testing.

{{Install_Package|package=
ram-wipe
}}

'''3.''' Reboot

{{CodeSelect|code=
sudo reboot
}}

'''4.''' Set up a virtual serial console.

A virtual serial console helps to read all journal and kernel messages during early boot and shutdown.

Can be set up as per the [[Recovery#Serial_Console|serial console documentation]]. Only a read-only serial console was somewhat recently tested and should suffice. An interactive serial console might not be required.

'''5.''' Status.

Now a serial console should clearly show the output during boot and shutdown of ram-wipe.

'''6.''' Bug [https://github.com/dracutdevs/dracut/issues/1888 dracut should unmount the root encrypted disk `cryptsetup luksClose` during shutdown] (fixed in dracut-ng, should be fixed in Debian trixie) will not be reproducible because {{project_name_short}} VM images do not use full disk encryption. (The rationale for not using full disk encryption for VM images is documented on the [[Encrypted_Images|Encrypted VM Images]] wiki page.)

As a workaround, install Debian bookworm using the Debian DVD ([[Debian Tips]]), then install {{project_name_short}} as per the [[Debian|distribution morphing Debian into {{project_name_short}}]] instructions. Then re-apply the instructions listed here.

= ram-wipe Functionality Testing =
TODO:

* [https://github.com/zarhus/ram-dump-efi <code>ram-dump-efi</code>] - Minimalistic application to dump RAM from EFI, based on Dasharo [https://github.com/Dasharo/ram-remanence-tester <code>ram-remanence-tester</code>]

= ram-wipe improvements =

* <code>sdmem</code> is problematic: it is unmaintained upstream, and there has been at least one case where shutdown was blocked due to a "kernel locked up" error. Writing to RAM until it fills up and <code>sdmem</code> gets OOM-killed is not a robust design. We should either replace <code>sdmem</code> or drop it entirely. It seems feasible to drop it.
* Review how Tails handles memory erasure: [https://tails.net/contribute/design/memory_erasure/ Tails memory erasure design]. They primarily rely on the kernel parameter <code>init_on_free=1</code>.
* The second RAM wipe pass might be completely unnecessary. It can cause issues with graphics initialization during the second run due to buggy drivers. This makes reboot or shutdown slower and potentially glitchy.
* All we might need to do is:
** Set <code>init_on_free=1</code> (currently only set in <code>security-misc</code>, but it should be set in <code>ram-wipe</code> to make it standalone).
** Drop caches (already implemented).
** Properly unmount all encrypted disks (already done due to fixes in <code>dracut</code> in Debian Trixie).
** Drop back to <code>initrd</code> (already implemented).
** Re-test.

''Task:'' Please consider the above, test it, implement necessary changes, and update the source code and wiki accordingly.

= Forum Discussion =
https://forums.whonix.org/t/is-ram-wipe-possible-inside-whonix-cold-boot-attack-defense/5596

= See Also =
* [[Dev/RAM Wipe Old Notes|RAM Wipe Archived Development Notes]]
* [[Cold Boot Attack Defense]]
* [[ram-wipe|<code>ram-wipe</code> User Documentation]]
* https://github.com/{{project_name_short}}/ram-wipe
* https://github.com/memtest86plus/memtest86plus/discussions/266

= Footnotes=
<references/>

{{Footer}}

[[Category: Design]]
[[Category: Development]]