cryptsetup-reencrypt.8 5.78 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
.TH CRYPTSETUP-REENCRYPT "8" "June 2012" "cryptsetup-reencrypt" "Maintenance Commands"
.SH NAME
cryptsetup-reencrypt - tool for offline LUKS device re-encryption
.SH SYNOPSIS
.B cryptsetup-reencrypt <options> <device>
.SH DESCRIPTION
.PP
Cryptsetup-reencrypt can be used to change reencryption parameters
which otherwise require full on-disk data change (re-encryption).

You can regenerate \fBvolume key\fR (the real key used in on-disk encryption
unclocked by passphrase), \fBcipher\fR, \fBcipher mode\fR.

Cryptsetup-reencrypt reencrypts data on LUKS device in-place. During
reencryption process the LUKS device is marked unavailable.

\fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware
or kernel failures during reencryption (you can lose you data in this case).

\fIALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.\fR
.br
\fITHIS TOOL IS EXPERIMENTAL.\fR

The reencryption can be temporarily suspended (by TERM signal or by
using ctrl+c) but you need to retain temporary files named LUKS-<uuid>.[log|org|new].
LUKS device is unavailable until reencryption is finished though.

For more info about LUKS see cryptsetup(8).
.PP
.SH OPTIONS
.TP
To start (or continue) re-encryption for <device> use:
.PP
\fIcryptsetup-reencrypt\fR <device>

\fB<options>\fR can be [\-\-block-size, \-\-cipher, \-\-hash, \-\-iter-time,
\-\-use-random | \-\-use-urandom, \-\-key-file, \-\-key-slot, \-\-keyfile-offset,
\-\-keyfile-size, \-\-tries, \-\-use-directio, \-\-use-fsync, \-\-write-log]

For detailed description of encryption and key file options see \fIcryptsetup(8)\fR
man page.
.TP
.B "\-\-verbose, \-v"
Print more information on command execution.
.TP
.B "\-\-debug"
Run in debug mode with full diagnostic logs. Debug output
lines are always prefixed by '#'.
.TP
.B "\-\-cipher, \-c" \fI<cipher-spec>\fR
Set the cipher specification string.
.TP
53 54 55 56 57 58 59 60 61 62 63 64
.B "\-\-key-size, \-s \fI<bits>\fR"
Set key size in bits. The argument has to be a multiple of  8.

The possible key-sizes are limited by the cipher and mode used. 

If you are increasing key size, there must be enough space in the LUKS header
for enlarged keyslots (data offset must be large enough) or reencryption
cannot be performed.

If there is not enough space for keyslots with new key size,
you can destructively shrink device with \-\-reduce-device-size option.
.TP
65 66 67 68 69 70 71 72 73 74 75 76 77 78
.B "\-\-hash, \-h \fI<hash-spec>\fR"
Specifies the hash used in the LUKS key setup scheme and volume key digest.
.TP
.B "\-\-iter-time, \-i \fI<milliseconds>\fR"
The number of milliseconds to spend with PBKDF2 passphrase processing for the
new LUKS header.
.TP
.B "\-\-use-random"
.TP
.B "\-\-use-urandom"
Define which kernel random number generator will be used to create the volume key.
.TP
.B "\-\-key-file, \-d \fIname\fR"
Read the passphrase from file.
79

80 81 82 83
WARNING: \-\-key-file option can be used only if there only one active keyslot,
or alternatively, also if \-\-key-slot option is specified (then all other keyslots
will be disabled in new LUKS device).

84
If this option is not used, cryptsetup-reencrypt will ask for all active keyslot
85 86 87 88
passphrases.
.TP
.B "\-\-key-slot, \-S <0-7>"
Specify which key slot is used.
89

90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
WARNING: All other keyslots will be disabled if this option is used.
.TP
.B "\-\-keyfile-offset \fIvalue\fR"
Skip \fIvalue\fR bytes at the beginning of the key file.
.TP
.B "\-\-keyfile-size, \-l"
Read a maximum of \fIvalue\fR bytes from the key file.
Default is to read the whole file up to the compiled-in
maximum.
.TP
.B "\-\-tries, \-T"
Number of retries for invalid passphrase entry.
.TP
.B "\-\-block-size, \-B \fIvalue\fR"
Use re-encryption block size of <value> in MiB.
105

106 107
Values can be between 1 and 64 MiB.
.TP
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
.B "\-\-reduce-device-size \fInumber of 512 bytes sectors\fR"
Enlarge data offset for specified value of sectors by shrinking
device size.

This means that last sectors on the original device will be lost,
ciphertext data will be effectively shifted by specified
number of sectors.

It can be usefull if you e.g. added some space to underlying
partition (so last sectors contains no data).

WARNING: This is destructive operation and cannot be reverted.
Use with extreme care - shrinked filesystems are usually unrecoverable.

You cannot shrink device more than by 64 MiB (131072 sectors).
123 124 125 126 127 128 129 130
.TP
.B "\-\-new, N"
Create new header (encrypt not yet encrypted device).

This option must be used together with \-\-reduce-device-size.

WARNING: This is destructive operation and cannot be reverted.

131
.TP
132 133
.B "\-\-use-directio"
Use direct-io (O_DIRECT) for all read/write data operations.
134

135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
Usefull if direct-io operations perform better than normal buffered
operations (e.g. in virtual environments).
.TP
.B "\-\-use-fsync"
Use fsync call after every written block.
.TP
.B "\-\-write-log"
Update log file after every block write. This can slow down reencryption
but will minimize data loss in the case of system crash.
.TP
.B "\-\-batch-mode, \-q"
Suppresses all warnings and reencryption progress output.
.TP
.B "\-\-version"
Show the program version.
.SH RETURN CODES
Cryptsetup-reencrypt returns 0 on success and a non-zero value on error.

Error codes are: 1 wrong parameters, 2 no permission,
3 out of memory, 4 wrong device specified, 5 device already exists
or device is busy.
.SH REPORTING BUGS
Report bugs, including ones in the documentation, on
the cryptsetup mailing list at <dm-crypt@saout.de>
or in the 'Issues' section on LUKS website.
Please attach the output of the failed command with the
\-\-debug option added.
.SH AUTHORS
Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
.SH COPYRIGHT
Copyright \(co 2012 Milan Broz
.br
Copyright \(co 2012 Red Hat, Inc.

This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH SEE ALSO
The project website at \fBhttp://code.google.com/p/cryptsetup/\fR