[dm-crypt] [ANNOUNCE] cryptsetup 1.5.0-rc1 (add veritysetup)

[dm-crypt] [ANNOUNCE] cryptsetup 1.5.0-rc1 (add veritysetup)

[Milan Broz]

The testing release candidate cryptsetup 1.5.0-rc1 is available at

   http://code.google.com/p/cryptsetup/

Feedback and bug reports are welcomed.

(Please report all bugs even in kernel dm-verity part, thanks!)

Cryptsetup 1.5.0 RC1 Release Notes
==================================

This testing release candidate version covers mainly
inclusion of new veritysetup tool (and related libcryptsetup extensions).

Please note that API extension and on-disk superblock can change in next
1.5.0 release candidate (despite it is not expected).

Changes since version 1.4.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Introduce veritysetup tool for dm-verity target management.

The dm-verity device-mapper target was added to Linux kernel 3.4 and
provides transparent integrity checking of block devices using a cryptographic
digest provided by the kernel crypto API. This target is read-only.

It is meant to be setup as part of a verified boot path (it was originally
developed by Chrome OS authors as part of verified boot infrastructure).

For deeper description please see http://code.google.com/p/cryptsetup/wiki/DMVerity
and kernel dm-verity documentation.

The libcryptsetup library was extended to support manipulation
with dm-verity kernel module and new veritysetup CLI tool is added.

There are no additional library requirements (it uses the same crypto
backend as cryptsetup).

If you want compile cryptsetup without veritysetup tool,
use --disable-veritysetup configure option.
For other configuration option see configure --help and veritysetup --help
(e.g. default parameters).

Supported libcryptsetup functions new CRYPT_VERITY type:
  crypt_init
  crypt_init_by_name
  crypt_set_data device
  crypt_get_type
  crypt_format
  crypt_load
  crypt_get_active_device
  crypt_activate_by_volume_key (volume key == root hash here)
  crypt_dump
and new introduced function
  crypt_get_verity_info

Please see comments in libcryptsetup.h and veritysetup.c as an code example
how to use CRYPT_VERITY API.

The veritysetup tool supports these operations:

  veritysetup format <data_device> <hash_device>
    Formats <hash_device> (calculates all hash areas according to <data_device>).
    This is initial command to prepare device <hash_device> for later verification.

  veritysetup create <name> <data_device> <hash_device> <root_hash>
    Creates (activates) a dm-verity mapping with <name> backed by device <data_device>
    and using <hash_device> for in-kernel verification.

  veritysetup verify <data_device> <hash_device> <root_hash>
    Verifies data in userspace (no kernel device is activated).

  veritysetup remove <name>
    Removes activated device from kernel (similar to dmsetup remove).

  veritysetup status <name>
    Reports status for the active kernel dm-verity device.

  veritysetup dump <hash_device>
    Reports parameters of verity device from on-disk stored superblock.

For more info see veritysetup --help and veritysetup man page.

Other changes
~~~~~~~~~~~~~

  * Both data and header device can now be a file and
    loop device is automatically allocated.

  * Require only up to last keyslot area for header device, previously
    backup (and activation) required device/file of size up to data start
    offset (data payload).

  * Fix header backup and restore to work on files with large data offset.
    Backup and restore now works even if backup file is smaller than data offset.

Appendix: Examples of veritysetup use
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

 Format device using default parameters, info and final root hash is printed:
 # veritysetup format /dev/sdb /dev/sdc
 VERITY header information for /dev/sdc
 UUID:                   fad30431-0c59-4fa6-9b57-732a90501f75
 Hash type:              1
 Data blocks:            52224
 Data block size:        4096
 Hash block size:        4096
 Hash algorithm:         sha256
 Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 Root hash:              7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1

 Activation of device in-kernel:
 # veritysetup create vr /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
 Note - if device is corrupted, kernel mapping is created but will report failure:
 Verity device detected corruption after activation.

 Userspace verification:
 # veritysetup verify /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
  Verification failed at position 8192.
  Verification of data area failed.

 Active device status report:
 # veritysetup status vr
 /dev/mapper/vr is active.
   type:        VERITY
   status:      verified
   hash type:   1
   data block:  4096
   hash block:  4096
   hash name:   sha256
   salt:        5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
   data device: /dev/sdb
   size:        417792 sectors
   mode:        readonly
   hash device: /dev/sdc
   hash offset: 8 sectors

 Dump of on-disk superblock information:
 # veritysetup dump /dev/sdc
 VERITY header information for /dev/sdc
 UUID:                   fad30431-0c59-4fa6-9b57-732a90501f75
 Hash type:              1
 Data blocks:            52224
 Data block size:        4096
 Hash block size:        4096
 Hash algorithm:         sha256
 Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9

 Remove mapping:
 # veritysetup remove vr

Re: [dm-crypt] [ANNOUNCE] cryptsetup 1.5.0-rc1 (add veritysetup)

[.. ink ..]

>  veritysetup format <data_device> <hash_device>
>    Formats <hash_device> (calculates all hash areas according to <data_device>).
>    This is initial command to prepare device <hash_device> for later verification.
>

I just cruised over mentioned docs and didnt find an answer.The only
thing i saw is that <data_device> and <hash_device> can be in the same
device in the DMVerify wiki page but nothing about relative sizes.

Does the <hash_device> need to be the same size as <data device> ? If
not, does the space taken by <hash_device> grow as some sort of a
function to the size of <data_device>?

>  veritysetup create <name> <data_device> <hash_device> <root_hash>

Does this mean a user will have to store the <root_hash> generated in
the formatting stage and supply it everytime a mapper is created? Is
the <root_hash> supposed to be a secret?

Re: [dm-crypt] [ANNOUNCE] cryptsetup 1.5.0-rc1 (add veritysetup)

[Milan Broz]

On 06/11/2012 08:08 PM, .. ink .. wrote:
>>  veritysetup format <data_device> <hash_device>
>>    Formats <hash_device> (calculates all hash areas according to <data_device>).
>>    This is initial command to prepare device <hash_device> for later verification.
>>
> 
> I just cruised over mentioned docs and didnt find an answer.The only
> thing i saw is that <data_device> and <hash_device> can be in the same
> device in the DMVerify wiki page but nothing about relative sizes.

Documentation is just part take form kernel doc, 
see also former patches on dm-devel from Google
https://www.redhat.com/archives/dm-devel/2012-March/msg00003.html
The kernel part was rewritten later though.
(I will perhaps add more info to wiki later...)

I just integrated existing code to cryptsetup (well, it means another
rewrite of userspace:-)

So, for shared device, it can be like this:

|-------------device----------------|
| -verified data- | |SB| -hash area-|
                    ^  ^
| --data blocks--|  |  offset provided to kernel
                    superblock offset

So if you want to store both hash and data on the same device,
you have to provide --data-blocks and --hash-offset for format.

(For verify and create --hash-offset is enough because data blocks
number is stored inside superblock.)
Also --no-superblock option can be used, then it needs to specify
all parameters (it is like "plain" device vs LUKS in cryptsetup).

For device sizes:
- data blocks describes size of verified area (usually the whole device).
So it is either provided by user, or it is calculated from the
whole device size (data_blocks = device_size / data_block_size)

- hash device size is calculated during format, currently it is
visible when you run it in debug mode (perhaps the API will be extended
later to get this directly, dunno yet.)

> Does the <hash_device> need to be the same size as <data device> ? If
> not, does the space taken by <hash_device> grow as some sort of a
> function to the size of <data_device>?

Yes. Obviously, hash area is smaller than data area
(one hash, typically 32 bytes, verifies one data block which is by default
4096 bytes + you need space for tree hash structure etc).

Try to run format with --debug on some testing device and you will see
a lot of info what it is doing, for example in release notes mail:
...
# Hash creation sha256, data device /dev/sdb, data blocks 52224, hash_device /dev/sdc, offset 1.
# Using 3 hash levels.
# Data device size required: 213909504 bytes.
# Hash device size required: 1695744 bytes.
# Updating VERITY header of size 512 on device /dev/sdc, offset 0.
VERITY header information for /dev/sdc
UUID:                   b415461f-93d3-4e3d-a5ef-3c3aa8b3686c
Hash type:              1
Data blocks:            52224
Data block size:        4096
Hash block size:        4096
Hash algorithm:         sha256

>>  veritysetup create <name> <data_device> <hash_device> <root_hash>
> 
> Does this mean a user will have to store the <root_hash> generated in
> the formatting stage and supply it everytime a mapper is created? Is
> the <root_hash> supposed to be a secret?

Yes, root hash must be supplied every time and must be trusted.
It is not secret - you can calculate hash yourself (that's exactly what
verification does - compares own calculated hash with stored value, from
leaf nodes to root level and, finally, compares with trusted root hash.) 
(So if is used to implementation of "trusted" boot, root hash should be signed,
stored in some trusted read-only device, whatever.)

(I guess dm-verity can be used in some special environments, it is perhaps
not something widely usable. If you ask about GUI - no, I do not think
there is some need for it;-)

Milan