What does LUKS header contain?

Question

What is contained inside the LUKS header? I know, the header has size of 2MB. Also, cryptsetup supports "detached header", where the header can be stored in a separate file.

Thus, for example, I can format luks device and specify detached header in a separate file:

dd if=/dev/zero of=LUKS-HEADER bs=1M count=2
cryptsetup luksFormat /dev/sdb1 --header LUKS-HEADER --align-payload=0

IIUC, this format operation only writes to the header. The disk partition is not modified (I checked with md5sum). So why does cryptsetyp luksFormat require specifying the device (/dev/sdb1) ?

Can I share one header for multiple luks devices?

UPDATE

After further investigation, it seems to me that the first 4096 B of the header contain the header information, which is being printed with cryptsetup luksDump.

What is stored in the remaining part of the 2MB file is a mystery to me. It seems to be overwritten with random data (I filled it the with zeros initially, so I can see the difference). Also, the 2MB file is absolutely un-compressible. Further indication of random/encrypted data.

Can somebody please authoritatively explain what is contained in the 2 MB LUKS header?

refex · Answer 1 · 2020-03-16T11:16:19.747

13

I believe that the header results being 2MB large because of the Anti-Forensic splitter: the encrypted master key is splitted in several blocks to enhance the diffusion and make sure that it can be easily erased from the disk. In particular erasing one single stripe makes the entire encrypted mk irrecoverable.

https://web.archive.org/web/20160517044339/http://tomb.dyne.org/Luks_on_disk_format.pdf

here's LUKS2 specification: https://gitlab.com/cryptsetup/LUKS2-docs/blob/master/luks2_doc_wip.pdf

I wonder how one can extract the encrypted master key...

edited Mar 16 '20 at 11:16

answered Jan 07 '16 at 01:06

refex

351
3
11

3

+1 because that on disk format pdf is the most authoritative source possible on what the header contains. – forest Apr 05 '16 at 03:32
2

URL is gone. Archived: https://web.archive.org/web/20160517044339/http://tomb.dyne.org/Luks_on_disk_format.pdf – nyov Aug 28 '19 at 20:36
1

Can you please update your answer to include a link to the LUKS2 specification as well? This became the default in early 2019. https://gitlab.com/cryptsetup/LUKS2-docs/blob/master/luks2_doc_wip.pdf – Michael Altfield Mar 16 '20 at 00:49

score 12 · Answer 2 · edited May 22 '21 at 18:44

For your information, I can't answer "Authoritatively" because I am not the author/contributor of LUKS/cryptsetup/dmcrypt but a user. But my answers are following,

What does LUKS header contain?

According to The cryptsetup FAQ the layout of LUKS header is:

    +------------------------+----+----+----+----+----+----+----+----+-----------+
    |  Luks Partition Header | K0 | K1 | K2 | K3 | K4 | K5 | K6 | K7 | BULK DATA |
    +------------------------+----+----+----+----+----+----+----+----+-----------+
                                   Figure - 1

Where,

Luks Partition Header (PHDR) consists of the necessary information to decrypt/encrypt the luks device as followings,

    -------------------------------+-----------------------------
    |   Partition Header Contents  |      Output by luksDump    |
    -------------------------------+-----------------------------
    |  Magic Byte                  | LUKS                       |
    -------------------------------+-----------------------------
    | Luks version                 | 1                          |
    -------------------------------+-----------------------------
    | Cipher Name                  | serpent                    |
    -------------------------------+-----------------------------
    | Cipher Mode                  | xts-plain64                |
    -------------------------------+-----------------------------
    | Hash Type                    | whirpool                   |
    -------------------------------+-----------------------------
    | Payload offset               | 4096                       |
    -------------------------------+-----------------------------
    | Master Key Bits              | 512                        |
    -------------------------------+-----------------------------
    | Master Key Digest            | 8a 90 77 7e ...            |
    -------------------------------+-----------------------------
    | Master Key Salt              | ca f3 40 fc ...            |
    -------------------------------+-----------------------------
    | Master Key Digest Iteration  | 23250                      |
    -------------------------------+-----------------------------
    | Partition UUID               | 46927c7d-7f17-4312-...     |
    -------------------------------+-----------------------------
                              Table - 1

2nd portion of partition header (PHDR) consists of 8 key-slot descriptors i.e information about key-slot as following,

    ------------------------------+------------------------------
    | Key Descriptors             |      Output by luksDump     |
    +-----------------------------+------------------------------
    | Activation status           | Enabled                     |
    +-----------------------------+------------------------------
    | Iteration                   | 146285                      |
    +-----------------------------+------------------------------
    | Salt                        | 1e c1 94 24 36 4c 98..      |
    +-----------------------------+------------------------------
    | Key Material Offset         | 8                           |
    +-----------------------------+------------------------------
    | AF Stripes                  | 4000                        |
    ------------------------------+------------------------------
                             Table - 2

For your Information the above luks partition header information is what you get by executing luksDump command and it is about 4.0K in size.

From Figure-1 after the Luks Partition header, we can see the Key-slot sections begins which followed by 8 key-slots. Each key slot is approximate 128kiB in size. So for 8 key slots, we get 8 * 128 = 1024 KiB which is 1MiB or 1048576 bytes.

So far we get 4096 bytes from the partition header and 131072 bytes for key-slots which totaling 1048576 + 4096 = 1052672 bytes for default luks configuration. For the most common configuration aes-xts-plain it about 2MiB.

So you can say the size of the header depends on various elements like master key size, hashing size, encryption algorithm, hashing algorithm etc. But it is safe to considering 2MiB as luks header.

After the key slots, the bulk data starts. From the cryptsetup FAQ,

Due to 2MiB default alignment, start of the data area for cryptsetup 1.3 and later is at 2MiB, i.e. at 0x200000. For older versions, it is at 0x101000, i.e. at 1'052'672 bytes.

You can see in the following output that the bulk data / encrypted data starts from the offset 00200000

[root@arif tmp]# hexdump -C /dev/sda99 -s 0X1FFFa0 | head
001fffa0  31 62 33 33 66 30 30 20  72 20 5f 5f 6b 63 72 63  |1b33f00 r __kcrc|
001fffb0  74 61 62 5f 64 6d 61 6d  5f 61 6c 6c 6f 63 5f 63  |tab_dmam_alloc_c|
001fffc0  6f 68 65 72 65 6e 74 0a  66 66 66 66 66 66 66 66  |oherent.ffffffff|
001fffd0  38 31 62 33 33 66 30 38  20 72 20 5f 5f 6b 63 72  |81b33f08 r __kcr|
001fffe0  63 74 61 62 5f 64 6d 61  6d 5f 61 6c 6c 6f 63 5f  |ctab_dmam_alloc_|
001ffff0  6e 6f 6e 63 6f 68 65 72  65 6e 74 0a 66 66 66 66  |noncoherent.ffff|
00200000  89 8d 9f 65 56 c0 f9 07  65 d8 50 58 18 3a 67 31  |...eV...e.PX.:g1|
00200010  87 c7 7c 2e 4a 3e 40 78  08 10 2c e3 14 52 5f dc  |..|.J>@x..,..R_.|
00200020  c9 7e 1e d3 a1 4d 4f fd  4c 6c f8 fb f2 bd 46 48  |.~...MO.Ll....FH|
00200030  3f e9 f8 4b ef f7 1c 82  be 7e 91 e0 78 35 aa bb  |?..K.....~..x5..|

Why does cryptsetyp luksFormat require specifying the device (/dev/sdb1) ?

Because,

cryptsetup needs to specify luks Device as an argument
There might be several luks device/partition as I have six as following,

[arif@arif ~]$ lsblk
NAME                                       MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
sda                                          8:0    0 931.5G  0 disk  
├─sda1                                       8:1    0   1.9G  0 part  /boot/efi
├─sda2                                       8:2    0   953M  0 part  /boot
├─sda3                                       8:3    0 614.7G  0 part  
│ └─luks-d84cd751-7f17-4312-ed89-4dfbc33dec61
                                           253:0    0 614.7G  0 crypt 
│   ├─vg1-root                             253:2    0 139.7G  0 lvm   /
│   ├─vg1-usr                              253:3    0 186.3G  0 lvm   
│   │ └─luks-03833316-8f82-4a78-0fc4-85ed66ffccd5
                                           253:4    0 186.3G  0 crypt /usr
│   ├─vg1-home                             253:5    0 186.3G  0 lvm   
│   │ └─luks-65f51991-7437-460b-9a0b-e3851b32fdb4
                                           253:8    0 186.3G  0 crypt /home
│   ├─vg1-var                              253:6    0  93.1G  0 lvm   
│   │ └─luks-d1b24b22-53eb-477f-8259-0a22846d3edc
                                           253:9    0  93.1G  0 crypt /var
│   └─vg1-tmp                              253:7    0   9.3G  0 lvm   
│     └─luks-b69a98b8-e257-5ca7-80a4-21725a721f00
                                           253:10   0   9.3G  0 crypt /tmp
├─sda4                                       8:4    0    14G  0 part  
│ └─luks-9bbcad99-3532-4583-a428-c02b559fdf3c
                                           253:1    0    14G  0 crypt [SWAP]
└─sda5                                       8:5    0 300.1G  0 part  
  └─storage

So if you want to luksFormat you must have to mention a standard partition or existing luks Device.

Can I share one header for multiple luks devices ?

As far my knowledge goes, no you can't use header of a luks Device on a different luks device because the configuration(cipher type, key size etc.) could be different (if the configuration is same I strongly don't believe it would work).

score 7 · Answer 3 · answered Dec 29 '15 at 16:09

As taken from https://www.lisenet.com/2013/luks-add-keys-backup-and-restore-volume-header/, you can see that the cryptsetup luksDump command will explain the contents. One header should be able to be used against any number of devices.

# cryptsetup luksDump /dev/sdb2
LUKS header information for /dev/sdb2

Version:        1
Cipher name:    aes
Cipher mode:    cbc-essiv:sha256
Hash spec:      sha1
Payload offset: 4096
MK bits:        256
MK digest:      e5 88 07 f2 4b ce 79 21 85 34 f7 a6 e3 0b 6b b2 a7 b8 d5 a1
MK salt:        0c dd 95 3d 1e 30 1f 66 d4 5e 31 03 12 a0 61 29
                e5 ef 34 8e 13 5d 80 76 8b 4a 0a c3 55 02 22 d3
MK iterations:  5750
UUID:           e4971160-047b-49ce-8246-b63f1fb67db9

Key Slot 0: ENABLED
        Iterations:             23233
        Salt:                   ff bc fc 78 98 5d 35 50 97 76 37 b4 70 99 38 44
                                9f bd a1 b9 02 2d 4d 1d 18 b5 dc f6 4c a0 37 fc
        Key material offset:    8
        AF stripes:             4000
Key Slot 1: ENABLED
        Iterations:             23956
        Salt:                   3a a0 06 83 d3 e0 ba da b0 5c e2 56 cb ed 72 69
                                76 9a 8a b8 e1 eb e6 90 44 b3 71 7a 2f 96 80 39
        Key material offset:    264
        AF stripes:             4000
Key Slot 2: DISABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

why does it need 2MB space for such a small amount of information ? — Martin Vegter, Dec 29 '15 at 16:14
Some space is needed for the "anti-forensics" key striping over several disk blocks to make it easier to erase (in case a block gets reallocated by disk firmware, the original becomes impossible to erase) — user1686, Jan 02 '16 at 11:34

score 7 · Answer 4 · answered Jan 04 '16 at 18:37

I believe I have found the answer to your question. The header is made up of the header itself and a space for keyslots. The reason for this section behind the header to be 2MB is by default. Here is where I found the answer: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions

Look in section 2.4 on that page and at the end of that section you will find the excerpt below.

"the sector numbers get shifted by the length of the header and key-slots and there is a loss of that size in capacity (1MB+4096B for defaults and 2MB for the most commonly used non-default XTS mode)"

I hope this answers your question and the site listed above had a lot of other great questions answered.

score 1 · Answer 5 · answered Mar 16 '20 at 00:47

A lot of answers here only provided information about LUKS1 (released in 2004), so I thought I'd add a reference to LUKS2 (released in 2017).

The LUKS header necessarily contains unencrypted metadata as well as your one or more symmetrically encrypted "keyslots" containing your master key and salts necessary for decrypting the data on your LUKS volume.

In LUKS1, this data included the following fields:

magic
version
cipher-name
cipher-mode
hash-spec
payload-offset
key-bytes
mk-digest
mk-digest-salt
mk-digest-iter
uuid
key-slot-0
key-slot-1
key-slot-2
key-slot-3
key-slot-4
key-slot-5
key-slot-6
key-slot-7

The exact encoding and size of the above data fields are outlined in the original LUKS On-Disk Format Specification written by Clemens Fruhwirth in January 2005.

The header for LUKS2 is very different from LUKS1. The size is much more variable, the metadata is stored in the more extensible JSON format, and the number of keyslots is variable.

For more information on exactly what data is stored in the LUKS2 header and how, see the LUKS2 On-Disk Format Specification released by Milan Broz in August 2018.

What does LUKS header contain?

5 Answers5

Linked