Re: [PATCH v2 3/3] dm: add documentation for dm-inlinecrypt target

[Linlin Zhang <linlin.zhang@oss.qualcomm.com>]

On 4/11/2026 1:07 AM, Milan Broz wrote:
> On 4/10/26 3:40 PM, Linlin Zhang wrote:
>> This adds the admin-guide documentation for dm-inlinecrypt.
>>
>> dm-inlinecrypt.rst is the guide to using dm-inlinecrypt.
>>
>> Signed-off-by: Linlin Zhang <linlin.zhang@oss.qualcomm.com>
>> ---
> 
> ...
> 
>> +
>> +<cipher>
>> +    Encryption cipher type.
>> +
>> +    The cipher specifications format is::
>> +
>> +       cipher
>> +
>> +    Examples::
>> +
>> +       aes-xts-plain64
>> +
>> +    The cipher type is correspond one-to-one with encryption modes. For
> 
> ... with encryption modes supported for inline crypto in block layer?
> 
> In your patch only BLK_ENCRYPTION_MODE_AES_256_XTS.

Thanks for your insights!

Yes, here the encryption modes refer to the inline crypto modessupported
by the block layer. Currently, this patch only supports
BLK_ENCRYPTION_MODE_AES_256_XTS. 

I will reword it as:

  The cipher type corresponds to the encryption modes supported by
  inline crypto in the block layer. Currently, only
  BLK_ENCRYPTION_MODE_AES_256_XTS (i.e. aes-xts-plain64) is supported.

Could you please let me know if you expect more than that?

> 
>> +    instance, the corresponding crypto mode of aes-xts-plain64 is
>> +    BLK_ENCRYPTION_MODE_AES_256_XTS.
> 
> ...
> 
>> +iv_large_sectors
>> +   IV generators will use sector number counted in <sector_size> units
>> +   instead of default 512 bytes sectors.
>> +
>> +   For example, if <sector_size> is 4096 bytes, plain64 IV for the second
>> +   sector will be 8 (without flag) and 1 if iv_large_sectors is present.
>> +   The <iv_offset> must be multiple of <sector_size> (in 512 bytes units)
>> +   if this flag is specified.
> 
> Is it true? I see this comment in the code:
> 
> /* dm-inlinecrypt doesn't implement iv_large_sectors=false. */

Thanks for your comment!

The example is describing the general IV generation semantics of
iv_large_sectors versus the legacy behavior, i.e. how plain64 IVs
would be computed conceptually with and without the flag.
However, for dm-inlinecrypt, the comment you quoted is correct:
iv_large_sectors=false is not implemented. When a sector size
larger than 512 bytes is used, iv_large_sectors is mandatory, and
the legacy 512-byte-based IV behavior is intentionally unsupported.

In the code this is enforced by rejecting configurations where
sector_size != 512 and iv_large_sectors is not specified, so in
practice the “without flag” case is not usable for dm-inlinecrypt.

I reword it as:

  iv_large_sectors
      Use <sector_size>-based sector numbers for IV generation instead of
      512-byte sectors.

      For dm-inlinecrypt, this flag must be specified when <sector_size>
      is larger than 512 bytes. The legacy 512-byte-based IV behavior is
      not supported.

      When specified, if <sector_size> is 4096 bytes, plain64 IV for the
      second sector will be 1, and <iv_offset> must be a multiple of
      <sector_size> (in 512-byte units).

Do think it's enough?

> 
> ...
> 
>> +Example scripts
>> +===============
>> +LUKS (Linux Unified Key Setup) is now the preferred way to set up disk
>> +encryption with dm-inlinecrypt using the 'cryptsetup' utility, see
>> +https://gitlab.com/cryptsetup/cryptsetup
> 
> Cryptsetup has no support for inlinecrypt and it is question if it should have.
> It would require additional options and maybe LUKS2 metadata flag to make it persistent.
> 
> How did you test it? Please remove this cryptsetup example.
> It can be added later when userspace get this functionality.

You are right.

cryptsetup currently has no support for dm-inlinecrypt, and the example
would indeed create a dm-crypt device instead. Supporting dm-inlinecrypt
in cryptsetup would require explicit userspace changes and possibly
extensions to LUKS2 metadata to make it persistent.

I did the testing using dmsetup directly, not via cryptsetup/LUKS. And
I'll remove the LUKS/cryptsetup references and examples from the
documentation and leave LUKS integration to be documented once
userspace support exists.

I reword it as:

  Currently, dm-inlinecrypt devices must be set up directly using dmsetup.
  There is no userspace support yet to integrate dm-inlinecrypt with LUKS
  or cryptsetup. In particular, cryptsetup currently only supports
  dm-crypt, and cannot be used to create dm-inlinecrypt mappings.

  The following examples demonstrate how to create dm-inlinecrypt devices
  using dmsetup.

> 
> ...> +
>> +    #!/bin/sh
>> +    # Create a inlinecrypt device using cryptsetup and LUKS header with default cipher
>> +    cryptsetup luksFormat $1
>> +    cryptsetup luksOpen $1 inlinecrypt1
> 
> ditto. This example will use dm-crypt, not dm-inlinecrypt.

ACK

> 
> Milan
>