{{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 during poweroff/reboot, utilizing the kernel's init_on_free mechanism. }} = Design = == cold-boot-attack-defense == Implemented by dracut module {{Github_link|repo=ram-wipe|path=/tree/master/usr/lib/dracut/modules.d/|text=cold-boot-attack-defense}} (by [[ram-wipe]]). # /usr/lib/dracut/modules.d/90crypt/cryptroot-ask.sh runs need_shutdown. # [https://github.com/dracut-ng/dracut-ng/pull/293 dracut-ng dm-shutdown.sh runs cryptsetup close to release the full disk encryption key during the shutdown process.] # A dracut cleanup hook is declared in {{Github_link|repo=ram-wipe|path=/blob/master/usr/lib/dracut/modules.d/40cold-boot-attack-defense/module-setup.sh|text=/usr/lib/dracut/modules.d/40cold-boot-attack-defense/module-setup.sh}} (by ram-wipe): inst_hook cleanup 80 "$moddir/wipe-ram-needshutdown.sh". Priority is 80. TODO # During boot, that dracut cleanup hook {{Github_link|repo=ram-wipe|path=/blob/master/usr/lib/dracut/modules.d/40cold-boot-attack-defense/wipe-ram-needshutdown.sh|text=/usr/lib/dracut/modules.d/40cold-boot-attack-defense/wipe-ram-needshutdown.sh}} (by ram-wipe) is calling dracut API function need_shutdown which results in file /run/initramfs/.need_shutdown being created. # As a result, at shutdown time when /lib/systemd/system/dracut-shutdown.service (by dracut) runs, /usr/lib/dracut/dracut-initramfs-restore (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 shutdown module (by dracut) will source 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. # {{Github_link|repo=ram-wipe|path=/blob/master/usr/lib/dracut/modules.d/40cold-boot-attack-defense/wipe-ram.sh|text=wipe-ram.sh}} (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 wipe-ram.sh dracut shutdown hook is executed. # The shutdown hook runs: * echo 3 > /proc/sys/vm/drop_caches ** To ensure any remaining disk cache is erased by Linux's memory poisoning. Inspired by Tails. https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/lib/initramfs-pre-shutdown-hook * dmsetup ls --target crypt: 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]:
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 init_on_free=1.
Additional kernel parameters shared with the [https://tails.net/contribute/design/kernel_hardening/ Tails kernel hardening setup] are implemented in the [[security-misc]] file {{Github_link|repo=security-misc|path=/blob/master/etc/default/grub.d/40_kernel_hardening.cfg|text=/etc/default/grub.d/40_kernel_hardening.cfg}}: * disabling merging of slabs with similar size (slab_nomerge) * passing FZ to slab_debug * enabling the kernel page allocator to randomize free lists (page_alloc.shuffle=1) * disabling vsyscalls (superseded by vDSO) (vsyscall=none) * causing kernel panic on unhandled exceptions (mce=0) The kernel parameter wiperam=skip 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 ram-wipe-exit: * The other dracut module cold-boot-attack-defense is independent. ** The cold-boot-attack-defense module, in its main source code file wipe-ram.sh, relies on dropping the remaining disk caches, ensuring that encrypted disks have been unmounted and using the kernel's init_on_free mechanism. {{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 initramfs-tools * Based on systemd-shutdown /lib/systemd/system-shutdown * 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 /usr/local/lib/initramfs-restore] / /usr/local/lib/udev-watchdog-wrapper * 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 [https://lore.kernel.org/kernel-hardening/20190626121943.131390-1-glider@google.com/ init_on_free mechanism] * Requires dracut * More generic * Should work on any Debian * Should be relatively easy to port to any Linux distribution since it is implemented as a dracut 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 echo messages even after the VM has already been powered off or rebooted. * In Kicksecure / Whonix, the package [https://github.com/{{project_name_short}}/debug-misc debug-misc] might be useful (sudo apt update && sudo apt install debug-misc) due to: ** {{Github_link|repo=debug-misc|path=/blob/master/etc/default/grub.d/45_debug-misc.cfg}} ** {{Github_link|repo=debug-misc|path=/blob/master/etc/sysctl.d/40_debug-misc.conf}} ** {{Github_link|repo=debug-misc|path=/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.) Maybe useful during development: * grep -r pre-udev --color /usr/lib/dracut 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 initramfs-tools is not planned by the authors of [[ram-wipe]]. No progress on initramfs-tools support should be expected. The problem with initramfs-tools support is that, in contrast to dracut, while initramfs-tools supports initrd (initial ramdisk), it does not support exitrd (exit ramdisk). dracut supports both initrd (initial ramdisk at boot time) as well as exitrd (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 initramfs-tools support to [[ram-wipe]] should first add exitrd support to upstream, original initramfs-tools. 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 initramfs-restore], which might be helpful to examine and use as inspiration when developing exitrd functionality for initramfs-tools. The Tails initramfs-tools exitrd 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 initramfs-tools developers for inclusion into the upstream source code. However, using the Tails implementation as a starting point is not a strict requirement. Once initramfs-tools gains exitrd support, it might then be straightforward to add initramfs-tools support to [[ram-wipe]]. = Development TODO = * [[Ram-wipe#ram-wipe_Known_Issues|ram-wipe known issues]] require fixing. = 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. [https://github.com/QubesOS/qubes-issues/issues/1562 Wipe RAM on shutdown #1562] '''2.''' Install ram-wipe. ram-wipe 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. = ram-wipe Functionality Testing = Done. * {{check-yes}} [https://github.com/zarhus/ram-dump-efi ram-dump-efi] - Minimalistic application to dump RAM from EFI, based on Dasharo [https://github.com/Dasharo/ram-remanence-tester ram-remanence-tester] {{check-yes}} * {{check-yes}} https://beta.blog.3mdeb.com/2025/2025-08-12-ram-wipe-further-analysis/ {{check-yes}} = ram-wipe improvements = * {{check-yes}} sdmem 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 sdmem gets OOM-killed is not a robust design. We should either replace sdmem or drop it entirely. It seems feasible to drop it. Done. sdmem no longer required. Removed: https://github.com/Kicksecure/ram-wipe/pull/4 {{check-yes}} * {{check-yes}} Review how Tails handles memory erasure: [https://tails.net/contribute/design/memory_erasure/ Tails memory erasure design]. They primarily rely on the kernel parameter init_on_free=1. Done. Testing was done by 3MDEB: https://beta.blog.3mdeb.com/2025/2025-08-12-ram-wipe-further-analysis/ {{check-yes}} * {{check-yes}} 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. Done. (No longer necessary. Removed.) {{check-yes}} * {{check-yes}} All we might need to do is: Done. {{check-yes}} ** {{check-yes}} Set init_on_free=1 (currently only set in security-misc, but it should be set in ram-wipe to make it standalone). Done. {{check-yes}} ** {{check-yes}} Drop caches (already implemented). Done. {{check-yes}} ** {{check-yes}} Properly unmount all encrypted disks (already done due to fixes in dracut in Debian Trixie). Done. {{check-yes}} ** {{check-yes}} Drop back to initrd (already implemented). Done. {{check-yes}} ** {{check-yes}} Re-test. Done. {{check-yes}} = 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|ram-wipe User Documentation]] * {{Github_link|repo=ram-wipe|path=}} * https://github.com/memtest86plus/memtest86plus/discussions/266 = Footnotes= {{Footer}} [[Category: Design]] [[Category: Development]]