Adding debian version 2:2.3.7-1+deb11u1.debian/2%2.3.7-1+deb11u1debian

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 637 insertions, 0 deletions

diff --git a/debian/doc/pandoc/encrypted-boot.md b/debian/doc/pandoc/encrypted-boot.md
new file mode 100644
index 0000000..52db07f
--- /dev/null
+++ b/debian/doc/pandoc/encrypted-boot.md
@@ -0,0 +1,536 @@
+% Full disk encryption, including `/boot`: Unlocking LUKS devices from GRUB
+
+Introduction
+============
+
+So called “full disk encryption” is often a misnomer, because there is
+typically a separate plaintext partition holding `/boot`.  For instance
+the Debian Installer does this in its “encrypted LVM” partitioning method.
+Since not all bootloaders are able to unlock LUKS devices, a plaintext
+`/boot` is the only solution that works for all of them.
+
+However, GRUB2 is (since Jessie) able to unlock LUKS devices with its
+[`cryptomount`](https://www.gnu.org/software/grub/manual/grub/html_node/cryptomount.html)
+command, which therefore enables encryption of the `/boot` partition as
+well: using that feature reduces the amount of plaintext data written to
+disk.  It is especially interesting when GRUB is installed to a read-only
+media, for instance as [coreboot payload](https://doc.coreboot.org/payloads.html#grub2)
+flashed to a write-protected chip.  On the other hand, it is *incompatible*
+with some other features that only enabled later at initramfs stage, such
+as slash screens or remote unlocking.
+
+Since enabling unlocking LUKS devices from GRUB [isn't exposed to the d-i
+interface](https://bugs.debian.org/814798) (as of Buster), people have
+come up with various custom workarounds.  But as of Buster [`cryptsetup`(8)]
+defaults to a new [LUKS header format version](https://gitlab.com/cryptsetup/LUKS2-docs),
+which isn't supported by GRUB as of 2.04.  **Hence the pre-Buster
+workarounds won't work anymore**.  Until LUKS *version 2* support is
+[added to GRUB2](https://savannah.gnu.org/bugs/?55093), the device(s)
+holding `/boot` needs to be in *LUKS format version 1* to be unlocked from
+the boot loader.
+
+This document describes a generic way to unlock LUKS devices from GRUB
+for Debian Buster.
+
+
+Encrypting the device holding `/boot`
+=====================================
+
+There are two alternatives here:
+
+  * Either format an existing `/boot` partition to LUKS1; or
+  * Move `/boot` to the root file system.  The root device(s) needs to
+    use LUKS version 1, but existing LUKS2 devices can be *converted*
+    (in-place) to LUKS1.
+
+These two alternatives are described in the two following sub-sections.
+
+We assume the system resides on a single drive `/dev/sda`, partitioned
+with d-i's “encrypted LVM” scheme:
+
+    root@debian:~# lsblk -o NAME,FSTYPE,MOUNTPOINT /dev/sda
+    NAME                    FSTYPE      MOUNTPOINT
+    sda
+    ├─sda1                  ext2        /boot
+    ├─sda2
+    └─sda5                  crypto_LUKS
+      └─sda5_crypt          LVM2_member
+        ├─debian--vg-root   ext4        /
+        └─debian--vg-swap_1 swap        [SWAP]
+
+*Note*: The partition layout of your system may differ.
+
+
+Formatting the existing `/boot` partition to LUKS1
+--------------------------------------------------
+
+Since the installer creates a separate (plaintext) `/boot` partition by
+default in its “encrypted LVM” partitioning method, the simplest
+solution is arguably to re-format it as LUKS1, especially if the root
+device is in LUKS2 format.
+
+That way other partitions, including the one holding the root file
+system, can remain in LUKS2 format and benefit from the *stronger
+security guaranties* and *convenience features* of the newer version:
+more secure (memory-hard) Key Derivation Function, backup header,
+ability to offload the volume key to the kernel keyring (thus preventing
+access from userspace), custom sector size, persistent flags, unattended
+unlocking via kernel keyring tokens, etc.
+
+Furthermore every command in this sub-section can be run from the main
+system: no need to reboot into a live CD or an initramfs shell.
+
+ 1. Before copying content of the `/boot` directory, remount it read-only
+    to make sure data is not modified while it's being copied.
+
+        root@debian:~# mount -oremount,ro /boot
+
+ 2. Archive the directory elsewhere (on another device), and unmount it
+    afterwards.
+
+        root@debian:~# install -m0600 /dev/null /tmp/boot.tar
+    <!-- -->
+        root@debian:~# tar -C /boot --acls --xattrs --one-file-system -cf /tmp/boot.tar .
+    <!-- -->
+        root@debian:~# umount /boot
+
+    (If `/boot` has sub-mountpoints, like `/boot/efi`, you'll need to
+    unmount them as well.)
+
+ 3. Optionally, wipe out the underlying block device (assumed to be
+    `/dev/sda1` in the rest of this sub-section).
+
+        root@debian:~# dd if=/dev/urandom of=/dev/sda1 bs=1M status=none
+        dd: error writing '/dev/sda1': No space left on device
+
+ 4. Format the underlying block device to LUKS1.  (Note the `--type luks1`
+    in the command below, as Buster's [`cryptsetup`(8)] defaults to LUKS
+    version 2 for `luksFormat`.)
+
+        root@debian:~# cryptsetup luksFormat --type luks1 /dev/sda1
+
+        WARNING!
+        ========
+        This will overwrite data on /dev/sda1 irrevocably.
+
+        Are you sure? (Type uppercase yes): YES
+        Enter passphrase for /dev/sda1:
+        Verify passphrase:
+
+ 5. Add a corresponding entry to [`crypttab`(5)] with mapped device name
+    `boot_crypt`, and open it afterwards.
+
+        root@debian:~# uuid="$(blkid -o value -s UUID /dev/sda1)"
+    <!-- -->
+        root@debian:~# echo "boot_crypt UUID=$uuid none luks" | tee -a /etc/crypttab
+    <!-- -->
+        root@debian:~# cryptdisks_start boot_crypt
+        Starting crypto disk...boot_crypt (starting)...
+        Please unlock disk boot_crypt:  ********
+        boot_crypt (started)...done.
+
+ 6. Create a file system on the mapped device.  Assuming source device for
+    `/boot` is specified by its UUID in the [`fstab`(5)] -- which the
+    Debian Installer does by default -- reusing the old UUID avoids
+    editing the file.
+
+        root@debian:~# grep /boot /etc/fstab
+        # /boot was on /dev/sda1 during installation
+        UUID=c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /boot           ext2    defaults        0       2
+    <!-- -->
+        root@debian:~# mkfs.ext2 -m0 -U c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /dev/mapper/boot_crypt
+        mke2fs 1.44.5 (15-Dec-2018)
+        Creating filesystem with 246784 1k blocks and 61752 inodes
+        Filesystem UUID: c104749f-a0fa-406c-9e9a-3fc01f8e2f78
+        […]
+
+ 7. Finally, mount `/boot` again from [`fstab`(5)], and copy the saved
+    tarball to the new (and now encrypted) file system.
+
+        root@debian:~# mount -v /boot
+        mount: /dev/mapper/boot_crypt mounted on /boot.
+    <!-- -->
+        root@debian:~# tar -C /boot --acls --xattrs -xf /tmp/boot.tar
+
+    (If `/boot` had sub-mountpoints, like `/boot/efi`, you'll need to
+    mount them back as well.)
+
+You can skip the next sub-section and go directly to [Enabling
+`cryptomount` in GRUB2].  Note that `init`(1) needs to unlock the
+`/boot` partition *again* during the boot process.  See [Avoiding the
+extra password prompt] for details and a proposed workaround.  (You'll
+need to substitute `/` resp. `sda5` with `/boot` resp. `sda1` in that
+section, however only steps 1-3 are relevant here: no need to copy the
+key file to the initramfs image since `/boot` can be unlocked and
+mounted later during the boot process.)
+
+
+Moving `/boot` to the root file system
+--------------------------------------
+
+The [previous sub-section][Formatting the existing `/boot` partition to LUKS1]
+described how to to re-format the `/boot` partition as LUKS1.
+Alternatively, it can be moved to the root file system, assuming the
+latter is not held by any LUKS2 device.  (As shown below, LUKS2 devices
+created with default parameters can be “downgraded” to LUKS1.)
+
+The advantage of this method is that the original `/boot` partition can
+be preserved and used in case of *disaster recovery* (if for some reason
+the GRUB image is lacking the `cryptodisk` module and the original
+plaintext `/boot` partition is lost, you'd need to reboot into a live CD
+to recover).  Moreover increasing the number of partitions *increases
+usage pattern visibility*: a separate `/boot` partition, even encrypted,
+will likely leak the fact that a kernel update took place to an attacker
+with access to both pre- and post-update snapshots.
+
+On the other hand, the downside of that method is that the root file
+system can't benefit from the nice LUKS2 improvements over LUKS1, some
+of which were listed above.  Another (minor) downside is that space
+occupied by the former `/boot` partition (typically 256MiB) becomes
+unused and can't easily be reclaimed by the root file system.
+
+### Downgrading LUKS2 to LUKS1 ###
+
+Check the LUKS format version on the root device (assumed to be
+`/dev/sda5` in the rest of this sub-section):
+
+    root@debian:~# cryptsetup luksDump /dev/sda5 | grep -A1 "^LUKS"
+    LUKS header information
+    Version:        2
+
+Here the LUKS format version is 2, so the device needs to be *converted*
+to LUKS *version 1* to be able to unlock from GRUB.  Unlike the rest of
+this document, conversion can't be done on an open device, so you'll
+need reboot into a live CD or an [initramfs shell].  (The `(initramfs)`
+prompt strings in this sub-section indicates commands that are executed
+from an initramfs shell.)  Also, if you have valuable data in the root
+partition, then *make sure you have a backup* (at least of the LUKS
+header)!
+
+[initramfs shell]: https://wiki.debian.org/InitramfsDebug#Rescue_shell_.28also_known_as_initramfs_shell.29
+
+Run `cryptsetup convert --type luks1 DEVICE` to downgrade.  However if
+the device was created with the default parameters then in-place
+conversion will fail:
+
+    (initramfs) cryptsetup convert --type luks1 /dev/sda5
+
+    WARNING!
+    ========
+    This operation will convert /dev/sda5 to LUKS1 format.
+
+
+    Are you sure? (Type uppercase yes): YES
+    Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible.
+
+This is because its first key slot uses Argon2 as Password-Based Key
+Derivation Function (PBKDF) algorithm:
+
+    (initramfs) cryptsetup luksDump /dev/sda5 | grep "PBKDF:"
+            PBKDF:      argon2i
+
+Argon2 is a *memory-hard* function that was selected as the winner of
+the Password-Hashing Competition; LUKS2 devices use it by default for
+key slots, but LUKS1's only supported PBKDF algorithm is PBKDF2.  Hence
+the key slot has to be converted to PBKDF2 prior to LUKS format version
+downgrade.
+
+    (initramfs) cryptsetup luksConvertKey --pbkdf pbkdf2 /dev/sda5
+    Enter passphrase for keyslot to be converted:
+
+Now that all key slots use the PBKDF2 algorithm, the device shouldn't
+have any LUKS2-only features left, and can be converted to LUKS1.
+
+    (initramfs) cryptsetup luksDump /dev/sda5 | grep "PBKDF:"
+            PBKDF:      pbkdf2
+<!-- -->
+    (initramfs) cryptsetup convert --type luks1 /dev/sda5
+
+    WARNING!
+    ========
+    This operation will convert /dev/sda5 to LUKS1 format.
+
+
+    Are you sure? (Type uppercase yes): YES
+<!-- -->
+    (initramfs) cryptsetup luksDump /dev/sda5 | grep -A1 "^LUKS"
+    LUKS header information
+
+### Moving `/boot` to the root file system ###
+
+(The moving operation can be done from the normal system.  No need to
+reboot into a live CD or an initramfs shell if the root file system
+resides in a LUK1 device.)
+
+ 1. To ensure data is not modified while it's being copied, remount
+    `/boot` read-only.
+
+        root@debian:~# mount -oremount,ro /boot
+
+ 2. Recursively copy the directory to the root file system, and replace
+    the old `/boot` mountpoint with the new directory.
+
+    <!-- -->
+        root@debian:~# cp -axT /boot /boot.tmp
+    <!-- -->
+        root@debian:~# umount /boot
+    <!-- -->
+        root@debian:~# rmdir /boot
+    <!-- -->
+        root@debian:~# mv -T /boot.tmp /boot
+
+    (If `/boot` has sub-mountpoints, like `/boot/efi`, you'll need to
+    unmount them first, and then remount them once `/boot` has been
+    moved to the root file system.)
+
+ 3. Comment out the [`fstab`(5)] entry for the `/boot` mountpoint.
+    Otherwise at reboot `init`(1) will mount it and therefore shadow data
+    in the new `/boot` directory with data from the old plaintext
+    partition.
+
+        root@debian:~# grep /boot /etc/fstab
+        ## /boot was on /dev/sda1 during installation
+        #UUID=c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /boot           ext2    defaults        0       2
+
+
+Enabling `cryptomount` in GRUB2
+===============================
+
+Enable the feature and update the GRUB image:
+
+    root@debian:~# echo "GRUB_ENABLE_CRYPTODISK=y" >>/etc/default/grub
+<!-- -->
+    root@debian:~# update-grub
+<!-- -->
+    root@debian:~# grub-install /dev/sda
+
+If everything went well, `/boot/grub/grub.cfg` should contain `insmod
+cryptodisk` (and also `insmod lvm` if `/boot` is on a Logical Volume).
+
+*Note*: The PBKDF parameters are determined via benchmark upon key slot
+creation (or update).  Thus they only makes sense if the environment in
+which the LUKS device is open matches (same CPU, same RAM size, etc.)
+the one in which it's been formatted.  Unlocking from GRUB does count as
+an environment mismatch, because GRUB operates under tighter memory
+constraints and doesn't take advantage of all crypto-related CPU
+instructions.  Concretely, that means unlocking a LUKS device from GRUB
+might take *a lot* longer than doing it from the normal system.  Since
+GRUB's LUKS implementation isn't able to benchmark, you'll need to do it
+manually.  It's easier for PBKDF2 as there is a single parameter to play
+with (iteration count) — while Argon2 has two (iteration count and
+memory) — and changing it affects the unlocking time linearly: for
+instance halving the iteration count would speed up unlocking by a
+factor of two.  (And of course, making low entropy passphrases twice as
+easy to brute-force.  There is a trade-off to be made here.  Balancing
+convenience and security is the whole point of running PBKDF
+benchmarks.)
+
+    root@debian:~# cryptsetup luksDump /dev/sda1 | grep -B1 "Iterations:"
+    Key Slot 0: ENABLED
+        Iterations:             1000000
+<!-- -->
+    root@debian:~# cryptsetup luksChangeKey --pbkdf-force-iterations 500000 /dev/sda1
+    Enter passphrase to be changed:
+    Enter new passphrase:
+    Verify passphrase:
+
+(You can reuse the existing passphrase in the above prompts.  Replace
+`/dev/sda1` with the LUKS1 volume holding `/boot`; in this document
+that's `/dev/sda1` if `/boot` resides on a separated encrypted
+partition, or `/dev/sda5` if `/boot` was moved to the root file system.)
+
+*Note*: `cryptomount` lacks an option to specify the key slot index to
+open.  All active key slots are tried sequentially until a match is
+found.  Running the PBKDF algorithm is a slow operation, so to speed up
+things you'll want the key slot to unlock at GRUB stage to be the first
+active one.  Run the following command to discover its index.
+
+    root@debian:~# cryptsetup luksOpen --test-passphrase --verbose /dev/sda5
+    Enter passphrase for /dev/sda5:
+    Key slot 0 unlocked.
+    Command successful.
+
+
+Avoiding the extra password prompt
+==================================
+
+The device holding the kernel (and the initramfs image) is unlocked by
+GRUB, but the root device needs to be *unlocked again* at initramfs
+stage, regardless whether it's the same device or not.  This is because
+GRUB boots with the given `vmlinuz` and initramfs images, but there is
+currently no way to securely pass cryptographic material (or Device
+Mapper information) to the kernel.  Hence the Device Mapper table is
+initially empty at initramfs stage; in other words, all devices are
+locked, and the root device needs to be unlocked again.
+
+To avoid extra passphrase prompts at initramfs stage, a workaround is
+to *unlock via key files stored into the initramfs image*.  Since the
+initramfs image now resides on an encrypted device, this still provides
+protection for data at rest.  After all for LUK1 the volume key can
+already be found by userspace in the Device Mapper table, so one could
+argue that including key files to the initramfs image -- created with
+restrictive permissions -- doesn't change the threat model for LUKS1
+devices.  Please note however that for LUKS2 the volume key is normally
+*offloaded to the kernel keyring* (hence no longer readable by
+userspace), while key files lying on disk are of course readable by
+userspace.
+
+ 1. Generate the shared secret (here with 512 bits of entropy as it's also
+    the size of the volume key) inside a new file.
+
+        root@debian:~# mkdir -m0700 /etc/keys
+    <!-- -->
+        root@debian:~# ( umask 0077 && dd if=/dev/urandom bs=1 count=64 of=/etc/keys/root.key conv=excl,fsync )
+        64+0 records in
+        64+0 records out
+        64 bytes copied, 0.000698363 s, 91.6 kB/s
+
+ 2. Create a new key slot with that key file.
+
+        root@debian:~# cryptsetup luksAddKey /dev/sda5 /etc/keys/root.key
+        Enter any existing passphrase:
+    <!-- -->
+        root@debian:~# cryptsetup luksDump /dev/sda5 | grep "^Key Slot"
+        Key Slot 0: ENABLED
+        Key Slot 1: ENABLED
+        Key Slot 2: DISABLED
+        Key Slot 3: DISABLED
+        Key Slot 4: DISABLED
+        Key Slot 5: DISABLED
+        Key Slot 6: DISABLED
+        Key Slot 7: DISABLED
+
+ 3. Edit the [`crypttab`(5)] and set the third column to the key file path
+    for the root device entry.
+
+        root@debian:~# cat /etc/crypttab
+        root_crypt UUID=… /etc/keys/root.key luks,discard,key-slot=1
+
+    The unlock logic normally runs the PBKDF algorithm through each key
+    slot sequentially until a match is found.  Since the key file is
+    explicitly targeting the second key slot, its index is specified with
+    `key-slot=1` in the [`crypttab`(5)] to save useless expensive PBKDF
+    computations and *reduce boot time*.
+
+ 4. In `/etc/cryptsetup-initramfs/conf-hook`, set `KEYFILE_PATTERN` to a
+    `glob`(7) expanding to the key path names to include to the initramfs
+    image.
+
+        root@debian:~# echo "KEYFILE_PATTERN=\"/etc/keys/*.key\"" >>/etc/cryptsetup-initramfs/conf-hook
+
+ 5. In `/etc/initramfs-tools/initramfs.conf`, set `UMASK` to a restrictive
+    value to avoid leaking key material.  See [`initramfs.conf`(5)] for
+    details.
+
+        root@debian:~# echo UMASK=0077 >>/etc/initramfs-tools/initramfs.conf
+
+ 6. Finally re-generate the initramfs image, and double-check that it
+    1/ has restrictive permissions; and 2/ includes the key.
+
+        root@debian:~# update-initramfs -u
+        update-initramfs: Generating /boot/initrd.img-4.19.0-4-amd64
+    <!-- -->
+        root@debian:~# stat -L -c "%A  %n" /initrd.img
+        -rw-------  /initrd.img
+    <!-- -->
+        root@debian:~# lsinitramfs /initrd.img | grep "^cryptroot/keyfiles/"
+        cryptroot/keyfiles/root_crypt.key
+
+    (`cryptsetup-initramfs` normalises and renames key files inside the
+    initramfs, hence the new file name.)
+
+Should be safe to reboot now :-)  If all went well you should see a
+single passphrase prompt.
+
+
+Using a custom keyboard layout
+==============================
+
+GRUB uses the US keyboard layout by default.  Alternative layouts for
+the LUKS passphrase prompts can't be loaded from `/boot` or the root
+file system, as the underlying devices haven't been mapped yet at that
+stage.  If you require another layout to type in your passphrase, then
+you'll need to manually generate the core image using
+[`grub-mkimage`(1)].  A possible solution is to embed a memdisk
+containing the keymap inside the core image.
+
+ 1. Create a memdisk (in GNU tar format) with the desired keymap, for
+    instance dvorak's.  (The XKB keyboard layout and variant passed to
+    `grub-kbdcomp`(1) are described in the [`setxkbmap`(1)] manual.)
+
+        root@debian:~# memdisk="$(mktemp --tmpdir --directory)"
+    <!-- -->
+        root@debian:~# grub-kbdcomp -o "$memdisk/keymap.gkb" us dvorak
+    <!-- -->
+        root@debian:~# tar -C "$memdisk" -cf /boot/grub/memdisk.tar .
+
+ 2. Generate an early configuration file to embed inside the image.
+
+        root@debian:~# uuid="$(blkid -o value -s UUID /dev/sda1)"
+    <!-- -->
+        root@debian:~# cat >/etc/early-grub.cfg <<-EOF
+			terminal_input --append at_keyboard
+			keymap (memdisk)/keymap.gkb
+			cryptomount -u ${uuid//-/}
+
+			set root=(cryptouuid/${uuid//-/})
+			set prefix=/grub
+			configfile grub.cfg
+		EOF
+
+    *Note*: This is for the case of a separate `/boot` partition.  If
+    `/boot` resides on the root file system, then replace `/dev/sda1`
+    with `/dev/sda5` (the LUKS device holding the root file system) and
+    set `prefix=/boot/grub`; if it's in a logical volume you'll also
+    [need to set][GRUB device syntax] `root=(lvm/DMNAME)`.
+
+    *Note*: You might need to remove the first line if you use a USB
+    keyboard, or tweak it if GRUB doesn't see any PC/AT keyboard among its
+    available terminal input devices.  Start by specifing `terminal_input`
+    in an interactive GRUB shell in order to determine the suitable input
+    device.  (Choosing an incorrect device might prevent unlocking if no
+    input can be be entered.)
+
+ 3. Finally, manually create and install the GRUB image.  Don't use
+    `grub-install`(1) here, as we need to pass an early configuration
+    and a ramdisk.  Instead, use [`grub-mkimage`(1)] with suitable image
+    file name, format, and module list.
+
+        root@debian:~# grub-mkimage \
+            -c /etc/early-grub.cfg -m /boot/grub/memdisk.tar \
+            -o "$IMAGE" -O "$FORMAT" \
+            diskfilter cryptodisk luks gcry_rijndael gcry_sha256 \
+            memdisk tar keylayouts configfile \
+            at_keyboard usb_keyboard uhci ehci \
+            ahci part_msdos part_gpt lvm ext2
+
+    (Replace with `ahci` with a suitable module if the drive holding
+    `/boot` isn't a SATA drive supporting AHCI.  Also, replace `ext2`
+    with a file system driver suitable for `/boot` if the file system
+    isn't ext2, ext3 or ext4.)
+
+    The value of `IMAGE` and `FORMAT` depend on whether GRUB is in EFI
+    or BIOS mode.
+
+     a. For EFI mode: `IMAGE="/boot/efi/EFI/debian/grubx64.efi"` and
+        `FORMAT="x86_64-efi"`.
+
+     b. For BIOS mode: `IMAGE="/boot/grub/i386-pc/core.img"`,
+        `FORMAT="i386-pc"` and set up the image as follows:
+
+            root@debian:~# grub-bios-setup -d /boot/grub/i386-pc /dev/sda
+
+    You can now delete the memdisk and the early GRUB configuration
+    file, but note that subquent runs of `grub-install`(1) will override
+    these changes.
+
+
+[`cryptsetup`(8)]: https://manpages.debian.org/cryptsetup.8.en.html
+[`crypttab`(5)]: https://manpages.debian.org/crypttab.5.en.html
+[`fstab`(5)]: https://manpages.debian.org/fstab.5.en.html
+[`initramfs.conf`(5)]: https://manpages.debian.org/initramfs.conf.5.en.html
+[`grub-mkimage`(1)]: https://manpages.debian.org/grub-mkimage.1.en.html
+[`setxkbmap`(1)]: https://manpages.debian.org/setxkbmap.1.en.html
+[GRUB device syntax]: https://www.gnu.org/software/grub/manual/grub/grub.html#Device-syntax
+
+ -- Guilhem Moulin <guilhem@debian.org>, Sun, 09 Jun 2019 16:35:20 +0200
diff --git a/debian/doc/pandoc/index.md b/debian/doc/pandoc/index.md
new file mode 100644
index 0000000..bd750c4
--- /dev/null
+++ b/debian/doc/pandoc/index.md
@@ -0,0 +1,24 @@
+Cryptsetup for Debian
+=====================
+
+The main documentation:
+
+* [Debian Cryptsetup README](README.Debian.html)
+* [Debian Cryptsetup Debugging README](README.debug.html)
+* [Cryptsetup Initramfs intregration README](README.initramfs.html)
+
+Detailed documentation of specific setups:
+
+* [Debian encrypted boot documentation](encrypted-boot.html)
+
+Documentation of some particular keyscripts:
+
+* [Cryptsetup GnuPG keyscript README](README.gnupg.html)
+* [Cryptsetup GnuPG smartcard keyscript README](README.gnupg-sc.html)
+* [Cryptsetup keyctl keyscript README](README.keyctl.html)
+* [Cryptsetup smartcard keyscript README](README.opensc.html)
+
+
+**Please note**: Some of the documentation might be outdated. We
+recommend to look at the date of the page footer. It gives an idea
+about when the docs last got written and/or updated.
diff --git a/debian/doc/pandoc/pandoc.css b/debian/doc/pandoc/pandoc.css
new file mode 100644
index 0000000..bb66ac5
--- /dev/null
+++ b/debian/doc/pandoc/pandoc.css
@@ -0,0 +1,77 @@
+body {
+    margin: auto;
+    padding-right: 1em;
+    padding-left: 1em;
+    margin-left: 2em;
+    border-left: 1px solid black;
+    color: black;
+    font-size: 100%;
+    line-height: 140%;
+    color: #333;
+}
+
+pre {
+    border: 1px dotted gray;
+    background-color: #ececec;
+    color: #1111111;
+    padding: 0.5em;
+    line-height: 1.42857143;
+    tab-size: 4;
+    -moz-tab-size: 4;
+}
+
+code {
+    font-family: monospace;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a {
+    text-decoration: none;
+    color: #7a5ada;
+}
+h1, h2, h3, h4, h5 {
+    font-family: sans-serif;
+    font-weight: bold;
+    text-decoration: underline;
+    color: #7a5ada;
+}
+h1 {
+    font-size: 130%;
+}
+h2 {
+    font-size: 110%;
+}
+h3 {
+    font-size: 95%;
+}
+h4 {
+    font-size: 90%;
+    font-style: italic;
+}
+h5 {
+    font-size: 90%;
+    font-style: italic;
+}
+h1.title {
+    font-size: 200%;
+    font-weight: bold;
+    padding-top: 0.2em;
+    padding-bottom: 0.2em;
+    text-align: left;
+    border: none;
+}
+
+dt code {
+    font-weight: bold;
+}
+dd p {
+    margin-top: 0;
+}
+
+#TOC {
+    float: right;
+    width: 40%;
+    background: #eee;
+    font-size: 0.8em;
+    padding: 1em 2em;
+    margin: 0.0 0.5em 0.5em;
+}