Documentation/power/swsusp-dmcrypt.rst

   1 =======================================
   2 How to use dm-crypt and swsusp together
   3 =======================================
   4
   5 Author: Andreas Steinmetz <ast@domdv.de>
   6
   7
   8
   9 Some prerequisites:
  10 You know how dm-crypt works. If not, visit the following web page:
  11 http://www.saout.de/misc/dm-crypt/
  12 You have read Documentation/power/swsusp.rst and understand it.
  13 You did read Documentation/admin-guide/initrd.rst and know how an initrd works.
  14 You know how to create or how to modify an initrd.
  15
  16 Now your system is properly set up, your disk is encrypted except for
  17 the swap device(s) and the boot partition which may contain a mini
  18 system for crypto setup and/or rescue purposes. You may even have
  19 an initrd that does your current crypto setup already.
  20
  21 At this point you want to encrypt your swap, too. Still you want to
  22 be able to suspend using swsusp. This, however, means that you
  23 have to be able to either enter a passphrase or that you read
  24 the key(s) from an external device like a pcmcia flash disk
  25 or an usb stick prior to resume. So you need an initrd, that sets
  26 up dm-crypt and then asks swsusp to resume from the encrypted
  27 swap device.
  28
  29 The most important thing is that you set up dm-crypt in such
  30 a way that the swap device you suspend to/resume from has
  31 always the same major/minor within the initrd as well as
  32 within your running system. The easiest way to achieve this is
  33 to always set up this swap device first with dmsetup, so that
  34 it will always look like the following::
  35
  36   brw-------  1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
  37
  38 Now set up your kernel to use /dev/mapper/swap0 as the default
  39 resume partition, so your kernel .config contains::
  40
  41   CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
  42
  43 Prepare your boot loader to use the initrd you will create or
  44 modify. For lilo the simplest setup looks like the following
  45 lines::
  46
  47   image=/boot/vmlinuz
  48   initrd=/boot/initrd.gz
  49   label=linux
  50   append="root=/dev/ram0 init=/linuxrc rw"
  51
  52 Finally you need to create or modify your initrd. Lets assume
  53 you create an initrd that reads the required dm-crypt setup
  54 from a pcmcia flash disk card. The card is formatted with an ext2
  55 fs which resides on /dev/hde1 when the card is inserted. The
  56 card contains at least the encrypted swap setup in a file
  57 named "swapkey". /etc/fstab of your initrd contains something
  58 like the following::
  59
  60   /dev/hda1   /mnt    ext3      ro                            0 0
  61   none        /proc   proc      defaults,noatime,nodiratime   0 0
  62   none        /sys    sysfs     defaults,noatime,nodiratime   0 0
  63
  64 /dev/hda1 contains an unencrypted mini system that sets up all
  65 of your crypto devices, again by reading the setup from the
  66 pcmcia flash disk. What follows now is a /linuxrc for your
  67 initrd that allows you to resume from encrypted swap and that
  68 continues boot with your mini system on /dev/hda1 if resume
  69 does not happen::
  70
  71   #!/bin/sh
  72   PATH=/sbin:/bin:/usr/sbin:/usr/bin
  73   mount /proc
  74   mount /sys
  75   mapped=0
  76   noresume=`grep -c noresume /proc/cmdline`
  77   if [ "$*" != "" ]
  78   then
  79     noresume=1
  80   fi
  81   dmesg -n 1
  82   /sbin/cardmgr -q
  83   for i in 1 2 3 4 5 6 7 8 9 0
  84   do
  85     if [ -f /proc/ide/hde/media ]
  86     then
  87       usleep 500000
  88       mount -t ext2 -o ro /dev/hde1 /mnt
  89       if [ -f /mnt/swapkey ]
  90       then
  91         dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
  92       fi
  93       umount /mnt
  94       break
  95     fi
  96     usleep 500000
  97   done
  98   killproc /sbin/cardmgr
  99   dmesg -n 6
 100   if [ $mapped = 1 ]
 101   then
 102     if [ $noresume != 0 ]
 103     then
 104       mkswap /dev/mapper/swap0 > /dev/null 2>&1
 105     fi
 106     echo 254:0 > /sys/power/resume
 107     dmsetup remove swap0
 108   fi
 109   umount /sys
 110   mount /mnt
 111   umount /proc
 112   cd /mnt
 113   pivot_root . mnt
 114   mount /proc
 115   umount -l /mnt
 116   umount /proc
 117   exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
 118
 119 Please don't mind the weird loop above, busybox's msh doesn't know
 120 the let statement. Now, what is happening in the script?
 121 First we have to decide if we want to try to resume, or not.
 122 We will not resume if booting with "noresume" or any parameters
 123 for init like "single" or "emergency" as boot parameters.
 124
 125 Then we need to set up dmcrypt with the setup data from the
 126 pcmcia flash disk. If this succeeds we need to reset the swap
 127 device if we don't want to resume. The line "echo 254:0 > /sys/power/resume"
 128 then attempts to resume from the first device mapper device.
 129 Note that it is important to set the device in /sys/power/resume,
 130 regardless if resuming or not, otherwise later suspend will fail.
 131 If resume starts, script execution terminates here.
 132
 133 Otherwise we just remove the encrypted swap device and leave it to the
 134 mini system on /dev/hda1 to set the whole crypto up (it is up to
 135 you to modify this to your taste).
 136
 137 What then follows is the well known process to change the root
 138 file system and continue booting from there. I prefer to unmount
 139 the initrd prior to continue booting but it is up to you to modify
 140 this.