"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/v1.5.0-ReleaseNotes" (24 Jul 2021, 8610 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Cryptsetup 1.5.0 Release Notes
    2 ==============================
    3 
    4 This release covers mainly inclusion of:
    5 
    6   * Veritysetup tool (and related libcryptsetup extensions for dm-verity).
    7 
    8   * Experimental cryptsetup-reencrypt tool (LUKS offline reencryption).
    9 
   10 Changes since version 1.5.0-rc2
   11 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   12 
   13   * Add --device-size option for reencryption tool.
   14 
   15   * Switch to use unit suffix for --reduce-device-size option.
   16 
   17   * Remove open device debugging feature (no longer needed).
   18 
   19   * Fix library name for FIPS check.
   20 
   21   * Add example of using reencryption inside dracut (see misc/dracut).
   22 
   23 Changes since version 1.5.0-rc1
   24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   25 Introduce cryptsetup-reencrypt - experimental offline LUKS reencryption tool.
   26 
   27 ! cryptsetup-reencrypt tool is EXPERIMENTAL
   28 ! ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL
   29 
   30 This tool tries to simplify situation when you need to re-encrypt the whole
   31 LUKS device in situ (without need to move data elsewhere).
   32 
   33 This can happen for example when you want to change volume (master) key,
   34 encryption algorithm, or other encryption parameter.
   35 
   36 Cryptsetup-reencrypt can even optionally shift data on device
   37 (reducing data device size - you need some free space at the end of device).
   38 
   39 In general, cryptsetup-reencrypt can be used to
   40 
   41  - re-generate volume key
   42  - change arbitrary encryption parameters
   43  - add encryption to not yet encrypted drive
   44 
   45 Side effect of reencryption is that final device will contain
   46 only ciphertext (for all sectors) so even if device was not properly
   47 wiped by random data, after reencryption you cannot distinguish
   48 which sectors are used.
   49 (Reencryption is done always for the whole device.)
   50 
   51 There are for sure bugs, please TEST IT IN TEST ENVIRONMENT before
   52 use for your data.
   53 
   54 This tool is not resistant to HW and kernel failures - hw crash
   55 will cause serious data corruption.
   56 
   57 You can enable compilation of this tool with --enable-cryptsetup-reencrypt
   58 configure option (it is switched off by default).
   59 (Tool requires libcryptsetup 1.4.3 and later.)
   60 
   61 You have to provide all keyslot passphrases or use --keyslot-option
   62 (then all other keyslots will be disabled).
   63 
   64 EXAMPLES (from man page)
   65 
   66 Reencrypt /dev/sdb1 (change volume key)
   67    # cryptsetup-reencrypt /dev/sdb1
   68 
   69 Reencrypt and also change cipher and cipher mode
   70   # cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
   71 
   72   Note: if you are changing key size, there must be enough space
   73   for keyslots in header or you have to use --reduce-device size and
   74   reduce fs in advance.
   75 
   76 Add LUKS encryption to not yet encrypted device
   77   First, be sure you have space added to disk.
   78   Or, alternatively, shrink filesystem in advance.
   79 
   80   Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
   81 
   82   # fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors
   83 
   84   # cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096
   85 
   86 There are some options which can improve performance (depends on system),
   87 namely --use-directio (use direct IO for all operations) can be faster
   88 on some systems. See man page.
   89 
   90 Progress and estimated time is printed during reencryption.
   91 
   92 You can suspend reencryption (using ctrl+c or term signal).
   93 To continue reencryption you have to provide only
   94 the device parameter (offset is stored in temporary log file).
   95 
   96 Please note LUKS device is marked invalid during reencryption and
   97 you have to retain tool temporary files until reencryption finishes.
   98 
   99 Temporary files are LUKS-<uuid>.[log|org|new]
  100 
  101 Other changes
  102 ~~~~~~~~~~~~~
  103 
  104   * Fix luks-header-from-active script (do not use LUKS header on-disk, add UUID).
  105 
  106   * Add --test-passphrase option for luksOpen (check passphrase only).
  107 
  108   * Fix parsing of hexadecimal string (salt or root hash) in veritysetup.
  109 
  110 Changes since version 1.4.3
  111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  112 Introduce veritysetup tool for dm-verity target management.
  113 
  114 The dm-verity device-mapper target was added to Linux kernel 3.4 and
  115 provides transparent integrity checking of block devices using a cryptographic
  116 digest provided by the kernel crypto API. This target is read-only.
  117 
  118 It is meant to be setup as part of a verified boot path (it was originally
  119 developed by Chrome OS authors as part of verified boot infrastructure).
  120 
  121 For deeper description please see http://code.google.com/p/cryptsetup/wiki/DMVerity
  122 and kernel dm-verity documentation.
  123 
  124 The libcryptsetup library was extended to support manipulation
  125 with dm-verity kernel module and new veritysetup CLI tool is added.
  126 
  127 There are no additional library requirements (it uses the same crypto
  128 backend as cryptsetup).
  129 
  130 If you want compile cryptsetup without veritysetup tool,
  131 use --disable-veritysetup configure option.
  132 For other configuration option see configure --help and veritysetup --help
  133 (e.g. default parameters).
  134 
  135 Supported libcryptsetup functions new CRYPT_VERITY type:
  136   crypt_init
  137   crypt_init_by_name
  138   crypt_set_data device
  139   crypt_get_type
  140   crypt_format
  141   crypt_load
  142   crypt_get_active_device
  143   crypt_activate_by_volume_key (volume key == root hash here)
  144   crypt_dump
  145 and new introduced function
  146   crypt_get_verity_info
  147 
  148 Please see comments in libcryptsetup.h and veritysetup.c as an code example
  149 how to use CRYPT_VERITY API.
  150 
  151 The veritysetup tool supports these operations:
  152 
  153   veritysetup format <data_device> <hash_device>
  154     Formats <hash_device> (calculates all hash areas according to <data_device>).
  155     This is initial command to prepare device <hash_device> for later verification.
  156 
  157   veritysetup create <name> <data_device> <hash_device> <root_hash>
  158     Creates (activates) a dm-verity mapping with <name> backed by device <data_device>
  159     and using <hash_device> for in-kernel verification.
  160 
  161   veritysetup verify <data_device> <hash_device> <root_hash>
  162     Verifies data in userspace (no kernel device is activated).
  163 
  164   veritysetup remove <name>
  165     Removes activated device from kernel (similar to dmsetup remove).
  166 
  167   veritysetup status <name>
  168     Reports status for the active kernel dm-verity device.
  169 
  170   veritysetup dump <hash_device>
  171     Reports parameters of verity device from on-disk stored superblock.
  172 
  173 For more info see veritysetup --help and veritysetup man page.
  174 
  175 Other changes
  176 ~~~~~~~~~~~~~
  177 
  178   * Both data and header device can now be a file and
  179     loop device is automatically allocated.
  180 
  181   * Require only up to last keyslot area for header device, previously
  182     backup (and activation) required device/file of size up to data start
  183     offset (data payload).
  184 
  185   * Fix header backup and restore to work on files with large data offset.
  186     Backup and restore now works even if backup file is smaller than data offset.
  187 
  188 Appendix: Examples of veritysetup use
  189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  190 
  191  Format device using default parameters, info and final root hash is printed:
  192  # veritysetup format /dev/sdb /dev/sdc
  193  VERITY header information for /dev/sdc
  194  UUID:                   fad30431-0c59-4fa6-9b57-732a90501f75
  195  Hash type:              1
  196  Data blocks:            52224
  197  Data block size:        4096
  198  Hash block size:        4096
  199  Hash algorithm:         sha256
  200  Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
  201  Root hash:              7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
  202 
  203  Activation of device in-kernel:
  204  # veritysetup create vr /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
  205  Note - if device is corrupted, kernel mapping is created but will report failure:
  206  Verity device detected corruption after activation.
  207 
  208  Userspace verification:
  209  # veritysetup verify /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
  210   Verification failed at position 8192.
  211   Verification of data area failed.
  212 
  213  Active device status report:
  214  # veritysetup status vr
  215  /dev/mapper/vr is active.
  216    type:        VERITY
  217    status:      verified
  218    hash type:   1
  219    data block:  4096
  220    hash block:  4096
  221    hash name:   sha256
  222    salt:        5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
  223    data device: /dev/sdb
  224    size:        417792 sectors
  225    mode:        readonly
  226    hash device: /dev/sdc
  227    hash offset: 8 sectors
  228 
  229  Dump of on-disk superblock information:
  230  # veritysetup dump /dev/sdc
  231  VERITY header information for /dev/sdc
  232  UUID:                   fad30431-0c59-4fa6-9b57-732a90501f75
  233  Hash type:              1
  234  Data blocks:            52224
  235  Data block size:        4096
  236  Hash block size:        4096
  237  Hash algorithm:         sha256
  238  Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
  239 
  240  Remove mapping:
  241  # veritysetup remove vr