man/cryptsetup-reencrypt.8.adoc

   1 = cryptsetup-reencrypt(8)
   2 :doctype: manpage
   3 :manmanual: Maintenance Commands
   4 :mansource: cryptsetup {release-version}
   5 :man-linkstyle: pass:[blue R < >]
   6 :COMMON_OPTIONS:
   7 :ACTION_REENCRYPT:
   8
   9 == Name
  10
  11 cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place
  12
  13 == SYNOPSIS
  14
  15 *cryptsetup _reencrypt_ [<options>] <device> or --active-name <name> [<new_name>]*
  16
  17 == DESCRIPTION
  18
  19 Run LUKS device reencryption.
  20
  21 There are 3 basic modes of operation:
  22
  23 * device reencryption (_reencrypt_)
  24 * device encryption (_reencrypt_ --encrypt/--new/-N)
  25 * device decryption (_reencrypt_ --decrypt)
  26
  27 <device> or --active-name <name> (LUKS2 only) is mandatory parameter.
  28
  29 Cryptsetup _reencrypt_ action can be used to change reencryption parameters
  30 which otherwise require full on-disk data change (re-encryption). The
  31 _reencrypt_ action reencrypts data on LUKS device in-place.
  32
  33 You can regenerate *volume key* (the real key used in on-disk encryption
  34 unclocked by passphrase), *cipher*, *cipher mode* or *encryption sector size*
  35 (LUKS2 only).
  36
  37 Reencryption process may be safely interrupted by a user via SIGINT
  38 signal (ctrl+c). Same applies to SIGTERM signal (i.e. issued by systemd
  39 during system shutdown).
  40
  41 For in-place encryption mode, the _reencrypt_ action additionally takes all
  42 options available for _luksFormat_ action for respective LUKS version (see
  43 cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8).
  44
  45 *NOTE* that for encrypt and decrypt mode, the whole device must be
  46 treated as unencrypted -- there are no quarantees of confidentiality as
  47 part of the device contains plaintext.
  48
  49 *ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.*
  50
  51 *<options>* can be [--batch-mode,
  52 --block-size,
  53 --cipher,
  54 --debug,
  55 --debug-json,
  56 --decrypt,
  57 --device-size,
  58 --disable-locks,
  59 --encrypt,
  60 --force-offline-reencrypt,
  61 --hash,
  62 --header,
  63 --hotzone-size,
  64 --iter-time,
  65 --init-only,
  66 --keep-key,
  67 --key-file,
  68 --key-size,
  69 --key-slot,
  70 --keyfile-offset,
  71 --keyfile-size,
  72 --tries,
  73 --timeout,
  74 --pbkdf,
  75 --pbkdf-force-iterations,
  76 --pbkdf-memory,
  77 --pbkdf-parallel,
  78 --progress-frequency,
  79 --progress-json,
  80 --reduce-device-size,
  81 --resilience,
  82 --resilience-hash,
  83 --resume-only,
  84 --sector-size,
  85 --use-directio,
  86 --use-random,
  87 --use-urandom,
  88 --use-fsync,
  89 --uuid,
  90 --verbose,
  91 --volume-key-file,
  92 --write-log].
  93
  94 == LUKS2 REENCRYPTION
  95
  96 With <device> parameter cryptsetup looks up active <device> dm mapping.
  97 If no active mapping is detected, it starts offline LUKS2 reencryption
  98 otherwise online reencryption takes place.
  99
 100 To resume already initialized or interrupted reencryption, just run the
 101 cryptsetup _reencrypt_ command again to continue the reencryption
 102 operation. Reencryption may be resumed with different --resilience or
 103 --hotzone-size unless implicit datashift resilience mode is used: either
 104 encrypt mode with --reduce-device-size option or decrypt mode with
 105 original LUKS2 header exported in --header file.
 106
 107 If the reencryption process was interrupted abruptly (reencryption
 108 process crash, system crash, poweroff) it may require recovery. The
 109 recovery is currently run automatically on next activation (action
 110 _open_) when needed or explicitly by user (action _repair_).
 111
 112 Optional parameter <new_name> takes effect only with encrypt option
 113 and it activates device <new_name> immediately after encryption
 114 initialization gets finished. That's useful when device needs to be
 115 ready as soon as possible and mounted (used) before full data area
 116 encryption is completed.
 117
 118 == LUKS1 REENCRYPTION
 119
 120 Current working directory must be writable and temporary files created during
 121 reencryption must be present. During reencryption process the LUKS1 device is
 122 marked unavailable and must be offline (no dm-crypt mapping or mounted
 123 filesystem).
 124
 125 *WARNING*: The LUKS1 reencryption code is not resistant to hardware
 126 or kernel failures during reencryption (you can lose your data in this case).
 127
 128 include::man/common_options.adoc[]
 129
 130 == EXAMPLES
 131
 132 *NOTE*: You may drop *--type luks2* option as long as LUKS2 format is
 133 default.
 134
 135 === LUKS2 ENCRYPTION EXAMPLES
 136
 137 Encrypt LUKS2 device (in-place). Make sure last 32 MiB on _/dev/plaintext_
 138 is unused (e.g.: does not contain filesystem data):
 139
 140 *cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device*
 141
 142 Encrypt LUKS2 device (in-place) with detached header put in a file:
 143
 144 *cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device*
 145
 146 Initialize LUKS2 in-place encryption operation only and activate the device (not yet encrypted):
 147
 148 *cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device*
 149
 150 Resume online encryption on device initialized in example above:
 151
 152 *cryptsetup reencrypt --resume-only /dev/plaintext_device* or
 153 *cryptsetup reencrypt --active-name my_future_luks_device*
 154
 155 === LUKS2 REENCRYPTION EXAMPLES
 156
 157 Reencrypt LUKS2 device (refresh volume key only):
 158
 159 *cryptsetup reencrypt /dev/encrypted_device*
 160
 161 === LUKS2 DECRYPTION EXAMPLES
 162
 163 Decrypt LUKS2 device with header put in head of data device (header file does not exist):
 164
 165 *cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device*
 166
 167 Decrypt LUKS2 device with detached header (header file exists):
 168
 169 *cryptsetup reencrypt --decrypt --header detached-luks2-header /dev/encrypted_device*
 170
 171 Resume interrupted LUKS2 decryption:
 172
 173 *cryptsetup reencrypt --resume-only --header luks2-hdr-file /dev/encrypted_device*
 174
 175 include::man/common_footer.adoc[]