[dm-crypt] LUKS2 on disk format

[dm-crypt] LUKS2 on disk format

[Maksim Fomin]

After reading LUKS2 on-disk format specification, I have one main question - does LUKS2 data resides entirely on header, which occupies first 16 mib (at most) of block device? Is is safe to assume that there is no LUKS metadata somewhere in the middle or in the end of the drive?

Thanks.

Re: [dm-crypt] LUKS2 on disk format

[Milan Broz]

On 11/05/2020 21:07, Maksim Fomin wrote:
> After reading LUKS2 on-disk format specification, I have one main
> question - does LUKS2 data resides entirely on header, which occupies
> first 16 mib (at most) of block device?

Yes, all LUKS metadata are stored in th eLUKS heaer.
But the LUKS header size is configurable (it is not fixed to 16MB,
16MB is just the default size)
(And most of the area is reserved for keyslots, used in online reencryption.)

> Is is safe to assume that
> there is no LUKS metadata somewhere in the middle or in the end of
> the drive?

Yes. There is small exception if you use experimental integrity protection
(authenticated encryption) where dm-crypt is stacked over dm-integrity device.
Then there is dm-integrity superblock in the beginning of data area.
(But this superblovk contains only configuration of dm-integrity metadata;
no LUKS metadata are stored there.
This superblock is required by the kernel dm-integrity implementation.)

Milan

[dm-crypt] FAQ :WAS: LUKS2 on disk format

[JT]

I had a similar question on my list.  This would be a good one for the
revised FAQ.

Q:  What is the size of the LUKS2 header?
A:  the LUKS header size is configurable.  16MB is the default size. 
It can be changed by .....

Q: Does all metadata exist in the header?  Can I be sure that there is
no LUKS metadata somewhere in the middle or in the end of the drive?  
A: Yes, all LUKS metadata is stored in the LUKS heaer.  (Most of the
area is reserved for keyslots, used in online reencryption.)

There is a small exception if you use experimental integrity protection
(authenticated encryption) where dm-crypt is stacked over dm-integrity
device.  In that case there is a dm-integrity superblock at the
beginning of data area which contains only configuration of dm-integrity metadata.  No LUKS metadata is stored in this location. The superblock is required by the kernel dm-integrity implementation.

[dm-crypt] LUKS2 on disk format

[Maksim Fomin]

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Monday, May 11, 2020 7:58 PM, Milan Broz <gmazyland@gmail.com> wrote:

> On 11/05/2020 21:07, Maksim Fomin wrote:
>
> > After reading LUKS2 on-disk format specification, I have one main
> > question - does LUKS2 data resides entirely on header, which occupies
> > first 16 mib (at most) of block device?
>
> Yes, all LUKS metadata are stored in th eLUKS heaer.
> But the LUKS header size is configurable (it is not fixed to 16MB,
> 16MB is just the default size)
> (And most of the area is reserved for keyslots, used in online reencryption.)

Can default size (16MiB) be extended after setting up LUKS partition? What is recommended size? What are reasons to increase default size?

> > Is is safe to assume that
> > there is no LUKS metadata somewhere in the middle or in the end of
> > the drive?
>
> Yes. There is small exception if you use experimental integrity protection
> (authenticated encryption) where dm-crypt is stacked over dm-integrity device.
> Then there is dm-integrity superblock in the beginning of data area.
> (But this superblovk contains only configuration of dm-integrity metadata;
> no LUKS metadata are stored there.
> This superblock is required by the kernel dm-integrity implementation.)
>
> Milan

Thanks.

Re: [dm-crypt] LUKS2 on disk format

[Ondrej Kozina]

On 5/12/20 7:48 AM, Maksim Fomin wrote:
> ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
> On Monday, May 11, 2020 7:58 PM, Milan Broz <gmazyland@gmail.com> wrote:
> 
>> On 11/05/2020 21:07, Maksim Fomin wrote:
>>
>>> After reading LUKS2 on-disk format specification, I have one main
>>> question - does LUKS2 data resides entirely on header, which occupies
>>> first 16 mib (at most) of block device?
>>
>> Yes, all LUKS metadata are stored in th eLUKS heaer.
>> But the LUKS header size is configurable (it is not fixed to 16MB,
>> 16MB is just the default size)
>> (And most of the area is reserved for keyslots, used in online reencryption.)
> 
> Can default size (16MiB) be extended after setting up LUKS partition? What is recommended size? What are reasons to increase default size?

There were basically two reasons for the increase in default LUKS2 
metadata size IIRC:

1) As Milan pointed out online reencryption performs much better when 
there's enough consecutive free space in LUKS2 keyslots area (the binary 
area for keyslots material).

While testing we figured out with 16 MiB LUKS2 metadata we hit good 
balance of getting good enough performance for reencryption and not 
consuming too much free space on a drive so that it's not a big issue 
for general use case and for users not interested in reencryption.

To get smaller metadata size you can format the device with:
cryptsetup luksFormat --offset 8192 and data offset (and LUKS2 metadata 
size) will be at 4MiB exactly (similar to current LUKS1 default).

2) LUKS2 supports up to 32 keyslots. With 4 MiB  keyslots area there 
were not enough space to fill all keyslots.

In general I don't think 16MB is big issue nowadays and for special use 
cases you can create smaller LUKS2 metadata. Even smaller than LUKS1. 
Milan gave example here: 
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932437#10

----

So I'd say 16 MiB is indeed recommended default LUKS2 metadata size in 
most cases.

-----

About extending existing LUKS2 metadata. Technically it's possible, but 
currently you have to use reencryption for it since we have to reduce 
data device size first before extending LUKS2 metadata.

cryptsetup reencrypt --reduce-device-size 4M /dev/sdx

(but do NOT forget to shrink residing filesystem/data first!)

By reducing data device by 4 MiBs we can extend LUKS2 metadata by same 
value. In the process the data are shifted backwards towards tail of the 
device.

In future we may add option to change LUKS2 metadata in-place w/o data 
shifting (reencryption) but that would be feature that requires 
cooperation with i.e. LVM2 or other volume management tools. If LVM2 
could extends device by adding extents in head of LV, it would be 
possible to simplify also online encryption etc.

Kind regards
O.

[dm-crypt] LUKS2 on disk format

[Maksim Fomin]

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Tuesday, May 12, 2020 12:54 PM, Ondrej Kozina <okozina@redhat.com> wrote:
>
> There were basically two reasons for the increase in default LUKS2
> metadata size IIRC:
>
> 1.  As Milan pointed out online reencryption performs much better when
>     there's enough consecutive free space in LUKS2 keyslots area (the binary
>     area for keyslots material).
>
>     While testing we figured out with 16 MiB LUKS2 metadata we hit good
>     balance of getting good enough performance for reencryption and not
>     consuming too much free space on a drive so that it's not a big issue
>     for general use case and for users not interested in reencryption.
>
>     To get smaller metadata size you can format the device with:
>     cryptsetup luksFormat --offset 8192 and data offset (and LUKS2 metadata
>     size) will be at 4MiB exactly (similar to current LUKS1 default).
>
> 2.  LUKS2 supports up to 32 keyslots. With 4 MiB keyslots area there
>     were not enough space to fill all keyslots.
>
>     In general I don't think 16MB is big issue nowadays and for special use
>     cases you can create smaller LUKS2 metadata. Even smaller than LUKS1.
>     Milan gave example here:
>     https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932437#10
>
>
> So I'd say 16 MiB is indeed recommended default LUKS2 metadata size in
> most cases.

OK.

> -------------------------------------------------------------------------------------
>
> About extending existing LUKS2 metadata. Technically it's possible, but
> currently you have to use reencryption for it since we have to reduce
> data device size first before extending LUKS2 metadata.
>
> cryptsetup reencrypt --reduce-device-size 4M /dev/sdx
>
> (but do NOT forget to shrink residing filesystem/data first!)
>
> By reducing data device by 4 MiBs we can extend LUKS2 metadata by same
> value. In the process the data are shifted backwards towards tail of the
> device.
>
> In future we may add option to change LUKS2 metadata in-place w/o data
> shifting (reencryption) but that would be feature that requires
> cooperation with i.e. LVM2 or other volume management tools. If LVM2
> could extends device by adding extents in head of LV, it would be
> possible to simplify also online encryption etc.
>
> Kind regards
> O.

My question was not how to do it (obviously, one needs to move partition first), but why extra space for header may be needed. Is it for the case where users want (for some reason) often to do reencryption (not just for one time, but periodically)?

Re: [dm-crypt] LUKS2 on disk format

[Ondrej Kozina]

On 5/12/20 12:31 PM, Maksim Fomin wrote:
> ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
> On Tuesday, May 12, 2020 12:54 PM, Ondrej Kozina <okozina@redhat.com> wrote:
>>
>> There were basically two reasons for the increase in default LUKS2
>> metadata size IIRC:
>>
>> 1.  As Milan pointed out online reencryption performs much better when
>>      there's enough consecutive free space in LUKS2 keyslots area (the binary
>>      area for keyslots material).
>>
>>      While testing we figured out with 16 MiB LUKS2 metadata we hit good
>>      balance of getting good enough performance for reencryption and not
>>      consuming too much free space on a drive so that it's not a big issue
>>      for general use case and for users not interested in reencryption.
>>
>>      To get smaller metadata size you can format the device with:
>>      cryptsetup luksFormat --offset 8192 and data offset (and LUKS2 metadata
>>      size) will be at 4MiB exactly (similar to current LUKS1 default).
>>
>> 2.  LUKS2 supports up to 32 keyslots. With 4 MiB keyslots area there
>>      were not enough space to fill all keyslots.
>>
>>      In general I don't think 16MB is big issue nowadays and for special use
>>      cases you can create smaller LUKS2 metadata. Even smaller than LUKS1.
>>      Milan gave example here:
>>      https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932437#10
>>
>>
>> So I'd say 16 MiB is indeed recommended default LUKS2 metadata size in
>> most cases.
> 
> OK.
> 
>> -------------------------------------------------------------------------------------
>>
>> About extending existing LUKS2 metadata. Technically it's possible, but
>> currently you have to use reencryption for it since we have to reduce
>> data device size first before extending LUKS2 metadata.
>>
>> cryptsetup reencrypt --reduce-device-size 4M /dev/sdx
>>
>> (but do NOT forget to shrink residing filesystem/data first!)
>>
>> By reducing data device by 4 MiBs we can extend LUKS2 metadata by same
>> value. In the process the data are shifted backwards towards tail of the
>> device.
>>
>> In future we may add option to change LUKS2 metadata in-place w/o data
>> shifting (reencryption) but that would be feature that requires
>> cooperation with i.e. LVM2 or other volume management tools. If LVM2
>> could extends device by adding extents in head of LV, it would be
>> possible to simplify also online encryption etc.
>>
>> Kind regards
>> O.
> 
> My question was not how to do it (obviously, one needs to move partition first), but why extra space for header may be needed. Is it for the case where users want (for some reason) often to do reencryption (not just for one time, but periodically)?

Yes, the better performance for reencryption is one reason. The other 
that comes on my mind is that some current or future projects may want 
to store some metadata in either LUKS2 unbound keyslot (binary area) or 
in LUKS2 json format. For example systemd uses LUKS2 json area (token) 
for systemd-homed metadata others may emerge.

Better plugin support is planned and it would also need some storage in 
LUKS2 metadata.

O.

Re: [dm-crypt] FAQ :WAS: LUKS2 on disk format

[Arno Wagner]

Hi JT,

thanks I had already planned to add this one.

Regards,
Arno

On Tue, May 12, 2020 at 01:15:27 CEST, JT wrote:
> I had a similar question on my list.  This would be a good one for the
> revised FAQ.
> 
> Q:  What is the size of the LUKS2 header?
> A:  the LUKS header size is configurable.  16MB is the default size. 
> It can be changed by .....
> 
> Q: Does all metadata exist in the header?  Can I be sure that there is
> no LUKS metadata somewhere in the middle or in the end of the drive?  
> A: Yes, all LUKS metadata is stored in the LUKS heaer.  (Most of the
> area is reserved for keyslots, used in online reencryption.)
> 
> There is a small exception if you use experimental integrity protection
> (authenticated encryption) where dm-crypt is stacked over dm-integrity
> device.  In that case there is a dm-integrity superblock at the
> beginning of data area which contains only configuration of dm-integrity metadata.  No LUKS metadata is stored in this location. The superblock is required by the kernel dm-integrity implementation.
> 
> 
> _______________________________________________
> dm-crypt mailing list
> dm-crypt@saout.de
> https://www.saout.de/mailman/listinfo/dm-crypt

-- 
Arno Wagner,     Dr. sc. techn., Dipl. Inform.,    Email: arno@wagner.name
GnuPG: ID: CB5D9718  FP: 12D6 C03B 1B30 33BB 13CF  B774 E35C 5FA1 CB5D 9718
----
A good decision is based on knowledge and not on numbers. -- Plato

If it's in the news, don't worry about it.  The very definition of 
"news" is "something that hardly ever happens." -- Bruce Schneier